Failure Importing WCF Extension configuration to BizTalk WCF-Custom Handler

One of the BizTalk application that I am working on has to access web services from a third-party which does not play nicely with WCF. Nothing too uncommon if the third-party is a little exotic.
The solution was that a Custom Message Encoder was written to be able to read the messages coming from the third-party. To configure the WCF runtime stack, a Custom Message Encoding Binding Element was also created. As we want this custom encoder to only be used by that BizTalk application, we created a specific WCF-Custom Adapter Handler for the application and only that handler is configured with the binding extension configuration (instead of doing a change in machine.config or maybe the BTSNTSvc.exe.config).

As I was recreating a new development environment, I tried to import the WCF binding extension configuration file (a .config file containing a bindingElementExtensions element) to the WCF-Custom Adapter handler and got the following error: “Unable to import configuration from file “xxx.config”. (System.UnauthorizedAccessException) Access to path ‘xxx’ is denied.

WCF Extension configuration fails BizTalk Handler

I found out that this was simply because the configuration file was read-only (as it was coming from TFS source control) and that the BizTalk Admin Console first copies the config file to a temp folder and then tries to delete it. As the file is read-only, it cannot be deleted and importing the binding configuration fails!

The solution was simple, I just had to make the file writeable.
I chose to check-out the file temporarily, import the WCF binding extension configuration file and undo the check-out once the configuration was imported through the BizTalk Admin Console.

Notes:

If you are unfamiliar with WCF extensibility, a sample of a Custom Message Encoder sample is available on MSDN at Custom Message Encoder: Custom Text Encoder and the source code of the sample (and other samples) can be downloaded at Windows Communication Foundation (WCF) and Windows Workflow Foundation (WF) Samples for .NET Framework 4.

To import WCF Extension to a WCF-Custom Adapter Handler, open the BizTalk Admin Console, navigate to BizTalk Group\Platforms Settings\Adapters\WCF-Custom and right click the Handler of choice. Click Properties and then click Import.

Import WCF Extension bindings for BizTalk WCF-Custom Adapter Handler

How to modify WCF services previously published with the BizTalk WCF Service Publishing Wizard?

The BizTalk WCF Service Publishing Wizard is the tool used to easily publish a WCF Service implemented in BizTalk (typically through an orchestration). See the Publish WCF Services section of the BizTalk documentation for some background information if you are not used to the process of publishing WCF services in BizTalk.

In short, the main output of the Wizard is a Web Application containing the Web Services defined by the user in the Wizard plus a bunch of definition files, and schemas. See Publishing WCF Services with the Isolated WCF Receive Adapters for details of the output produced.

The main problem when using the Wizard from the Program Files menu is that it always start empty. If you have previously published a WCF service through the wizard and wish to modify it, you will always have to redefine the existing services and methods from scratch. This is quite inefficient as it is common at development time to have to either:

  • Add new services to the site (in case it is hosted in IIS).
  • Add new web methods on an existing service.
  • Change a schema (which is probably the change we do the most often).

It would thus be particularly tedious to have to redefine completely a WCF service each time we need to modify it.

One of the files produced by the Wizard is WcfServiceDescription.xml (located under \App_Data\Temp). As explained in Publishing WCF Services with the Isolated WCF Receive Adapters on MSDN, it is an XML file that summarizes the settings used when defining the WCF services in the Wizard.

Luckily, it is possible to feed this file back to the Wizard when running it again so that all the existing services and methods can be pre-populated. This is a great time saver at development time as more often than not, methods and contracts (schemas) are changing regularly.

Nevertheless the tool is far from perfect and I had to deploy the BizTalk assembly containing the updated schema to the GAC so that the Wizard would see it. Having the assembly compiled and picked up by the wizard’s file dialog box did not seem to work properly as I could only see the schemas that were already in the GAC from a previous deployment.

The way to do that is to launch the wizard from the command line by using the following syntax:
BtsWcfServicePublishingWizard.exe -wcfServiceDescription=C:\FolderPath\App_Data\Temp\WcfServiceDescription.xml

BtsWcfServicePublishingWizard.exe is located right in the folder where BizTalk is installed: “C:\Program Files (x86)\Microsoft BizTalk Server 2010” on my 64 bit machine.
The only shortcomings I have noticed so far are:

  1. In the wizard, if you chose to create receive locations in a BizTalk application, it will attempt to create all the receive locations defined in the wizard. If any of the receive locations already exist in the BizTalk application (from a previous run), the creation of ALL the receive locations will fail. Therefore, none of the new receive locations will be created while the already existing receive locations obviously still exist in the BizTalk Application. This does not mean that the wizard fails, it still succeeds. We can thus grab the new BindingInfo.xml generated by the wizard, extract the new ports and import them separately through the BizTalk Admin console. Alternatively, it is also possible to simply delete the pre-existing receive locations before running the wizard.
  2. The wizard does not repopulate the target namespace of the generated WCF services, it will default back to http://www.tempuri.org/. The work around is to pick it up beforehand from the service’s wsdl. When opening the wsdl, just look for the “targetNamespace” attribute in the element <wsdl:definitions> , take its value and paste it back in the Wizard.

Anyhow, even with these shortcomings, reusing the WcfServiceDescription.xml is still a great time saver!

BtsWcfServicePublishing.exe

On a side note, there is another tool similarly named, BtsWcfServicePublishing.exe which can be downloaded here (notice that there is no “Wizard” at the end of the name). As this tool does not have any GUI, it can be used to script and automate creation of WCF services for BizTalk. That can be useful for automated deployment for example. See the tool reference. As the tool was made available for BizTalk 2006 R2 (.Net 2.0 runtime), the following <startup> configuration section must be added to the tool’s config file so that it can run against BizTalk 2010 assemblies (.Net 4.0 assemblies).

<configuration>
<startup>
<supportedRuntime version="v4.0" />
</startup>
</configuration>

I have actually wrote a note about it in the MSDN documentation (see the Community Content section).

Datetime XML element converted to UTC – How to read the original time of a different time zone?

I noticed that time information is converted to UTC or to the local time zone when converting XML messages elements of the datetime XML type to a DateTime .Net type. The side effect is that the original time is lost and can’t be recovered.

I will demonstrate this through a scenario and then postulate conclusion and best practice to keep in mind. As this post got a little lengthier than expected, you can jump right to the summary section if you just want the facts.

 

Scenario

I had an orchestration for which I had to read a datetime XML element from an incoming message and put its value in a user friendly string message which would ultimately be visible in an application front-end. The datetime element was made a distinguished field so that it would be easier to access.  When I did a ToString() on the distinguished field, the time part was modified to reflect UTC time instead of the original time from the XML datetime element. This was a problem as the log message had to reflect the actual time of the original message regardless of the time zone.

I wrote a little application to study what was going on through a few illustrating cases. The application has an Order Message containing a <ProviderTime> datetime element with a value using the time zone of Bangkok (UTC+7).

 

Case 1: Get the value from a distinguished field.

In this case I simply mark the datetime XML element as a distinguished field (in the message’s schema) and assign it to a DateTime .Net variable in an expression shape (* – See the footnote on a remark about this).

Input XML:

<ProviderTime>2012-09-22T21:30:00.000+07:00</ProviderTime>

Result:

Calling the ToString() method on the DateTime variable prints: 9/22/2012 2:30:00 PM. This corresponds to UTC time and it means that BizTalk’s runtime created a UTC System.DateTime structure when reading the distinguished field and assigning to the variable.

While it is “correct” in the sense that both the XML datetime element and the .Net DateTime structure represent the same instant in time, it was not good for me as the user expected to see  9/22/2012 9:30:00 PM.

The reason this happens is that as the System.DateTime structure does not contain any information regarding the time zone, the BizTalk runtime converts the time to UTC time. To be exact, the BizTalk runtime calls the .Net framework XmlConvert.ToDateTime(String, XmlDateTimeSerializationMode) method which creates a DateTime object and loses the original time zone information. BizTalk then converts the resulting DateTime to UTC. There is thus no way to display the time as it was in the original message.

We would not want to use a promoted property just for reading a value out of a message but if we had a promoted property, using it would produce the same result.

 

Case 2: Get the value from XPath and convert it to a System.DateTime structure

In this case I use Xpath to get the element value and parse the resulting string into a System.DateTime structure with the following mothod: System.Xml.XmlConvert.ToDateTime(String). I also tried to various overload of the ToDateTime() method.

Input XML:

<ProviderTime>2012-09-22T21:30:00.000+07:00</ProviderTime>

Result:

Calling the DateTime.ToString() method on the DateTime structure would now print: 9/22/2012 3:30:00 PM. This is UTC+1, Dublin’s time zone (+0) with Daylight Time Savings (+1 in summer). It means that the XmlConvert.ToDateTime(String) method creates a System.DateTime structure reflecting the Local Time. Note that this particular overload is deprecated and other exists, which I tried, but basically all they let you chose for is if you want to create a DateTime reflecting Local Time or UTC.

 

Using the DateTime structure is a lost cause as it is not time zone aware and I would thus never be able to hold anything else than local time or UTC time. To solve my problem, I had to do something else but did not want to do some ugly manual string parsing.

