Configuring the Query Application Block

The Query Application Block uses the Enterprise Library Configuration Console to manage its configurable settings.

Adding the Query Application Block

Once you have opened your configuration file, or created a new one, in the Enterprise Library Configuration Console, the Query Application Block appears as one of the available block types in the context menu for the Application Configuration node under the New menu option:

Adding the Query Application Block

Having selected the Query Application Block the console should appear like this:

The Console with the Query Application Block added

Notice that the Query Application Block supports the partial trust permissions interface and configuration settings encryption. Also note that three collections appear in the Query Application Block configuration node tree which hold configuration for the three primary objects within the QAB: Commands, Parameters and Queries.

Adding a Query

A query is the main object within the QAB and combines a command and an optional set of parameters to query a data source. There are five different types of Query representing the five supported data source types. A common and mandatory property of all Queries is the Name which acts as the query "instance" name used in your code to select the query to execute.

Adding a Query

Adding a Data Query

A data query targets a relational database and integrates with the Data Access Application Block. Once you select a Data Query you can configure all the properties for a SQL query to a relational database.

Adding a Data Query

Note that if the DAAB has not been configured it will be automatically added when you add a Data Query.
  • The DataCommandName is an optional property where you can select a custom command. This is discussed fully on the Custom Commands page.
  • The Command mandatory property is where you will enter the command to call from the relational database. If this is a stored procedure then it will be the stored procedure name. If this is a text command then it will be a SQL command string. For lengthy command strings you can click on the drop down arrow to expand the property into a larger text box. The third type of command is a TableDirect command where you enter a table name.
  • The CommandType mandatory property is where you can specify the type of command sent to the relational database from a choice of StoredProcedure, Text or TableDirect.
  • The DatabaseInstance mandatory property is the name of a configured connection string from the DAAB. Simply drop down the combo box and select the one you wish to use.
  • The ParameterSet optional property is the name of a configured ParameterSet from the Parameters collection and supplies a set of parameters to a query. Simply drop down the combo box and select the set of parameters that you wish to use. Of course, if your query does not take parameters then this must be left as (none).
The following shows a Data Query with all the properties added and represents a stored procedure call to "ReadEmployee" from the "MyDatabase" database which takes parameters from the "EmployeeSet" ParameterSet:

[image:Data Query with Properties|Data Query with Properties.gif]

Adding a WCF Service Query

A WCF service query targets a Windows Communication Framework Service client. Once you select a WCF Service Query you can configure all the properties for a call to a service operation.

Adding a WCF Service Query
  • The ServiceCommandName is an optional property where you can select a custom command. This is discussed fully on the Custom Commands page.
  • The Address optional property is the Url to the service, if different from the default configured address set when you added the Service Reference to your application.
  • The Endpoint mandatory property is where you can specify the "endpoint" name of a WCF service. Endpoints are a combination of an Address, Binding and a Contract see WCF documentation for more information on endpoints.
  • The ParameterSet optional property is the name of a configured ParameterSet from the Parameters collection and supplies a set of parameters to a query. Simply drop down the combo box and select the set of parameters that you wish to use. Of course, if your query does not take parameters then this must be left as (none).
  • The TypeMethodName mandatory property is the name of the service method (WCF Service Operation). A TypeMethodName is the combination of a Type and a Method name. It is not possible to type in this name, instead click on the ellipsis button and the MethodSelector editor appears. Please note that you are selecting a client to a service not the service itself, in other words you need to be loading an assembly that has added a service reference to the service, expanding the subsequently autogenerated {service name}Client class and finally selecting one of its methods. You may even need to add the service reference to an assembly in your application to force this.

Method Selector Editor for WCF Service

This editor shows all currently loaded assemblies that reference WCF services. Only assemblies that contain types that implement the ICommunicationObject interface will be shown. If your service is not shown then you can load it by clicking on the Load Assembly from File... button. Note1 that you have to expand the tree nodes to get at the methods, then you can select the method to be called by this query. Note2 You must target an assembly that references the service NOT the service itself. Besides you won't always have access to the service assembly if it is not yours.

The following shows a WCF Service Query with all the properties added and represents a call to "ReadBasic2" found in the "WcfDataServiceClient" client type from the "MyService.svc" service using the "MyEndpoint" endpoint and which takes parameters from the "EmployeeSet" ParameterSet:

WCF Service Query with Properties

Adding an XML File Query

An XML File query targets an XML file and is ideal for configuration data or data feeds from external sources etc. Once you select an XML File Query you can configure all the properties for a call to a LINQ to XML query.

Adding an XML File Query
  • The FileCommandName is an optional property where you can select a custom command. This is discussed fully on the Custom Commands page.
  • The DataFile mandatory property is the path to the xml file itself. You can type in this path by hand or alternatively click on the elipsis button to load the open file dialog.

