How to move from BizTalk Server to BizTalk Services (WABS) - BizTalk Summit 2014, London
Issue 7 Q3 2009 Table of Contents 07, 2017 · WMI and Dynamics AX Integration with BizTalk. ......
Transcript of Issue 7 Q3 2009 Table of Contents 07, 2017 · WMI and Dynamics AX Integration with BizTalk. ......
Page 1
Issue 7 Q3 2009
Table of Contents Preface .......................................................................................................................................................... 3
B2B 2.0 Azure – a durable competitive advantage for Microsoft Take 2 ..................................................... 4
EDI - continues to dominate B2B! ........................................................................................................... 4
B2B Adoption blockers are in fact opportunities for Microsoft ............................................................. 5
State of the „technology‟ .......................................................................................................................... 5
B2B 2.0 with Azure – the durable competitive advantage for Microsoft ............................................. 6
Unit Testing Schemas and Maps in BizTalk Server 2009 – A Different Approach! ...................................... 8
Summary ................................................................................................................................................... 8
Testing schema ......................................................................................................................................... 8
Why is it Failing? ................................................................................................................................. 10
How can it be Resolved? ..................................................................................................................... 10
Now let’s look at Map Files ..................................................................................................................... 12
Why is it Failing? ................................................................................................................................. 13
How can it be Resolved? ..................................................................................................................... 13
Conclusion ............................................................................................................................................... 15
Advantages with the above approaches ............................................................................................. 15
Disadvantages with the above approaches ........................................................................................ 15
Book Review for "SOA Patterns with BizTalk Server 2009" By Richard Seroter ......................................... 16
How to Throw Typed Fault Exceptions from Orchestrations Published as WCF Services .......................... 18
Typed Faults ............................................................................................................................................ 18
Untyped Faults ........................................................................................................................................ 19
Page 2
BizTalk Orchestrations and Typed Faults ................................................................................................ 19
The Solution ............................................................................................................................................ 22
Proof of Concept in Action ...................................................................................................................... 35
Show me the code! ................................................................................................................................. 35
BizTalk Resources ........................................................................................................................................ 37
BizTalk 24x7............................................................................................................................................. 37
BizTalk Gurus ........................................................................................................................................... 37
BizTalk Server Customer Advisory Team ................................................................................................ 37
Recently Released Documentation ......................................................................................................... 37
BizTalk Server 2009 Install Documentation - June 2009 Update ........................................................ 37
BizTalk Server 2009 Operations Guide - July 2009 ............................................................................. 37
Microsoft Dynamics AX integration using Microsoft BizTalk Server ........................................................... 39
Introduction ............................................................................................................................................ 39
Configuring Microsoft Dynamics AX Adapter for BizTalk ........................................................................ 41
Terminology ........................................................................................................................................ 41
Configuring Microsoft Dynamics AX – Application Integration Framework (AIF) .............................. 42
Send Data from BizTalk to Dynamics AX ............................................................................................. 54
Receive Data from Dynamics AX in BizTalk ......................................................................................... 56
Error Handling and Messages ............................................................................................................. 59
Appendix A Configuring Message Properties for sending data to Microsoft Dynamics AX ................... 73
Appendix B Related Documents/References .......................................................................................... 74
Manage BizTalk Services Thru WMI – Using C# .......................................................................................... 75
Summary ................................................................................................................................................. 75
Creating a WMI Managed Class for BizTalk ............................................................................................ 75
Terminate Suspended Instances ............................................................................................................. 76
Resume Suspended Instances ................................................................................................................. 78
Advantages of WMI with C# approach ................................................................................................... 79
Conclusion ............................................................................................................................................... 79
Page 3
Preface
This issue has articles about Azure, BizTalk WCF Adapters, Book review, Unit Testing, Management with
WMI and Dynamics AX Integration with BizTalk.
BizTalk 2009 was released in May 2009. It was followed by ESB Toolkit 2.0. ESB Toolkit is now available
to download from http://www.microsoft.com/biztalk/en/us/esb-guidance.aspx. It is built on top of
BizTalk 2009 and is a fully supported product. BizTalk Adapter Pack 2.0 was also released. In addition to
enhancements to the existing adapters it contains new adapters for SQL Server and Oracle EBS.
I want to thank Virtual TS Andy Morrison(Digineer) for helping with this issue. I also want to thank all the
contributors for submitting their articles. If you have any suggestions for improvements or want to write
in a future issue don't hesitate to contact me.
Rajinder Singh
Page 4
B2B 2.0 Azure – a durable competitive advantage for Microsoft Take 2 By Suren Machiraju, Principal Program Manager, Customer Experience Team, Microsoft
Business-to-business (B2B) describes commerce transactions between businesses, such as
between a manufacturer and a wholesaler, or between a hospital and an insurance
company. Such transactions are expected to be generated and consumed by Line-of-
Business applications with a high degree of automation and integration. Although the level
of automation and processing of the B2B commerce has matured in industry segments
dominated by mega- corporations such as financials (banking industry) and shipping (sea
cargo and locomotive freight); and there are great many opportunities for establishing B2B
commerce in supply chain and the Health Care industry verticals.
EDI - continues to dominate B2B!
The National Institute of Standards and Technology defines Electronic Data Interchange
(EDI) as "the computer-to-computer interchange of strictly formatted messages that
represent documents. The current volume of worldwide EDI transactions is more than 20
million per day and accounts for a significant amount of worldwide commercial activity. In
fact, some studies determined that more than one-third of the US GDP is directly supported
by EDI transactions. The EDI market is estimated to be worth $3-$7 trillion. Some estimate
that global EDI transactions are increasing between 5% and 10% per year.
EDI transaction volume is expected to continue to grow in view of the adoption of
automation strategies around the world to reduce cost of doing business; and politically
driven investment initiatives e.g., in Health Care IT initiatives in American Recovery and
Reinvestment Act of 2009.
For the sake of completeness it‟s worth mentioning here that there are other encoding
standards (Financial–SWIFT; internet commerce/B2C-xCBL or cXML; Manufacturing-
RosettaNet); however these do not match the popularity or prevalence of EDI. However there
is no technical reason to exclude building out vertical/domain specific protocol handlers in
line with the solution advocated here for EDI.
Page 5
B2B Adoption blockers are in fact opportunities for Microsoft
Many surveys conducted have consistently indicated that key adoption blockers to
implementing B2B/EDI solutions are related to investments; availability; and reliability of the
computer applications. More than 2/3rd of typical survey respondents have cited initial
investment of the computer system to be the prime adoption blocker. This is quite easy to
comprehend given the complexity of setting up computer systems to conduct B2B
transactions. These adoption blockers play easily into the strength of the Microsoft,
especially around the hosted offering with Azure. Additionally BPD has the core abilities to
design and implement on a topical solution B2B2.0!
Results of a (typical and publicly available data) survey conducted in an emerging market
are presented below.
Factor Mean* Std Deviation
Initial Investment 4.16 0.97
Customer and supplier requirements 3.72 1.10
Software reliability 3.68 1.10
Software capability 3.66 1.08
Software availability 3.66 0.88
Hardware availability 3.59 0.74
Hardware reliability 3.56 0.90
Management Support 3.55 1.15
Availability of EDI applications 3.54 1.14
Internet skills/resources 3.54 0.85
Availability of EDI standards 3.45 1.26
Availability of maturity in EDI applications 3.25 1.08
Strategic objectives 3.13 1.13
End user acceptance 3.10 1.15
Organizational resistance 2.82 1.12
*measured using a 5-point scale
State of the „technology‟
EDI encoded documents are presented as delimited flat files and although the Standards
(SDOs) and Industry Advisory organizations do not recommend transmission protocols, FTP
(EDI over dedicated networks) and HTTP along with SMIME encryption and signature (EDI-
INT or EDI over Internet) are the prevalent protocols with the latter gaining ground by the
day.
Page 6
While EDI documents over FTP are a prevalent protocol among the VAN (Value Added
Networks) providers; EDI-INT is gaining market share over VAN solutions due to low
operational costs and availability. Further dominant industry leaders (e.g., Walmart) force
suppliers to use EDI-INT over VAN further eroding the latter‟s market share. However VANs
have some advantages over EDI-INT, mostly the requirement of only one physical
connection, allowing multiple trading partners to be accessed via a single VAN connection
reliably and securely. VAN revenues are expected to continue to decrease as EDI-INT
increases. As this shift continues, VANs are focusing on the “Value Added” part of their
offerings, by offering more sophisticated mailbox features and reporting for the trading
partners they service.
There is a breed of ISV/Vendors that have sized on the opportunity to use the ubiquity of the
internet for EDI-INT transmissions while providing the single point connectivity that VAN
solutions offer. Such vendors are categorized as EDI Service Bureaus.
The attractiveness of an EDI Service Bureaus is that they have out-of-box connectivity to
100s of „Partners‟. Partners are generally the mega corporations that everyone wants to
transact with. The more comprehensive the list the grater attraction it is to its customer
community. Customers are the „smaller‟ partners that are forced into EDI solutions by their
larger „partners‟.
B2B 2.0 with Azure – the durable competitive advantage for Microsoft
Having established the business case for B2B and EDI messaging and armed with data that
the TCO for computer systems are the adoption blocker; it‟s fair to surmise that there is a
durable business model for Microsoft to provide a B2B platform to Service Bureaus thereby
providing a competitive opportunity vis-à-vis traditional VAN players in the B2B space.
Now let‟s examine the possibility of delivering a solution to customer inline with the
Microsoft Business Online Group‟s business model.
Hosted Platform: Windows Azure with .NET Services and SQL Data Services provides
the ideal platform for developing and hosting a secure cloud scale B2B Server
platform. The Server Platform would provide a range of essential (WCF) Services for
EDI Parsing; Mapping framework; Batching; Enveloping; Ack Reconciliation; Partner
Onboarding and Trading Partner Management Dashboard among other such
essential services accessed via a browser based client. Identity Services would be
Page 7
deployed for security and SQL Data Services would act as the interim store and by
choice the non repudiation-able receipt store.
On-premise client application(s): Although document management (e.g.,
upload/download of Excel documents) could be achieved via a browser client;
additionally an on-premise „black box‟ solution is proposed. The client would
comprise of a Silver Light client and use .NET components (WCF, WF, XSLT) and .EDI
libraries to process, establish connectivity, authenticate and upload the documents
to the Server. WCF streaming functionality with binary encoding and compression
would provide the superior performance for uploading the XML based content; while
Silver Light client would provide the rich client experience. Integration options
(adapters?) would be available for a set of back end applications (e.g., Dynamics
ERP). For customers desiring BPM and advanced connectivity options, the well
established BizTalk Server could be a preferred option with out-of-box connectivity to
back end systems while being able to offer comprehensive EDI functionality.
Importantly the client and dashboard will be customizable by the Service Bureau to
address the domain needs.
Monetization strategies will be in line with Business Online Service Group‟s licensing models
– usage or subscription based.
Page 8
Unit Testing Schemas and Maps in BizTalk Server 2009 – A Different
Approach! By Sooraj Payyoormana, Senior Development Lead, Microsoft
This article assumes you are familiar with BizTalk Server Schemas, Maps and Visual Studio 2008 Unit
testing scripts.
Audience: BizTalk Developers
Technologies: BizTalk Server 2009, VS.NET 2008
Skill level: Beginner to Expert
The source code used in this article can be downloaded from the following location:
http://cid-
61b5fd0cc0cf5b2e.skydrive.live.com/self.aspx/Source%20Code/BTSUnitTests/BTSUnitTests.zip
Summary There was an article on “Unit Testing in BizTalk Server 2009” by Rajinder Singh in BizTalk Hotrod
magazine1. I followed this article and the MSDN article on “Using the Unit Testing Features with
Schemas and Maps”2 to write unit test scripts for schema and map files.
In this article, I am trying to explain the approaches I took to resolve the following issues which I faced
during my unit test script development.
Not able to do the unit testing on the schema which was referring other schemas that are part
of different BizTalk assembly.
Unit Test scripts are not working on the map file which uses multi-part message as input.
Testing schema I needed to create automated unit test scripts for the “SalesOrder” and “PurchaseOrder” schemas.
The following unit testing script was written to validate the “SalesOrder” schema using valid and invalid
XML instances. Here I had written the unit test scripts based on the Unit Testing feature of BizTalk
Server 2009.
[TestMethod]
public void TestSOSchemaWithBuiltInMethod()
{
TestableSchemaBase salesOrderSchema = new SalesOrder.Schemas.SalesOrder();
Assert.IsTrue(salesOrderSchema.ValidateInstance(VALID_SO_INSTANCE,
Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML), "Test failed for the Valid
Instance scenario.");
Assert.IsFalse(salesOrderSchema.ValidateInstance(INVALID_SO_INSTANCE,
Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML), "Test failed for the
InValid Instance scenario.");
1 Issue 5 Q1 2009. See http://biztalkhotrod.com/Documents/BizTalk%20HotRod%20Magazine%20Q1%202009.pdf
2 http://msdn.microsoft.com/en-us/library/dd224279.aspx
Page 9
}
Let us see the Test Result after executing the above test method.
The test passed without any errors.
Now, let us write the unit test script for “PurchaseOrder” schema.
The “PurchaseOrder” schema was created by importing two schemas named “DocHeader” schema and
“OrderComponents” schema from different BizTalk assemblies.
We will follow the above mentioned code to write the unit test script for “PurchaseOrder” schema.
[TestMethod]
public void TestPOSchemaWithBuiltInMethod()
{
TestableSchemaBase purchaseOrderSchema = new
PurchaseOrder.Schemas.PurchaseOrder();
Assert.IsTrue(purchaseOrderSchema.ValidateInstance(VALID_PO_INSTANCE,
Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML), "Test failed for the valid
Instance scenario.");
Assert.IsFalse(purchaseOrderSchema.ValidateInstance(INVALID_PO_INSTANCE,
Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML), "Test failed for the
invalid Instance scenario.");
}
Let us execute the test script and see the result.
Page 10
The test failed! Are there any issues with the input instance XML files? Any issue with the schema(s)? Is
the instance XML file path is valid?
I manually verified whether the XML instance file path was wrong, whether the instances where
valid/invalid for their scenario (against the schema) and whether there were issues with the schemas.
There were no issues.
Why is it Failing?
The ValidateInstance method of TestableSchemaBase class returns a Boolean value.
Unfortunately, ValidateInstance method does not return any error information and it doesn’t
throw any exceptions. In the above code it returns false always, due to this, the first test method with
Assert.IsTrue is failing. One of the reasons could be that the ValidateInstance method is not
able to resolve the schemas specified in the import section which are referenced from other BizTalk
assemblies. The Assert.IsFalse in the above code block will execute successfully as the
ValidateInstance method returns false always.
How can it be Resolved?
The XmlReaderSettings and XmlReader3 classes can be used to validate the schema. I wrote a
helper class to do the XML validation using these classes. In the validation implementation code, the
method takes the object of the schema class and the XML instance file path.
public static ValidationResult ValidateSchema(TestableSchemaBase schemaObject, string
xmlInstancePath)
Now, create the XmlReaderSettings object using the schemaObject argument and set its
ValidationType property and ValidationEventHandler event handler.
XmlReaderSettings settings = new XmlReaderSettings();
XmlSchemaSet schemaSet = new XmlSchemaSet();
schemaSet.Add(schemaObject.Schema);
settings.Schema = schemaSet;
settings.ValidationType = ValidationType.Schema;
settings.ValidationEventHandler += new
ValidationEventHandler(SchemaReaderSettingsValidationEventHandler);
Next, create the XmlReader object using the XmlReaderSettings object created above, and with
the XML instance specified in the xmlInstancePath argument.
using (XmlReader reader = XmlReader.Create(xmlInstancePath, settings))
{
XmlValidatingReader xmlValidator = new
XmlValidatingReader(xmlInstanceReader);
3 The XmlReader class can enforce validation using a document type definition (DTD) or XML Schema definition
language (XSD) schema. Settings on the XmlReaderSettings object used by the Create method determine what type of data validation, if any, the XmlReader object supports – from MSDN.
Page 11
Read and validate the schema.
while (reader.Read())
{
if (!_IsValid)
break;
}
The code for the validation event handler:
void SchemaReaderSettingsValidationEventHandler(object sender, ValidationEventArgs
arguments)
{
if (arguments.Severity == XmlSeverityType.Error)
{
_IsValid = false;
validationMessage = arguments.Message;
Trace.WriteLine(arguments.Message);
}
}
The ValidationResult class code snippet:
/// <summary>
/// Class for returning the validation results.
/// </summary>
public class ValidationResult
{
/// <summary>
/// Return true if the schema is valid else false.
/// </summary>
public bool IsValid { get; set; }
/// <summary>
/// Returns the error message if the schema validation is failed.
/// </summary>
public string ValidationMessage { get; set; }
}
That’s it. You are now ready to call the ValidateSchema method from the unit test script:
Finally this is the customized unit test script for testing “PurchaseOrder” schema:
[TestMethod]
public void TestPOSchemaWithCustomMethod()
{
TestableSchemaBase purchaseOrderSchema = new
PurchaseOrder.Schemas.PurchaseOrder();
ValidationResult result1 =
XmlValidationHelper.ValidateSchema(purchaseOrderSchema, VALID_PO_INSTANCE);
Assert.IsTrue(result1.IsValid, "Test failed for the Valid Instance
scenario. Exception: {0}", result1.ValidationMessage);
ValidationResult result2 =
XmlValidationHelper.ValidateSchema(purchaseOrderSchema, INVALID_PO_INSTANCE);
Assert.IsFalse(result2.IsValid, "Test failed for the InValid Instance
scenario. Exception: {0}", result.ValidationMessage);
}
Page 12
In the above code block, we are creating the object of the “PurchaseOrder” schema and passes as the
first argument to the ValidateSchema method of the XmlValidationHelper class. The
ValidationResult class is used to capture the error message while validating the schema. The
IsValid property returns the Boolean value, which indicates the validation is successful or not and the
ValidationMessage returns the error message.
Now we will execute this test script and see the test result.
Yes, this time the test passed without any errors.
Now let’s look at Map Files The “PurchaseOrder” schema instance should be transformed as a “SalesOrder” schema instance. The
map file which is created for the transformation takes a multi-part message as the input and creates the
instance of the “SalesOrder” schema instance as output. One part of the multi-part message input is the
instance of the “PurchaseOrder” schema and the other is the instance of the “Store” schema, which is
created using a .NET assembly from the Orchestration. I have created an instance file for this multi-part
message type using the “Test Map” menu option of Visual Studio context menu.
The following unit test script is written for testing the map file, using the TestMap method of
TestableMapBase class.
[TestMethod]
public void TestSOMapping()
{
TestableMapBase target = new TransformSOMessage();
InputInstanceType inputType = InputInstanceType.Xml;
OutputInstanceType outputType = OutputInstanceType.XML;
target.TestMap(INPUT_FILE, inputType, OUTPUT_FILE, outputType);
Assert.IsTrue(File.Exists(OUTPUT_FILE), "Failed to generate output
file..");
ValidationResult vr = XmlValidationHelper.ValidateOutput(OUTPUT_FILE,
EXPECTED_FILE);
Assert.IsTrue(vr.IsValid, "Mapping test failed. Exception {0}",
vr.ValidationMessage);
}
We will execute the above test script and see the result.
Page 13
The test is failed!
Why is it Failing?
The generated output file and the expected results are not matching. The TestMap method generates
output with whitespace. Another reason could be that the unit test feature of BizTalk Server 2009
doesn’t support multi-part message types for testing map files.
How can it be Resolved?
By using the XslCompiledTransform 4class we can transform the schema instance with the help of
XSLT specified in the map file. BizTalk Server does the transformation based on the XSLT 1.0 syntax.
I wrote a c# function using the XslCompiledTransform class. Here is the code:
public static ValidationResult TestMapper(string inputPath, TransformBase mapperClass,
string outPutPath,
string expectedResultPath)
{
string xsltContent = mapperClass.XmlContent;
ValidationResult vr = new ValidationResult { IsValid = true,
ValidationMessage = string.Empty };
using (XmlTextReader xmlReader = new XmlTextReader(new
StringReader(xsltContent)))
{
XPathDocument inputDocument = new XPathDocument(inputPath);
XslCompiledTransform myXslTrans = new XslCompiledTransform();
myXslTrans.Load(xmlReader);
XmlWriterSettings settings = new XmlWriterSettings();
settings.OmitXmlDeclaration = true;
using (XmlWriter xmlWriter = XmlWriter.Create(outPutPath, settings))
{
myXslTrans.Transform(inputDocument, mapperClass.TransformArgs,
xmlWriter);
}
}
if (File.Exists(outPutPath))
{
4 The XslCompiledTransform class is an XSLT processor that supports the XSLT 1.0 syntax. It is a new
implementation and includes performance gains when compared to the obsolete XslTransform class. The structure of the XslCompiledTransform class is very similar to the XslTransform class. The Load method loads and compiles the style sheet, while the Transform method executes the XSLT transform. – From MSDN.
Page 14
vr = XmlValidationHelper.ValidateOutput(outPutPath,
expectedResultPath);
}
else
{
vr.IsValid = false;
vr.ValidationMessage = "Mapping failed..Output file is not generated";
}
return vr;
}
string xsltContent = mapperClass.XmlContent;
The above code returns the XSLT defined in the map class. Using that XSLT, we will be able to generate a
XML file which is the expected output from the map.
settings.OmitXmlDeclaration = true;
The OmitXmlDeclaration property is used to create the XML without having the XML declaration and allow us to do the comparison between the generated output file with the expected result. XmlValidationHelper.ValidateOutput method is used here to compare both the XML file and it reports the errors during the comparison. This code is available in the above mentioned for download. Finally the unit test script will look like this: [TestMethod]
public void TestSOMappingUsingCustomMethod()
{
TransformSOMessage salesOrderMap = new TransformSOMessage();
ValidationResult vr = XmlMapperHelper.TestMapper(INPUT_FILE,
salesOrderMap, OUTPUT_FILE, EXPECTED_FILE);
Assert.IsTrue(vr.IsValid, "Mapping test failed. Exception {0}",
vr.ValidationMessage);
}
Let us execute the test script and see the result.
Wow! The test passed without any errors.
Page 15
Conclusion The ValidateInstance method of the TestableSchemaBase class does not return any error
information, it always returns either true or false. Due to this we are not able to find the exact error with
the schema unit tests. My article is trying to address this issue and helps to find the exact error while
validating the schema.
Even though you will be able to find out the errors while testing the map files using the TestMap
method of the TestableMapBase class, we are not be able to compare the output file with the
expected result. Also, the Unit Testing feature of BizTalk Server 2009 doesn’t support unit testing of map
file which uses the multi-part type messages.
My article is trying to address these issues of map file unit testing and reports the issues.
Advantages with the above approaches
Generic and reusable code to do the unit test scripts on map and schema files
Better validation and error reporting
Write unit test scripts to test and validate map, when the input for the map file is a multi-part
message
Write unit test scripts to test schema, when there are one or more external referenced schemas
imported in the schema
Disadvantages with the above approaches
Developer should write the custom classes and methods for validating the Schemas and map
files for the first time. Later this can be reused in other unit test projects.
The developer should know more on XML, XSD and its related classes and methods in .NET.
Whereas with the BizTalk unit test script methods, the developer need not know these
classes/methods.
Happy Unit Testing!
Page 16
Book Review for "SOA Patterns with BizTalk Server 2009" By Richard
Seroter
I was recently asked to review this book. Like the title implies this book is shows you how to use BizTalk
to implement Service Oriented Architecture. It is written for developers and architects. It is not meant to
be a BizTalk tutorial. SOA cannot be implemented by any one tool. However anyone trying to implement
Service Oriented applications on Microsoft Platform should learn more about Windows Communication
Foundation and BizTalk Server.
Chapter 1 gives a brief overview of BizTalk Architecture and also describes artifacts needed to develop
BizTalk based solutions.
Chapter 2 gives you primer of Windows Communication Foundation. You will need to rely on other
sources to learn more about WCF.
Chapter 3 describes BizTalk WCF Adapters. It also shows how to use WCF adapters from Orchestrations
and Messaging only scenarios. It shows how to publish Orchestrations as WCF service and how to
consume a WCF Service from an Orchestration. This chapter did a great job in explaining how to use
BizTalk WCF adapters.
Chapter 4 starts by explaining core principles of SOA. It expands on this principles and shows how
BizTalk can be used to design SOA solutions. It also identifies various message exchange patterns and
service types.
Chapter 5 does an excellent job in documenting the best practices for building schemas that will work
well with the type of service you have chosen. It talks about building canonical schemas and benefits,
limitations of schema reuse. It also shows the impact of data type and node definition on the client
code. There is also a section on using generic schemas and tips for building contract first endpoints. This
chapter is must read for anyone who is designing schemas in a SOA based solution.
Chapter 6 explains benefits of asynchronous communication and how one can implement them with
WCF. It also shows how to implement such a solution with BizTalk. There is also a section on queue
based communication.
Chapter 7 you will learn about Orchestrations. It explains Direct binding and dynamic service ports. It
also shows how to implement various message exchange patterns in an Orchestration. There is a
section that shows how to chain Orchestrations together with the help of Business Rules Engine. The
chapters finishes with a section on role of Transactions and Complex Event Processing
Chapter 8 is must read for anyone who is grappling with versioning schemas, services and
Orchestrations. Versioning schemas and other BizTalk artifacts has always been tricky. This chapter is
one of the best reference you will find out this topic.
Page 17
Chapter 9 describes WCF SQL Server Adapter that was recently released as a part of BizTalk Adapter
Pack 2.0. It shows the differences between the old SQL adapter and the new adapter. It also shows you
various ways in which you can use this new adapter.
Chapter 10 UDDI V3 is now a part of BizTalk 2009. This chapter explains UDDI and shows you how to use
the UDDI Service that is a part of BizTalk 2009. There is not much documentation out there for UDDI and
this chapter will be a great resource for anyone interested in using UDDI.
Chapter 11 Gives you an overview of ESB Guidance 2.0. It describes various components of the ESB
Toolkit. It also shows how to implement various scenarios with ESB Toolkit. This chapter did a great job
in covering ESB Toolkit.
Chapter 12 This chapter briefly talks about Dublin, .Net Services and Oslo.
I found this book to be very easy to read. Richard has a knack for explaining concepts clearly with the
help of examples. There are not many books available that do such a good job of showing how to use
BizTalk to implement SOA. Anyone implementing SOA solutions on Microsoft platform will benefit from
this book.
Rajinder Singh
Technical Solutions Professional
Microsoft
Page 18
How to Throw Typed Fault Exceptions from Orchestrations Published as
WCF Services
By Paolo Salvatori, Principal Program Manager, Customer Experience Team, Microsoft Italy
In general, a WCF Web Service can return two types of SOAP faults: typed and untyped SOAP faults. BizTalk development tools allow you to publish an Orchestration was a WCF Service. Out of the box BizTalk Orchestrations published as WCF Services can throw untyped faults. This article will show you how to throw Typed Faults from Orchestrations published as a WCF Service.
Typed Faults
In order to throw a typed fault, a service operation must be decorated with a System.ServiceModel.FaultContractAttribute that specifies a fault data contract defined earlier. The following code snippet shows a WCF web service called HelloWorld which implements the IHelloWorld service or contract interface. This interface exposes a single synchronous operation called SayHello that is decorated with the FaultContractAttribute. The attribute declares that the SayHello method can throw a typed fault exception defined by the CustomError data contract class. The implementation of the SayHello method in the HelloWorld class checks if the incoming request is null and in this case it throws an error of type FaultException<CustomError>.
namespace Microsoft.BizTalk.CAT.Samples.PublishTypedFaults.Services
{
[Serializable]
[DataContract(Name = "HelloWorldRequest", Namespace =
"http://microsoft.biztalk.cat/10/helloworld")]
public class HelloWorldRequest
{
...
}
[Serializable]
[DataContract(Name = "HelloWorldResponse", Namespace =
"http://microsoft.biztalk.cat/10/helloworld")]
public class HelloWorldResponse
{
...
}
[Serializable]
[DataContract(Name = "CustomError", Namespace =
"http://microsoft.biztalk.cat/10/customerror")]
public class CustomError
{
...
}
[ServiceContract(Name = "HelloWorld", Namespace =
Page 19
"http://microsoft.biztalk.cat/10/helloworld")]
public interface IHelloWorld
{
[OperationContract(Action = "SayHello", ReplyAction = "SayHello",
ProtectionLevel = ProtectionLevel.None)]
[FaultContract(typeof(CustomError), Action = "CustomErrorFault")]
HelloWorldResponse SayHello(HelloWorldRequest request);
}
[ServiceBehavior(Name = "HelloWorld", Namespace =
"http://microsoft.biztalk.cat/10/helloworld")]
public class HelloWorld : IHelloWorld
{
[OperationBehavior]
public HelloWorldResponse SayHello(HelloWorldRequest request)
{
if (request == null || string.IsNullOrEmpty(request.Name))
{
throw CreateFault(NameCannotBeNullOrEmpty);
}
return new HelloWorldResponse(string.Format(SayHelloFormat,
request.Name));
}
private FaultException<CustomError> CreateFault(string message)
{
...
return fault;
}
}
}
Untyped Faults
Untyped SOAP faults are those that do not require a service operation to be decorated with a FaultContractAttribute that specify a custom data contract class.
BizTalk Orchestrations and Typed Faults
BizTalk Server 2006 R2 and BizTalk Server 2009 allow handling typed fault contracts when consuming WCF services from within orchestrations. The steps necessary to implement this technique are clearly described in the article “How to Handle Typed Fault Contracts in Orchestrations” on MSDN. Instead, WCF adapters actually do not support processing typed fault contract exceptions within orchestrations published as WCF services. However, untyped SOAP faults can always be returned by orchestrations or pipelines. For more information on this topic review the article “How to Throw Fault Exceptions from Orchestrations Published as WCF Services” on MSDN.
This constraint arises from how the Receive Handler of WCF Adapters is actually implemented. The WCF Receive Adapter instantiates a singleton instance of the BizTalkServiceInstance class for each WCF Receive Location. This class can be found in the Microsoft.BizTalk.Adapter.Wcf.Runtime.dll assembly. In particular, as you can see in the picture below, the BizTalkServiceInstance class is decorated with the attribute
Page 20
ServiceBehavior(InstanceContextMode=InstanceContextMode.Single, ConcurrencyMode=ConcurrencyMode.Multiple).
Therefore, all the incoming requests towards a given WCF Receive Location are managed by the same singleton object. When you enable a WCF Receive Location, the Adapter initializes and opens a dedicated instance of a ServiceHost-derived class (WebServiceHost), which dynamically builds the WCF runtime components within the in-process or isolated host process. This includes the channel stack, dispatcher, and generic service instance. Almost all of the WCF adapters can be hosted within the BizTalk service process itself – the only exception is WCF-CustomIsolated, which must be used in a BizTalk isolated host by design. Even the HTTP adapters can be hosted in-process now. The WCF Adapters build the generic service contracts shown in the table below. Each service contract implemented by the BizTalkServiceInstance covers a different scenario.
[ServiceContract(Namespace = "http://www.microsoft.com/biztalk/2006/r2/wcf-adapter")]
public interface IOneWayAsync
{
// Methods
[OperationContract(AsyncPattern = true, IsOneWay = true, Action = "*")]
IAsyncResult BeginOneWayMethod(Message message, AsyncCallback callback, object state);
[OperationContract(IsOneWay = true, Action = "BizTalkSubmit")]
Page 21
void BizTalkSubmit(Message message);
void EndOneWayMethod(IAsyncResult result);
}
[ServiceContract(Namespace = "http://www.microsoft.com/biztalk/2006/r2/wcf-adapter")]
public interface IOneWayAsyncTxn
{
// Methods
[OperationContract(AsyncPattern = true, IsOneWay = true, Action = "*")]
IAsyncResult BeginOneWayMethod(Message message, AsyncCallback callback, object state);
[OperationContract(IsOneWay = true, Action = "BizTalkSubmit")]
void BizTalkSubmit(Message message);
void EndOneWayMethod(IAsyncResult result);
}
[ServiceContract(Namespace = "http://www.microsoft.com/biztalk/2006/r2/wcf-adapter")]
public interface ITwoWayAsync
{
// Methods
[OperationContract(AsyncPattern = true, IsOneWay = false, Action = "*", ReplyAction =
"*")]
IAsyncResult BeginTwoWayMethod(Message message, AsyncCallback callback, object state);
[OperationContract(IsOneWay = false, Action = "BizTalkSubmit")]
Message BizTalkSubmit(Message message);
Message EndTwoWayMethod(IAsyncResult result);
}
[ServiceContract(Namespace = "http://www.microsoft.com/biztalk/2006/r2/wcf-adapter")]
public interface ITwoWayAsyncVoid
{
// Methods
[OperationContract(AsyncPattern = true, IsOneWay = false, Action = "*", ReplyAction =
"*")]
IAsyncResult BeginTwoWayMethod(Message message, AsyncCallback callback, object state);
[OperationContract(IsOneWay = false, Action = "BizTalkSubmit")]
void BizTalkSubmit(Message message);
void EndTwoWayMethod(IAsyncResult result);
}
[ServiceContract(Namespace = "http://www.microsoft.com/biztalk/2006/r2/wcf-adapter")]
public interface ITwoWayAsyncVoidTxn
{
// Methods
[TransactionFlow(TransactionFlowOption.Mandatory), OperationContract(AsyncPattern =
true, IsOneWay = false, Action = "*", ReplyAction = "*")]
IAsyncResult BeginTwoWayMethod(Message message, AsyncCallback callback, object state);
[TransactionFlow(TransactionFlowOption.Mandatory), OperationContract(IsOneWay = false,
Action = "BizTalkSubmit")]
void BizTalkSubmit(Message message);
void EndTwoWayMethod(IAsyncResult result);
}
As you can easily see in the code above, all the service contracts implemented by the BizTalkServiceInstance Class are generic and asynchronous. In fact, one-way service operations are decorated with [OperationContract(AsyncPattern = true, IsOneWay = true, Action = "*")] attribute, while request-response methods are decorated with the [OperationContract(AsyncPattern = true, IsOneWay = false, Action = "*", ReplyAction = "*")] attribute. Besides, they receive a generic inbound message of type System.ServiceModel.Channels.Message and eventually return a message of the same type.
Page 22
As a consequence, these methods can accept any request message and eventually process any reply message. However, since these operations are generic and untyped, they are not decorated by any FaultContractAttribute. As a consequence, WCF Receive Locations cannot return typed fault exceptions. Since every WCF Receive Location is implemented as an instance of the BizTalkServiceInstance and this class cannot be customized or inherited to expose typed service contracts, BizTalk Server does not natively support throwing typed fault exceptions within orchestrations published as WCF services or more in general throwing typed fault exceptions within a WCF Receive Location.
At this point a question arises: is there any workaround to throw typed fault exceptions within orchestrations published as WCF services? The answer, fortunately, is yes.
The Solution
The WCF-Custom and WCF-CustomIsolated Adapters provided by BizTalk Server 2006 R2 and BizTalk Server 2009 allow to define a custom WCF binding configuration to meet your precise communication needs. These adapters can be used to define custom WCF configurations for Send Ports or Receive Locations and extend their standard functionality using custom components as endpoint and service behaviors, message inspectors, custom bindings, binding elements, channels, etc. Therefore, I decided to create the following custom components:
Microsoft.BizTalk.CAT.Samples.PublishTypedFaults.WsdlExportExtensions assembly: flattens and extends the WSDL generated by the BizTalk WCF Service Publishing Wizard to enable WCF Receive locations to expose typed soap faults.
Microsoft.BizTalk.CAT.Samples.PublishTypedFaults.MessageInspector assembly: intercepts a reply message and when this latter is a fault, it creates and returns a typed fault message.
The following picture depicts the architecture of the proof of concept I implemented to test these components:
1. A WCF-CustomIsolated Request-Response Receive Location receives a new xml document from a client application.
2. The XML disassembler component within the XMLTransmit pipeline promotes the MsgType context property. The Message Agent submits the incoming message to the MessageBox (BizTalkMsgBoxDb).
Page 23
3. The inbound request starts a new instance of the HelloWorld orchestration type. 4. The orchestration checks the incoming HelloWorldRequest message, and if the Name
element is null or empty, it creates and return a new fault message of type CustomError. Otherwise, the orchestration returns a reply message of type HelloWorldResponse.
5. The HelloWorld orchestration publishes the reply message to the MessageBox (BizTalkMsgBoxDb).
6. The response message is retrieved by the WCF-CustomIsolated Request-Response Receive Location.
7. The reply message is processed by the CustomErrorMessageInspector component. If the response is a fault message, it creates a new typed fault message using the configuration data set on the Receive Location.
8. The reply message is returned to the client application.
The following picture shows the XML Schema which defines the CustomError typed fault.
The following figure shows the configuration of the WCF-CustomIsolated Request-Response Receive Location.
Page 24
Page 25
The Receive Location exposes an endpoint that uses the WsHttpBinding and make use of the serviceThrottling service behavior (see System.ServiceModel.Description.ServiceThrottlingBehavior for more information) and 2 custom endpoint behaviors:
customError wsdlExport
These components must be configured in the machine.config as follows:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
...
<system.serviceModel>
...
<extensions>
<behaviorExtensions>
...
<add name="customError"
type="Microsoft.BizTalk.CAT.Samples.PublishTypedFaults.MessageInspector.CustomErrorBehaviorExte
nsionElement,
Microsoft.BizTalk.CAT.Samples.PublishTypedFaults.MessageInspector, Version=1.0.0.0,
Culture=neutral,
PublicKeyToken=d7f63d8d08d8f3a2" />
Page 26
<add name="wsdlExport"
type="Microsoft.BizTalk.CAT.Samples.PublishTypedFaults.WsdlExportExtensions.WsdlExportBehaviorE
xtensionElement,
Microsoft.BizTalk.CAT.Samples.PublishTypedFaults.WsdlExportExtensions, Version=1.0.0.0,
Culture=neutral,
PublicKeyToken=d7f63d8d08d8f3a2" />
</behaviorExtensions>
</extensions>
</system.serviceModel>
</configuration>
The “Include exception detail in faults” option must be set on the Messages tab to enable the WCF Receive Location to return the error detail in fault messages. Below you can see the code of the CustomErrorMessageInspector component. The constructor retrieves configuration data from the Receive Port configuration, while the IDispatchMessageInspector::BeforeSendReply method intercepts the reply message and if this latter is a fault, it generates a typed fault exception using the configuration data.
namespace Microsoft.BizTalk.CAT.Samples.PublishTypedFaults.MessageInspector
{
/// <summary>
/// This class can be customized to create a message inspector.
/// </summary>
public class CustomErrorMessageInspector : IDispatchMessageInspector,
IClientMessageInspector
{
#region Private Constants
...
#endregion
#region Private Fields
...
#endregion
#region Public Constructors
public CustomErrorMessageInspector(bool enabled,
bool traceEnabled,
int maxBufferSize,
string typedFaults)
{
this.enabled = enabled;
this.traceEnabled = traceEnabled;
this.maxBufferSize = maxBufferSize;
this.typedFaults = typedFaults;
try
{
if (!string.IsNullOrEmpty(typedFaults))
{
TypedFaults faultData = SerializationHelper.XmlDeserialize(typedFaults,
typeof(TypedFaults)) as TypedFaults;
if (faultData != null &&
faultData.FaultList != null &&
faultData.FaultList.Count > 0)
{
for (int i = 0; i < faultData.FaultList.Count; i++)
{
if (!string.IsNullOrEmpty(faultData.FaultList[i].Action) &&
Page 27
!string.IsNullOrEmpty(faultData.FaultList[i].Name))
{
faults.Add(string.Format(MessageTypeFormat,
faultData.FaultList[i].Namespace,
faultData.FaultList[i].Name ??
string.Empty),
new
CustomErrorFaultInfo(faultData.FaultList[i].Action,
faultData.FaultList[i].Reason));
}
}
}
}
}
catch (Exception ex)
{
EventLog.WriteEntry(Source, ex.Message, EventLogEntryType.Error);
}
}
#endregion
#region IDispatchMessageInspector Members
public object AfterReceiveRequest(ref Message request, IClientChannel channel,
InstanceContext instanceContext)
{
return request.Headers.Action;
}
public void BeforeSendReply(ref Message reply, object correlationState)
{
try
{
if (enabled &&
reply.IsFault &&
string.Compare(((string)correlationState), TransferGetNamespace, true) !=
0)
{
string action = correlationState as string;
MessageFault fault = MessageFault.CreateFault(reply, maxBufferSize);
string detail = fault.Reason.ToString();
CustomErrorMessageFault faultMessage = new CustomErrorMessageFault(faults,
new
FaultCode(FaultCodeName), detail, traceEnabled);
Message message = Message.CreateMessage(reply.Version, faultMessage, null);
message.Headers.CopyHeadersFrom(reply.Headers);
message.Properties.CopyProperties(reply.Properties);
if (string.IsNullOrEmpty(faultMessage.Action))
{
message.Headers.Action = action;
}
else
{
message.Headers.Action = faultMessage.Action;
}
reply = message;
}
}
catch (Exception ex)
{
EventLog.WriteEntry(Source, ex.Message, EventLogEntryType.Error);
throw ex;
Page 28
}
return;
}
#endregion
#region IClientMessageInspector Members
public void AfterReceiveReply(ref Message reply, object correlationState)
{
return;
}
public object BeforeSendRequest(ref Message request, IClientChannel channel)
{
return null;
}
#endregion
}
}
The following table contains the XML snippet used as configuration data for the CustomErrorMessageInspector component. As you can see, it allows defining multiple typed faults in a declarative way. At runtime it will use this data to recognize a fault reply message and accordingly set the Action and Reason properties of the fault message returned.
<TypedFaults xmlns="http://microsoft.biztalk.cat/10/typedfaults">
<TypedFault>
<Action>SayHello</Action>
<Name>CustomError</Name>
<Namespace>http://microsoft.biztalk.cat/10/customerror</Namespace>
<Reason>Custom Error</Reason>
</TypedFault>
</TypedFaults>
If you set the TraceEnabled property to true, at runtime the CustomErrorMessageInspector component will produce a trace that you can intercept and review with a tool such as Debug as shown in the picture below.
Page 29
The WCF-Receive Location can be created using the BizTalk WCF Service Publishing Wizard. In particular, this allows to create a WCF Receive Location to expose the HelloWorld orchestration as a WCF service. Moreover, setting the Enable metadata endpoint option it’s possible to enable the WCF Receive Location to expose a Metadata Endpoint.
This allows a developer to use Visual Studio or a tool such as svcutil to generate a proxy class to invoke the WCF Receive Location. Now, let’s say that you want to create a WCF client application to invoke the WCF Receive Location. Within Visual Studio you can create a new Windows Application, right-click the project inside the Solution Explorer and then select “Add Service Reference”. If the WCF Receive Location exposes a Metadata Endpoint, this operation will create a proxy class to invoke the corresponding WCF web service. However, if you review the code and in particular the contract interface, you’ll realize that the SayHello method is not decorated with a FaultContractAttribute. This is due to the fact, that since BizTalk Server does not support throwing typed fault exceptions, the native wsdl returned by the Metadata Endpoint exposed by the WCF Receive location does not contain any soap fault message. In order to sort out this problem, you can adopt one of the following techniques:
Create and expose a custom wsdl that contains the definition of your typed soap faults. Create a custom endpoint behavior to dynamically modify the wsdl produced by BizTalk.
The first technique is quite straightforward:
You manually define a custom wsdl using a text or xml editor. You publish the resulting wsdl file to IIS (e.g. http://localhost/samples/service.wsdl) You configure your WCF-Custom or WCF-CustomIsolated Receive Location to expose
metadata and in particular the newly created wsdl file.
Page 30
In order to accomplish the finale step, you can proceed as follows:
Start the BizTalk Server Administration Console. Open your WCF-Custom/WCF-CustomIsolated Receive Location. Click the Configure button in the Transport section. Click the Behavior tab. Right-click the Service Behavior node and choose to Add Extension. In the Select Behavior Extension window, choose the serviceMetadata component. Set the value of the httpGetEnabled property of the serviceMetadata behavior to True
(see the picture below). Set the value of the externalMetadataLocation property of the serviceMetadata behavior
to the url of your hand-built wsdl (see the picture below).
The second technique consists in creating a custom component called WsdlExtensions to modify at run-time the wsdl returned by the Metadata Endpoint exposed by a WCF-
Page 31
Custom/WCF-CustomIsolated Receive location. This component is implemented as an a custom endpoint behavior and it can be used along with any WCF-Custom or WCF-CustomIsolated Receive Location, as shown in the picture below.
The WsdlExtensions property exposed by the component accepts an XML snippet that allows to specify how the wsdl has to be customized at runtime.
<WsdlExtensions xmlns="http://microsoft.biztalk.cat/10/wsdlextensions">
<Prefix>bts</Prefix>
<XmlSchemas>
<XmlSchema>
<Name>CustomError</Name>
<Namespace>http://microsoft.biztalk.cat/10/customerror</Namespace>
</XmlSchema>
</XmlSchemas>
<Messages>
Page 32
<Message>
<Name>HelloWorld_SayHello_CustomErrorFault_FaultMessage</Name>
<Namespace>http://microsoft.biztalk.cat/10/customerror</Namespace>
<Parts>
<Part>
<Name>detail</Name>
<Element>CustomError</Element>
</Part>
</Parts>
</Message>
</Messages>
<PortTypes>
<PortType>
<Name>HelloWorld</Name>
<Operations>
<Operation>
<Name>SayHello</Name>
<Faults>
<Fault>
<Name>CustomErrorFault</Name>
<Message>HelloWorld_SayHello_CustomErrorFault_FaultMessage</Message>
</Fault> </Faults> </Operation> </Operations>
</PortType> </PortTypes></WsdlExtensions>
As shown in the picture above, the components allows to define the following information:
The prefix for the namespace of new messages created inside the wsdl. One or multiple Xml Schemas each defining a different typed fault. These schemas must
be deployed to BizTalk. At runtime, the component is able to retrieve the content of each schema from the BizTalkMgmtDb that subsequently is inserted in the outbound wsdl.
One or multiple fault messages, each containing one or multiple parts. One or multiple operation-fault associations. At runtime the component search through
the original wsdl structure and creates faults accordingly.
At runtime the WsdlExtensions component validates the XML configuration specified on the port and if the TraceEnabled property is set to true, it produces a trace with a tool such as Debug as shown in the picture below.
Formatted: Font: (Default) Times NewRoman, 12 pt, Font color: Blue
Page 33
The following picture shows the wsdl produced by the WsdlExtensions component at runtime. In particular, the parts added by the component are highlighted by a red frame.
Page 34
Page 35
Note: Flattening the wsdl to include the XML schemas used to define messages allows to make the wsdl document compatible with non-Microsoft development environments. In fact, Visual Studio supports import and include directives in a wsdl, but some non-Microsoft development environments are not able to consume the wsdl exposed by a WCF web service.
Note: the XML Schemas defining the structure of the XML configuration data consumed at runtime respectively by the CustomErrorMessageInspector and by the WsdlExportEndpointBehavior can be found inside the BehaviorSchemas project. The corresponding assembly doesn’t need to be deployed to BizTalk Server.
Proof of Concept in Action
In order to test the WCF custom components, I created a WinForms application. In particular, when I leave the Name textbox blank and press the Call button, the HelloWorld orchestration returns a fault message. The client application intercepts the error with a catch (FaultException<HelloWorldBizTalk.CustomError> ex) block and opens a MessageBox to show the detail of the exception.
Show me the code!
At this point, you are probably saying “ok, cool, where’s the code”?
Well, I packaged the code in 2 different flavors:
- BizTalk Server 2009
- BizTalk Server 2006 R2
Page 36
Obviously, everything there are many ways to implement the same functionalities, so I’d be glad if you could leave a message on my blog(http://blogs.msdn.com/paolos/) and let me know how you used/customized/improved my code. Enjoy! ;-)
Page 37
BizTalk Resources We will use this section to document other BizTalk resources.
BizTalk 24x7 This site has a lot of great information about Books, Technical articles, Vides, blogs, Tools related to
BizTalk.
http://www.biztalk247.com/
BizTalk Gurus This is another BizTalk community site. You can sign up for their newsletter too.
http://www.biztalkgurus.com/
BizTalk Server Customer Advisory Team This team consists folks with deep knowledge about BizTalk. They have produced excellent
documentation about BizTalk operations, performance optimization etc.
http://msdn.microsoft.com/en-us/biztalk/dd876758.aspx
Recently Released Documentation
BizTalk Server 2009 Install Documentation - June 2009 Update
http://msdn.microsoft.com/en-us/biztalk/dd876758.aspx
BizTalk Server 2009 Operations Guide - July 2009
This document is a collaboration of Technical folks with real-world experience. Anyone working with BizTalk will find invaluable information in this guide.
Download it here
http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=46a77327-affb-4ca2-9451-67912babbb03
Read it online
Page 38
http://msdn.microsoft.com/en-us/library/ee308947(BTS.10).aspx
Page 39
Microsoft Dynamics AX integration using Microsoft BizTalk Server By Ashish Mehndi, Consultant, Global Services, Microsoft
Introduction
Microsoft Dynamics AX is a global, adaptable business management solution that enables
organizations to make business decisions with greater confidence. By automating and streamlining
financial, customer relationship and supply chain processes, Microsoft Dynamics AX brings together
people, processes and technologies, increasing the productivity and effectiveness of the business
and helping to drive business success.
In today’s business environment all enterprises make extensive use of computer systems and
applications in order to establish and maintain a competitive advantage. In order for these
applications and systems to provide the desired advantage it is essential to ensure that the
resources are available to all users and business processes that may benefit from the use. To ensure
the same, these applications should be fully integrated to seamlessly flow the information across
and pool the available resources to maximize the benefits. And here fits Microsoft BizTalk Server as
a Business process management Server that enables companies to integrate, automate and
manage Business processes.
Enabling businesses to expose processes and data in real-time, BizTalk Server helps organizations to
optimize business processes, decreasing costs and eliminating inefficiencies. By providing simple
yet powerful tools to gain a real-time understanding of business processes, BizTalk enables
organizations to grow their business.
This article focuses on how to integrate Microsoft Dynamics AX using Microsoft BizTalk Server. But
before we dwell into the details of integration it is important to understand the features provided
by Dynamics AX and BizTalk Server to integrate seamlessly and making sure that they have been
installed appropriately.
Microsoft Dynamics AX provides Application Integration Framework (AIF):
Application Integration Framework (AIF) provides an extensible framework that supports multiple
asynchronous transports, as well as synchronous transport using Web services, to reliably exchange
Page 40
documents in XML format with trading partners or other systems. An exchange starts with a
document, that is, a document class defined using Microsoft Dynamics AX business logic. The
document is serialized into XML and header information is added to create a message, which may
then be transferred into or out of your Microsoft Dynamics AX system (called the local endpoint
within AIF). The other entity taking part in the exchanges is called the endpoint.
Microsoft Dynamics AX Adapter provided by Microsoft BizTalk Server:
BizTalk adapters extend the functionality of BizTalk Server, enabling it to connect to other servers,
applications and Web services. Specifically, they remove the need to develop infrastructure
components such as network protocol support and translation, data conversion, data
transformation, in the development of business process automation solutions. BizTalk Server
adapters are "no-code" connectivity solutions, and are provided in-box with BizTalk Server.
The Microsoft Dynamics AX Adapter for BizTalk can be installed on the BizTalk machine using the
Dynamics AX setup. After running the Dynamics AX setup on the BizTalk machine the following
steps needs to be followed:
1. On the Select installation type page, click Custom installation, and then click Next. 2. On the Select Computer Role page, under Application integration gateway, select BizTalk
adapter, and then click Next. 3. On the Installing page, you can monitor installation progress as Setup proceeds. 4. On the Completing Microsoft Dynamics AX Setup page, you can review the summary of roles
installed on the computer. 5. To exit the Microsoft Dynamics AX Setup wizard, click Finish.
Customers use these adapters to connect these applications and automate processes that may
span applications or organizational boundaries.
Page 41
The Microsoft Dynamics AX Adapter for BizTalk Server supports both Inbound and outbound
message processing.
Inbound message processing: An external system sends a message through a BizTalk Server
adapter. The AIF gateway receives service polls for messages and then brings them into the
gateway queue. The AIF inbound processing service takes the messages from the gateway queue.
Next, the business logic in the AIF document service processes the message and interacts with the
internal Microsoft Dynamics AX database.
Outbound message processing: The AIF outbound processing service processes send requests using
the document services and places the outbound messages in the gateway queue. The AIF gateway
send service then reads the messages from the gateway queue and sends them out using a
transport adapter. These transports adapters include Microsoft Message Queuing (MSMQ), the file
system, or other BizTalk Server adapter. The external system then receives the message from the
appropriate transport.
This article details on configuration operations related to the integration of Dynamics AX using
BizTalk Server and covers both inbound as well as outbound message exchange. Further it also
covers the basic guidance on where to look for errors in case of unexpected situations.
Configuring Microsoft Dynamics AX Adapter for BizTalk
Terminology This section explains the concepts used in the AIF.
Term Description
adapter A software component that enables message exchange using a specific transport. In AIF, an adapter means a transport adapter.
channel A named entity used to specify where and how to send and receive messages. A channel specifies an adapter with its associated configuration information and transport address.
endpoint A company or entity that participates in a business-to-business (B2B) or application-to-application (A2A) data exchange. An endpoint can be an in-house independent system, in the case of A2A.
endpoint action policy Determines which actions are valid for a particular endpoint. An action is bound to an endpoint using an endpoint action policy.
Page 42
gateway queue Provides temporary storage for documents while they wait for processing. Inbound messages are placed in a gateway queue by an inbound transport adapter. Outbound messages wait in a gateway queue until an outbound transport adapter picks it up for sending.
message An individual unit of data transported between endpoint locations. A message consists of a document plus a header containing information about the transfer.
document class An X++ class (prefixed with Axd) with methods that perform actions on documents.
pipeline processor The pipeline processor enables transformations of the inbound/outbound XML before/after the Microsoft Dynamics AX document class acts on the document. Components are provided in the base Microsoft Dynamics AX system for data value substitution and XSLT document transformations.
Web services A unit of application logic that provides data and services to other applications that clients invoke by using the Simple Object Access Protocol (SOAP) over the Hypertext Transfer Protocol (HTTP). Web services can perform functions ranging from simple requests to complicated business processes.
Configuring Microsoft Dynamics AX – Application Integration Framework (AIF) In order to integrate BizTalk with Microsoft Dynamics AX we need to configure the Application Integration Framework which acts as a bridge between the two. The following steps lists down the steps to set up the Application Integration Framework which exposes data to BizTalk Microsoft Dynamics AX adapter.
1. Start the Microsoft Dynamics AX client, and browse to the Basic Module (as shown below):
Page 43
2. Create the Local Endpoint or make sure that the Local Endpoint is configured:
A local endpoint is the origination for sent messages and the destination for received
messages. There may be more than one local endpoint, depending on how many companies
are configured for your Microsoft Dynamics AX installation.
a. Click Basic Setup Application Integration Framework Local endpoints. b. Press CTRL+N to create a new local endpoint record. c. Select a company from the Company field. d. Enter a name for the endpoint in the Local endpoint field. e. The name for the local endpoint should be representative of the Microsoft Dynamics
AX company name that participates in the exchange. f. Press CTRL+S to save the data.
Page 44
3. Configure an adapter
The following adapters are available after installing Microsoft Dynamics AX:
a. AifFileSystemAdapter
b. AifMSMQAdapter
c. AifWebServiceAdapter
d. AifBizTalkAdapter
Channels define the transport method that enables messages to move in and out of the framework to reach the endpoint. We need to configure adapter to use the channels in order to enable messages reach the endpoint. To configure an adapter for use in a channel, you activate it and specify its direction (inbound, outbound, or both) on the Transport adapters form. Ensure that Transport Adapter is configured for AifBizTalkAdapter.
Page 45
a. Click Basic Setup Application Integration Framework Transport Adapters. b. Press CTRL+N to create a new transport adapter record. c. Select the AifBizTalkAdapter from the list of Adapter classes available.
d. Enter a Name and make it active by selecting the “Active” checkbox (that is shown in the above figure as “A”), so that it is available for use.
e. The default value for AifBizTalkAdapter is “Receive and Respond” and this cannot be changed (as AifBizTalkAdapter is used for both sending and receiving data between BizTalk and Microsoft Dynamics AX).
Page 46
4. Creating and configuring channels
Channels define the transport method that enables messages to move in and out of the framework to reach the endpoint. Before configuring a channel, a transport adapter must be available.
Channels may support inbound transfers only, outbound only, or both. Configuration settings are different depending on the direction for the transfer in the channel as well as for different adapters. Inbound channels may use a response channel that handles verification or error responses to inbound transfers.
a. Click Basic Setup Application Integration Framework Channels.
b. Press CTRL+N to create a new channel.
c. Select an adapter in the Adapter field.
You must first have activated an adapter on the Transport adapters form before it appears in the list of available adapters.
d. Enter the unique identification information for the new channel, including an identifier in the Channel ID field and a friendly name in the Name field.
a. Provide the channel ID as “BizTalkChannel”
b. Provide the friendly Name as “BizTalkChannel”
e. To activate the channel and allow it to participate in document exchanges, click Active (or “A” as shown in the figure).
f. Configure the address for the adapter.
a. Provide the address as “BizTalkChannel”
Page 47
g. Select from the available directions for the transfers to be performed in this channel. The list of available directions depends on the adapter.
a. Provide the direction as “Both”
h. If the direction is set to Inbound / Both, you can select a response channel.
Inbound channels can use an outbound channel called a "response channel" to transfer or "respond back" to the source endpoint with verification results or error responses to inbound transfers.
i. On the General tab, set the Maximum batch size to the maximum number of messages to be processed at one time from the queues. You can select Unlimited if you do not want to limit this number.
j. Press CTRL + S to save the created / configured channel.
k. Now select the Channel created and press “Configure”, and enter the BizTalk Server
groups that you want AX to connect to:
Page 48
l. Enter the names of the computers running BizTalk Server that belong to the specified BizTalk group. Press CTRL+N to add each server to the list.
m. Press CTRL+S to save the channel.
5. Configure an action:
An action refers to the document and the operation to be performed on it, such as Send or Receive.
a. Click Basic Setup Application Integration Framework Action.
Page 49
b. To register all actions for document classes that exist, click Scan and register.
c. After all items are scanned and registered, select “Enabled” (in above figure the checkboxes with Column named as “E…”) to enable the actions you need for your
exchange.
Enable the action corresponding to the Interface, for example: “createListVendTable” for Interface 32.
6. Creating and configuring endpoints
Using Application Integration Framework (AIF), you enable document exchanges between endpoints and the local endpoint. A local endpoint is the origination for sent messages and the destination for received messages. That is, the local endpoint refers to your Microsoft Dynamics AX installation.
An endpoint is the destination for an outbound document and the source of an incoming document. That is, an endpoint represents your trading partner in a document exchange.
Before you can configure an endpoint, the following must already exist and be configured:
a. A local endpoint.
b. A named action for the exchange, consisting of a document and a description of the operation to be performed on it.
c. Microsoft Dynamics AX users to be associated with the endpoint.
d. An outbound channel must be already be defined if needed.
Steps to configure / create endpoint:
a. Click Basic Setup Application Integration Framework Endpoints.
b. Press CTRL+N to create a new endpoint, or select an existing endpoint from the list to be modified.
Page 50
c. Enter a unique Endpoint ID and user friendly name.
i. Enter Endpoint ID as “Inbound Vendors”. (an example)
ii. Enter friendly name as “Inbound Vendors”. (an example)
d. Go to “Constraints” tab and select “No Constraints” checkbox (as shown in figure below
e. Go back to the “Overview” tab, and select / provide the “Local endpoint ID”
from the list of local endpoint configured. (for example “AMC” as shown in figure below)
f. Now click on the “General” tab and select the “Outbound channel ID” from the list of Channels already configured (for example “BizTalkChannel” as shown below)
Page 51
e. Configure Action Policies:
To enable exchange of documents for endpoints, select which actions an endpoint may perform. This process is called configuring endpoint action policies.
a. To Configure the Action Policies for the End Point and associate action and endpoint, click on the “Action Policies”
i. Press CTRL + N to create a new Endpoint Action policy and select from the List of Actions displayed
Page 52
ii. Set the Status as “Enabled” and Logging Mode as “Log All”
f. Configure Action Data Policies:
A document is made up of many data fields. When you set up a document exchange, you decide, on a field-by-field basis, which data fields are transferred. This is known as the data policy. You configure the data policy on the Data Policies form.
a. To Configure the Action Data Policies for each of the Action Policies configured above.
Page 53
i. Select the Action Id in the window shown in figure above and click on Data Policies.
ii. Enable the fields as per the schema / requirements of the Interface
iii. Mark the fields as required which are not Optional as part of the Interface requirements / schemas.
g. Configure an endpoint user
You must enter information for at least one endpoint user or trusted intermediary who is authorized to initiate transactions for the endpoint on the Users tab.
Follow the steps mentioned below:
a. Click the Users tab.
b. Under Endpoint users, in the User type field, select either User or User group.
c. In the Application user or group field, select a valid Microsoft Dynamics AX user or user group name
For our purpose on the Users Tab follow the steps below:
i. On the “Users” tab, press (CTRL + N) for associating the new User /
Groups
ii. Select “User Group” under User type and “Admin” from the list under
Application user or group
Page 54
In order for the Application Integration Framework (AIF) to begin sending and receiving
documents with adapters, four services must be running as batch jobs within Microsoft
Dynamics AX:
a. AIFOutboundProcessingService b. AIFInboundProcessingService c. GatewaySendService d. GatewayReceiveService
Until these batch jobs are started, no documents can be processed in adapter-based exchanges.
Inbound documents do not enter your Microsoft Dynamics AX system and outbound documents
accumulate in the AIF outbound processing queue.
Refer the link below for more details.
http://msdn.microsoft.com/en-us/library/aa570105(AX.10).aspx
Send Data from BizTalk to Dynamics AX Interface 32 sends data to Microsoft Dynamics AX.
The following configuration needs to be performed in BizTalk Send Port which would send the data from the BizTalk Server to the Microsoft Dynamics AX using the Application Integration Framework (AIF):
Page 55
1. Create a New Send Port or use an existing Send Port (in case Orchestration is used).
2. Select the Transport Type as “Microsoft Dynamics AX”, and provide the details like Send
Handler, Send pipeline and Receive pipeline as per the requirements of the Interface.
3. Press “Configure” and set the following properties:
a. Set “Authentication Type” = “Host User”
b. Set “Gateway User” as BizTalk user under which the BizTalk Host Instance is
executing.
c. Set “AOS Server” to the name of “Dynamics AX Server”
d. Set “AOS Port” to the port number on which of Dynamics AX Server is running – the default is 2712.
Page 56
4. Please refer “Appendix A – Configuring Message Properties for sending data to Microsoft Dynamics AX”.
Receive Data from Dynamics AX in BizTalk
Microsoft Dynamics AX adapter pulls the data available in the Dynamics AX Queue and publishes
it into the Message Box. In one BizTalk Group there can be only one Receive Location that points
to a combination of AOS Server Name and AOS Port Number. You can create multiple receive
locations that points to different AOS Server and Port combination. BizTalk Server receive
location can receive different messages from the same AOS Server & Port combination and can
route the same do different BizTalk artifacts based upon the filters.
The following configuration needs to be performed in BizTalk Receive Port / Receive Location
which would receive the data from Microsoft Dynamics AX using the Application Integration
Framework (AIF) and publish the same into BizTalk Message Box:
1. A Static One Way port needs to be created under Receive Port in BizTalk Application
Page 57
2. The following provides the configuration for Receive Location –
a. Select the Transport Type as “Microsoft Dynamics AX”, also choose the Receive
handler and Receive pipeline as per the business requirement.
Page 58
b. Press “Configure” and set the following properties:
i. Set “Authentication Type” = “Host User”
ii. Set “Gateway User” as BizTalk user under which the BizTalk Host Instance
is executing.
iii. Set “AOS Server” to the name of “Dynamics AX Server”
iv. Set “AOS Port” to the port number on which of Dynamics AX Server is running – the default is 2712.
Page 59
Error Handling and Messages
Categories of Exceptions related to BizTalk / Dynamics AX Interfaces
1. When error Event Source: “Microsoft Dynamics AX adapter”
a. Refer the Microsoft Dynamics AX Server Event Log for more details
b. Refer the Microsoft Dynamics AX Exceptions
2. When error Event Source: “Microsoft BizTalk Server” / “Company.EAI.BizTalk”
a. This category of error is related to some error in Transformation, Orchestration or Transport.
b. Refer the BizTalk Administration Console for more details.
Microsoft BizTalk Server
(Event Source: “Microsoft BizTalk Server”)
This section provides the information on the exceptions that gets logged by BizTalk in case of erroneous conditions for Microsoft Dynamics AX interfaces.
Page 60
All the Exceptions that occur in Microsoft BizTalk Server are logged in Event Log of the BizTalk Server machine. These exceptions are logged on the Machine based upon the Host Instance configuration.
Apart from the Error / Detailed exception the Message / Orchestration (in case orchestration is used for processing and routing the message) also gets “SUSPENDED” as either Resume-able
or Non-Resume able state based upon the category and nature of the Exception.
The following sections detail the steps to be followed in case the error Event Source is “Microsoft BizTalk Server”.
1.1.1.1 Error Handling for data being sent to Microsoft Dynamics AX from BizTalk Server
1. Error occurs in the Interface which sends data to Microsoft Dynamics AX.
a. Case I: If the error occurs while transforming the data received from the Source
Systems into Canonical Message.
i. In this case the message would get suspended.
ii. The suspended messages can be retrieved using Microsoft BizTalk Server Administration Console.
iii. If the message needs to be replayed without any correction and is resume-able, then right-click click on the Suspended Message and click on “Resume Instance”.
Page 61
iv. If the message needs to be corrected, then the data needs to be altered in Source System and reposted to BizTalk.
b. Case 2: If the error occurs after the data has been transformed into the standardized or canonical format Canonical
i. The Interface would output / dump the Canonical Message to a configured location as per the Send Error Port.
ii. After correcting the issue in the Canonical Message the file can be replayed using the configured Error Replay folder.
Page 62
iii. Drop the Canonical Message at above configured location. Microsoft BizTalk Server would route the corrected canonical to the right Interface and perform the required transformations.
1.1.1.2 Error Handling for data being received from Microsoft Dynamics AX into BizTalk Server
2. Error occurs in the Interface which receives data from Microsoft Dynamics AX.
a. Case I: If the error occurs while transforming the data received from the Microsoft
Dynamics AX.
i. In this case the message would get suspended.
ii. The suspended messages can be retrieved using Microsoft BizTalk Server Administration Console.
Page 63
iii. If the message needs to be replayed without any correction and is resume-able, then right-click click on the Suspended Message, and click “Resume Instance”.
iv. If the message needs to be corrected, then the data needs to be altered in Microsoft Dynamics AX and reposted (refer Section 2.4.3.4 Repost Messages)
b. Case 2: If the error occurs after the data received from the Microsoft Dynamics AX
has been transformed into the Canonical (for Interface with Orchestration).
i. The Interface would output / dump the Canonical Message to a configured location as per the Send Error Port.
Page 64
ii. After correcting the issue in the Canonical Message the file can be replayed using the configured Error Replay folder.
Page 65
iii. Drop the Canonical File at above configured location. Microsoft BizTalk Server would route the corrected canonical to the right Interface and perform the required transformations.
c. Case 3: If the error occurs after the data received from the Microsoft Dynamics AX
has been transformed into the Canonical (for Interface without Orchestration).
i. In this case the message would get suspended.
ii. The suspended messages can be retrieved using Microsoft BizTalk Server Administration Console.
Page 66
iii. If the message needs to be replayed without any correction and is resume-able, then right-click click on the Suspended Message, and click on “Resume Instance”.
iv. If the message needs to be corrected then double click on any Suspended Message
Page 68
vii. Click on Body and copy the Message and store it on the Hard disk.
viii. Correct the message and rename the file as per the Interface (refer the Design Document for the corresponding Interface for the same)
ix. Drop the file at above configured location which is being monitored by BizTalk Server for existence of any new inputs (e.g. “C:\ErrorReplay” folder).
Microsoft BizTalk Server would route the corrected canonical to the right Interface and perform the required transformations.
Microsoft Dynamics AX (Event Source: “Microsoft Dynamics AX adapter”)
1.1.1.3 Queue Manager
The Queue Manager is internal queue maintained in Microsoft Dynamics AX. This Queue is the bridge between Dynamics AX and external systems.
All the messages sent from other systems or needs to be sent to external systems from Microsoft Dynamics AX goes through the Queue. The Queue Manager UI lets you monitor the messages sent to / from Dynamics AX.
The erroneous messages are not moved out of the Queue Manager and can be tracked using the User Interface as shown below:
Steps to monitor data under Queue Manager:
Page 69
1. Under Basic module, click on “Periodic” “Application Integration Framework” “Queue Manager”
1.1.1.4 Document History
The Document History maintains the history of all the messages sent to / from the Microsoft Dynamics AX. It’s a kind of Log of messages.
Steps to view data under Document History:
1. Under Basic module, click on “Periodic” “Application Integration Framework” “Document History”
Page 70
1.1.1.5 Exceptions
The exception view provides the details of Exceptions that occurred while processing messages received by Microsoft Dynamics AX. This view only provides the details of exceptions raised by Microsoft Dynamics AX.
1. Under Basic module, click on “Periodic” “Application Integration Framework” “Exceptions”
2. To view the details of the Exception, right click and select Record Info, then select Show All Fields. This would display the details of the Exception as below:
Page 71
1.1.1.6 Repost Messages
Microsoft Dynamics AX would be sending data to Microsoft BizTalk Server using Application Integration Framework (AIF). In case the any exception occurs while transmitting the data through AIF, the exception gets logged in the exception list as mentioned above.
Microsoft Dynamics AX would be configured to auto send the new / updated data to BizTalk Server. This would be done by configuring and executing Batch in Dynamics AX.
In case of errors, the administrators can repost the data using the Microsoft Dynamics AX UI. The batch still needs to run which actually post the data into the Dynamics AX Queue from where the BizTalk Adapter would pick the data and send the same to the Message Box.
The steps below detail the how to post an Invoice data manually, this posting of Invoices can be done in case there has been an exception in the batch process which posting invoices:
1. Click on the “Accounts Payable” module in Microsoft Dynamics AX
Page 73
Appendix A Configuring Message Properties for sending data to Microsoft
Dynamics AX
To send data to Microsoft Dynamics AX from BizTalk there are properties that needs to be set on the message, before Microsoft Dynamics AX adapter can push the same.
The following properties need to be set on the message:
i. Set the Dynamics Action on the Message as per the Action configured in Microsoft Dynamics AX: _message (Dynamics.Action)
ii. Set the Dynamics Destination Endpoint on the Message as per the Destination Endpoint configured in Microsoft Dynamics AX: _message (Dynamics.DestinationEndpoint)
iii. // Set the Dynamics Source Endpoint on the Message as per the Destination Endpoint configured in Microsoft Dynamics AX _message (Dynamics.SourceEndpoint)
iv. // Set the Dynamics Source Endpoint User on the Message as per the Destination Endpoint configured in Microsoft Dynamics AX _message (Dynamics.SourceEndpointUser)
Here is the sample for the setting the properties for VendTable:
// Set the Dynamics Action for VendTable
msg_VendTableRequest(Dynamics.Action)="createListVendTable"; // this
too can be made configurable and taken from SSO
// Set the Dynamics Destination Endpoint from the SSO Config
msg_VendTableRequest(Dynamics.DestinationEndpoint) =
SSOConfigHelper.Read("Company.BizTalk.OracleFinancials.VendorData",
"Dynamics.DestinationEndpoint");
// Set the Dynamics Source Endpoint from the SSO Config
msg_VendTableRequest(Dynamics.SourceEndpoint) =
SSOConfigHelper.Read("Company.BizTalk.OracleFinancials.VendorData",
"Dynamics.SourceEndpoint");
Page 74
// Set the Dynamics Source Endpoint User from the SSO Config
msg_VendTableRequest(Dynamics.SourceEndpointUser) =
SSOConfigHelper.Read("Company.BizTalk.OracleFinancials.VendorData",
"Dynamics.SourceEndpointUser");
Appendix B Related Documents/References
Document Document Location
Microsoft Dynamics AX
AIF Configuration White
Paper
http://www.microsoft.com/DOWNLOADS/details.aspx?FamilyID=e5764
bdf-c88d-47f2-a1df-55f368ca9f8d&displaylang=en
Microsoft Dynamics AX
AIF BizTalk Adapter
Configuration White
Paper
http://www.microsoft.com/downloads/details.aspx?FamilyID=fb4a979e
-cce1-4542-8188-4e8592031da2&displaylang=en
Page 75
Manage BizTalk Services Thru WMI – Using C# By Alok Verma, Software Development Engineer, Microsoft
This article assumes you are familiar with BizTalk Server, WMI and C#.
Audience: BizTalk Developers
Technologies: BizTalk Server 2006/2009, VS.NET 2005/2008, WMI
Skill level: Intermediate to Expert
The source code used in this article can be downloaded from this location
http://cid-e210012d5d7e02e1.skydrive.live.com/browse.aspx/Public/BizTalk%20Code
Summary There are situations when maintaining the BizTalk server MessageBox database becomes
challenging. Specifically, when your BizTalk application processes high volume transactions and
sporadically encounters many unsuccessful instances which end up putting many services and messages
into suspended queue.
The BizTalk Administration console is a handy tool for cleaning up small volumes of suspended service
instances; however, for large numbers of suspended service instances a different tool would be
beneficial.
WMI (Windows Management instrumentation) unleashes the capabilities of automating the
administrative tasks for a BizTalk application. To meet this requirement I was looking for a customizable
solution. Out of several options I chose to write a C# program using strongly typed WMI class.
The example I am discussing here talks about a managed solution for following requirements
- Terminate all suspended messages from queue.
- Terminate suspended messages older than 5 days.
- Resume messages which are suspended during last 24 hour.
Creating a WMI Managed Class for BizTalk To create the WMI Managed class follow these steps...
1- Select Management Classes from Visual Studio Server explorer as shown in Fig-1
Page 76
Fig-1
2- Expand the node to select “MSBTS_ServiceInstance” and generate managed class, Fig-2
Fig-2
This will create strongly typed BizTalk WMI class in file named as
“ROOT.MicrosoftBizTalkServer.MSBTS_ServiceInstance.cs”
Terminate Suspended Instances Here we have two requirements, the first is to terminate all suspended services from the
suspended message queue. Following is the sample code
public static void TerminateAllSuspendedMsgs()
{
try
{
//Retrieve the suspended (resumable and non-resumable) instance
collection and terminate each one in loop.
ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance.ServiceInstanceCollection
colServiceIns;
string condition = " (ServiceClass5= 1 OR ServiceClass= 4 OR
ServiceClass = 64) AND (ServiceStatus6=4 OR ServiceStatus=32)";
colServiceIns =
ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance.GetInstances(condition);
5See http://msdn.microsoft.com/en-us/library/ms949479.aspx
6 See http://msdn.microsoft.com/en-us/library/aa510147.aspx
Page 77
foreach(ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance serviceIns in
colServiceIns)
{
serviceIns.Terminate();
}
}
catch (Exception ex)
{
Console.WriteLine("Error: " + ex.Message);
}
}
In the second scenario, we are terminating only those suspended services which are older than 5 days. To achieve this we will use the “SuspendTime” Property of “ServiceInstance” class.
public static void TerminateOldSuspendedMsgs()
{
try
{
double expiryDayIncrement = 5.0;
ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance.ServiceInstanceCollection
colServiceIns; ;
string condition = " (ServiceClass = 1 OR ServiceClass = 4 OR
ServiceClass = 64) AND (ServiceStatus=4 OR ServiceStatus=32)";
colServiceIns =
ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance.GetInstances(condition);
foreach (ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance serviceIns in
colServiceIns)
{
DateTime dtSuspend = DateTime.MinValue;
dtSuspend = serviceIns.SuspendTime;
if (DateTime.Now.CompareTo(dtSuspend.AddDays(expiryDayIncrement))
< 0)
{
serviceIns.Terminate();
}
}
}
catch (Exception ex)
{
Console.WriteLine("Error: " + ex.Message);
}
}
In the above example, I am considering 5 days and this value can be customized using
ConfigurationManager class. The following code set the expiry day value by reading the configuration
file.
//Replace this code in the TerminateOldSuspendedMsgs() to get the expiry daya value
from config setting.
double expiryDayIncrement = 0.0;
expiryDayIncrement = Convert.ToDouble(ReadDataFromConfig("AddExpiryDay"));
private static string ReadDataFromConfig(string section)
{
Page 78
try
{
string value = ConfigurationManager.AppSettings[section];
return (value == null) ? null : value;
}
catch (ConfigurationException ex)
{
Console.WriteLine("Error while reading config data from App.config for
Section: " + section + " Error Message: " + ex.Message);
return null;
}
}
Here is “App.Config” setting,
<configuration>
<appSettings>
<!--AddExpiryDay value specify the number of day when added to a
suspended message time
will be treated as dead message afterwards, range 0-365 -->
<add key ="AddExpiryDay" value="5" />
</appSettings>
</configuration>
Resume Suspended Instances In this scenario we will resume service instances which are suspended in the last 24 hours. For service
instances older than 24 hours you can perform the clean up by calling the “TerminateAllSuspendedMsgs
()” as explained in above sample code.
public static void ResumeCurSuspendedMsgs()
{
try
{
double hourRange = 24.0;
ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance.ServiceInstanceCollection
colServiceIns; ;
string condition = " (ServiceClass = 1 OR ServiceClass = 4 OR
ServiceClass = 64) AND (ServiceStatus=4)";
colServiceIns =
ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance.GetInstances(condition);
foreach (ROOT.MICROSOFTBIZTALKSERVER.ServiceInstance serviceIns in
colServiceIns)
{
DateTime dtSuspend = DateTime.MinValue;
dtSuspend = serviceIns.SuspendTime;
if (DateTime.Now.CompareTo(dtSuspend.AddHours(hourRange))>= 0)
{
serviceIns.Resume();
}
}
}
catch (Exception ex)
{
Console.WriteLine("Error: " + ex.Message);
}
}
Page 79
Advantages of WMI with C# approach
Secured and reliable unlike VBScript code which is not acceptable in some production
environments
Better validation and exception handling
Scalable and Reusable code
Code can be invoked from task scheduler to execute at certain interval or can be run as
Windows service.
Conclusion WMI supports a uniform application programming interface (API) that gives applications and
scripts access to the WMI provider on a local computer or a remote computer. In above samples we just
tried to explore a small feature of the WMI capabilities for BizTalk administration tasks and there is lot
more to be explored in WMI world.
Happy Coding!