I did some research about Date and Time in the .Net framework and read from MSDN that:

DateTimeOffset should be considered the default date and time type for application development

So yes you read it correctly, System.DateTime is “sort of” deprecated! See for yourselves directly from the horse’s mouth: http://msdn.microsoft.com/en-us/library/bb384267.aspx

As The DateTimeOffset structure contains an Offset property (a TimeSpan) which represents the time difference between the time stored in the DateTime structure and UTC time, it can represent other times than local time or UTC time.

 

Case 3: Get the value from XPath and convert it to a System.DateTimeOffset structure

In this case I use Xpath to get the element value and parse the resulting string into a System.DateTimeOffset structure with the following mothod: System.Xml.XmlConvert.ToDateTimeOffset(String).

Input XML:

<ProviderTime>2012-09-22T21:30:00.000+07:00</ProviderTime>

Result:

Bingo! Calling the ToString() method on the DateTimeOffset variable would print 9.30 PM as in the original message! Now all I had to do was to use an overload of the ToString() method taking a format string to display that in a user-friendly manner.

 

Here is a screenshot of the result of my investigations with cases 1,2&3 highlighted:

datetime timezone xml element parsing

And here is a Visual Studio solution if you want to play around yourself (or for myself in the future).

 

Summary:

  1. A distinguished field on a datetime xml element creates a System.DateTime structure adjusted for UTC Time. The DateTime.Kind property is DateTimeKind.Utc. So if in a different scenario than mine, the distinguished field is always Local Time, you can use DateTime.ToLocalTime () to convert the value back to local time. In that case, the DateTime.Kind property will have the value DateTimeKind.Local. Time in original time zone is lost.
  2. Reading a datetime xml element into a string by using XPath and then converting it to a System.DateTime structure by using one of the XmlConvert.ToDateTime() method overloads creates a Local Time or UTC time structure (depending of a parameter on one of the overload). Time in original time zone is lost.
  3. Reading a datetime xml element into a string by using XPath and then converting it to a System.DateTimeOffset structure by using one of the XmlConvert.ToDateTimeOffset() method overloads keeps the original time as it holds the time zone offset information (i.e. +7 hours). We can thus either display the time of the original time zone or convert it to another time zone offset.

 

Type of XML datetime read .Net Type created Default Time zone Time in original time zone available?
Distinguished field System.DateTime UTC NO
Promoted Property System.DateTime UTC NO
XPath and  XmlConvert.ToDateTime() System.DateTime Local Time (for default overload) NO
XPath and  XmlConvert.ToDateTimeOffset() System.DateTimeOffset Original time zone YES

 

Conclusion:

  1. Do not use distinguished fields on datetime elements; use XPath and a DateTimeOffset variable instead. This is a tip I will keep in mind so that I don’t have to worry about the original time value being lost. If you decide to use a distinguished field anyway, you must be aware of its limitation and if it impacts you or not.
  2. When using a promoted property on a datetime element, be aware that its value will be converted to UTC timezone. This might be of importance on subscriptions (port filters and so on). There is no work around on this at its part of the BizTalk engine.

 

I like to use distinguished field when it makes sense because it avoids having to use xpath query all over the place which can be an annoyance when a schema change. As Microsoft advises to use the System.DateTimeOffset structure, would it not be nice to have a distinguished field assignable to DateTimeOffset variable instead of DateTime? It would make a lot of sense as the XML datetime type is time zone aware while DateTime is not but DateTimeOffset is. Making the latter type is a much better match. Anyhow it is definitely something I would put in my wish list of BizTalk features!

It might of course not be straightforward to implement this feature as the code generated by the BizTalk compiler would depend of the type of the variable you assign to the distinguished field (either DateTime or DateTimeOffset). Or maybe that some automatic/easy casting is possible, there is a lengthy article on the conversion between DateTime and DateTimeOffset on MSDN but I did not try to play around with it.

 

(*) Footnote:

While the distinguished field looks like a .Net variable accessed like an object’s member, it actually is not, it is just how it is displayed in the expression shape editor. If you have in the editor something like myVar = MyMsg.MyDistinguishedField, it is just the syntax to access the distinguished field in the expression shape. In real, the code generated from the expression shape will be: myVar = MyMsg.part.GetDistinguishedField(“MyDistinguishedField”). The method will return the correct .Net type depending of the XML type of the distinguished field.

This is why you can’t think of the distinguished field as an object member and can’t call any method such as ToString() directly on it, it will confuse the code generator and the orchestration won’t compile. Hence, we must always assign the distinguished field to a variable.

