The Project Properties window within Visual Studio 2008 provides centralized control of the settings for an application. The Settings panel of this window, shown in Figure 14-1, provides access to the application’s custom settings.

Figure 14-1. The Settings panel with no defined settings

To add a setting, type in its Name, select its data Type from the drop-down list, choose the Scope (User or Application), and enter its Value using whatever value editor is available for the selected type. The Type list includes many default selections, including the basic Visual Basic data types, fonts, colors, and drawing-related sizes. Also included is a “(Connection string)” type that, when selected, enables a Connection Properties string builder in the Value column.

It’s important that you select the correct type for each stored setting; otherwise, your workstation will explode. Actually, I think they fixed that in a later beta. It’s really because all settings are strongly typed. If you set the type to Integer, you won’t be able to stuff the word None in there as a special flag as you could have done with an INI file. You can choose any valid .NET type for the data type, although complex types without their own custom editors will require that you set their value through code.

What happens when you add a new setting to your Visual Basic project? Let’s find out. I’ll add two settings to a new Windows Forms project: an Integer named WarningLimit, and a System.Drawing.Font named NoticeFont (see Figure 14-2).

Figure 14-2. The Settings panel with two new settings

As you already know, Visual Studio is just a user-friendly wrapper around .NET code, and the Settings panel is no different. So, the real changes occur somewhere in the code, or more correctly, in both code and the related Settings.settings file. If you “Show All Files” in the Solution Explorer panel, and expand My Project followed by Settings.settings, you will find that this XML file has its own Visual Basic source code file, Settings.Designer.vb.

If you open the Settings.Designer.vb file, you find the following partial code:

Namespace My
   Partial Friend NotInheritable Class MySettings
      Inherits Global.System.Configuration. _
         ApplicationSettingsBase
      <Global.System.Configuration. _
         UserScopedSettingAttribute(  ),  _
         Global.System.Diagnostics. _
         DebuggerNonUserCodeAttribute(  ),  _
         Global.System.Configuration. _
         DefaultSettingValueAttribute("25")>  _
      Public Property WarningLimit(  ) As Integer
         Get
            Return CType(Me("WarningLimit"),Integer)
         End Get
         Set
            Me("WarningLimit") = value
         End Set
      End Property

      <Global.System.Configuration. _
         UserScopedSettingAttribute(  ),  _
         Global.System.Diagnostics. _
         DebuggerNonUserCodeAttribute(  ),  _
         Global.System.Configuration. _
         DefaultSettingValueAttribute( _
         "Arial, 14.25pt, style=Bold")>  _
      Public Property NoticeFont(  ) _
            As Global.System.Drawing.Font
         Get
            Return CType(Me("NoticeFont"), _
               Global.System.Drawing.Font)
         End Get
         Set
            Me("NoticeFont") = value
         End Set
      End Property
   End Class
End Namespace

I excluded a lot of the extra code. It’s amazing how much code Microsoft loads up in prewritten attributes, and it’s not really possible to know what goes on inside. I can guess what the DefaultSettingValueAttribute attribute does for each setting (assigns the initial default value of the setting), but some of the others are mysteries. Oh well. Even the ancients didn’t have answers for everything.

But the code that remains is quite clear. Visual Studio generates two properties within the My.MySettings class, properties named—amazingly enough—WarningLimit and NoticeFont. Here’s the property entry for NoticeFont:

Public Property NoticeFont(  ) As Global.System.Drawing.Font
   Get
      Return CType(Me("NoticeFont"), _
         Global.System.Drawing.Font)
   End Get
   Set
      Me("NoticeFont") = value
   End Set
End Property

You won’t find any private class members that store the hidden WarningLimit and NoticeFont values. Instead, somewhere else in this partial class is a default property (named Item) that gets and sets each defined property value, accessed through Me("something").

The settings available through this default property are loaded directly from the XML stored in the Settings.settings file. (This file is compiled into the application; you don’t have to distribute Settings.settings with the application.) Here’s the content from that file with our two new configuration values:

