Naming Conventions

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

BizTalk.Factory has baked support into its Binding DSL for naming Microsoft BizTalk Server® artifacts such as applications, receive ports and locations, and send ports —see INamingConvention and ISupportNameResolution— and comes with a few ready-to-use custom naming conventions too.

Strictly speaking, the Be.Stateless.BizTalk.Dsl.Binding NuGet package provides the support for artifact naming conventions but only comes with one unstructured string-only naming convention, which is the convention that has been used throughout our sample application so far. This allowed us to write binding configuration code as follows, where the name of an artifact can just be any string literal:

using Be.Stateless.BizTalk.Dsl.Binding;

public class Application : ApplicationBinding
{
   public Application()
   {
      Name = "Accounting";
      ReceivePorts.Add(
         ReceivePort(
            rp => {
               rp.Name = "Billing Receive Port";
               rp.ReceiveLocations.Add(
                  ReceiveLocation(
                     rl => {
                        rl.Name = "Credit Note Receive Location";
      ...

The Be.Stateless.BizTalk.Dsl.Binding.Conventions NuGet package, on the other hand, provides both a simple and a detailed structured naming conventions. The developer is invited to have a look at sample application bindings making use of the simple and detailed naming conventions.

From these samples, there are a few key concepts that one needs to grasp. The actual application binding configuration class the developer writes derives from a base class accepting a naming convention as a generic type argument, see for instance ApplicationBinding. This base class defines protected factory members that bootstraps the naming convention for any given artifact, e.g. ApplicationName, ReceivePortName, ReceiveLocationName, and SendPortName. These factory members allows for the following code to be written, where the name of an artifact can only be assigned a structured expression rooted in one of them:

public class SampleApplication : ApplicationBinding<NamingConvention>
{
   public SampleApplication()
   {
      Name = ApplicationName.Is("SampleApplication");
      ReceivePorts.Add(
         ReceivePort(
            rp => {
               rp.Name = ReceivePortName.Offwards("Batch");
               rp.ReceiveLocations.Add(
                  ReceiveLocation(
                     rl => {
                        rl.Name = ReceiveLocationName.About("Release").FormattedAs.Xml;
                        rl.ReceivePipeline = new ReceivePipeline<...>();
                        rl.SendPipeline = new SendPipeline<...>();
                        rl.Transport.Adapter = new WcfSqlAdapter.Inbound(a => { ... });
                     }));
            }));
      SendPorts.Add(new StandaloneSendPort());
   }
}

public class StandaloneSendPort : SendPort<NamingConvention>
{
   public StandaloneSendPort()
   {
      Name = SendPortName.Towards("Job").About("Notification").FormattedAs.Xml;
      SendPipeline = new SendPipeline<...>();
      Transport.Adapter = new FileAdapter.Outbound(a => { ... });
   }
}

The artifact names will be computed when the XML bindings are generated and it will be expanded according to the following structured pattern for a receive/send port or location:

<ApplicationName>.<RP|RL|SP><1|2>.<Party>.<Subject>.<Adapter>.<MessageFormat>

where

• <ApplicationName> is the application name defined via the convention API, i.e. ApplicationName.Is("Simple.SampleApplication");
• <RP|RL|SP> respectively denotes either a receive port, a receive location, or a send port;
• <1|2> respectively a one-way or two-way port;
• <Party> is the party with which the port interacts, i.e. ReceivePortName.Offwards("Job") or SendPortName.Towards("Job");
• <Subject> denotes what the message is about, i.e. .About("AddPart") or .About("Notification");
• <Adapter> is the adapter used by the port;
• <MessageFormat> is the format of the message payload.

Remark The <RP|RL|SP>, <1|2>, and <Adapter> tokens are automatically computed by the naming convention. For the most cases, the <Adapter> token is the name of the adapter, bound to the port’s Transport, as actually defined in the Adapters section underneath the Platform Settings of the Microsoft BizTalk Server® Administration Console. Exceptions are made for the Office365EmailAdapter, WcfCustomAdapter, and WcfCustomIsolatedAdapter adapters and details can be found in the source code of the ComputeAdapterName method and its unit tests.

In our case, the naming conventions will produce the following artifact names:

• SampleApplication as the application name,
• SampleApplication.RP2.Batch for the two-way receive port,
• SampleApplication.RL2.Batch.Release.WCF-SQL.XML for the two-way receive location,
• SampleApplication.SP1.Job.Notification.FILE.XML for the one-way send port.

Finally, the detailed naming convention is similar to simple one, but furthermore constrains the party —OffWards and ToWards— and subject —About— names to be defined by some type instead, e.g. an enumeration.