Manage adapter versioning with the WCF LOB Adapter SDK

Article
07/07/2021

After initial deployment of adapters and potentially several times during their lifetime, adapters (and the endpoints they expose) may need to be changed for a variety of reasons. These reasons include changing business needs, information technology requirements, or issues with the line of business system or the adapter itself. This topic discusses different strategies for handling versioning for adapters that are written using the Microsoft Windows Communication Foundation (WCF) Line of Business (LOB) Adapter SDK.

Versioning and Windows Communication Foundation

The WCF LOB Adapter SDK is built upon Windows Communication Foundation (WCF) and relies on its infrastructure for exchanging messages between systems. Using mechanisms that WCF exposes, you can version both services and data contracts. For more information, including best practices for service versioning, see Service Versioning in the WCF online reference. For more information, including best practices for data contract versioning, see Data Contract Versioning in the WCF online reference.

Versioning Scenarios

There are two primary versioning scenarios:

One adapter version supports multiple versions of the target system.
Two or more adapter versions support the same system or two or more different systems.

You may also need to release a new version of your adapter if updates to the WCF LOB Adapter SDK affect existing functionality.

Each of these scenarios requires a different versioning strategy.

Note

The WCF LOB Adapter SDK does not enforce any specific versioning scenarios. It is left to the developer to determine versioning requirements for an adapter.

One adapter supports multiple versions of target system

When the adapter supports multiple versions of the target system, you should expose one or more binding properties that can be used to identify the desired version. For example, an adapter might support multiple communication libraries supplied by the target system's vendor. Using a custom binding property named "LibraryVersion," the adapter consumer could choose which library to use based on the deployment environment or other requirements.

Two or more adapters support one version of target system

In this case, each adapter should use a unique scheme (ContosoV1:// and ContosoV2://) and a unique binding name (ContosoV1Binding and ContosoV2Binding). Vendors should consider using their name in the scheme and binding name as well (for example, Microsoft.ContosoV1:// and Microsoft.ContosoV1Binding).

New versions of the WCF LOB Adapter SDK

When new versions of the WCF LOB Adapter SDK are released, you will be able to install the new version without having to recompile your adapter, since WCF LOB Adapter SDK releases are be backward-compatible. However, you should evaluate new releases to determine if there is a change in functionality that your adapter depends on, or if there is new functionality that your adapter would benefit from implementing.