Visual Studio compile error: Cryptographic failure while signing assembly Access is denied

One of the development environment for developing BizTalk Server 2006 solutions I worked on had Windows XP and Visual Studio 2005 running on it. The environment was quite complicated with scripts and Domain Controller Policies executing each time you would log on the machine. Moreover, I think that the C:\Documents and Settings directory was mapped to some network resource as the directory would become inaccessible when network problems occurred.

Anyhow, one day while compiling a BizTalk solution in Visual Studio, I had the following error:

Cryptographic failure while signing assembly ‘MyAssemblyName’ Access is denied.

The cause was that I had lost access rights in the following directory: C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys.  I don’t know why I had lost access rights but it was probably due to one of those unusual scripts/policies loaded at startup… and I never had such error on any other environments. After giving myself full access rights on that folder, the BizTalk solution would compile without error.

In the following screenshot I gave full access right to “Everyone” for simplicity sake as more than one user needed the access rights.

crypto_RSA_Folder_ACL

 

Conclusion:

The underlying reason for the compilation error is that because BizTalk libraries are deployed to the GAC, they must be signed with a strong name key file. As the signing process uses the C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys folder, the assembly could not be signed without being able to access the folder and the compilation would faild. Once I fixed the access rights, the assembly could be signed and Visual Studio could compile the BizTalk solution successfully.

This means that this error can happen any time the folder is needed such as in the following scenarios:

  • Compiling a Visual Studio project which assembly is signed.
  • Compiling a project or solution containing strongly signed assemblies through msbuild and/or TFS.
  • Generating a strong name key file with Visual Studio or with the utility sn.exe
There are probably other scenarios this folder is used for but it will obviously always be related to cryptography.

 

Failure to configure BizTalk BRE on named SQL Server instance‏.

I was installing BizTalk on a multi server environment and it failed while configuring BizTalk Server Business Rules Engine (BRE) with an error I never had before so I thought to write a little post about it in case it helps someone some day.

The infrastructure was as follow:

  • BizTalk Server: Windows Server 2008.
  • SQL Server: Windows Server 2008 cluster (2 nodes).
  • The SQL Server was clustered, running on a named instance on a custom port (instead of the default TCP port 1433).
  • There is a Firewall between the BizTalk Server and SQL Server with only the necessary ports open.
  • SQL Browser is not running.

Symptoms:

When configuring BizTalk Server; Enterprise SSO, BizTalk Group, the BizTalk runtime and all their respective databases could be configured successfully but the BRE (Business Rules Engine) failed to be configured correctly.

When looking at the log file, I saw the following error:

[ Error RulesEngine] System.Net.Sockets.SocketException (0x80004005): No such host is known at System.Net.Dns.GetAddrInfo(String name) at System.Net.Dns.InternalGetHostByName(String hostName, Boolean includeIPv6)

Solution:

This was quite puzzling as I could not see why all BizTalk services and Databases could be configured correctly except for BRE. The only thing I could think of from the error message was that the tool configuring BRE was using a different way to connect to the SQL Server machine.
While defining the SQL Server Name in the BizTalk Server Configuration tool, I used the following syntax:
<SQLServerName>,<PortNumber>\<SQLInstanceName>.
I then tried to reconfigure BRE using an alternative syntax I knew of:
<SQLServerName>\<SQLInstanceName>,<PortNumber>.
This did the trick and BRE got configured correctly. As I said before, this is probably due to the underlying API used to connect to the SQL Server box.

As it was a little disturbing for me that the former syntax works in most cases (and particularly in SQL Server Management Studio) but does not work for the Business Rule Engine part of BizTalk Server configuration, I decided to dig out a little more to find out what was the actual canonical syntax. After a quick research, I realized that it is redundant to specify both the SQL Server Instance Name and the port number because a SQL Server instance is mapped to only one TCP port. This is actually what SQL Browser does, it converts the Instance Name to the TCP port number the Named Instance listens to. On a side note, SQL Browser will map the Instance Name to a named pipe when using the named pipe protocol instead of TCP.
So the actual canonical syntaxes are either:

  • <SQLServerName>\<SQLInstanceName> in case SQL Browser is running.
  • <SQLServerName>,<PortNumber> for TCP connection in case SQL Browser is not running.
  • <SQLServerName>\<pipe>\<pipename> for named pipe connections in case SQL Browser is not running.

Conclusion:

I shall stick to the canonical syntax instead of using uncommon alternatives, especially the one I was using: <SQLServerName>,<PortNumber>\<SQLInstanceName>.

References:

SQL Server Browser Service

SqlConnection.ConnectionString Property