Open File Dialog for XML Files
  • The Element mandatory property is the XML Element within the file that holds the data to be retrieved or updated.
  • The ParameterSet optional property is the name of a configured ParameterSet from the Parameters collection and supplies a set of parameters to a query. Simply drop down the combo box and select the set of parameters that you wish to use. Of course, if your query does not take parameters then this must be left as (none).
The following shows an XML File Query with all the properties added and represents a call to the "Basic1" element within the "XmlData.xml" data file and which takes parameters from the "EmployeeSet" ParameterSet:

XML File Query with Properties

Adding a Custom Query

A Custom Query deals with queries from a data source that is not currently supported. This is where you can extend the Query Application Block with your own query providers and configure them within your applications. If you selected a Custom Query you are asked for two properties. The Attributes collection and provider TypeName are well documented in the Enterprise Library help documentation but essentially the typename is the type name of your custom provider and the attributes collection is a set of parameters that get passed to your provider.

Adding a Custom Query

Adding Parameters

Some queries need a set of parameters to be sent with the command to the data store. For this the Query Application Block provides configuration for ParameterSets and Parameters. ParameterSets are collections of Parameters. ParameterSets are used in all instances even when only one Parameter is required. When you configure a query that takes parameters you specify just the ParameterSet. Select New|ParameterSet from the Parameter Collection context menu:

Adding a Parameter Set

A ParameterSet only requires a name:

Parameter Set with Properties

Once the ParameterSet is in place then you can add Parameters to this set. By selecting New from the context menu you will see that there are 5 parameter types you can choose from:

Adding a Parameter

Adding a Data Parameter

This is the typical parameter that you would use for most data queries and simply needs a name, data type and direction:

Adding a Data Parameter

Adding a DataSet Parameter

Although the Data Parameter suffices for most queries to a relational database. A DataSet provides additional features when it comes to managing the changing states of data and adds a source column and data row version in addition to the standard Data Parameter properties:

Adding a DataSet Parameter

Adding a Name Value Parameter

This is a generic parameter type that you can use for most file or service queries and simply needs a name:

Adding a Name Value Parameter

Adding an XML Parameter

This is the parameter type that you would use for complex XML file queries that include Namespaces and needs a name and an optional namespace. XML file queries that do not support namespaces can work with either Name Value Parameters or XML Parameters:

Adding an XML Parameter

Adding a Custom Parameter

A Custom Parameter deals with parameter types that are not currently supported. This is where you can extend the Query Application Block with your own parameter providers and configure them within your applications. If you selected a Custom Parameter you are asked for two properties. The Attributes collection and provider TypeName are well documented in the Enterprise Library help documentation but essentially the typename is the type name of your custom provider and the attributes collection is a set of parameters that get passed to your provider.

Adding a Custom Parameter

Copying a ParameterSet

Creating lengthy parameter sets can be quite tedious, especially if you are creating one very similar to one you already have. This is where the Copy function from the ParameterSet context menu helps allowing you to create an exact copy of a ParameterSet along with its set of parameters:

Copying a ParameterSet

The Copied ParameterSet

Note how the name is given a sequence number suffix to keep it unique. You will probably want to change this straight away?

Adding a Command

Custom Commands are there for those situations when the default calling interface is just not sophisticated enough. Typical examples include reading and writing BLOB data types using buffered calls, XML Queries to data buried several Elements deep in the file and special security requirements for service queries etc. In these situations you create small assemblies with custom class(es) inheriting from predefined base classes and register these assemblies with the QAB by adding them as commands. There are three command types that can be added see Custom Commands for more details on how to create custom commands:

Adding a Command

Adding a Data Command

A Data Command is a custom command to a relational database:

Adding a Data Command

The Data Command simply needs a name and a command type. The command type cannot be entered directly instead click on the elipsis button to open the TypeSelector editor:

The Type Selector Editor

Adding a File Command

A File Command is a custom command to a file-based command like an XML command:

Adding a File Command

Like the Data Command a File Command simply needs a name and a command type.

Adding a Service Command

A Service Command is a custom command to a service-based command like a WCF service:

Adding a Service Command

Like the Data Command a Service Command simply needs a name and a command type.

Linking a Command to a Query

When you have registered your command assembly with QAB you can then link it to a query by adding the query and then dropping down the command name combo box and selecting your custom command from the list:

Linking a Command to a Query

Saving and Validating the Query Application Block

When you save your configuration a number of validation checks are performed. All mandatory properties must have a value and all validation messages appear in the grid at the bottom of the Console window

Saving and Validating the Query Application Block

Last edited Jun 15, 2010 at 5:05 PM by ewdev, version 32

Comments

No comments yet.