Entering Configuration Information

The following procedures describe how to configure the Data Access Application Block. Properties associated with the nodes appear in the right pane of the Configuration Console or the Properties window of the Visual Studio® Configuration Editor. For details of the schema for the Data Access Application Block configuration, see Source Schema for the Data Access Application Block. You can also configure the block in code by using an alternate configuration source. For more information, see Advanced Configuration Scenarios and Using the Fluent Configuration API.

To add the Data Access Application Block

1. Open the configuration file. For more information, see Configuring Enterprise Library.
2. Open the Blocks menu and then click Add Data Settings.
3. The configuration tool automatically adds the Database Settings section with default settings. Click the properties expander chevron in the Database Settings section to view the settings for this section.

The next procedure explains how to configure an instance of the default database that is added automatically to the configuration. This instance is used if the application resolves a Database with no instance name.

To configure the default database

1. In the Database Instances pane, click the expander arrow for the Connection String section.

   

2. (Optional) Set the Name property by typing a new name. The default name is ConnectionString.

3. Use the Database Provider property to change the provider name as required. Enter the name of the provider or select it from the drop-down list. The default provider name is System.Data.SqlClient. You can choose a different provider if you wish, such as System.Data.OleDb. The Database Provider property must be a provider name specified in a DBProviderFactory class.

4. Click the ellipses (...) button in the Connection String property to show the connection string in a pop-up window. Edit it as required.

The next procedure explains how to create additional database instances for other databases.

To configure additional database instances

1. Click the plus sign icon in the Database Instances pane and then click Add Database to add a new connection string section.

   

2. (Optional) Set the Name property by typing a new name. This is the name you will use to refer to the database.

3. In the Database Provider property section, enter the name of the database provider or select it from the drop-down list. The Database Provider property must be a provider name specified in a DbProviderFactory class. If you are using the Visual Studio integrated configuration editor and you do not see the provider type you require in the list, you must add a reference to the assembly containing the provider to your project.

4. Click the ellipses (...) button in the Connection String property to show the connection string in a pop-up window. Type the connection string that this database will use. For example, the following connection string specifies the database named CorpData1 on the SQL Server instance named DBSERVER1 using integrated Windows® security:

   Server=DBSERVER1; Initial Catalog=CorpData1; Integrated Security=SSPI
   

The next procedure describes how to change which of the currently configured databases is the default that will be used if the application resolves a Database with no instance name.

To change the default database

1. Click the properties expander chevron in the Database Settings section to view the settings for this section if it is not already open.
2. Select the database that you want to use as the default in the drop-down list for the Default Database Instance property.

The next procedure describes how to configure a SQL Server CE database. These steps are appropriate if your application always uses a single file that you name during configuration. For more information about SQL Server CE, see Creating a Database Object.

To configure SQL Server CE

1. Click the plus sign icon in the Custom Databases pane and then click Add Custom Database Provider.

2. Set the Name property of the custom database by typing a new name. This name is used to link the SQL Server CE database provider to the connection string you will define for it.

3. In the Type property, click the ellipses (...) button, fully expand the Microsoft.Practices.EnterpriseLibrary.Data.SqlCe node, and select SqlCeDatabase. Then click OK.

4. Click the plus sign icon in the Database Instances pane and then click Add Database Connection String. This adds a new connection string to the configuration, which you will use to specify the connection string for the SQL Server CE database. Alternatively, you can configure the default Connection String item that the configuration tool adds if you do not require any other connection strings in your configuration.

5. (Optional) Set the Name property of the connection string item by typing a new name. This is the name you will use to refer to the database in your code.

6. Click the ellipses (...) button in the Connection String property to show the connection string in a pop-up window. Enter the appropriate value for the Connection String property; for example:

   Data Source='C:\MyApp\MyDatabase.sdf'
   

   Note

   The SQL CE database is created by the Enterprise Library SQLDatabase provider, which does not enforce password protection or encryption on the database during creation. To ensure security of yoru data, you should consider setting the connection string to protect the file and create it with the correct permissions, and encrypt the file. For more information see SqlCEConnection ConnectionString Property on MSDN.

