General Prevention

You can minimize the number of bugs introduced into your BizTalk solution through rigorous development practices, strong coding practices, early and frequent testing, repeatable deployment, and a well-defined source code control process. It is better to prevent bugs early in the development process than to troubleshoot a solution in production.

There are many different preventative measures you can take when developing your application. Many of the measures involve seemingly minor details like naming conventions and project organization; however, these details can have a huge impact on productivity and your ability to enhance and debug an application as it evolves.

Application Development Best Practices

By following these best practices you can minimize the number of errors introduced into your BizTalk application:

  • Follow a consistent rule for naming namespaces. Unless your company has different guidelines, follow the general rule of using company name followed by technology name followed by feature name and optionally the design (Company.TechnologyName.Feature.Design). You may choose to omit the technology name for brevity in your BizTalk solutions. For more guidelines on naming namespaces, see Namespace Naming Guidelines.
  • Create a standard for new XML target namespaces. Consistency across namespaces is important, so choose a standard that is clear, concise, and therefore easy to follow. One possibility is to use organization name and artifact name and optionally a version name and direction name (inbound, outbound).
  • Use project and assembly names that match the associated namespace. This provides consistency and can make deployment and maintenance easier because assemblies are readily identifiable. Exceptions can be made for shared projects and custom assemblies that can use a non-project-specific name.
  • Adopt naming conventions for orchestrations, messaging, ports, and other BizTalk artifacts. There are many different conventions available; you should choose the one that best conveys what an artifact is trying to accomplish, represents, or contains. For example, naming map files using the template <SourceSchema>_To_<DestinationSchema>.btm enables the user to quickly identify the transform performed by the map. For more details on artifact naming, see Developing Integration Solutions with BizTalk Server 2004.
  • Develop custom Visual Studio project templates for often-used configurations. If your team relies on the same configuration for each new project, you can package the configuration as a Visual Studio project template and ensure the basic configuration is consistent for all team members. For more information about project templates, see the MSDN® article Create Reusable Project and Item Templates For Your Development Team.
  • Consider creating secondary message pick-up locations for testing and error recovery. As you build your orchestrations and other artifacts, consider creating an alternative message pick-up location for processes that could fail.
  • Minimize the size of your BizTalk project. The Visual Studio compiler will not successfully compile a project if it would result in an assembly larger than 75 megabytes. When the compiler reaches a size constraint it will emit fatal error CS0013 "Unexpected error writing metadata to file <filename>" and halt.
  • Avoid using the project name as a map type name. When adding a new map to a BizTalk project in Visual Studio 2005, do not use the project name as the type name. If you do, the compiler will generate one or more errors similar to "The type name <name>' does not exist in the type".
  • Avoid using keywords or namespace names as orchestration types. Do not use reserved words like "string" for orchestration (or any other) type name; doing so will result in one or more compilation errors.

Other Resources

The following resources may be useful when developing your application:

  • Visual Studio Templates in the Visual Studio documentation. This page provides links to topics on using existing templates and creating new templates.
  • Developing Integration Solutions with BizTalk Server 2004 by Angus Foreman and Andy Nash. While written for BizTalk Server 2004, much of the information contained in this technical article can be applied to BizTalk Server 2006 development including naming conventions, deployment scenarios, and testing information.

When you are writing custom code, your ability to extend and troubleshoot your custom components will be greatly affected by how the code is written, commented, tested, and versioned. This section contains important best practices and resources for minimizing the defects in your code.

Custom Coding Best Practices

The following best practices may help you develop more maintainable, reliable, and extensible code for your BizTalk application:

  • Provide purposeful, relevant comments. Use whatever commenting features your language offers to write purposeful comments that are relevant to the code. Always concisely document algorithms, general method flow, and all conditional and loop statements.
  • Create and maintain key design and other development artifacts. Create documentation relevant to the solution and keep it current by updating it as the requirements, code, environment, or other application facts change. You should document key designs more fully in your design document than in code comments.
  • Use Trace or Debug to follow program flow. Using Trace switches, you can control trace behavior through the configuration file. Both Trace and Debug allow you to send output to interested listeners that you or another tool implements.
  • Avoid using Microsoft.BizTalk.ExplorerOM in 64-bit processes. The Microsoft.BizTalk.ExplorerOM DLL is only supported in 32-bit processes.

Other Resources

The following resources may be useful when coding your application:

  • Exception Handling Application Block by Microsoft. The Enterprise Library Exception Handling Application Block lets developers and policy makers create a consistent strategy for processing exceptions that occur in all architectural layers of an enterprise application. For more information about other application blocks, see Enterprise Library for .NET Framework 2.0.
  • Logging Application Block by Microsoft. This application block provides extensive support for logging to many different targets including e-mail and files. For more information about other application blocks, see Enterprise Library for .NET Framework 2.0.
  • Patterns & Practices online documentation on MSDN. Microsoft patterns & practices contain deep technical guidance and tested source code based on real-world experience. Content includes software factories, guides, reference implementations, and application blocks and was created, reviewed, and approved by Microsoft architects, product teams, consultants, product support engineers, and by Microsoft partners and customers.

