SubmitDirect (BizTalk Server Sample)

Article
02/02/2021

The SubmitDirect sample demonstrates how to programmatically submit one-way and request/response messages to Microsoft BizTalk Server from .NET-based applications. The sample demonstrates the use of BizTalk Server APIs for adapters. It also provides a receive adapter, named Submit, that can be used to submit messages to BizTalk Server.

Prerequisites

Before running this sample, ensure you are logged on as a user who belongs to BizTalk Isolated Host Users group.

What This Sample Does

This sample shows how to perform various tasks related to BizTalk adapters. Specifically, it shows how to:

Work with isolated adapters that run outside of the BizTalk Server process. The Submit adapter is an isolated adapter because it is created by a process external to the BizTalk Server process (you start it as a .NET application).
Submit batches of messages to BizTalk Server. The Submit adapter uses batch message submittal functionality to submit several messages at once.
Submit messages synchronously using a request/response paradigm, as well as asynchronously using a one-way paradigm.
Register an adapter with BizTalk Server. This sample shows how to register an adapter and provides a registration executable that automates the registration of an adapter.

This sample is actually two samples in one, as follows:
Submission of a batch of one-way messages. The console application SubmitMessages.exe takes the strings from its command line and submits each one as a separate message to BizTalk Server. Each of these submitted messages is picked up at the receive location by BizTalk Server, sent through pass-through receive and send pipelines, and then written to a text file.
Submission of request/response message. The console application SubmitRequest.exe takes the .xml file specified on its command line and submits it to BizTalk Server. The schema of this .xml file defines elements that contain two integer fields. BizTalk Server picks up the .xml file and processes it with an orchestration (with one request/response port). It uses a map to produce an XML response message that returns an integer that is the product of the two integers in the request. When the console application receives the response, it displays the result.

Where to Find This Sample

<Samples Path>\AdaptersDevelopment\SubmitDirect\

The following table lists the files in this sample and describes their purpose.

File(s)	Description
Cleanup.bat	Undeploys assemblies and removes them from the global assembly cache (GAC); removes send and receive ports; removes Microsoft Internet Information Services (IIS) virtual directories as needed.
Setup.bat	Builds and initializes this sample.
SubmitDirect.sln	Solution file that includes the BizTalk project in the ProcessRequest folder and the Microsoft Visual C# projects in the other folders.
SubmitMessagesBinding.xml, SubmitRequestBinding.xml	Used for automated setup such as port binding.
In the \ProcessRequest folder: DocIn.xsd, DocOut.xsd, Multiplier.odx, Multiply.btm, ProcessRequest.btproj	Provides a BizTalk project that performs the multiplication of integers in the request/response scenario.
In the \SubmitMessages folder: AssemblyInfo.cs, SubmitMessages.cs, SubmitMessages.csproj	Provides a Visual C# project for the console application that passes its command line string parameters as a batch of separate messages.
In the \SubmitRequest folder: AssemblyInfo.cs, DocInstance.xml, SubmitRequest.cs, SubmitRequest.csproj	Provides a C# project for the console application that passes an .xml file (DocInstance.xml) containing two integers to be multiplied.
In the \TransportProxyUtils folder: AssemblyInfo.cs, MessageHelper.cs, MessagingAPIInterface.cs, MessagingAPIs.cs, ResponseCallBack.cs, TpBatchAsyncCallback.cs, TpBatchAsyncResult.cs, TpBatchStatus.cs, TransportProxyUtils.csproj	Provides a C# project for the run-time portion of the Submit adapter that implements methods for synchronous and asynchronous message submission, and for batch and single request message submission.
In the \TransportProxyUtilsReg folder: AssemblyInfo.cs, RegisterAdapter.cs, TransportProxyUtilsReg.csproj	Provides a Visual C# project that demonstrates code that you can use to register adapters with BizTalk Server.
In the \TransportProxyUtilsUI folder: AssemblyInfo.cs, TransportProxyUtilsMgmt.cs, TransportProxyUtilsUI.csproj	Provides a Visual C# project for the user interface portion of the Submit adapter.

Building and Initializing the Sample

To build and initialize the SubmitDirect sample

In a command window, navigate to the following folder:

<Samples Path>\AdaptersDevelopment\SubmitDirect
Run the file Setup.bat, which performs the following actions:
- Creates the following output folder for the batch submission portion of this sample.
  
  <Samples Path>\AdaptersDevelopment\SubmitDirect\Out