7. The following example enables encryption on the database:

   "Data Source=MyData.sdf;Encrypt Database=True;Password=myPassword;File Mode=shared read;Persist Security Info=False;"
   

8. Set the Database Provider property of your SQL Server CE connection string item to the name you entered for the custom database provider in step 2. The following screenshot shows details of the configuration for a SQL Server CE database in the configuration tools.

   

9. For information on using SQL Server CE, see the section "Using SQL Server CE" in the topic Creating a Database Object.

The next procedure describes how to add Oracle packages. An Oracle package serves as a way to group stored procedures into common groups, typically based on their functionality. When an application calls an Oracle stored procedure located in a package, the code must prefix the stored procedure name with the package name. For example, to call a procedure named GetEmployeeName that is in a package named Employee_pkg, you would call Employee_pkg.GetEmployeeName.

Incorporating this code into the application makes it less portable because this syntax is specific to Oracle. Instead, the Data Access Application Block can prefix the stored procedure with the package name. This means your client code does not need to specify the package name to call a stored procedure. To do this, the application block uses information in the configuration file. The OraclePackage node stores a name/prefix pair. The name is the name of the package. The prefix is a string that is associated with the package. All stored procedures that start with that prefix are assumed to be in the associated package.

When the application calls a stored procedure, the Data Access Application Block checks to see if it begins with any of the prefixes in the configuration file. If it does, the application block prefixes the stored procedure with the associated package name. (The first match it finds is the one the application block uses.) If you specify an asterisk ("*") as the prefix, the associated package is used for all stored procedure calls.

To configure an Oracle package

1. Click the plus sign icon in the Oracle Connections pane, and click Add Oracle Connection.

2. An Oracle Packages for Oracle Connection section is added to the Oracle Connections pane and its properties are displayed.

3. (Optional) Set the Name property by typing a new name.

4. Click the plus sign icon in the Packages row to add a new package.

   

5. Change the Name property by entering the name of the Oracle package. The default name is Package.

6. Enter a value for the Prefix property.

The next procedure describes how to add custom provider mappings by associating a provider with the fully qualified name of a database.

To configure a custom provider

1. Click the plus sign icon in the Custom Databases pane, and then click on Add Custom Database Provider.

2. (Optional) Set the Name property by typing a new name or select it from the drop-down list. The default provider name is Custom Database Provider.

3. In the Type property text box, click the ellipsis button (…) and use the type selector to select the fully qualified name of the Enterprise Library database type. If the provider is registered in the global assembly cache (GAC), click the Add from GAC button to locate it. If you are using the Visual Studio integrated configuration editor and you do not see the provider type you require in the list, you must add a reference to the assembly containing the provider to your project.

   

Usage Notes

There are three points to remember about configuration files:

• When you use the configuration tools to open an existing application configuration file that includes the Data Access Application Block, they display connection strings stored in the Machine.config file. Although the graphical user interfaces allow you to edit these connection strings, the configuration tools cannot modify the Machine.config file and none of the changes take effect. The configuration tools only save the changes you make to connection strings stored in your application file.

• The configuration files are not encrypted by default. A configuration file may contain sensitive information about connection strings, user IDs, passwords, database servers, and catalogs. You should protect this information against unauthorized read/write operations by using encryption techniques. For information about how to encrypt configuration files, see Configuring Enterprise Library.

• When the configuration tools save the connection string, they generate a semicolon-delimited string that stores the connection information as a series of name/value pairs in the <connectionStrings> section of the application configuration file. For example, if you used the configuration tools to create a connection string with all the default values, they would generate the following connection string.

  Database=Database;Server=(local)\SQLEXPRESS;Integrated Security=SSPI;