While it may seem obvious to use a source control system, it is important to emphasize that tracking changes to source code—and protecting the source code from inadvertent changes and loss—should be a top priority in any development process. By maintaining a healthy version control system and check-in process, you can minimize the errors that are introduced to your BizTalk solution.

Source Control Best Practices

Compare the following source control best practices with your own development process:

  • Use a consistent folder structure for solutions and projects. Team development is made easier when a consistent folder structure is used on all member computers. This practice can also reduce the amount of time it takes to identify build issues across computers and decrease project ramp-up time for new team members.
  • Keep source control and file system structures identical. This keeps team member directories synchronized with the source system and with other developers and helps to ensure they are following team project organization guidelines.
  • Define and use a common root folder. Organize projects under a common root folder in the source control system. Developers should create the same root directory on their own computers.
  • Create a master solution that will hold all projects. The master solution can be used as the main build solution and is a recommended practice for medium to large BizTalk projects. All related BizTalk projects should be stored under the master solution.
  • Divide the project folder structure according to business process. Shared processes should be sequestered to their own folder. This will make it easy for developers to navigate to the different business processes in the solution and make enhancements without modifying unrelated processes.
  • Group related pipelines into separate projects. During development of pipeline components, it is a common requirement to modify and retest a pipeline independent of the rest of the solution. For this reason it is often helpful to keep pipeline solutions as a separate BizTalk project, resulting in a separate pipeline assembly that can be removed and redeployed without the need to rebind the rest of the solution.
  • Use unique strong name keys when appropriate. If the business solution being developed is composed of two or more distinct parts, then consider whether multiple key files should be used. Multiple keys in this scenario allow the parts to be treated as independent entities in the future, for example with differing upgrade paths.
  • Keep test messages in their own folder under the project. Choose a folder name to hold messages ("Msgs" or "SampleMessages") and use it consistently across all BizTalk projects. You should keep generated and example messages distinct by naming convention or by placing them in a separate folder. Track version numbers in the file name and through your version control system.
  • Check in code only when it has passed functional tests. The developer should be confident that the code will build successfully without breaking any related code. Schemas should be checked in only when they have been tested against a wide variety of messages, BizTalk projects containing business processes should be checked in only after testing with expected (and unexpected) messages with all ports configured, and Web service projects should be checked in only after testing using a test harness or by the initiating system.
  • Use the version control system to track non-BizTalk projects related to your solution. Use the version control system to track custom tools, deployment utilities, scripts, documentation, and other artifacts relevant to your BizTalk project. For example, if your project uses a Visual Basic® .NET Windows® application to manage accounts in a related system, you should consider tracking the executable and configuration files.
  • Choose a versioning number approach and stick with it. There are two approaches to setting version numbers for BizTalk solution assemblies: choose a fixed assembly version and increment only the file version, or increment both assembly and file version for a build. The approach you choose will impact how you maintain and deploy your project.

Other Resources

The following resources may be helpful additions to your source code control process:

  • Concurrent Versions System (CVS) by the Free Software Foundation. CVS is an open-source version control system with server and client software that runs on a number of different platforms. It contains a number of features and ample documentation.
  • Visual SourceSafe 2005 by Microsoft. Visual SourceSafe® contains many features for managing source code and integrates with Visual Studio 2005. It also provides a seamless migration path to Visual Studio Team System if you later move to that platform.
  • Visual Studio Team System (VSTS) by Microsoft. VSTS is not directly supported by BizTalk projects, but you may find that your project can be managed through VSTS through alternative methods.
  • Assembly Versioning in the .NET Framework documentation. Provides additional information about versioning .NET assemblies without focusing on BizTalk Server. It also provides links to useful information about configuration files, how the runtime locates an assembly, and assembly attributes.

Testing should be an integral part of any BizTalk Server development process.

Testing Best Practices

By following these best practices you can minimize the number of errors introduced into your BizTalk application:

  • Make testing a first-class part of your software development process. If your software development process does not consider testing a top priority on par with business and functional requirements, testing may be haphazard, resulting in potentially more errors.
  • Develop and maintain a test plan and test cases. Conduct formal requirements gathering for testing and work with the project team to ensure that user, support, stake holder, and developer staff concerns are met. Many test cases can be written by reviewing the requirements document.
  • Integrate unit testing into your development process. Write your unit tests before or during the development process. If you write the test before the development process, you have an easy way to verify your code before checking it in.
  • Use check-in tests for code. Only check in code that has been tested by the developer and, ideally, by another individual to ensure the code works as expected.
  • Verify BizTalk artifacts using built-in tools whenever possible. For example, by using the validate, test, and source code viewing functionality of BizTalk Mapper, you can verify that your map works as expected against a broad range of test data.
  • Maintain separate test, staging, and production environments for your application. By maintaining separate environments, you can safely test the installation, operation, and maintenance of your BizTalk solution. By keeping the staging server in sync with production, you can test enhancements, updates, and configuration changes without impacting production.

Other Resources

