This is the second article in a multi-part series about assemblies and how they relate to BizTalk. This part discusses deploying assemblies to BizTalk and where things need to go in order to work correctly.
The nature of BizTalk necessitates the existence of a special type of assembly, called a BizTalk assembly. A BizTalk assembly is a class library (.dll) assembly just like many other assemblies, but it has some special metadata in it that BizTalk uses for its own purposes. A BizTalk assembly is what's created when you build a BizTalk project in Visual Studio (as opposed to a standard C# class library project). If you've ever worked on a BizTalk project in VS, you'll know that unlike a standard class library or executable project, there are only a few types of resources you can add - schemas, pipelines, maps and orchestrations. These constructs are unique to BizTalk and are not fully understood or recognized by the rest of the .NET runtime or the GAC.
To deploy a BizTalk assembly, you must do two things: deploy it to the GAC, and register it within BizTalk. GACing an assembly is simple, and can be done with gacutil (discussed in pt. 1). Note that since a BizTalk assembly must be GACed to be used, it must be strongly-named. To strongly name a BizTalk assembly, first create a .snk (strong-name key) file using Visual Studio's sn.exe utility (the path is already present in a Visual Studio Tools command prompt; the path to it on my machine is C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin\sn.exe). The syntax is "sn.exe -k MyKeyFile.snk". Place the key in a location easily referenced from your project folder. In your BizTalk project in Visual Studio, open the project properties (right-click the project and select Properties). Click "Assembly" in the left pane, scroll down to "Assembly Key File", and enter the path to the .snk file or use the ellipsis button within the text field to browse to it. Click OK when finished - now the assembly that will result from building the project will be strongly-named.
Registering the assembly in BizTalk is required so BizTalk "knows" about it. An assembly is not registered directly from the GAC, it must be registered from a file on your machine. For this reason, you should treat your BizTalk assemblies like you treat program files for other applications - give them a folder somewhere where they aren't going to get moved or deleted. When you register a BizTalk assembly, BizTalk reads its metadata to discover what kinds of BizTalk artifacts (schemas, orchestrations, pipelines, maps) are present in it. Registration can be done via the command line, the admin console or Visual Studio. I will walk through the admin console and VS procedures - deploying from the command line is convenient for build/deploy scripts and the like, but if you're new to developing for BizTalk, odds are you'll be doing this manually from a GUI for a while.
To deploy a BizTalk assembly via the admin console, expand the application that you want to add the assembly to, right click the Resources folder and click "Add > BizTalk Assemblies..." Clicking the "Add" button in the next dialog will allow you to search for any file to add as a resource. Anything can be added as a resource to a BizTalk application, but what we are interested in right now is BizTalk assemblies, so dig up a .dll from a BizTalk VS project and add it. The File Type drop-down box should show System.BizTalk:BizTalkAssembly. Everything below this drop-down box is generally only relevant to the creation and usage of BizTalk MSI files, which I will cover in a later post. However, one of the checkbox options that will appear, "Add to the global assembly cache on add resource (gacutil)" will GAC the assembly for you once you click OK if you haven't GACed it yourself with gacutil.
To deploy a BizTalk assembly via Visual Studio, first configure the deployment options in the Deployment page of the project properties. Server and Configuration Database are required. Leaving Application blank will attempt to deploy to the default application, otherwise you may enter the name of a BizTalk application to deploy to. Redeploy should generally always be set to True, as should Install to Global Assembly Cache (this will GAC it for you). If you are working in a local development environment, go ahead and set Restart Host Instances to True as well - restarting the host instances is always a must when deploying or redeploying assemblies, it's just that you may want to wait for an opportune time to do it, and that may not be build/deploy time. Once you have filled out this page, selecting Deploy Solution or Deploy Project from the Build menu will attempt to deploy the assembly/assemblies to BizTalk for you, quick and easy.
If you are redeploying an assembly that already exists in BizTalk and the GAC, you generally need to follow the same procedure as when you deployed it the first time unless the version number has changed. Just like the GAC, multiple version numbers of the same assembly can co-exist within BizTalk. The components of those assemblies will exist as separate entities and are distinguished by the version number of the assembly in their full name. If the version number of your assembly has not changed, simply deploy it from Visual Studio with Redeploy set to True, or manually reGAC it and re-add it as a BizTalk Assembly resource from the admin console and make sure Overwrite is checked. Note that simply replacing the .dll on disk and in the GAC is not enough - it must be re-added to BizTalk's resources so it can read the assembly metadata again.
If the version number has changed as a part of development and you don't want the versions to co-exist (i.e. you want one definitive version in your environment to avoid confusion), you need to remove the old assembly by right-clicking it from the Resources screen of your application and clicking Remove. For this to succeed, none of the assembly's components can be used as configuration items within any of your binding objects (ports, orchestrations, etc.). The admin console will warn you and fail the operation if this is not true. Note that removing the resource from BizTalk does not unGAC the assembly: to keep your GAC clean, I suggest removing the assembly from it if you are no longer using it.
That wraps up part two of the deployment posts. In the third and last post I will discuss MSI files, binding files and assembly references, as well as pipeline components, which are the exceptions to all of the rules.