<?xml version='1.0' encoding='utf-8'?>
<SettingsFile xmlns="http://schemas.microsoft.com/
VisualStudio/2004/01/settings"
   CurrentProfile="(Default)"
   GeneratedClassNamespace="My"
   GeneratedClassName="MySettings"
   UseMySettingsClassName="true">
  <Profiles />
  <Settings>
    <Setting Name="WarningLimit"
        Type="System.Int32" Scope="User">
      <Value Profile="(Default)">25</Value>
    </Setting>
    <Setting Name="NoticeFont"
        Type="System.Drawing.Font" Scope="User">
      <Value Profile="(Default)">
        Arial, 14.25pt, style=Bold</Value>
    </Setting>
  </Settings>
</SettingsFile>

Each setting contains distinct Name, Type, Scope, and Value attributes or entries, matching the four columns that appeared in the Visual Studio settings editor.

Visual Basic creates an instance of the My.MySettings class we just saw previously, and makes it available as My.Settings. As you add settings to your project, they become strongly typed class members of My.Settings. To access one, simply reference it directly in your code.

MsgBox("The font for notices is: " & _
   My.Settings.NoticeFont.ToString(  ))

(The output for this code appears in Figure 14-3.) The My.Settings.NoticeFont is an actual instance of System.Drawing.Font that you can use like any other Font instance.

Figure 14-3. Be sure to take “notice” of this font

You can modify the value of any setting scoped as “User,” and have the new value preserved for your next use of the application (i.e., for the current user’s next use of the application).

My.Settings.WarningLimit = 30

All changes made to these settings are saved automatically to the user-specific setting files by default. If you don’t want the updates saved automatically, set the My.Application.SaveMySettingsOnExit flag to False. Then, when you are ready to save the new settings, use the My.Settings.Save method.

Settings come in three delicious flavors: default, persisted, and current. Default settings are those values defined by the programmer through the Visual Studio settings editor. Persisted settings include the saved changes to specific settings, and the default settings for those that have never been altered by the user. Current settings include any changes made to the settings during the current session, but not yet saved. You can play with these states using members of the My.Settings object:

One of the strangest aspects of settings is that they are version-specific. If you release your application as version 1.0.0.0, and then later release version 1.1.0.0, each user will lose all of the previously persisted settings. Actually, they won’t be lost, but they will be stuck in 1.0.0.0-land. If you always want to have the most up-to-date settings as modified by the user, you will have to make sure that older settings are “upgraded” when installing a new version. My.Settings includes an Upgrade method that does the work for you. But if the user installs a newer version and upgrades the settings, makes changes to those settings, and then calls Upgrade again, any changes made since the last upgrade will be lost.

To get around this problem, the code should upgrade settings only when a new version appears. The easiest way to do this is to include a setting called something like SettingsUpgraded and set it to False. Check this flag before calling Upgrade. If it is still False, it is safe to call Upgrade. Once the code upgrades the settings, change SettingsUpgraded to True.

If (My.Settings.SettingsUpgraded = False) Then
   My.Settings.Upgrade(  )
   My.Setttings.SettingsUpgraded = True
End If

This need to upgrade settings whenever even minor version number changes are made to an assembly seems a bit over the top. But it’s necessary to support .NET’s goal of side-by-side installation. The user should be able to install two different versions of your application on the same workstation, and use each one without interference from the other. Storing version-specific settings helps to achieve this goal.

Although using and updating your own custom configuration values can be exciting, even more exciting is that the fields in your Windows Forms and related controls can interact with the persisted settings automatically. By binding form- and control-specific properties to the settings system, Visual Basic automatically saves and restores user-controlled preferences within the user interface.

A typical use for bound settings is to have the application remember where a particular form appeared on the screen when the program was last run. The form’s Location property maintains its on-screen position. Recording this value to the settings requires two steps. First, create a setting of type System.Drawing.Point to hold the persisted location value. Second, indicate in the form’s properties that its Location value should persist to the new settings entry.

Perform the first step by adding a new user-scoped System.Drawing.Point setting in the project properties’ Settings panel. Let’s name it “MainFormPosition,” and leave the Value field blank for now.

Back in the form editor, select the form object itself, and then access the Properties panel. Expand the “(ApplicationSettings)” property to locate the “(PropertyBinding)” subproperty. Clicking the " . . . " button for this entry displays the Application Settings dialog. This selection process appears in Figure 14-4.