The following resources may be helpful when testing your solution:

  • Visual Studio Team Edition for Software Testers by Microsoft. This version of Visual Studio provides enhanced support for managing the test life cycle and features an extensible test infrastructure for running legacy and custom tests.
  • BizUnit by Kevin Smith. BizUnit is a test framework for automated testing of BizTalk applications. The tool provides an extensive collection of built-in test steps for different activities including the rule engine, orchestrations, Web services, database, performance counters, and validating XML.
  • LoadGen by Microsoft. This tool is useful for generating loads on a BizTalk server and can be used to stress-test your deployment.

In BizTalk Server 2006, application deployment complexity can run the gamut from simple (a project with few dependencies and artifacts) to complex (multiple applications with many dependencies installed on multiple servers). The key to managing deployments of any size is to consider deployment during the requirements phase and follow through in development, building appropriate scripts and modifying the solution to ensure that you have a documented, repeatable deployment process.

Deployment Best Practices

You can minimize deployment problems by following these best practices:

  • Group related artifacts together in a single application. This simplifies management and provides a logical grouping of similar functionality, making troubleshooting easier.
  • Deploy shared artifacts in a separate application. Only one artifact having the same locally unique identifier (consisting of the artifact name and possibly other attributes) can exist in a BizTalk group. By storing shared artifacts like schemas in their own application, you have finer control over dependencies.
  • Deploy a shared Web site in a separate application. If you are deploying a Web site that will be shared by more than one solution, deploy it as a separate application. If it were shared and part of another application, its virtual directory would be removed when that application was removed. The Web site would stop working and any applications relying on it would stop working.
  • Never deploy an assembly to a production computer from Visual Studio. During deployment, Visual Studio may undeploy, unbind, stop, and unenlist artifacts contained in project assemblies, causing unexpected and undesired consequences in a production environment. Never install Visual Studio on the production computer and never refer to a production database from a computer running Visual Studio.
  • Avoid large (over 100 MB) MSI files. Large (over 100 MB) MSI files may not be deployed within the transaction time-out of the COM+ components used by BizTalk Server during application deployment, causing the deployment to fail. You should deploy smaller MSI files or modify the default transaction time-out for the deployment COM+ objects. For more information about changing the transaction time-out, see Best Practices for Deploying a BizTalk Application.
  • Document your deployment process. Even the most complex deployment scenario can be simplified with documentation. You should document the deployment environment, steps for deploying the solution, and custom configuration settings for hardware and software.
  • Configure a binding file for each environment and computer. You can control settings by environment or server by packaging additional binding files in your solution's exported MSI file. For more information about creating custom binding files, see Customizing Binding Files.
  • Customize your MSI file with pre- and post-processing scripts. For more information about processing scripts and MSI, see Using Pre- and Post-processing Scripts to Customize Application Deployment.
  • Ensure that only BizTalk administrators have access to the assemblies, binding files, and policy files. These files may contain sensitive business data such as connectivity and configuration information. If you deploy applications through a network share, configure the discretionary access control list (DACL) on the network share so that only BizTalk administrators can view its contents.
  • Verify the security settings on virtual directories before exporting an MSI file. Be aware that the security settings on the virtual directory are those in effect when the MSI file is generated. If you are deploying an application with a virtual directory and the virtual directory already exists in the destination environment, the security settings on the existing virtual directory will be in effect.
  • Avoid using Dotfuscator or any other obfuscation technology for assemblies deployed to BizTalk Server. Obfuscation modifies symbol names and other objects within an assembly in an effort to protect intellectual property and can cause problems with BizTalk Applications. Do not obfuscate BizTalk Server assemblies unless you can control naming and other obfuscation properties to ensure the assembly works with BizTalk Server.

Other Resources

The following resources may be useful when packaging and deploying your BizTalk applications:

  • Understanding BizTalk Application Deployment and Management in the online documentation. This topic points to in-depth details on all aspects of BizTalk application deployment including binding files, management tools, and dependencies.
  • Application Deployment Security Recommendations in the online documentation. This is an excellent source of security recommendations for application deployment and contains links to many useful related articles.
  • .NET Build Tool (NAnt) on Sourceforge. The .NET build tool provides functionality similar to the Ant by the Apache Software foundation but for .NET; you can extend the tool using .NET classes and accommodate many diverse build tasks including BizTalk tasks.
  • Deployment Framework for BizTalk Server 2006 by Scott Colestock. The chief goal of the Deployment Framework is to streamline the deployment process and make deployment consistent and repeatable. It requires the NAnt tool.
  • UK SDC BizTalk 2006 Documentor by Jason Birth. The UK SDC BizTalk 2006 Documenter creates compiled help files (*.chm) or Microsoft Word 2003 XML files to quickly document a given BizTalk Server 2006 installation. This tool can be run on an ad-hoc basis using the UI or from the command line as a post build/deploy task to create a compiled help file describing a BizTalk Server 2006 installation.
  • BizTalk Server 2006 Minty Fresh Documentor by Eric Battalio. The Documentor program retrieves BizTalk Server 2006 configuration information and saves it as XML for reference; it also includes an XSLT file that transforms the XML into HTML with a table of contents.