When using multiple BizTalk Hosts the process relating to each host can be identified using the following command line instruction:
tasklist /SVC /FI "IMAGENAME eq btsntsvc.exe"
This will display a list of BizTalk processes with the name of the Host and the PID. Note the PID for the host you are interested in. Match the correct PID with the process listed in Task Manager or the Visual Studio Attach To Process dialog.
A common schema related error that may occur when building BizTalk projects that include schemas is:
BEC2017: Node "<Schema>" - This schema file has a TypeName that collides with the RootNode TypeName of one of its root nodes. Make sure that they are different.
The reason for this is quite simple - when the project is compiled, a .NET class will be generated for each top level element in your schema. If you have two schemas which share the same top level element name a clash will occur.
This is quite a common scenario and it is not always practical (or even possible) to change the element names. The solution is to change the generated type name for the schema. To do so, select the schema in the Solution Explorer and press F4 to display the Properties window. Then change the Type Name property so that it is not the same as any of the top level elements.
On a couple of occasions recently I have hit upon the need to use default content in some elements of a message generated via a map. More specifically I had an orchestration which did the following:
The area of interest is the message sent to the error logging orchestration. This schema contains the standard header along with error information to be logged (for which each element defined as a distinguished field) i.e.
<xsd:element name="exception_details">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="type" type="xsd:string" />
<xsd:element name="description" type="xsd:string" />
<xsd:element name="error_source" type="xsd:string" />
<xsd:element name="details" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
To create an instance of this message I transform the original request (to create the standard header) and insert the error details via code in a message assignment shape.
msgException.exception_details.description = ex.Message;
msgException.exception_details.details = ex.ToString();
msgException.exception_details.error_source = "orch name";
msgException.exception_details.type = "details here";
However, in order to programmatically insert the content into these elements, the elements had to exist in the new message! If it does not I get an XPath error when trying to set the distinguished property values.
To ensure that the elements exist I used the useful but often overlooked property of the element - Value. To find this open the Map Designer, select the target element and go to the Properties window. There you will see a Value property which can be used to set a default value for the element or <empty>. In this case <empty> was most appropriate giving message content of:
<message>
<header>
...header content omitted
</header>
<payload>
<exception_details>
<description/>
<details/>
<error_source/>
<type/>
</exception_details>
</payload>
</message>
This allowed me to set the error detail programmatically as required. Voila!
When using HTTP, SOAP or WCF send ports it can be incredibly useful to view the content of messages that are sent on the wire. This allows you to inspect the headers (SOAP or HTTP). Fiddler is a simple but fantastic tool to allow you to do this.
By default, Fiddler will not trace any messages sent to endpoints by BizTalk as it does not use WinInet. However, BizTalk send ports can be configured to use a proxy allowing Fiddler to intercept them. On the Send Port tick the Use Proxy checkbox and set the Server to 127.0.0.1 and the port to 8888. For dynamic ports, set the following properties (as applicable to the adapter being used)
// Debug via fiddler
msgSendRequest(SOAP.UseProxy) = true;
msgSendRequest(SOAP.ProxyAddress) = "127.0.0.1";
msgSendRequest(SOAP.ProxyPort) = 8888;
Note that this needs to be removed when Fiddler is not running since traffic directed to the proxy will not be received by anything.
A bit off topic here but useful nonetheless. Recently my Vista box mislaid the default system font Segoe UI and consequently fell back to the italic version of the same font. Whilst this is not a huge issue, it just looks ugly!
Anyway after a lot of searching, the font can be replaced for free by installing Windows Live. Worked for me!
Single Sign-on is something that is often overlooked as being related only to Parties and for management of credentials. However, in its raw form, SSO provides a secure data store that can be used to store any information your application needs. In fact it can be used by non-BizTalk applications and doesn't have to only be for sensitive data, though this is the most typical usage.
In order to use SSO programmatically, an API is provided for accessing data. An MMC snap-in is also supplied for administrative purposes and third-party tools also exist for this purpose. Command line based tools also exist enabling scripting support.
Adding new configuration items to SSO
Using the tools supplied out-of-the-box with BizTalk 2006 R2, it is pretty easy to create an SSO schema and populate it with some data.
Create a schema for the configuration data. This is an XML file that look like the following:
<sso>
<application name="Application Name here">
<description>Description here</description>
<contact>email address here</contact>
<appuserAccount>domain\AppUserAccount</appuserAccount>
<appAdminAccount>domain\AppAdminAccount</appAdminAccount>
<field ordinal="0" label="reserved" masked="no" />
<field ordinal="1" label="field name here" masked="no" />
<field ordinal="2" label="field name here" masked="yes" />
<flags groupApp="no" configStoreApp="no" allowTickets="no"
validateTickets="yes" allowLocalAccounts="no" timeoutTickets="yes"
adminAccountSame="no" enableApp="no" />
</application>
</sso>
You can create as many fields as needed and multiple applications too. Note that the first field should not be used for a custom setting and is reserved for internal use.
Use the ssomanage.exe command line tool (in the C:\Program Files\Common Files\Enterprise Single Sign-On\ folder) to create the SSO application based upon the schema. To do so use the -createapps option specifying the filename of the schema XML created above. The application has access control for user and administrators based upon groups. By default these are the “BizTalk Application Users” and “BizTalk Server Administrators” groups respectively.
ssomanage -createapps "MySchema.xml"
To populate the schema with some data, use the BTSScnSSOApplicationConfig.exe command line tool (supplied with source code) in the C:\Program Files\Microsoft BizTalk Server 2006\SDK\Common\SsoApplicationConfig folder. Run Setup.bat to compile the tool and the executable should be generated in the bin folder.
BTSScnSSOApplicationConfig.exe -set AppName "ConfigProperties" "paramname" "paramvalue"
To retrieve a data item
BTSScnSSOApplicationConfig.exe -get AppName "ConfigProperties" "paramname"
Retrieving SSO configuration values in code
Once the data is stored, it can be accessed using the API. BizTalk 2006 comes with a client DLL which can be used to create a configuration reader class. In most instances it is recommended to create a type safe version to convert data items from their name/value pairs into the correct data type.
public class ConfigurationPropertyBag : IPropertyBag
{
private HybridDictionary properties;
internal ConfigurationPropertyBag()
{
properties = new HybridDictionary();
}
public void Read(string propName, out object ptrVar, int errLog)
{
ptrVar = properties[propName];
}
public void Write(string propName, ref object ptrVar)
{
properties.Add(propName, ptrVar);
}
public bool Contains(string key)
{
return properties.Contains(key);
}
public void Remove(string key)
{
properties.Remove(key);
}
}
public static class SSOConfigHelper
{
private static string idenifierGUID = "ConfigProperties";
/// <summary>
/// Read method helps get configuration data
/// </summary>
/// <param name="appName">The name of the affiliate application
/// to represent the configuration container to access</param>
/// <param name="propName">The property name to read</param>
/// <returns>
/// The value of the property stored in the given affiliate
/// application of this component.
/// </returns>
public static string Read(string appName, string propName)
{
try
{
SSOConfigStore ssoStore = new SSOConfigStore();
ConfigurationPropertyBag appMgmtBag = new ConfigurationPropertyBag();
((ISSOConfigStore) ssoStore).GetConfigInfo(appName, idenifierGUID, SSOFlag.SSO_FLAG_RUNTIME, (IPropertyBag) appMgmtBag);
object propertyValue = null;
appMgmtBag.Read(propName, out propertyValue, 0);
return (string)propertyValue;
}
catch (Exception e)
{
System.Diagnostics.Trace.WriteLine(e.Message);
throw;
}
}
}
Whilst the use of these command line tools is potentially advantageous from a scripting perspective, their use on an ad-hoc basis is not ideal. An MMC snap-in now exists for managing an SSO database. Richard Seroter has written a really cool configuration tool for managing configuration data which has a handy export feature that will export the application schema as an XML file. Source code is also available.
In most instances properties are promoted from message content during the disassemble stage of a pipeline. However, in some cases it is useful to promote a property that does not relate to the content of a message. For example you may want to generate a unique identifier for a transaction and promote that into context for later use. To do so:
Following on from my previous post concerning dynamic HTTP adapters, this time I'll extend the same concept to the SOAP adapter. Many of the techniques previously presented are still applicable but the SOAP adapter has it's own little idiosyncrasies which once explained are easy enough to overcome.
The first issue is that of a proxy. In traditional .NET applications, when using a web service it is typical to add a web reference which, under the covers will generate a proxy to the remote service based on its WSDL definition. This is also what would happen if you add a web reference in your orchestration and use a static SOAP send port. However, for a dynamic send port we don't want to create a web reference - we'll generate the proxy manually using the wsdl.exe tool as follows:
C:\>wsdl /l:CS /o:c:\temp\wsdl http://localhost/CalcWebService/CalcService.asmx?wsdl
Microsoft (R) Web Services Description Language Utility
[Microsoft (R) .NET Framework, Version 2.0.50727.42]
Copyright (C) Microsoft Corporation. All rights reserved.
Writing file 'c:\temp\wsdl\CalcService.cs'.
Here we have generated a proxy class from the WSDL of the web service. Add this to a new Class Library project. Ensure the resulting assembly is strong named and add it to the GAC. Note that the WebMethod to be called should have a signature as below that will accept an XML message and return one too. If an alternative method signature is required it will be necessary to update the proxy class to act as an facade between the required signature and the web service one.
[WebMethod]
public XmlNode MyMethod(XmlNode Message)
As with the HTTP example, we'll be invoking a dynamic adapter from an orchestration, setting adapter properties to change its behaviour at runtime. Again, add a request/response send port to the orchestration port surface and mark its type as Dynamic. The only other configuration required on the port is to specify the pipelines to be used, in this case XmlTransmit and XmlReceive. Connect up the request and response operations to the relevant send and receive shapes in the orchestration. Note that the operation on the send port should have the same name as the WebMethod being called.
Prior to sending the message set the following send port properties:
// Assign message
msgSendRequest = msgReceiveRequest;
// Set base properties
MySendPort(Microsoft.XLANGs.BaseTypes.Address) =
"http://localhost/CalcWebService/CalcService.asmx";
MySendPort (Microsoft.XLANGs.BaseTypes.TransportType) = "SOAP";
// Set HTTP adapter specific properties
msgSendRequest(BTS.SOAPAction) = "Add";
msgSendRequest(SOAP.MethodName) = "Add";
msgSendRequest(SOAP.AssemblyName) = "CalcTest.CalcWebServiceProxy.CalcService,
CalcWebServiceProxy, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=b713f1108bae3109";
msgSendRequest(SOAP.TypeName) = "CalcTest.CalcWebServiceProxy.CalcService";
Some important points to note here:
OK, now you should be good to go. Build, deploy and (hopefully) watch those SOAP requests flying to and from your web service. Whilst it's a little more fiddly to setup that the HTTP equivalent, using a dynamic SOAP adapter is a really powerful technique for creating flexible and extensible BizTalk applications.
Jon Fancey has taken this a step further by creating a more generic SOAP router. Check it out.
Part of the project I'm currently working on involves sending XML messages to a variety of trading partners. Each partner has several products each of which could require different port settings (URL, credentials, timeout, retry strategy). Another variable is the transport type. Currently all support plain XML over HTTP but in the future SOAP may be a requirement. As we have up to 1000 different partner/product combinations to support dynamic ports seem like a logical choice.
So how do you implement dynamic HTTP and SOAP send ports? Let's start with HTTP first as it's a little more straightforward.
Assuming that the orchestration is in place, add a request/response send port to the port surface and mark its type as Dynamic. The only other configuration required on the port is to specify the pipelines to be used and to connect up the request and response operations to the relevant send and receive shapes in the orchestration.
Prior to the send shape (I have used the message assignment shape that builds the request message) add the following code.
// Assign message
msgSendRequest = msgReceiveRequest;
// Set base properties
MySendPort(Microsoft.XLANGs.BaseTypes.Address) = "http://localhost/testpartner/test.aspx";
MySendPort(Microsoft.XLANGs.BaseTypes.TransportType) = "HTTP";
// Set HTTP adapter specific properties
msgSendRequest(HTTP.AuthenticationScheme) = "Basic";
msgSendRequest(HTTP.Username) = "mark";
msgSendRequest(HTTP.Password) = "pwd";
This code sets up the address URI and the transport type to be used. The TransportType is a means of informing BizTalk which adapter you want to use. If it is omitted the prefix of the Address (in this case http://) will be used to query an alias table to lookup the adapter to use. For some prefixes there are multiple adapters that could handle the request. For http:// it could be the HTTP, WCF-Basic or WCF-WSHttp so the TransportType property can be used to explictly choose the correct adapter. In this instance I could have omitted the TransportType since the HTTP is the default for http:// addresses.
Next I have set some properties that are specific to the HTTP adapter. In this instance I have just configured the authentication details but there are lots of other that can be used. Typically these settings could be looked up from a database or other configuration store and set dynamically based on the request.
And that's it! The request should then be routed to the URI configured in code above using the HTTP adapter. This is a very powerful technique to add flexibility to your application. I'll continue by demonstrating how to use the same technique for the SOAP adapter in a future post.
When installing BizTalk Server 2006, the process is generally pretty smooth. I have installed it a couple of times on different machines and had no problems to speak of. However, there are a few things to look out for if you do encounter problems:
A warm welcome to the BizTalk-Dev blog. My name is Mark and I am a Senior Developer for a mid-sized Financial Services company in the UK. I have been working with BizTalk for a few months now and hope to share a few hints, tips and observations that may be helpful.
