Using the Microsoft Enterprise Libraries
Using the Data Access Application Blocks in Applications
Using the Microsoft Enterprise Libraries can simplify application development by wrapping common tasks, such as data access, into portable code that makes it easier to move your application from one DBMS to another.
The PSQL data providers support the Data Access Application Blocks (DAAB) and Logging Application Blocks (LAB). The classes in the DAABs provide access to the most frequently used features of ADO.NET. Applications can use the DAABs for tasks such as passing data through application layers and returning changed data back to the database. Using DAABs eliminates the need to keep writing the same data access tasks for each new or revised application, so you can spend your time more productively
Applications that use the standard Logging Application Block and design patterns can quickly display the SQL that is generated as part of the ADO.NET Entity Framework data provider.
To use features of the Enterprise Library with your data provider, download Microsoft Enterprise Library 6.0 from
http://msdn.microsoft.com/en-us/library/dn169621.aspx. You can also download the Enterprise Library documentation, which contains detailed information about using the application blocks.
Data Access Application Blocks
The Data Access Application Block (DAAB) is designed to allow developers to replace ADO.NET boiler-plate code with standardized code for everyday database tasks. The overloaded methods in the Database class can:
•Return Scalar values or XmlReaders
•Determine which parameters it needs and create them
•Involve commands in a transaction
If your application needs to address specific DBMS functionality, you can use the PSQL ADO.NET Data Provider.
When Should You Use the DAAB?
The DAAB includes a small number of methods that simplify the most common methods of accessing a database. Each method encapsulates the logic required to retrieve the data and manage the connection to the database. You should consider using the application block if your application uses standard data access techniques.
The DAAB is used with ADO.NET, increasing efficiency and productivity when creating applications for ADO.NET. The abstract Database class provides a number of methods, such as ExecuteNonQuery, ExecuteReader, and ExecuteScalar, that are the same as the methods used by the DbCommand class, or, if you are using database-specific code, a data provider-specific class such as PsqlCommand.
Although using the default DAAB during development is convenient, the resulting application lacks portability. When you use the provider-specific PSQL DAAB implementation, the application includes the PSQL ADO.NET Data Provider’s SQL leveling capabilities. You have more flexibility, whether your application needs to access multiple databases, or whether you anticipate a change in your target data source.
Should You Use Generic or Database-specific Classes?
The application block supplements the code in ADO.NET that allows you to use the same code with different database types. You have two choices when using the DAAB with the ADO.NET data provider:
•The GenericDatabase class
•The provider-specific PSQL DAAB implementation
The GenericDatabase class option is less suited to applications that need specific control of database behaviors. For portability, the provider-specific solution is the optimal approach.
If your application needs to retrieve data in specialized way, or if your code needs customization to take advantage of features specific to PSQL, using the PSQL ADO.NET Data Provider might suit your needs better.
Configuring the DAAB
Before you can configure the DAAB for use with your application, you must set up the environment:
2 Open the PSQL DAAB project for your data provider, located in install_dir\Enterprise Library\Src\CS\Pervasive.
3 Then, compile the project and note the output directory.
Configuring the Data Access Application Block consists of two procedures:
Adding a New DAAB Entry
Now, use the Enterprise Library Configuration Tool to add a new DAAB entry:
1 Right-click Enterprise Library Configuration, and select New Application.
2 Right-click Application Configuration, then select New > Data Access Application Block. The Enterprise Library Configuration window appears.
3 In the Name field, type a name for the DAAB connection string.
4 In the ConnectionString field, enter a connection string.
5 Right-click the field, and select the data provider. For example, select Pervasive.Data.SqlClient.
6 Right-click Custom Provider Mappings and select New > Provider Mappings.
7 In the Name field, select the data provider name you specified in Step
5.
8 Select the TypeName field, and then choose the Browse button to navigate to the Debug output directory of the PSQL DAAB that you want to build. Then select the TypeName. For example, the PSQL TypeName is Pervasive.EnterpriseLibrary.Data.Pervasive.dll.
9 Leave the Enterprise Library Configuration window open for now and do not save this configuration until you complete the following section.
Adding the Data Access Application Block to Your Application
To add the DAAB to a new or existing application, perform these steps:
1 Add two additional References to your Visual Studio solution:
•Enterprise Library Shared Library
•Enterprise Library Data Access Application Block
2 Add the following directive to your C# source code:
using Microsoft.Practices.EnterpriseLibrary.Data;
using System.Data;
3 Rebuild the solution to ensure that the new dependencies are functional.
4 Determine the output Debug or Release path location of your current solution, and switch back to the Enterprise Library Configuration window (see
Adding a New DAAB Entry).
5 Right-click the connection string under the Application Configuration node and select Save Application.
6 Navigate to the Debug or Release output directories of your current solution, and locate the .exe file of the current solution.
7 Click the file name once, and add .config to the name, for example, MyPSQL.config.
8 Ensure that Save as type 'All Files' is selected, and select Save.
9 Using File Explorer, copy the Pervasive.EnterpriseLibrary.Data.Pervasive.dll from the PSQL DAAB directory.
10 Place the copy of this DLL into either the Debug or Release output directory of your current solution.
Using the DAAB in Application Code
Now that you have configured the DAAB, you can build applications on top of this DAAB.
In the example below, we use the DAAB MyPSQL and the DatabaseFactory to generate an instance of a Database object backed by a PSQL data source.
using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.Practices.EnterpriseLibrary.Data;
using System.Data;
namespace DAAB_Test_App_1
{
class Program
{
static void Main(string[] args)
{
Database database = DatabaseFactory.CreateDatabase("MyPSQL");
DataSet ds = database.ExecuteDataSet(CommandType.TableDirect, "SQLCOMMANDTEST_NC_2003SERVER_1");
}
}
}
The Microsoft Enterprise Library DAAB coding patterns are now at your disposal.
Logging Application Blocks
Using the Enterprise Library Logging Application Block (LAB) makes it easier to implement common logging functions. The ADO.NET Entity Framework data provider uses the standard Logging Application Block and design patterns, and offer LAB customizations for additional functionality.
When Should You Use the LAB?
If your applications have a requirement to log information to a database, a message queue, the Windows Event Log, or Windows Management Instrumentation (WMI), the LAB provides this functionality. In particular, the LAB is useful if you need to filter logging messages based on category or priority, if you need to format the messages, or if you need to change the destination of the message without changing the application code.
Configuring the LAB
A logging capability can be added to an application by adding an entry to an applications configuration file (either app.config or web.config) using the Enterprise Library configuration tool. This tool contains specific instructions in order to enable the Logging Application Block .config file. The tool also contains the necessary AppSetting to enable the LAB.
To enable the Logging Application Block output, set the environment property Psql_Enable_Logging_Application_Block_Trace to true. Alternatively, in the app.config file, set the AppSetting property Psql.EnableLoggingApplicationBlock to true.
A following C# code snippet shows the loggingConfiguration property of the app.config file.
<loggingConfiguration name="Logging Application Block" tracingEnabled="true"
defaultCategory="General" logWarningsWhenNoCategoriesMatch="true">
Setting either of these properties to false disables the logging block.
If enabled, the data provider must establish a new LogEntry entry instance for each SQL statement generated by the ADO.NET Entity Framework canonical query tree.
The SQL logged to the Logging Block must be the SQL that is ultimately transmitted to over the wire.
►To configure the Logging Application Block
1 Select Start > Programs > Microsoft patterns and practices > Enterprise Library 6.0 > Enterprise Library Configuration. The Enterprise Library Configuration window appears.
2 Select File > New Application.
3 Right-click the Application Configuration node and select New > Logging Application Block.
4 Right-click Category Sources, and select New > Category.
5 In the Name pane, select Name. Type the name of the new category, and then press ENTER. The following example creates the category name PSQL Error.
6 From the SourceLevels drop-down list, set the logging level for the new category. By default, all logging levels are enabled.
7 Right-click the new category and select New > TraceListener Reference. A Formatted EventLog TraceListener node is added. From the ReferencedTraceListener drop-down list, select Formatted EventLog TraceListener.
8 Repeat Step 4 through Step 7 to create the following categories:
•PSQL Information: Information not related to errors
•PSQL Command: Enables SQL, Parameter, and DbCommandTree logging
9 Select File > Save Application. In the Save As dialog, enter a name for your configuration file. By default, the file is saved to C:\Program Files\Microsoft Enterprise Library\Bin\filename.exe.config, where filename is the name that you entered for Save As.
Adding a New Logging Application Block Entry
Now, use the Enterprise Library Configuration Tool to add a new Logging Application Block entry:
1 Start Enterprise Library Configuration, and select File > New Application.
2 Right-click Application Configuration, then select New > Logging Application Block. The Configuration section appears in the right pane.
3 In the TracingEnabled field, enter True.
4 Save the Logging application block.
Using the LAB in Application Code
The LAB that you configured must be added to the app.config or web.config file for your application.
The following settings can be used to enable and configure the data provider's interaction with the LAB.
•EnableLoggingApplicationBlock: Enables the Logging Application Block.
•LABAssemblyName: Specifies the assembly name to which the Logging Application Block applies.
Note: If you use any version of the LAB other than the Microsoft Enterprise Library 4.1 binary release, you must set the LABAssemblyName. For example, if you use an older or newer version of the LAB, or a version that you have customized, you must specify a value for LABAssemblyName.
•LABLoggerTypeName: Specifies the type name for the Logging Application Block.
•LABLogEntryTypeName: Specifies the type name for the LogEntry object.
The following code fragment provides an example of a Logging Application Block that could be added to a PSQL data access application.
<loggingConfiguration name="Logging Application Block"
tracingEnabled="true"
defaultCategory="" logWarningsWhenNoCategoriesMatch="true">
<listeners>
<add fileName="rolling.log"
footer="----------------------------------------"
header="----------------------------------------"
rollFileExistsBehavior="Overwrite"
rollInterval="None" rollSizeKB="0"
timeStampPattern="yyyy-MM-dd"
listenerDataType="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.RollingFlatFileTraceListenerData, Microsoft.Practices.EnterpriseLibrary.Logging, Version=6.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
traceOutputOptions="None" filter="All" type="Microsoft.Practices.EnterpriseLibrary.Logging.TraceListeners.RollingFlatFileTraceListener, Microsoft.Practices.EnterpriseLibrary.Logging, Version=6.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
name="Rolling Flat File Trace Listener" />
</listeners>
<formatters>
<add template="Message: {message}
Category: {category}
Priority: {priority}
EventId: {eventid}
Severity: {severity}
Title:{title}

"
type="Microsoft.Practices.EnterpriseLibrary.Logging.Formatters.TextFormatter, Microsoft.Practices.EnterpriseLibrary.Logging, Version=6.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
name="Text Formatter" />
</formatters>
<categorySources>
<add switchValue="All" name="Psql">
<listeners>
<add name="Rolling Flat File Trace Listener" />
</listeners>
</add>
</categorySources>
<specialSources>
<allEvents switchValue="All" name="All Events" />
<notProcessed switchValue="All" name="Unprocessed Category" />
<errors switchValue="All" name="Logging Errors & Warnings">
<listeners>
<add name="Rolling Flat File Trace Listener" />
</listeners>
</errors>
</specialSources>
</loggingConfiguration>
Additional Resources
The following sources provide additional information about using Application Blocks:
•The Microsoft patterns & practices Developer Center includes a section on
Application Blocks.