Figure 14-4. Bringing up the application settings dialog for a form

Find the Location entry in the list, and choose “MainFormPosition” for its value. Now, each time you run the application containing this bound setting, the modified form will “remember” its previous location.

Let’s document the settings used by the application in the project’s Resource Kit. Add the following content to the Resource Kit word processing file.

Since we know all of the settings we will add to the application, let’s add them now. Open the project properties window and select the Settings tab. Add each setting to the application using Table 14-1 as a guide. If a setting in Table 14-1 has no listed value, leave the Value field blank as well in the settings editor.

Make sure you type the settings names as listed. The application will not be able to match up incorrectly spelled names.

I showed you how to link a form’s or control’s property value to one of the settings earlier in this chapter, so let’s do it for real in the project. We’ll link the main form’s Location property to the MainFormPosition setting. Just to refresh your memory, follow these steps to enable the link:

Although all the settings are as close as typing “My.Settings.something" in the code, some settings may initially be undefined, and using them could involve a lot of repetitive code that checks for valid settings. To reduce overall code and CPU cycles, we will cache some of the settings for easy use throughout the application.

Let’s add three more global variables to cache some of the settings. Open the General.vb module, and add these three new class members.

Public MainHelpFile As String
Public MainAdminHelpFile As String
Public FineGraceDays As Integer

Let’s give these variables initial values in the InitializeSystem method, where the code already initializes some other values. Add the following statements to that routine in the General module.

FineGraceDays = −1

' ----- Locate the online help files.
MainHelpFile = My.Settings.HelpFile & ""
MainAdminHelpFile = My.Settings.HelpFileAdmin & ""

In an earlier chapter, we stored some settings in the SystemValue table that apply to all workstations that connect to the database. Since we’re caching settings anyway, we should add some code to cache these database-stored values so that we don’t have to keep opening and closing the database. Add the LoadDatabaseSettings method to the General module.

Public Sub LoadDatabaseSettings(  )
   ' ----- Get some system-level values from
   '       database storage.
   Dim holdText As String

   On Error Resume Next

   ' ----- Get the default location.
   holdText = GetSystemValue("DefaultLocation")
   If (holdText = "") Then holdText = "−1"
   DefaultItemLocation = CInt(holdText)

   ' ----- Get the maximum number of search matches.
   holdText = GetSystemValue("SearchLimit")
   If (holdText = "") Then holdText = "−1"
   SearchMatchLimit = CInt(holdText)

   ' ----- Get the number of days to wait before
   '       charging fines.
   holdText = GetSystemValue("FineGrace")
   If (holdText = "") Then holdText = "−1"
   FineGraceDays = CInt(holdText)
End Sub

We will call this routine during application startup, just after we open and confirm the database. Add the following code to the end of the MyApplication_Startup event handler. If it’s been awhile, remember that this handler is in the ApplicationEvents.vb file, one of the files normally hidden from view in the Solution Explorer.

' ----- Load some settings that reside in the database.
LoadDatabaseSettings(  )

It’s time to actually use a setting. The My.Settings.HideLogin setting indicates whether the Login button (ActLogin) on the main Library application form should appear when running in nonadministrator (nonlibrarian) mode. The administrator can still bring up the login form through the F12 key, even if the button is hidden. In an environment where the patrons may be unknown, the system will be slightly more secure if the temptation of a Login button is removed.

The UpdateDisplayForUser routine in the MainForm class includes code for user mode (LoggedInUserID = −1) and administrator mode (LoggedInUserID <> −1). In the user mode block (the first block), replace this line:

ActLogin.Visible = True

with the following code:

' ----- Show or hide the Login button per the settings.
ActLogin.Visible = Not My.Settings.HideLogin

It’s time to add the forms that will manage all of the various application settings, both those stored locally in the user-focused settings file, and the system-wide settings stored in the database. Most of the settings are pretty simple—just basic strings, numbers, and Boolean flags—so it shouldn’t overwhelm the administrator to have them all appear on a single form. But before we get to that form, we’ll add a form that lets us manage the database connection.