- Compiles the various Visual Studio projects for this sample.
- Registers the Submit adapter with BizTalk Server.
- Creates and binds the BizTalk Server receive locations, and the send and receive ports.
  
  Note
  
  This sample displays the following warnings when creating and binding the ports:
  
  Warning: Receive handler not specified for receive location "SubmitDirectRL"; updating with first receive handler with matching transport type.
  
  Warning: Host not specified for orchestration "Microsoft.Samples.BizTalk.ProcessRequest.Multiplier"; updating with first available host.
  
  You can safely ignore these warnings. (To accommodate for possible naming differences in user installations, the host name and receive handler have been omitted from the binding file.)
- Enables the receive locations, and starts the send ports and orchestration.
  
  Note
  
  You should confirm that BizTalk Server did not report any errors during the build and initialization process before attempting to run this sample.
  
  Note
  
  If you choose to open and build the projects in this sample without running the file Setup.bat, you must first create a strong name key pair using the .NET Framework Strong Name Utility (sn.exe). Use this key pair to sign the resulting assemblies.
  
  Note
  
  To undo changes made by Setup.bat, run Cleanup.bat. You must run Cleanup.bat before running Setup.bat a second time.

Running the Sample

Because this sample uses File adapter, the BizTalk host (BizTalkServerApplication) must be running. Use the following procedures to run the SubmitDirect sample.

To run the batch submission portion of the SubmitDirect sample

In a command window, navigate to the following folder:

<Samples Path>\AdaptersDevelopment\SubmitDirect\SubmitMessages\bin\Debug
Run the file SubmitMessages.exe, passing multiple strings on the command line.

Example: SubmitMessages msg1 msg2 msg3
Observe the multiple text files created in the output folder Out. These files contain the strings passed on the command line, one per file.

To run the request/response portion of the SubmitDirect sample

In a command window, navigate to the following folder:

<Samples Path>\AdaptersDevelopment\SubmitDirect\SubmitRequest\bin\Debug
Run the file SubmitRequest.exe, passing an appropriate .xml file name on the command line.

Example: SubmitRequest ..\..\DocInstance.xml
Observe the response XML message, containing the result of the multiplication operation, displayed to the console.

Comments

You can use the Submit adapter in other applications. You can use it from any .NET-based code to submit messages to your BizTalk Server programmatically. To use this adapter with your code, use the following procedure.

To use the sample adapter with your code

Register the Submit adapter with your BizTalk Server. If you have run the file Setup.bat provided with this sample, the adapter should be registered and ready to use. Otherwise, you can register it by building the projects TransportProxyUtils.csproj, TransportProxyUtilsUI.csproj, and TransportProxyUtilsReg.csproj, and then running the executable produced by the latter project, RegisterAdapter.exe.

Important

If you install BizTalk on a 64 bit machine, change all instances of the HKEY_CLASSES_ROOT\CLSID\ registry entry to HKEY_CLASSES_ROOT\Wow6432Node\CLSID\ in the RegisterAdapter.cs file.
Create a receive port with a receive location that uses the Submit adapter. Specify the address of the receive location. The address can be any string that is unique within the receive locations that use this adapter.
Reference the assembly Microsoft.BizTalk.SDKSamples.AdaptersDevelopment.TransportProxyUtils.dll in your Visual Studio project.

Submit messages to your BizTalk Server by using one or more of the following methods provided by this assembly.

Method(s)	Description
SubmitMessage() BeginSubmitMessage() EndSubmitMessage()	Synchronous and asynchronous methods to submit a one-way message to BizTalk Server. The address of the receive location where the message is submitted must be set on the message context. A Boolean value indicating the status of submission (success/failure) is returned.
SubmitMessages() BeginSubmitMessages() EndSubmitMessages()	Synchronous and asynchronous methods to submit an array of one-way messages to BizTalk Server. The addresses of the receive locations where the messages are submitted should be set on the context of the messages. A Boolean value indicating the status of submission (success/failure) is returned.
SubmitSyncMessage() BeginSubmitSyncMessage() EndSubmitSyncMessage()	Synchronous and asynchronous methods to submit a request message to BizTalk Server. The address of the receive location where the message is submitted should be set on the message context. The response message is returned.
CreateMessageFromString()	Creates a BizTalk Server message object from a string and sets the receive location address property on the message context. Returns a BizTalk message object.
CreateMessageFromStream()	Creates a BizTalk Server message object from a stream and sets the receive location address property on the message context. Returns a BizTalk Server message object.

For details about the parameter and return types for these methods, see the file MessagingAPIInterface.cs in the TransportProxyUtils folder.