Be.Stateless.BizTalk.Dsl.Binding

Build Pipelines

Latest Release

Release Preview

Overview

Be.Stateless.BizTalk.Dsl.Binding is part of the BizTalk.Factory’s Development Packages. This component provides an embedded C# DSL allowing the developer to define the bindings of Microsoft BizTalk Server® applications in a code-first type-safe way.

Rationale

Deploying a Microsoft BizTalk Server® application in various environments is often a tedious and error prone task. One developer usually bootstraps the deployment process by first manually deploying and configuring the application locally in order to be able to produce parameterized deployment artifacts such as XML bindings.

To this regard, BizTalk Deployment Framework provides a better and much more repeatable alternative thanks to its Binding Files, but the task is still tedious and error-prone, and the developer must still often bootstrap such a Binding File by exporting the bindings of the Microsoft BizTalk Server® application that he has manually deployed locally beforehand.

Due to their deployment-time preprocessing for a given target environment, importing XML bindings may often fail for a variety of reasons. For instance, the generated XML bindings may be corrupted due to badly written preprocessing directives, invalid parameter values, or, because after all, XML bindings do contain lots of magic strings —e.g. host instance names, assembly-qualified type names like maps, schemas, orchestrations, pipelines, pipeline components, and so on. Because their preprocessing happens at deployment-time, troubleshooting XML bindings import failures is often painful because it only fails when the Microsoft BizTalk Server® application is actually deployed in its target environment and not when the deployment package is produced —which typically occurs on the build server, that is to say, much sooner.

BizTalk.Factory departs from these repetitive, error-prone, and too often manual operations by allowing the developer to write the bindings of the Microsoft BizTalk Server® application he is currently developing right from the start in C# without any need to bootstrap the process in any way. Thanks to the embedded C# DSL offered by Be.Stateless.BizTalk.Dsl.Binding, the developer can configure all the various aspects of the bindings of a given Microsoft BizTalk Server® application for every target environment in which it is supposed to be deployed.

These C# code-first bindings will be used at deployment time to generate the XML bindings to be imported in Microsoft BizTalk Server® for the targeted environment. As we will see, these code-first bindings can —and should— be unit tested during build, guaranteeing this way that the XML bindings can be generated and will successfully import in any target environment.

Remark The only reason why XML bindings could still fail to import will be due to misalignment between the conventions used by the code and the ones used by the actual configuration of the Microsoft BizTalk Server® Group, like, for instance, host instance names.

Basic Usage

Downloads The code samples used in this user guide have been made available in the Be.Stateless.BizTalk.Factory.Samples GitHub repository.

Let us imagine we are writing the bindings for the Microsoft BizTalk Server® Accounting application of a fictitious company called Org.Anization.

First of all, the developer has to create a new .NET class library project —let us call it Org.Anization.Accounting.Bindings— and reference the Be.Stateless.BizTalk.Dsl.Binding NuGet package. Being a seasoned developer, he will also create a second test project —let us call it Org.Anization.Accounting.Bindings.Tests— and reference the Be.Stateless.BizTalk.Dsl.Binding.Unit NuGet package so as to be able to continuously test and validate the Microsoft BizTalk Server® application bindings for the Accounting application.

Now that we have created the bindings project, as well as the automated test project, we are ready to write the configuration for the various aspects of the Microsoft BizTalk Server® Accounting application. Be.Stateless.BizTalk.Dsl.Binding exposes and supports the following application binding aspects and allows the developer to configure them entirely in C#:

• Applications,
• Orchestrations,
• Receive Ports and Receive Locations,
• Send Ports,
• Pipelines,
• Transports,
• Adapters.

Remark Be.Stateless.BizTalk.Dsl.Binding does not currently supports the Send Port Groups and the Parties —or Role Links— binding aspects.

Advanced Usages

To better support the declaration of application bindings, the Binding DSL also offers a series of convenient and powerful features to effectively streamline and reduce the code one has to write:

• Environment Dependent Values
• Environment Overrides
• Naming Convention
• Host Resolution Policy
• TimeSpan Usage Generalization

Consuming Code-First Bindings

So far we have seen how to write Microsoft BizTalk Server® application bindings, at varying levels of refinement, by leveraging the features of BizTalk.Factory’s Binding DSL. It has also been said that the C# code-first bindings will be used at deployment time to generate the XML bindings to be imported in Microsoft BizTalk Server® for the targeted environment. Generating the XML bindings is just one of the many uses one could make of an application’s C# code-first bindings, and BizTalk.Factory comes with several of them that we will cover later on.

But before that, it is worth mentioning that the visitor pattern is the key mechanism through which one can put these code-first application bindings to use. Thanks to the combined work of both IApplicationBindingVisitor and IVisitable<TVisitor> interfaces together with the VisitorPipeline class, it is actually quite easy to write a custom visitor to benefit from these code-first application bindings: one simply has to provide an implementation of the IApplicationBindingVisitor interface.

Out of the box, BizTalk.Factory’s Binding DSL provides 3 implementations of the IApplicationBindingVisitor interface:

• The EnvironmentOverrideApplicator class, whose purpose is to ensure that the application bindings are all set for a given target deployment environment —in concrete terms it makes sure that the ApplyEnvironmentOverrides method has been called against all instances that make up the application binding object model, see Environment Overrides;

• The ApplicationBindingValidator class, whose purpose is to check whether the application bindings are valid for one given target deployment environment —in concrete terms it makes sure that the Validate method has been called against all instances that make up the application binding object model;

• The BindingInfoBuilder class, whose purpose is to serialize to XML the application binding object model that has been set for a given target deployment environment.

Notice that though the EnvironmentOverrideApplicator is an internal class —i.e. not accessible to the end-user,— it is nevertheless guaranteed to be called by the VisitorPipeline, whose purpose is precisely to make sure that all the environment overrides have been applied and the bindings validated before eventually calling any custom IApplicationBindingVisitor implementation.

Finally, even though the BindingInfoBuilder class is bundled in the Be.Stateless.BizTalk.Dsl.Binding NuGet package, one has to install the BizTalk.Deployment PowerShell module to actually be able to generate the XML bindings.

Developer Help

Detailed developer help has been provided as XML comments directly embedded in source code. Though developers usually browse through this documentation while developing thanks to, for instance, JetBrains ReSharper quick help —ctrl+shift+F1, an online version of this inlined help has also been provided here for greater reachability: