BizTalk Server 2006 : Starting a New BizTalk Project - BizTalk Assembly Naming and Versioning

A BizTalk assembly is created by compiling a BizTalk project using VS .NET. Any artifacts in the project will be included in the compiled assembly that is to be deployed. BizTalk assemblies

should match the name of their associated namespace. For example, if your namespace is Company.Project.Subsystem, then your assembly should be named Company.Project. Subsystem.dll.

In theory, the formal assembly name and the DLL name can be different, but you can only make them different by creating a custom build script outside of Visual Studio. Generally, it isn't necessary to use a DLL name that doesn't correspond to the namespace, and you're better off avoiding the extra work by keeping the names the same.

Note that a division into assemblies such as the following will often be quite suitable for a small- to medium-sized BizTalk project, as in many cases the BizTalk artifacts are shared across all features and subsystems:

• MyCompany.MyProject.Orchestrations.dll

• MyCompany.MyProject.Schemas.dll

• MyCompany.MyProject.Pipelines.dll

• MyCompany.MyProject.Transforms.dll

• MyCompany.MyProject.PipelineComponents.dll

If these artifacts were not shared and were specific to a feature, the namespace would be MyCompany.MyProject.MySubsystem.

Often long names such as MyCompany.MyProject.MySubsystem can be difficult to deal with (especially in Visual SourceSafe 6.0, where the file open dialogs do not expand for longer names). The benefits, however, with having the full scoping available when the assemblies and associated artifacts are accessed outside of Visual Studio, especially in a production support and deployment scenario, far outweigh this minor inconvenience.

Side-by-Side Deployments

Within most BizTalk projects, there may be "in-progress" development that can take days, weeks, or even months to complete. In such scenarios, deploying new releases or hot fixes is difficult to achieve. In order to upgrade to a new version of the currently running application, it becomes necessary to allow any in-progress processes to reside side by side with the newer releases. When all in-progress processes are complete, then the earlier versions can be safely undeployed without affecting any processes of the newer releases.

In some cases, there may also be a need for multiple versions to reside side by side for an indefinite amount of time. In these scenarios, it becomes vital to ensure the activating logic is unique to guarantee the correct messages are passed on to correct versions. The default versioning process is shown in Figure 1.

Figure 1. Default versioning

Following are some unique requirements for side-by-side deployments:

• Provide an ability to deploy new releases.

• Provide an ability to deploy incremental releases (without affecting previous deployments).

• Provide an ability to deploy hot fixes (redeployment of recent deployment installs without affecting previous deployments).

• To ease maintenance, stamp all assemblies with the same version.

Side-by-Side Deployment Strategies

To achieve side-by-side deployment, it is necessary to ensure versioning is maintained appropriately between all referenced assemblies. Without a versioning strategy, any side-by-side deployment strategy is prone to errors. Within .NET, any assembly references (either BizTalk or non-BizTalk) need to match the assembly versions defined within referenced objects at compile time.

The default versioning schema causes a conflict within the BizTalk environment. In a typical BizTalk environment, along with the assemblies, you also have external objects like receive/ send ports and schemas that are shared between different versions. Messages meant for one version can be picked up and processed by another version, which may lead to errors or undesired results.

To solve this problem, it becomes necessary to extend .NET's versioning scheme for BizTalk. The following sections describe three common strategies for doing this.

Versioned Deployment Using Versioned Receive/Send Ports

In this strategy, all receive port and send port names are unique across multiple deployments.Hence any messages that arrive at these ports are guaranteed to be processed by the specific versioned modules that are listening to these specific ports. A diagram of this approach is shown in Figure 2.

Figure 2. Versioned deployment using ports

Following are the steps involved:

The advantages of this process are as follows:

• The deployment strategy is clean.

• Any number of deployments are guaranteed to process only those messages that arrive at specific binded ports.

• Namespaces of associated schemas do not need to be changed.

The sole disadvantage is this:

• For every release, all associated receive/send ports will need to be updated to reflect the new version. If external partners are submitting messages, new locations will need to be communicated with external partners.

Versioned Deployment Using Versioned Schema Namespaces

This strategy involves changing the namespaces associated with specific schemas. Changing a namespace is easily accomplished by suffixing each schema's namespace with a specific version number before compilation. This strategy solves the correlation error encountered with the preceding approach and is diagrammed in Figure 3.

Performthe following procedure to deploy the assemblies in your project using versioned schema namespaces:

Figure 3 . Versioned deployment using namespaces

Following are the advantages of the versioned deployment approach:

• As BizTalk distinguishes schemas based on namespaces and root node, specific messages are processed by specific versioned assemblies.

• This process works in scenarios where correlation sets are initialized.

• Receive/Send port names do not need to be changed. This is beneficial in scenarios where external partners are submitting messages to specific ports. Using this approach, new port locations do not need to be communicated to external partners.

Disadvantages of the versioned deployment approach include the following:

• Namespaces of associated schemas should be changed even if there are no structural changes to these specific schemas. This is to ease the management of the schemas once they have been deployed. For instance, it is much easier to examine a DLL and know that all the schemas within it contain the same version. If not, the management of the schemas can become cumbersome.

• For every release, all associated schema namespaces will need to be updated to reflect the new version. This could constitute a significant architectural change.

Combining the Two Approaches

You can combine the previous two approaches using versioned schema namespaces in conjunction with versioned receive/send ports. This approach is shown in Figure 4.

Figure 4. Versioned deployment using ports and namespaces

The steps involved in the combined approach are as follows:

Advantages of the combined approach are as follows:

• It presents a cleaner deployment strategy and easier debugging scenarios.

• As BizTalk distinguishes schemas based on namespaces and root node, specific messages are processed by specific versioned assemblies.

• It works in scenarios where correlation is used.

And the disadvantages:

• Namespaces of associated schemas need to be changed even if there are no structural changes to these specific schemas.

• All receive/send port names also need to be changed.

• For every release, all associated schema namespaces as well as receive/send ports will need to be updated to reflect the new version.

Versioned Deployment Using Filtering

This strategy involves promoting an element within a message (e.g., version) that is used within the filter associated with a Receive shape that gets activated when a message is received by the orchestration. This has the benefit of allowing you to use content-based routing information, which can be changed in a production scenario with no code modification and very little downtime. This approach is shown in Figure 5.

Figure 5. Versioned deployment using filtering

Use the following steps to implement this strategy:

The advantages of this method are as follows:

• Only filter expressions need to be updated.

• Receive/Send port names do not need to be changed.

• Schema namespaces do not need to be changed.

And the disadvantages:

• It will not work for scenarios where orchestrations are required to initialize a correlation set. If correlation sets are being initialized and schemas of the same version are being referenced between different deployments (different assembly versions), BizTalk does not know which combination of assembly and associated schema to use and generates a runtime error.

• An element within the schema that contains the version number will need to be promoted.

• For every release, this filter will need to be changed to reflect the current version.