I thought about calling up the connection properties dialog that Visual Studio uses to establish connection strings. I’m sure it’s possible, but it provides way more flexibility than we need in this project. For instance, it supports the configuration of non-SQL Server databases, which is of no interest to the Library Project. Instead, we’ll design a simpler form that collects only those data values that we need to build the Library connection string. The LocateDatabase form appears in Figure 14-5.

Figure 14-5. The new “Locate Database” form

I’ve already added the form and its controls to the project. Open the LocateDatabase.vb file to see the form. Four of the fields on this form are basic text entry fields (one with a password mask character). The fifth entry field, Authentication, lets the user select between Microsoft Windows authentication and SQL Server authentication.

Most of the form’s code parallels what we’ve seen in many of the other forms already in the application. Go ahead and add in all of the form’s code now.

The significant work in this form occurs in the Load event when the existing connection string is parsed out into distinct data entry fields, and in the PromptUser routine where the parts are put back together.

There are many different ways you could chop up the connection string into its base parts. I took the basic divide-and-conquer approach, extracting out each semicolon- and equals sign-separated component. Here’s the main block of code from the Load event handler that does the chopping and extracting:

' ----- Load in the existing data.
connectionString = My.Settings.DBConnection & ""
For counter = 1 To CountSubStr(connectionString, ";") + 1
   ' ----- Each comma-delimited part has the format
   '       "key=value".
   oneKey = GetSubStr(connectionString, ";", counter)
   oneValue = Trim(GetSubStr(oneKey, "=", 2))
   oneKey = Replace(UCase(Trim(GetSubStr( _
      oneKey, "=", 1))), " ", "")

   ' ----- Process each part.
   Select Case oneKey
      Case "DATASOURCE"
         ' ----- Show the server host.
         RecordServer.Text = oneValue
      Case "INITIALCATALOG"
         ' ----- Show the default database name.
         RecordDatabase.Text = oneValue
      Case "INTEGRATEDSECURITY"
         ' ----- Only check for "true". False is assumed.
         If (UCase(oneValue) = "TRUE") Then _
            RecordAuthentication.SelectedIndex = _
            RecordAuthentication.Items.IndexOf( _
            AuthenticationTypeWindows)
      Case "USERID"
         ' ----- A user ID forces SQL authentication.
         RecordAuthentication.SelectedIndex = _
            RecordAuthentication.Items.IndexOf( _
            AuthenticationTypeSQL)
         RecordUser.Text = oneValue
      Case "PASSWORD"
         ' ----- A password forces SQL authentication.
         RecordAuthentication.SelectedIndex = _
            RecordAuthentication.Items.IndexOf( _
            AuthenticationTypeSQL)
         RecordPassword.Text = oneValue
   End Select
Next counter

Putting the parts together is less complicated. Here’s the needed string concatenation code found in the PromptUser routine:

newConnection = "Data Source=" & Trim(RecordServer.Text) & _
   ";Initial Catalog=" & Trim(RecordDatabase.Text)
If (CInt(CType(RecordAuthentication.SelectedItem, _
      ListItemData)) = AuthenticationTypeWindows) Then
   ' ----- Use Windows security.
   newConnection &= ";Integrated Security=true"
Else
   ' ----- Use SQL Server security.
   newConnection &= ";User ID=" & Trim(RecordUser.Text) & _
      ";Password=" & Trim(RecordPassword.Text)
End If

Although the LocateDatabase form does all of the parsing and building of the connection string, it doesn’t actually update the saved setting. Instead, it returns the newly built connection string, and depends on the calling code to save it.

Now, back to our single-form configuration editor, Maintenance.vb. This form does all of the direct modification of the values in both the database and the local My.Settings items. Figure 14-6 and Figure 14-7 show the two main panels of the Maintenance form. The centralized settings stored in the database are “system-wide,” and the “workstation-specific” values are those accessed through My.Settings.

Figure 14-6. The new “Maintenance” form showing the “System-Wide” panel

Figure 14-7. The new “Maintenance” form showing the “Workstation-Specific” panel

This form begins its work in its Load event handler, Maintenance_Load. This routine sets up the choices in some drop-down fields, including a list of fonts. The code loops through the collection of installed fonts made available through the GDI+ object System.Drawing.Text.InstalledFontCollection.

Dim allFonts As New _
   System.Drawing.Text.InstalledFontCollection
RecordFontName.Items.Add(New ListItemData( _
   "<Not Selected>", −1))
For counter = 0 To allFonts.Families.Length − 1
   RecordFontName.Items.Add(New ListItemData( _
      allFonts.Families(counter).Name, counter))
Next counter

The routine also includes similar code to load a list of installed printers.

For Each installedPrinter As String In _
      PrinterSettings.InstalledPrinters
   RecordPrinterLocation.Items.Add(installedPrinter)
Next installedPrinter

Once everything is set up, the PopulateCurrentValues procedure completes the initialization. Its code retrieves all the current values from both the database and the My.Settings object, and stores those values in the various on-screen data entry fields. I’ve already added the database-specific code. Go ahead and add in the settings-specific code.

LibraryConnection = My.Settings.DBConnection & ""
RecordDBLocation.Text = GetDBDisplayText(LibraryConnection)
RecordConfigLocation.Text = My.Settings.ReportConfig & ""
RecordBasicHelp.Text = My.Settings.HelpFile & ""
RecordAdminHelp.Text = My.Settings.HelpFileAdmin & ""
EnableReceipts.Checked = My.Settings.UseReceipts
RecordPrinterLocation.Text = My.Settings.ReceiptPrinter & ""
RecordPrinterWidth.Text = CStr(My.Settings.ReceiptWidth)
RecordPostlude.Text = My.Settings.ReceiptPostlude & ""
HideLogin.Checked = My.Settings.HideLogin

Most of the code in this form deals with basic user interaction while the form is in use. For example, the ActDBLocation_Click event handler displays the LocateDatabase form we added earlier. Add the relevant source code to that event handler.

' ----- Prompt for the database connection details.
Dim newConnection As String

' ----- Prompt the user for the new setting.
newConnection = LocateDatabase.PromptUser(  )
If (newConnection = "") Then Return

' ----- Store the new value.
LibraryConnection = newConnection
RecordDBLocation.Text = GetDBDisplayText(LibraryConnection)

Several of the settings specify the locations of files used by the application, such as the online help files. The user can type in the path to the file directly, or use the Open File dialog to locate the file visually. To display this dialog, I’ve added an OpenFileDialog control named LocateFile. Using it is a matter of setting the various file-specific properties and calling the ShowDialog method. Here’s some of the code already included in the ActBasicHelp_Click event handler used to locate the nonadministrative online help file:

' ----- Set up the file structure.
LocateFile.DefaultExt = "chm"
LocateFile.FileName = RecordBasicHelp.Text
LocateFile.Filter = "Help Files (*.chm)|*.chm|" & _
   "All Files (*.*)|*.*"
LocateFile.FilterIndex = 1
LocateFile.Title = "Locate Help"

' ----- Prompt the user.
If (LocateFile.ShowDialog(  ) <> _
   Windows.Forms.DialogResult.OK) Then Return

' ----- Save the file path.
RecordBasicHelp.Text = LocateFile.FileName

Once the user has made the various setting changes, a click on the OK button saves each new setting to its storage area. I’ve included the database-focused saving code in the SaveFormData routine. I’ll let you add the settings-focused code, near the end of that routine.

My.Settings.DBConnection = LibraryConnection
My.Settings.ReportConfig = Trim(RecordConfigLocation.Text)
My.Settings.HelpFile = Trim(RecordBasicHelp.Text)
My.Settings.HelpFileAdmin = Trim(RecordAdminHelp.Text)
My.Settings.HideLogin = HideLogin.Checked
My.Settings.UseReceipts = EnableReceipts.Checked
My.Settings.ReceiptPrinter = Trim(RecordPrinterLocation.Text)
My.Settings.ReceiptPostlude = RecordPostlude.Text

' ----- Save the receipt printer width.
If (Trim(RecordPrinterWidth.Text) = "") Then
   My.Settings.ReceiptWidth = DefaultReceiptPrinterWidth
Else
   My.Settings.ReceiptWidth = CInt(RecordPrinterWidth.Text)
