Generating the schemas and binding files for the operations
you intend to use in your project is one of the major steps enabling
consumption of the ASDK-based adapters in BizTalk applications. The tool
of choice for this task is the Consume Adapter Service wizard, a
design-time tool offered by ASDK. To call the wizard we have to
right-click Visual Studio project, select Add..., and then Add Generated Items…. In the Add Generated Items windows we need to select Consume Adapter Service and click Add. Once the Consume Adapter Service
window shows up, the very first step is to specify the appropriate
binding. The ASDK SQL adapter is represented by the sqlBinding—this is
what you have to choose in the Select a binding drop down list before performing other operations in the Consume Adapter Service wizard.
Then, after selecting the binding, we click the Configure button to open the Configure Adapter window to specify the database connectivity and binding properties.
Providing credentials
The Security
tab of the Configure Adapter window allows us to specify credentials to
access SQL Server. The ASDK SQL adapter supports only two modes—Windows
authentication and SQL Server authentication, but the Client credential
type drop down list offers four:
These options are common and
intended to cover requirements of different ASDK-based adapters, so let
us review the options with respect to the ASDK SQL Adapter:
None This option is the same as Windows.
Windows The adapter will use Windows authentication to connect to SQL Server.
Username The adapter will connect to SQL Server using credentials supplied in the User name and Password fields.
Certificate
Even if the Certificate option is chosen, the adapter will ignore it
and use Windows authentication. Users mapped to certificates are not
supported, so this option does not apply to the ASDK SQL adapter.
Keep in mind that only the
SQL Server objects that the user has permissions to will be shown on the
Consume Adapter Service wizard. So please ensure when selecting Windows
authentication mode, that the account Visual Studio is running under
has the appropriate access to the database objects required for your
project. The same applies to the user name specified for the SQL Server
authentication.
Connecting to SQL Server URI properties
The URI Properties tab is
where we specify the values for the properties necessary to build a
connection string to the SQL Server.
For example, to connect to a
database called AdventureWorksCh2 on the default instance of SQL Server
called BT2010DEV-PC, running on the default port 1433 with no failover
server we can specify the following:
This will map to the following connection URI:
mssql://BT2010DEV-PC//AdventureWorksCh2?
Instead of using the URI
Properties tab, you can also type connection string into the URI textbox
of the main Consume Adapter Service wizard window if this is more
convenient for you.
In the general form the URI connection string to the SQL Server looks as follows:
mssql://[Server_Name[:Portno]]/[SQL_SERVER_Instance_Name]/[Database_Name]?FailoverPartner=[Partner_Server_Name]&InboundId=[Inbound_ID]
where:
Server name
(Server_Name), port ([:Portno]), and instance name
([SQL_SERVER_Instance_Name]) determine the SQL Server instance to
connect to and Database name ([Database_Name]) specifies the database.
If you connect to the default instance of the SQL Server, you can leave
the SQL_SERVER_Instance_Name part blank.
The
partner server name ([Partner_Server_Name]) is used if the SQL Server
instance also has a failover partner to be used by the adapter if the
primary server does not respond.
The
last part of the Connection URI to note is InboundID ([Inbound_ID]). It
must be set when using TypedPolling operations to generate unique
schemas and uniquely identify the corresponding receive location. If we
generate schemas with an InboundID, then it is imperative that we also
provide this same InboundID in the corresponding Receive Location
configuration. If we do not, we will receive a runtime error indicating
that BizTalk could not find the document specification by message type.
Internally,
the LOB SQL adapter uses a combination of the URI and binding
properties to build a final ADO.NET connection string as explained in
the following blog post:
http://connectedthoughts.wordpress.com/2011/01/18/how-the-wcf-sql-adapter-builds-the-ado-net-connection-string/
Binding Properties
The Binding Properties tab is where we can configure runtime behaviour of the adapter:
The properties presented on
this tab are reflected in the binding file generated by the Consume
Adapter Service wizard. For the outbound operations we can usually
accept the default values since the defaults are adequate for the
majority of the situations. In the situations where the default values
are not satisfactory, we can always make adjustments on the physical
ports using the BizTalk Admin Console.
For the Inbound operations
the picture is a bit more complicated. Due to the nature of the Inbound
operations, the Consume Adapter Service Wizard offers no default values
and we have to provide configuration settings explicitly. We can do it
either at the design time and then import the binding file to create
configured receive locations, or we can provide the settings later using
BizTalk Admin Console. The only exception is the PolingStatement property used to configure the TypedPolling
inbound operation. This property directly impacts the schema that
Consume Adapter Service wizard generates for the operation and therefore
must be set at the development time. When we deploy the application, we
must ensure that the PollingStatement property set on the receive
location is the same as we used at the development time. If this sounds
confusing, please read on. We provide detailed coverage of the
TypedPolling operation and applicable configuration properties in the
examples sections.
Generating schemas
Once we are done with
the connectivity and binding settings, we click OK to close the
Configure Adapter window and return to the main Consume Adapter Service
window. At this point the Configure a URI text control contains a connection uri string built off the properties we specified on the URI tab of the Configure Adapter window.
Now we click the Connect button; if connection is established successfully, the Consume Adapter Service wizard grants us access to the operations exposed by the adapter:
First, we need to select contract type in the Select contract type control. Then, in the Available categories and operations panel we can select desired operations and click Add to add the operations to the Added categories and operations list. Once we collected all desired operations, we can click OK
to close the wizard. This action will return us to Visual Studio where
we will see one or more xsd schemas and a binding file added to the
project. If we need to generate the schemas for another contract type,
we will have to make another trip to the Consume Adapter Service Wizard
and repeat the procedure.
ASDK SQL Adapter in the BizTalk Administration Console
After
we have deployed an application, and using the BizTalk Admin Console
imported the binding files generated for us by the Consume Adapter
Service Wizard, we may need to adjust adapter configuration for a
particular environment.
