Create a deployment package with the WCF LOB Adapter SDK
During the development cycle, you can build, debug, and run your adapter within Visual Studio. The output of an adapter solution is a DLL assembly. You can build your adapter solution using Visual Studio IDE or use the devenv.exe scripts to create an adapter assembly. Once the adapter is developed and it is ready for use within the adapter consumer's environment, you must create a deployment package that allows the adapter to be installed in test and production environments.
You can include a Visual Studio Setup and Deployment project within the solution. This can be used to automatically generate an .msi file as part of the solution build.
Note
You can prevent the Setup and Deployment project from building each time you build the solution on your local workstation by excluding it through the Configuration Manager (on the Build menu) within Visual Studio .NET. If you exclude a project from a solution build using this method, you do not affect the source controlled solution file. Changes are maintained within the solution user option file, which is developer-specific and not under source control.
Whenever new projects are added to your solution you must remember to update and configure the deployment project to ensure that the output of the new project is included within the .msi file and that any project-specific installation steps are performed.
It is not enough to just install the output of the adapter project on the user's computer. The adapter needs to be installed in global assembly cache (GAC) and the machine.config file needs to be updated to register the adapter with WCF.
Following is a sample custom action that can be used to register or unregister an adapter with WCF.
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Configuration.Install;
using System.Reflection;
using System.ServiceModel.Configuration;
using System.Diagnostics;
using System.Configuration;
namespace Microsoft.Adapters.Samples.EchoV2
{
//Custom action to register the adapter with WCF configuration in machine.config
//<system.serviceModel>
// <extensions>
// <bindingElementExtensions>
// <add name="{BINDINGELEM_NAME}" type="{BINDINGELEM_TYPE}, {Assembly Information}" />
// </bindingElementExtensions>
// <bindingExtensions>
// <add name="{BINDING_NAME}" type="{BINDING_TYPE}, {Assembly Information}" />
// </bindingExtensions>
// </extensions>
// <client>
// <endpoint binding="{BINDING_NAME}" contract="IMetadataExchange" name="{BINDING_SCHEME}" />
// </client>
//</system.serviceModel>
[RunInstaller(true)]
public partial class WCFLOBAdapterInstaller : Installer
{
private Assembly adapterAssembly;
private Type bindingSectionType;
private Type bindingElementExtensionType;
const string INSTALLER_PARM_INSTALLDIR = "INSTALLDIR";
const string BINDING_ASSEMBLY_NAME = "Microsoft.Adapters.Samples.EchoV2.EchoAdapter.dll";
const string BINDINGELEM_NAME = "echoAdapterV2";
const string BINDINGELEM_TYPE = "Microsoft.Adapters.Samples.EchoV2.EchoAdapterBindingElementExtensionElement";
const string BINDING_NAME = "echoAdapterBindingV2";
const string BINDING_TYPE = "Microsoft.Adapters.Samples.EchoV2.EchoAdapterBindingCollectionElement";
const string BINDING_SCHEME = "echov2";
/// <summary>
/// Constructor - initialize the components and register the event handlers
/// </summary>
public WCFLOBAdapterInstaller()
{
InitializeComponent();
this.AfterInstall += new InstallEventHandler(AfterInstallEventHandler);
this.BeforeUninstall += new InstallEventHandler(BeforeUninstallEventHandler);
}
/// <summary>
/// Add the WCF configuration information in machine.config when installing the adapter.
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void AfterInstallEventHandler(object sender, InstallEventArgs e)
{
try
{
Debug.Assert(this.Context != null, "Context of this installation is null.");
string path = this.Context.Parameters[INSTALLER_PARM_INSTALLDIR] + BINDING_ASSEMBLY_NAME;
adapterAssembly = Assembly.LoadFrom(path);
Debug.Assert(adapterAssembly != null, "Adapter assembly is null.");
bindingSectionType = adapterAssembly.GetType(BINDING_TYPE, true);
Debug.Assert(bindingSectionType != null, "Binding type is null.");
bindingElementExtensionType = adapterAssembly.GetType(BINDINGELEM_TYPE, true);
Debug.Assert(bindingElementExtensionType != null, "Binding element extension type is null.");
AddMachineConfigurationInfo();
}
catch (Exception ex)
{
throw new InstallException("Error while adding adapter configuration information. " + ex.InnerException.Message);
}
}
/// <summary>
/// Registers the adapter with the WCF configuration
/// NOTE: The
/// </summary>
public void AddMachineConfigurationInfo()
{
System.Configuration.Configuration config = ConfigurationManager.OpenMachineConfiguration();
Debug.Assert(config != null, "Machine.Config returned null");
// add <client><endpoint>
ServiceModelSectionGroup sectionGroup = config.GetSectionGroup("system.serviceModel") as ServiceModelSectionGroup;
if (sectionGroup != null)
{
bool channelEndpointElementExists = false;
// this call can throw an exception if there is problem
// loading endpoint configurations - e.g. each endpoint
// tries to load binding which in turn loads the DLL
ClientSection clientSection = sectionGroup.Client;
foreach (ChannelEndpointElement elem in clientSection.Endpoints)
{
if (elem.Binding.Equals(BINDING_NAME, StringComparison.OrdinalIgnoreCase) && elem.Name.Equals(BINDING_SCHEME, StringComparison.OrdinalIgnoreCase) && elem.Contract.Equals("IMetadataExchange", StringComparison.OrdinalIgnoreCase))
{
channelEndpointElementExists = true;
break;
}
}
if (!channelEndpointElementExists)
{
Debug.WriteLine("Adding ChannelEndpointElement for : " + BINDING_NAME);
ChannelEndpointElement elem = new ChannelEndpointElement();
elem.Binding = BINDING_NAME;
elem.Name = BINDING_SCHEME;
elem.Contract = "IMetadataExchange";
sectionGroup.Client.Endpoints.Add(elem);
Debug.WriteLine("Added ChannelEndpointElement for : " + BINDING_NAME);
}
// add <bindingElementExtension>
if (!sectionGroup.Extensions.BindingElementExtensions.ContainsKey(BINDINGELEM_NAME))
{
ExtensionElement ext = new ExtensionElement(BINDINGELEM_NAME, bindingElementExtensionType.FullName + "," + bindingElementExtensionType.Assembly.FullName);
sectionGroup.Extensions.BindingElementExtensions.Add(ext);
}
// add <bindingExtension>
if (!sectionGroup.Extensions.BindingExtensions.ContainsKey(BINDING_NAME))
{
ExtensionElement ext = new ExtensionElement(BINDING_NAME, bindingSectionType.FullName + "," + bindingSectionType.Assembly.FullName);
sectionGroup.Extensions.BindingExtensions.Add(ext);
}
config.Save();
}
else throw new InstallException("Machine.Config doesn't contain system.serviceModel node");
}
/// <summary>
/// Remove the machine configuration information when uninstalling the adapter
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void BeforeUninstallEventHandler(object sender, InstallEventArgs e)
{
try
{
RemoveMachineConfigurationInfo();
}
catch (Exception ex)
{
throw new InstallException("Error while removing adapter configuration information" + ex.InnerException.Message);
}
}
/// <summary>
/// Unregisters the adapter with WCF configuration
/// </summary>
public void RemoveMachineConfigurationInfo()
{
System.Configuration.Configuration config = ConfigurationManager.OpenMachineConfiguration();
Debug.Assert(config != null, "Machine.Config returned null");
ServiceModelSectionGroup sectionGroup = config.GetSectionGroup("system.serviceModel") as ServiceModelSectionGroup;
ChannelEndpointElement elemToRemove = null;
if (sectionGroup != null)
{
// Remove <client><endpoint>
foreach (ChannelEndpointElement elem in sectionGroup.Client.Endpoints)
{
if (elem.Binding.Equals(BINDING_NAME, StringComparison.OrdinalIgnoreCase) && elem.Name.Equals(BINDING_SCHEME, StringComparison.OrdinalIgnoreCase) && elem.Contract.Equals("IMetadataExchange", StringComparison.OrdinalIgnoreCase))
{
elemToRemove = elem;
break;
}
}
if (elemToRemove != null)
{
Debug.WriteLine("Removing ChannelEndpointElement for : " + BINDING_NAME);
sectionGroup.Client.Endpoints.Remove(elemToRemove);
Debug.WriteLine("Removed ChannelEndpointElement for : " + BINDING_NAME);
}
// Remove <bindingExtension> for this adapter
if (sectionGroup.Extensions.BindingExtensions.ContainsKey(BINDING_NAME))
{
sectionGroup.Extensions.BindingExtensions.RemoveAt(BINDING_NAME);
}
// Remove <bindingElementExtension> for this adapter
if (sectionGroup.Extensions.BindingElementExtensions.ContainsKey(BINDINGELEM_NAME))
{
sectionGroup.Extensions.BindingElementExtensions.RemoveAt(BINDINGELEM_NAME);
}
config.Save();
}
else
{
throw new InstallException("Machine.Config doesn't contain system.serviceModel node");
}
}
/// <summary>
/// Use this for testing outside of the Setup project
/// </summary>
/// <param name="assemblyDirectory">Directory where the adapter assembly is located</param>
public static void TestAddConfiguration(string assemblyDirectory)
{
WCFLOBAdapterInstaller action = new WCFLOBAdapterInstaller();
InstallContext context = new InstallContext();
// In the Setup project, this is set by selecting custom action
// and in Properties setting /INSTALLDIR="[TARGETDIR]\" for CustomActionData
context.Parameters.Add("INSTALLDIR", assemblyDirectory);
action.Context = context;
action.AfterInstallEventHandler(null, null);
}
/// <summary>
/// Use this for testing outside of the Setup project
/// </summary>
/// <param name="assemblyDirectory">Directory where the adapter assembly is located</param>
public static void TestRemoveConfiguration(string assemblyDirectory)
{
WCFLOBAdapterInstaller action = new WCFLOBAdapterInstaller();
InstallContext context = new InstallContext();
// In the Setup project, this is set by selecting custom action
// and in Properties setting /INSTALLDIR="[TARGETDIR]\" for CustomActionData
context.Parameters.Add("INSTALLDIR", assemblyDirectory);
action.Context = context;
action.BeforeUninstallEventHandler(null, null);
}
}
}
If you want to explore a sample adapter with a deployment package, you can download a completed Echo Adapter including test code and installation script. This sample is included with your BizTalk installation files at \BizTalk Server\ASDK_x86\Program Files\WCF LOB Adapter SDK\Documents\Samples or \BizTalk Server\ASDK_x64\Program Files\WCF LOB Adapter SDK\Documents\Samples.
See Also
Deploy an adapter using the WCF LOB adapter SDK
Undeploy an adapter using the WCF LOB adapter SDK