End If

Although the Maintenance form provides a user-friendly interface to the database-stored settings, you probably remember that we already wrote code to update SystemValue table records through the SystemValue.vb file. In Chapter 12, we connected that form to the main form, but we’re going to alter that logic. First, we’ll add the call to the SystemValue form to the Maintenance form’s ActAllValues_Click event handler.

' ----- Let the user edit the list of system values.
Dim RecordsForm As Library.ListEditRecords

' ----- Edit the records.
RecordsForm = New Library.ListEditRecords
RecordsForm.ManageRecords(New Library.SystemValue)
RecordsForm = Nothing

' ----- Refresh the display elements.
PopulateCurrentValues(  )

Then we’ll change the AdminLinkValues_LinkClicked event handler back in MainForm.vb. Currently, it calls the SystemValue editor directly. Replace that part of the LinkClicked handler’s code with code that calls the Maintenance form instead.

' ----- Access the maintenance portion of the program.
Maintenance.ShowDialog(  )

The last change in this chapter uses the configured connection string to establish the connection to the database. When we originally wrote the ConnectDatabase routine in the General module, we added a hardcoded connection string just to get the program working.

' ----- Build the connection string.
' !!! WARNING: Hardcoded for now.
connectionString = "Data Source=MYSYSTEMSQLEXPRESS;" & _
   "Initial Catalog=Library;Integrated Security=true"

Now that we have a user-configured connection string available, we will use that instead. The changes we must make to this routine are somewhat extensive, so just replace the function’s existing content with the updated code.

' ----- Connect to the database. Return True on success.
Dim connectionString As String
Dim configChanged As Boolean

' ----- Initialize.
HoldTransaction = Nothing
configChanged = False

' ----- Obtain the connection string.
If (Trim(My.Settings.DBConnection & "") = "") Then
   ' ----- Inform the user about the need to configure
   '       the database.
   If (MsgBox("This copy of the application has not " & _
      "been configured to connect to the library " & _
      "database. If you know the database settings, " & _
      "you can configure it now. Would you like to " & _
      "proceed?", MsgBoxStyle.YesNo Or _
      MsgBoxStyle.Question, ProgramTitle) _
      <> MsgBoxResult.Yes) Then Return False

   ' ----- Prompt for the new connection details.
   connectionString = LocateDatabase.PromptUser(  )
   If (connectionString = "") Then Return False
   configChanged = True
Else
   connectionString = My.Settings.DBConnection
End If

TryConnectingAgain:

' ----- Attempt to open the database.
Try
   LibraryDB = New SqlClient.SqlConnection(connectionString)
   LibraryDB.Open(  )
Catch ex As Exception
   ' ----- Some database failure.
   GeneralError("ConnectDatabase", ex)

   ' ----- Perhaps it is just a configuration issue.
   If (MsgBox("The connection to the database may " & _
      "have failed due to invalid configuration " & _
      "settings. Would you like to change the " & _
      "database configuration at this time?", _
      MsgBoxStyle.YesNo Or MsgBoxStyle.Question, _
      ProgramTitle) <> MsgBoxResult.Yes) Then Return False

   ' ----- Prompt for new details.
   connectionString = LocateDatabase.PromptUser(  )
   If (connectionString = "") Then Return False
      configChanged = True
   GoTo TryConnectingAgain
End Try

' ----- Save the udpated configuration if needed.
If (configChanged = True) Then _
   My.Settings.DBConnection = connectionString

' ----- Success.
Return True

The basic gist of the code involves setting the connectionString variable to the persisted connection string, and using that to open the LibraryDB object. The new code obtains the connection string from My.Settings.DBConnection. If for any reason the connection string is missing or fails to generate an open database connection, the user is prompted to supply or correct the connection string through our new LocateDatabase form.

The program is back to a condition where you can run it. The first time you run the program, it will prompt you to supply the database connection information. The values you supply will match the hardcoded version that used to be in the ConnectDatabase routine:

In the next chapter, we’ll focus on file manipulation techniques. Although we did update the settings file in this chapter, it was done indirectly through features provided by the framework. Chapter 15 will discuss more direct approaches to file manipulation.