Sharing a BizTalk pipeline component in BizTalkComponents component library

So you have decided to share a pipeline component to our library? Great! The BizTalkComponent library is hosted on GitHub. A sample pipeline component that can be used as a template is available at GitHub.

Setting up Git

Before a component is added to the official GitHub repository of BizTalkComponents it must be reviewed. To do that you must first create a public GitHub repository. Make sure to add the .gitattributes file and the .gitignore file for Visual Studio. Also create a README file and a license file. BizTalkComponents uses MIT license. To start working on our component we need to clone the newly created repository using your favorite Git client like Visual Studio or GitHub for Windows.

Creating the solution

Fire up Visual Studio and create an empty solution in the root folder of the newly cloned repository. The solution file should be called BizTalkComponents.PipelineComponents.{component name}.sln.

Adding unit tests

All components must have unit tests so the first thing we are going to do is to add a new Unit Test project to our solution. The unit test project should be located in Tests/UnitTests under the root folder. To be able to run a pipeline component outside of BizTalk we use the Winterdom BizTalk Pipeline Testing library available as a NuGet package.

Build tests that not only ensures that the components output is as expected when everything is setup correctly but also that relevant exceptions are thrown when any preconditions like parameters set by the BizTalk administrator or existence of context properties fails.

Implementing the pipeline component

The pipeline component itself should be located in a Src folder under root. All pipeline components should target .NET 4.0 to ensure compatibility with BizTalk 2010.

BizTalkComponents.Utils

The pipeline components of BizTalk components uses a shared utility library called BizTalkComponents.Utils. This library contains helper classes to reduce the amount of code we need to write for common tasks like interacting with the message context and reading and writing to the components property bag. The library is available on NuGet.

Partial classes for a more readable component

The interfaces that every pipeline component needs to implement contains a lot of plumbing code that has nothing to do with what the component actually do. To keep the implementation clean and easy to read BizTalkComponents uses partial classes to separate plumbing code from the component implementation. The class files should be called {component name}.cs and {component name}.Component.cs. The component class should contain any component metadata properties and methods as well as any Validate method. BizTalkComponents does not use resource files for component metadata. Name, Version and Description are set directly in the property. The IPersistPropertyBag interface contains a method for validating parameters. This method is called when the component is built. This method should use the ValidationHelper from the utils library. This method can be completed with an additional Validate method that is not called at build time but rather when the component is called in BizTalk.

Component parameters

Any component parameter should have annotations: • Parameters required to be set already at design time should be annotated with the Required attribute • Parameters required to be set at runtime should be annotated with the RequiredRunTime attribute available in the Utils library. • All parameters should be annotated with a user friendly name in the DisplayName attribute. • All parameters should be annotated with a description in the Description attribute.

The parameter property should be accompanied with a string constant to be used when reading and writing from the property bag.

The Load and Save methods should be implementing using the PropertyBagHelper from Utils.

The Execute method

If the component has any RequiredRuntime properties the custom Validate method should be called at the beginning of the Execute method to ensure that all parameters are set as expected.

All interactions with the message context should use the utils library’s extension methods. ContextProperty entity should be used for referencing any context property. This entity can be initialized either with the BizTalk property notation namespace#property name or by separating namespace and property in to different strings. The Utils library also contains constants for some BizTalk standard properties.

Building the component

All pipeline components should be strong named so that they can be installed into the GAC. A new strong name file (snk) is created for every pipeline component.

MSI files for all components will be generated. To be able to generate an MSI from MSBuild BtsMsiTask must be installed and used. BtsMsiTask is called from a custom MSBuild build script that should be located in a Build folder under the root. All MSI should have a version. The AssemblyInformationalVersion attribute is used for versioning and to be able to read that attribute from the build script MSBuild Extension Pack must also be installed. The build script should be called Build.proj and also be included as a Solution folder in the solution.

This sample build script can be used by just replacing the component name.

Readme file

The README.md mark down file generated by GitHub should have a short description of the component. There are many tools for editing mark down files, for example this extension to Visual Studio.

This blog post aims to introduce the BizTalk Components library and the coding standard it uses. If you have any questions or comments on the component library or the coding standard don’t hesitate to write a comment to this blog post.

Posted in: •Integration  | Tagged: