An important function of the planning process is to draw up the master list of business processes that you will deliver with the integration solution. This task ensures that a single, comprehensive list of all the business processes exists, along with a list of all the business rules that apply to those processes. You can use this list to plan and design the development of the BizTalk Server 2004 artifacts that are required to carry out those business processes.

One possible approach to developing the list of business processes is to devise logical categories of related business processes and then list all the processes within each category. For example, categories like "User Management," "Supplier Transactions," "Customer Transactions," "Catalogue Management," or "Credit Control" are often meaningful to the business and typically consist of several related business processes (with related system and messaging requirements).

In the example scenario, the business process list is documented in the following tabular format.

Table 1 Example processes and categories

The team now has a master list of business processes that need to be developed. The next step is to capture the process details that are significant to the integration solution. Detailed information that is typically captured about each process falls into two categories—logical process information and implementation information. You may also want to diagram the high-level processes so that developers will have a starting point for creating BizTalk orchestrations.

Logical Process Information

Implementation Information

Diagramming Business Processes

The process of examining all business processes produces a list of the messages that are required to deliver the solution. When defining messages consider the following:

• Determine the complete list of entities that are meaningful to the organization to allow the processes to be designed. Typically you started this list when looking at the processes and you will refine it here to produce the "business-centric" list of all the entities that are required.
  
• Determine which message schema will define the "standard" messages. These are messages that are not constrained by any specific integration requirement but instead define a business entity, concept, or operation.
  As an example, consider a "customer" message. Typically, different back-office systems implement interfaces that handle many different subsets of customer data, but there is only one standard that represents the organization's view of "customer." Note that this standard is based upon how the organization views the entity (as opposed to a system). This information could then used to define the Customer Message Standard for the organization and will be driven by the organization's long-term goals. For example, you can define the customer message so that it can contain data that is not currently required, but will be needed to deliver new services in the future.
  
• When considering standards for messages, consider the cost of creating a standard and the cost of mapping to and from the standard for each of the upstream and downstream systems. In some cases, the standard provides benefits (especially when multiple systems all use a variation on the standard). In other cases mapping from one system to another system (without mapping to the intervening standard) can be a more practical approach.
  
• Determine the ownership of standards. It is important for an organization to realize that messaging standards are a representation of business entities and concepts and should be owned by the business and IT jointly. This includes the owning of namespaces.
  
• Are there existing messaging standards that you can use? Industry-specific standards may exist for exchanging data between organizations (for example, health care and finance). It is worth determining whether such a standard exists, and if it does, whether using the standard rather than defining a new one can provide benefits (both current and future).
  
• Some vendors may publish standard messages for interacting with their systems. Using these schemas may save considerable development effort and remove specific integration challenges from the project team to a vendor's supported solution.
  
• When defining messages, your result should be a comprehensive list of the messages you require to implement the solution. By stabilizing and gaining agreement to this list early in the project, you can avoid the introduction of new messages late in your development phase.
  

When describing an integration solution, there is typically a large amount of detail to be captured about each of the systems and processes. It is useful to start by listing some common properties of each of the systems involved. It is typical to collect this information for each system participating in the integration solution.

The following table shows some common system attributes.

Table 3 Common attributes of systems

Example Integration Information Gathering Scenario

Having previously defined the systems and business processes in scope, the next step is to document the interfaces that are required to enable the integration layer to connect to the upstream and downstream systems. One way to capture this information is to list the processes and then detail each of the interfaces required by each process. If you are designing a system to replace an existing integration solution it can be helpful to obtain actual copies of all the types of messages that are currently going through the various systems.

The following list describes typical information that you should gather while you are categorizing interfaces:

• Interface name
  
• Business name
  
• Interface description
  
• Source system name
  
• Destination system name
  
• Interface address (URI/URL)
  
• Interface direction—examples include:
  
  • Unidirectional/Incoming (to the integration layer)
    
  • Unidirectional/Outgoing (from the integration layer)
    
  • Bidirectional/Incoming
    
  • Bidirectional/Outgoing
    
• Protocol
  
• Message/data format used
  
• Message schema name
  
• Expected number of messages per minute, average and peak
  
• Expected average message size
  
• Message schema owner
  

Later in the planning process, this list of interfaces can be further extended to help produce a detailed list of functional requirements that can be used as the basis of a BizTalk Server 2004 development.

A helpful way to document those functional requirements is in the form of test cases with specific input files and expected output files. This typically means collecting a lot of data early in the project, but in all likelihood this data will be required when development or testing starts. By gathering it early in the development process, you can spot any unanticipated challenges early on.

When developing an integration solution, the definition of interfaces is a significant part of the design process. The interface is typically considered as a "contract" between each of the parties involved in the development of the integration solution. The contract verifiably ensures that parties are developing compatible systems.

When documenting interfaces it is useful to be able to produce detailed descriptions of the interfaces as part of the contract. The best way to document the contract is with a domain-specific language like Web Services Description Language (WSDL), or with some other consumable form of metadata. All parties can use these descriptions to validate that their development meets the interfaces expected by upstream and downstream systems. When working with XML-based solutions like Web services and BizTalk Server 2004, standards exist to produce these detailed contract descriptions. The following table shows the contract formats for various interface types.

Table 5 Interface types and contract formats

Interface message type	Contract format
XML message	XSD schema files. Note If no XSD schema file exists, but sample XML messages exist, then BizTalk Server 2004 can generate an XSD based upon a sample XML file. See "Add Generated Items" in BizTalk Server 2004 Help for more details on this functionality.
XML Web service	WSDL definition files.
Flat files	BizTalk schema and the flat file validation tools. Note The flat file command-line tools can be used to aid the validation of flat file instances against a BizTalk Server schema and can be found in the SDK under SDK\Utilities\Pipeline tools.

At the end of the information-gathering process, the high-level requirements of the integration solution are captured in a series of related documents that list unique business processes, systems, and interfaces. As the design process progresses, the level of detail captured increases. Prior to development, it is typical to produce a list of BizTalk Server 2004 artifacts to be developed during the build phase.

Additionally the planning phase may well identify the number and type of test harnesses or stub systems that will be required to meaningfully develop and test the business processes. The planning phase may also identify the data requirements needed to allow development to proceed. This may include migration requirements and cross-reference data.

You use this list of requirements to aid in designating teams, planning schedules, and identifying required development resources.

When developing a solution within a team it can be very helpful to define owners and development teams for distinct parts of the solution early in the development process. Typically, named individuals (or groups of individuals) are given ownership of logical parts of the solution. Useful divisions of work can include allocating ownership of:

• Individual business processes
  
• Process-specific messages, schemas, transports, and protocols
  
• Shared message standards
  
• Map development
  
• Error messages and error-handling standards
  
• Upstream and downstream system interfaces
  
• Helper classes and utilities
  
• Test data and test tools
  
• Deployment and build processes
  

Typically, the owners are responsible for understanding their parts of the solution and act as the "gateway" to any requested modifications. In this way when a modification to a design is proposed, the owner can assess the effect of the proposed changes and then allow or disallow that change. This is particularly important when working with shared parts of the solution, like shared message standards, where a change can have a potentially significant impact upon the development team and upstream or downstream systems.

The following sections discuss solution structures and development models for a BizTalk Server 2004 project with multiple developers.

The term "solution structure" refers here to the logical and physical structure used to store all the related BizTalk Server 2004 files and folders required to produce, develop, test, and deploy a production solution.

The term "team development model" refers to the relationship between Visual Studio .NET projects and solutions, Microsoft Visual SourceSafe® source configuration, and the setup and processes used for a team of developers using common resources across multiple workstations.

It is important to enforce a solution structure. A BizTalk Server 2004 solution that is built to meet business requirements typically consists of many separate related artifacts. To avoid rework and build failures, these artifacts need to be managed throughout the project from development, test, deployment, and production. A typical BizTalk Server 2004 solution will contain the artifacts in the following table.

Note
This list does not include artifacts related to Business Activity Monitoring (BAM), Human Workflow Services (HWS), and the Business Rules Engine (BRE).

Table 6 Typical Visual Studio .NET and BizTalk solution entities

The solution structure is important to a team of BizTalk Server 2004 developers for the following reasons:

• Any integration solution by its nature consists of many independently developed assemblies that need to fit together, like pieces of a jigsaw puzzle, to deliver the complete solution. If these pieces are not closely managed throughout the development, there is a strong chance the pieces will not fit together when the complete solution is tested. A predefined solution structure assists in enabling the management of these parts.
  
• In a solution of medium to high complexity, BizTalk Server 2004 projects are themselves often linked and dependent upon each other. A solution structure helps ensure that the relationships between BizTalk Server 2004 projects is enforced and maintained throughout the development process.
  
• Deploying and testing a BizTalk Server 2004 solution requires more than just the output of the compilation process. A typical process may require binding files, test data, test harnesses, and stub systems as well as the BizTalk Server 2004 assemblies to perform a functional test. A well-defined solution structure allows testing and deployment to be automated.
  

A typical BizTalk Server 2004 solution structure is composed of the following logical elements:

• A Visual Studio .NET solution structure, which describes the relationship between BizTalk Server 2004 solutions, project files, and dependencies.
  
• A file system folder structure in which to store BizTalk Server 2004 project files and the other associated entities required to develop and test a solution.
  
• A development model that describes how a team of developers share the server resources required to develop a solution.
  
• An approach to using Visual SourceSafe that enables the BizTalk Server 2004 projects and artifacts to be successfully source controlled and shared among a team of developers.
  

There are many ways to create a BizTalk Server application composed of maps, schemas, orchestrations, pipelines, and so on. The most common is to place all of the BizTalk artifacts in one project, compiled and then deployed as a single unit. This method has the benefit of simplicity but is less effective when you take into account required modifications and project upgrades.

Using this model, when modifications or upgrades are needed, you must first undeploy the complete application. This means stopping the orchestrations and potentially affecting related entities. For example, if you use custom pipelines, the undeploy operation causes the pipeline bindings to default back to the pass-through pipeline. After you deploy a change, you must reconfigure any location that uses custom pipelines.

As an alternative to using the single-project approach, consider how the application is structured and look for ways to split the artifacts into logical groups. A typical way to manage this is to place orchestrations, pipelines, schemas, and maps in their own projects. If a pipeline changes, just a single assembly can be undeployed, and there is no need to undeploy maps or schemas. In the same way, if a map changes there is no need to undeploy the schemas. Additionally, consider dividing sub orchestrations (that is, orchestrations that are called by other orchestrations) into their own projects.

Remember that a project can only be deployed as a single unit. If the task of redeploying a single project begins to involve the rebinding of unrelated resources, then you should consider splitting the project into smaller units that allow the deployment and binding of related items only.

Note

The preceding approach is a "horizontal" division of work. You may want to consider a vertical division as well (that is, by project or business process functionality). For example, if a pipeline or schema is updated it should only affect the business project that it is related to. This is relevant if you have the requirement to avoid shutting down a CRM integrator when the ordering system updates a schema.

The following table shows the structure of a typical project.

Table 7 Typical project structure

Team development with BizTalk Server 2004 has close parallels with team development of Web applications. Both models typically have dependent elements that can be shared between the team members or a user in isolation.

The development model for BizTalk Server 2004 proposed in this paper is based upon the "isolated model" of development. The models available for BizTalk Server development are "isolated," "semi-isolated," or "non-isolated." In the isolated model, no elements of the developer environment are shared (with the exception of access to a common Visual SourceSafe tree). When using semi-isolated and non-isolated models, increasing areas of the developer environment are shared. The nature of the BizTalk Server 2004 runtime means that isolated development typically provides the most effective approach. BizTalk Server 2004 developments are typically composed of several distinct environments, as shown in the following table.

Table 8 BizTalk Server environments

The team development model described below details an approach to configuring the developer tools, developer runtime, and shared runtime to provide an isolated developer environment.

What Is the Isolated Development Model?

Using an isolated model a developer edits, debugs, and runs functional tests completely isolated from other developers. Each developer has a self-contained development workstation with a local BizTalk Server Group. Access to the master source files is controlled via a Visual SourceSafe database located on a network file share. The following figure illustrates an isolated development model.

Figure 2 Isolated BizTalk Server development

The isolated model of BizTalk Server development provides the following benefits:

• No chance that BizTalk Server shared configuration information will interfere with another developer's work (for example, XML target namespace clashes occurring from multiple installed versions of shared schema)
  
• No opportunity for any one individual's BizTalk Server deployment and test processes interrupting other users (for example, the starting and stopping of BizTalk Server host instances, receive locations, or dependent services like IIS, SQL, and SSO)
  
• Ability to clear resources like event logs and tracking databases without disrupting other users
  
• Ability for developers to use different versions of shared resources, for example, helper classes and error-handling processes
  
• Ability for developers to attach and debug the BTSsvc.exe process without halting other developers' processes
  

A shared or non-isolated model can be used for developing with BizTalk Server 2004 if it is absolutely required, but developer efficiency may be reduced by the lack of the benefits listed above.

Using Microsoft Virtual PC to Host BizTalk Server 2004 Development Environments

Visual Studio solution files (with the .sln file extension) are used to group related projects together and are primarily used to control the build process. You can use solutions to control build dependency issues and control the precise order in which contained projects are built. Partitioning describes the processes of creating Visual Studio .NET solution files that divide up the multiple projects that compose a complete BizTalk solution. The approach used to partition BizTalk Server 2004 solutions and projects has a significant impact on the development and build processes in a team environment. There are three main approaches to consider when partitioning solutions and projects, as shown in the following table.

Table 9 Solution partitioning approaches

The partitioned single solution approach is often applicable, but is the most complex to set up. For these reasons this approach is documented in the appendix. The single solution approach uses the same principles as the partitioned, and the approach documented can easily be modified for the single solution. Unless you have very good reasons to use a multi-solution model, you should avoid this approach.

Attributes of a Partitioned Single Solution

When developing more complex BizTalk solutions it can be advisable to reduce the number of projects and source files required on each development workstation by grouping related sets of projects together within separate sub-solution files. This approach can be particularly beneficial if the complexity of the BizTalk Server 2004 solution means that loading, navigating, and rebuilding projects can take a significant amount of time.

This partitioned single solution allows developers to work on separate, smaller subsystems within the inner-system boundary. The following diagram illustrates the partitioned single solution model. Notice how separate solution files are used to allow you to work on smaller subsystems contained within the inner-system boundary. Also note how this results in projects being contained within more than one solution file. For example, in the following figure, Projects D and H are in a total of three solution files including the master solution.

Figure 3 Partitioned single solution

In the partitioned single solution model:

• All projects are contained within a master solution file. This is used by the system build process to rebuild the entire system. If you need to work on the top-level project file, you also work with the master solution.
  
• Project references are used between individual projects. For example, file references are not used and instead the project containing the dependency is added to the solution and a project reference created.
  
• Separate solution files are introduced for selected project files. If you want, you can introduce a solution file for each project within your system. Each solution file contains the main project file, together with any downstream project it depends on and any further projects it depends on, and so on down the dependency chain.
  
• Separate solution files allow you to work on smaller subsystems within your overall system but retain the key benefits of project references. Within each sub-solution file, project references are used between constituent projects.
  

For more information about partitioning Visual Studio .NET solutions see Chapter 3, "Structuring Solutions and Projects," in the MSDN white paper Team Development with Visual Studio .NET and Visual SourceSafe that was referenced at the beginning of this section.

As described in the previous section, single solutions and partitioned single solutions use project references to create references between dependent BizTalk Server 2004 projects. This is significant because project references provide significant advantages over file-based (DLL) references. Specific benefits include:

• A build process using project references automatically calculates the build order dictated by the dependencies. This significantly simplifies the build process for projects with dependencies.
  
• A project-referenced solution can determine if a referenced project has been updated and will manage the rebuilding of the references. This is important in an environment when several users have dependencies upon a shared project (like a helper project) that is changing during the development phase.
  

Referencing External Dependencies

Copy Local Attribute

The file system folder structure used to store the BizTalk Server 2004 integration solution must accommodate not only the BizTalk Server 2004 solutions and projects, but also all the additional artifacts that are required to develop, build, test, and deploy a BizTalk Server 2004 solution. The folder structure must also be compatible with the structure used within the team's Visual SourceSafe (VSS) repository to ensure efficient integration with the common source control tasks.

The folder structure described here is based upon typical BizTalk Server 2004 requirements and is designed to comply with common Visual SourceSafe tasks. It can be modified to meet the requirements of a given development team.

When creating the VSS structure, keep in mind the following points:

• Use a consistent folder structure for solutions and projects. Development in a team development environment is easier to manage if a common structure for storing Visual Studio .NET solutions and projects is used across the whole team. This is especially true when each BizTalk Server 2004 project will be generating and using files such as binding files that will be required by build, test, and deployment teams.
  The structure of BizTalk Server 2004 project files means that certain project entities (like the strong name key file) are by default referenced by an absolute file path. This means that unless the same file structure is replicated by each developer, each developer will need to modify the project to allow the project to compile and deploy.
  It is often easy to start development without taking the time to standardize on the folder structures. This will inevitably cost more time later on as project links and test harnesses need to be "patched" as the solution develops.
  
• Keep VSS and file system structures identical. To simplify the management of multiple developers' environments, set up a folder structure within Visual SourceSafe that matches your local file system structure. This helps ensure that a developer can simply get a latest version from Visual SourceSafe and know that the structure on the disk is compliant to the team's standards.
  
• Define and use a common root folder across the team. It is recommended to keep all project code and deliverables under a single folder root, which can be created on all developers' computers. For example, create a root folder of $/SysInteg2004 within Visual SourceSafe and all developers can create C:\SysInteg2004 on their local file systems. This acts as a container for all of your development systems.
  The drive need not be the C drive, but if a drive other than C is used, make sure that all developers have a similarly named drive available. In case you want to use drive letters that are not available on all computers, the SUBST shell command can be used to create drive letters mapped to physical folders, for example:
  
  SUBST m: c:\SysInteg2004

  When the preceding command is executed at the command prompt, it creates a drive letter m: mapped to physical folder c:\SysInteg2004. Avoid using a network share to store the project files (to avoid the security warning that arises from developing a .NET application on a non-local drive).
  
• Create a master solution that will hold all projects. As described in the section above, the single partitioned model for BizTalk Server development is generally recommended for medium to high complexity BizTalk projects. For this reason a master solution should be created that will hold all the subprojects. This master solution will typically be used as the main build solution. For notes on creating a master solution for a partitioned single solution in Visual SourceSafe see "Appendix: Step-by-Step Guide to Setting Up a Partitioned Single Solution."
  
• Store all Visual Studio .NET BizTalk Server 2004 projects in a folder under the master solution. If Visual SourceSafe is being used as the source control environment then it is necessary to ensure that all subprojects are created in a folder underneath the folder holding the master solution that contains them.
  

  Note
  It is possible to store multiple solution files in the same folder, but this limits the ability of Visual SourceSafe to create partitioned solutions.

  For notes on adding subprojects to a master solution for a partitioned single solution in Visual SourceSafe see "Appendix: Step-by-Step Guide to Setting Up a Partitioned Single Solution."
  For more information, see "Working with Visual SourceSafe" in the MSDN white paper Team Development with Visual Studio .NET and Visual SourceSafe that was referenced at the beginning of this section.
  
• Divide the folder structure into shared and process-specific sections. When creating the file structure it is usual to divide up the folder structure to separate the shared entities versus the specific business process entities. The shared entities are common to multiple projects and may include helper classes.
  For example, the first three folders in the following list are organized by shared entity and the last two are organized by business process:
  
  C:\SysInteg2004\_Master_Solution\Shared\
  C:\SysInteg2004\_Master_Solution\Shared\EmailHelper
  C:\SysInteg2004\_Master_Solution\Shared\SharedSchema
  C:\SysInteg2004\_Master_Solution\AccountRequest\
  C:\SysInteg2004\_Master_Solution\AccountValidate\

• Pipeline 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 Server 2004 project, resulting in a separate pipeline assembly that can be removed and redeployed without the need to perform rebinding of the rest of the solution.
  Additionally it is common practice to keep the code that implements the actual pipeline interfaces and pipeline processing logic in a separate project with a reference from the BizTalk Server 2004 project (containing the .btp files) to the C# or Microsoft Visual Basic® .NET project.
  For notes on debugging pipelines see "Debugging Pipelines" later in this document.
  
• Creating deployment and test scripts. When developing with BizTalk Server 2004 it is common to automate complex or often-repeated tasks by using scripts or command (.cmd) files. Nearly all BizTalk Server 2004 deployment and runtime tasks are exposed as command-line tools or Windows Management Instrumentation (WMI) interfaces to enable the development of scripts to aid automation of these tasks.
  To enable the development of a unified build and deployment process, build and install scripts should be built by the individual developers, but viewed as reusable parts of the complete solution. If the scripts are written to be reusable then tasks like the deployment of a complete solution package can reuse the scripts. For example, if the deployment and undeployment scripts accept parameters to specify the paths for the DLL and binding file folder locations, the scripts can be reused when the compiled BizTalk Server assemblies are in a different location.
  Using this approach, each developer adds the install scripts for their specific processes to the folder and then a single process can easily be written to perform a full deployment of all processes. For more information about deployment scripts see "Automating Deployment Tasks." For more information about build scripts see "Automated Build Processes."
  Scripts are typically stored along with the process they reference, using standard script names as in the following examples:
  
  C:\SysInteg2004\_Master_Solution\AccountValidate\scripts
  C:\SysInteg2004\_Master_Solution\AccountValidate\scripts\deploy.cmd
  C:\SysInteg2004\_Master_Solution\AccountValidate\scripts\undeploy.cmd

  In this way solution-wide scripts can be built up that call the individual process scripts (for example, SolutionDeploy.cmd calls AccountValidate\scripts\undeploy.cmd).
  An alternative approach may dictate that the scripts used to deploy a BizTalk Server 2004 solution need to be in a single shared folder. In this case the scripts need to be named according to the process they relate to. Again this approach can be used to build solution-wide scripts by calling individual scripts.
  
• Strong name keys. All BizTalk Server 2004 projects result in assemblies that are deployed to the global assembly cache, and as such they must be signed with a strong named key during compilation.
  Typically a single Visual Studio .NET solution uses a single key file. This is true because the solution is treated as a single entity and is managed as such. If the business solution being developed is actually composed of two or more distinct parts, then consider if two 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.
  When considering helper projects, the same considerations apply. If the helper project is (or will be) a separate entity then it should be built using a separate strong name key.
  In an organization that has a closely guarded secure key that developers do not have access to, consider using delayed signing with the key. For more details on delayed signing, see Delay Signing an Assembly in the .NET Framework Developer's Guide available in the MSDN Library.
  The process of creating the key and including it in the project is simple; however developers should be aware that the path to the key stored in the BizTalk Server 2004 project is stored by default as an absolute path that includes the drive name (for example, Z:\CommonFiles\Keys). This has the disadvantage that projects cannot be edited or compiled on another workstation unless the path to the keys is exactly the same (or the key paths are modified every time the project is moved).
  If it is required to not tie the project to a specific drive name it is possible to change the path to a relative path (and hence remove the drive name) by modifying the assembly key file path.
  For a BizTalk project with the default folder structure for the output assembly, for example:
  
  <project folder>\bin\development 

  The key file path will be modified to the following:
  
  ..\..\<keyfilename>.snk 

  The following figure shows the relative key file path.
  Figure 4 Relative strong name key paths
  
  
  
  It is often helpful to build a project directory structure that can be replicated upon every workstation with a specific path to the key in the structure, for example:
  C:\SysInteg2004\_Master_Solution\Shared\Keys
  
• Test harnesses and stubs. It is generally recommended that test harnesses and test stubs be developed early in the project because they are useful resources and they also help develop a deeper understanding of the actual interactions between the integration layer and the other systems. If test harnesses are kept under the master solution then they can be included in the source control of a specific process or under a more general shared project. For example:
  C:\SysInteg2004\_Master_Solution\Shared\Test
  For more details on test harnesses, see "Testing BizTalk Server 2004 Solutions."
  
• Cross-reference seed data. If the BizTalk Server 2004 cross-reference databases are being used as part of the business processes under development then it is often necessary to load the databases with the necessary data to allow lookup operations to successfully take place. Cross-reference data can be input using the BizTalk Server 2004 Cross Reference Import Tool (btsxrefimport.exe) and XML "seed files."
  When the import tool is run it empties the cross-reference databases before importing new data from the seed file. This means that prior to the development of the "all processes" deployment script all seed data must be consolidated into one seed file. For example:
  
  C:\SysInteg2004\_Master_Solution\Shared\CrossRefData\MasterSeedData.XML

  Early in the development cycle, individual developers may need to seed their local database with process-specific data only. In this case the seed data should be held in individual files, named according to the process they relate to. For example:
  
  C:\SysInteg2004\_Master_Solution \Shared\CrossRefData\AccountRequestSeedData.XML

• Storing BizTalk binding files. When developing BizTalk Server 2004 projects binding files are produced that define the binding of a logical process to the physical transports and hosts. This binding information is initially created by using the GUI tools but is then persisted in binding files to ensure that a process can easily be deployed in a repeatable, scripted manner.
  Complexity arises from the fact that the physical binding information for the development environment may be different from that in the test, pre-production, and final production environments. Additionally the binding files contain references to the specific version numbers for the DLLs being deployed, and consequently these files need to be managed to be kept in sync with any DLL version number changes.
  To help manage this complexity the binding files should always be located within a specific location for a given process and named following a naming convention. This makes it easier to perform modifications to the binding files (either manually or automatically).
  Typically binding files should be kept in a folder called "bind" underneath the project folder and named according to a naming standard. For example, the binding files for the "AccountRequest" process in the development environment could be kept in a file as in the following example:
  
  C:\SysInteg2004\_Master_Solution \AccountRequest\bind\bind_AccountRequest_Stage1_DevEnv.xml

  Note how this convention allows binding files from multiple processes to be moved to a single folder location and still be identified. In some solutions multiple binding files may be required. Ensure that the naming convention used can take this into account.
  
• Location for file dependency DLLs. When creating the folder structure it is helpful to create a common folder to hold DLLS that are referenced as file dependencies. By ensuring that all developers follow the same folder structure, file references will not become broken when solutions are moved between developers or workstations. For example:
  
  C:\SysInteg2004\ReferencedBin

• Test messages. When developing schemas and using messages it is common to spend considerable effort testing many different sample messages against XML schema and orchestration processes.
  In a real-world solution, sample messages are a valuable asset because they contain data that is meaningful to the business solution. Random or dummy values in the same message will typically cause the process to fail. For this reason sample messages should be treated with as much care as the code of the solution.
  To assist in managing the message files, keep test messages under a specific folder called "msgs". In cases where there are both "generated instances" and "example messages" (for example, messages from an existing system) it is useful to keep these messages separate to allow comparison between the developed schema and actual data. For example:
  
  C:\SysInteg2004\_Master_Solution\AccountRequest\msgs\
  C:\SysInteg2004\_Master_Solution\AccountRequest\msgs\generated\
  C:\SysInteg2004\_Master_Solution\AccountRequest\msgs\examples\

  It is common in an integration project to have multiple versions of schemas and consequently, multiple versions of message files. In the same way that code has a version number applied, it is worth considering ensuring that version numbers are used when naming files.
  It may also be worth considering storing message instances within Visual SourceSafe. This has the added advantage of allowing comments to be added to versions and previous versions to be examined.
  

  Note

  Instances of a message can be generated from a schema and can also be validated by using the "Generate Instance" function in the Visual Studio .NET BizTalk Server 2004 Schema editor. This function is extremely useful when testing a newly created schema against a system to be integrated. The generation capability also allows you to start development when the schema of a message is known but you have not yet been provided with instance messages.

• Example folder structure. The example folder structure described above typically looks like the following for a sample project:
  
  C:\SysInteg2004\ReferencedBin\
  C:\SysInteg2004\_Master_Solution\Shared\Keys\
  C:\SysInteg2004\_Master_Solution\Shared\CrossRefData\
  C:\SysInteg2004\_Master_Solution\Shared\TestHarnesses\
  C:\SysInteg2004\_Master_Solution\Shared\SharedSchema\
  C:\SysInteg2004\_Master_Solution\Shared\EmailSendOrchestration\
  C:\SysInteg2004\_Master_Solution\Shared\ErrorHandlingOrchestration\
  C:\SysInteg2004\_Master_Solution\AccountRequest\
  C:\SysInteg2004\_Master_Solution\AccountRequest\bind\ C:\SysInteg2004\_Master_Solution\AccountRequest\msgs\
  C:\SysInteg2004\_Master_Solution\AccountRequest\msgs\generated\
  C:\SysInteg2004\_Master_Solution\AccountRequest\msgs\examples\
  C:\SysInteg2004\_Master_Solution\AccountRequest\scripts\
  C:\SysInteg2004\_Master_Solution\AccountRequest\AccReqRecPipe
  C:\SysInteg2004\_Master_Solution\AccountRequest\AccReqRecPipeCode

There is a known limitation with Visual SourceSafe related to the handling of Unicode files. When working with BizTalk solutions it is necessary to prevent Visual SourceSafe from corrupting BizTalk Unicode files by performing the following steps before adding a BizTalk Server 2004 solution to Visual SourceSafe:

1. Start Visual SourceSafe 6.0 Admin.
   
2. Select the SourceSafe database to be used.
   
3. On the Tools menu, click Options.
   
4. Click the File Types tab.
   
5. Add the following to the end of the list of binary files. Verify there are semicolons between each file type.
   *.btm;*.btp;*.xsd;*.odx
   
6. Click OK.
   

The preceding steps cause Visual SourceSafe not to inspect BizTalk files and attempt to change their formatting.

Note
Files of the above type previously added to Visual SourceSafe will need to be deleted, including selecting the check box to destroy them permanently. Files then need to be re-added to Visual SourceSafe. Ensure that a backup of the files exists before carrying out this step.

All project creation and manipulation within Visual SourceSafe should be performed by using the integrated Visual SourceSafe support menus within Visual Studio .NET. Do not use Visual SourceSafe Explorer to perform these operations.

Note
Even when using the Virtual PC approach to development, Visual SourceSafe should be used in exactly the same manner as in a traditional development environment.

The recommended approach to using Visual SourceSafe is to check in code only when it has successfully passed functional tests and the developer is confident that the code will successfully build without breaking any related code. Applying this model to BizTalk Server 2004 results in the following guidelines:

• BizTalk Server 2004 projects that contain only message schema should not be checked in until the schema have been successfully tested against a variety of sample messages.
  
• BizTalk Server 2004 projects that contain a business process should not be checked in until the solution has been successfully tested using the appropriate input and output messages using the correct send and receive ports.
  
• ASP.NET Web service projects should not be checked in until the Web service code has been tested against the initiating system or by using a test harness.
  

If this model is followed, then the Visual SourceSafe repository will always hold a build that can be successfully built and tested. This principle is important if the approach of "nightly builds" is to be adhered to.

An alternative approach to check-in is that of checking in "intermediate" versions. In this approach an intermediate version will not yet have successfully passed functional tests and can be thought of as "between builds." This is generally not a recommended approach because it breaks the general principle of always having a buildable version within the source control system. However some teams prefer this approach because it allows developers to use the source control system to check in and roll back versions without needing to fulfill the criteria needed to check in a formal build.

If the approach of checking in intermediate versions is required, then the source control can no longer be assumed to contain a "buildable" version. Instead it is required to distinguish between the intermediate versions and build versions. Using Visual SourceSafe this can be done in a variety of ways, either automatic or process based. For example:

• Developers follow a process of notifying the build manager when a "buildable" version is added to Visual SourceSafe.
  
• Developers check in a tested version, ready for building, into a "promoted area" within Visual SourceSafe. This promoted area is then used as the source upon which the master build is based.
  
• Code or script can be written that uses the Visual SourceSafe COM interfaces. For example, a specific label can be used to denote code ready for a build and the script searches for this label and then "pins" this source into a separate Visual SourceSafe branch This branch is then used as the source for master builds.
  

BizTalk Server uses additional files that can beneficially be versioned and stored in Visual SourceSafe. The following files are examples:

• Binding files (both development and test)
  
• Custom pipeline assemblies
  
• Test data (for example, test messages)
  
• Test harnesses (which may change over the project lifetime)
  
• Build, deployment, and start-and-stop scripts that may need to be shared between development and build teams
  

If these files are related to a specific Visual Studio .NET BizTalk project then these files can be included within the BizTalk project and managed by using the Visual Studio .NET integrated source control functions. To include a file or folder into an existing Visual Studio .NET project, do the following:

1. In Solution Explorer, click Show All Files.
   
2. Select the folder or file to include in the solution.
   
3. Right-click the folder or file, and then select Include In Project.
   

The following figure shows the screen for including files in a project.

Figure 5 Including files in a project

If the non-BizTalk Server project files are not part of a Visual Studio .NET project, then you can manage them by using Visual SourceSafe Explorer.

Note
Visual SourceSafe Explorer should NOT be used to manage any items that are part of a Visual Studio .NET project under source control.

When Visual SourceSafe databases are large, heavily used, or being accessed by many concurrent users, it is recommended to regularly run the "Analyze VSS DB" command from the Visual SourceSafe menu. If the analysis detects errors, then they can be fixed by using the "Analyze and Fix VSS DB" command. Both these commands need to lock the Visual SourceSafe database, and hence require everyone to be disconnected from Visual SourceSafe.

"Appendix: Step-by-Step Guide to Setting Up a Partitioned Single Solution" contains a step-by-step guide to creating a partitioned single solution structure using Visual Studio .NET and Visual SourceSafe that follows the guidance listed earlier. This step-by-step guide is intended as a working example and individual projects should modify the steps listed to meet their requirements.

When developing with the .NET Framework, versioning is governed by a standard set of rules that ensure that when a version number changes, the impact of that change is typically minimal. Due to certain design and implementation choices made during the development of BizTalk Server 2004, version numbers with BizTalk Server 2004 do not always follows the standard .NET Framework rules. The following sections describe these conditions.

Overview of .NET Versioning

When a BizTalk Server 2004 project is compiled, the resulting DLL is a .NET assembly and its behavior follows the standard .NET versioning behavior. If it occurs that multiple versions of the same assembly are installed with the same assembly version number, the system will produce unexpected results. For this reason it is important to ensure that BizTalk Server 2004 assembly versioning is planned and managed.

Each DLL containing a .NET assembly has two distinct ways of expressing version information. The following table shows the difference between the assembly version and the file version.

Table 10 DLL version numbers

Assembly version

File version

The assembly version number together with the assembly name and culture information is part of the assembly's identity. The assembly version number is used by the runtime to enforce version policy and plays a key part in the type resolution process at run time. This version number is physically represented as a four-part string with the following format: <major version>.<minor version>.<build number>.<revision>

The file version is a string that is displayed by Microsoft Windows® Explorer. This number can be used to manually determine which version of a file is installed.

The following figure shows where these two version numbers can be viewed for a DLL.

Figure 6 DLL version numbers

Implications of Changing Version Numbers

Approaches to Incrementing BizTalk Server 2004 Assembly Version Numbers

When to Change File and Assembly Versions

Map Function Version Numbering

One approach to developing BizTalk Server orchestration designs is to use Visual Studio .NET to produce "skeleton" projects. The skeleton projects provide a way of validating the assumptions about the number and type of messages and the operations taking place upon the messages to complete a process.

These skeleton projects exhibit the following attributes:

• Projects should be divided up in accordance with the planned schema and process ownership.
  
• Projects contain skeleton schema with correct schema names. These schema contain correctly named root nodes and correct target namespaces, but need not contain any further schema detail.
  
• Projects contain skeleton maps that have a source and destination schema but need not have any links.
  
• Orchestrations reference the appropriate skeleton schema.
  
• Orchestrations contain messages and variables created from the skeleton schema. This can be useful to understand which orchestrations share messages.
  
• Orchestrations contain the receive and send operations dictated by the design.
  
• Orchestrations contain the process logic associated with the process, including send, receive, mapping, and logic operations.
  
• Expression shapes contain comments that describe the functionality of the expression. The expression shapes also need to contain at least one valid line of expression to allow the skeleton solution to compile without errors (for example, System.Diagnostics.Debug.WriteLine("In expression 1");).
  

As the designs are progressed, the skeleton projects can be used as the starting point for the BizTalk Server 2004 development phase. To add documentation to a group of related workflow shapes, use a Group shape. Group shapes display as much text as you care to associate with the shape. Many of the other orchestration shapes can hold descriptions, and it can be useful to use this to express planned implementation detail.

To make best use of the BizTalk Server skeleton designs, it is helpful to use a documentation tool to export the skeleton design. See "Documenting BizTalk Server 2004 Systems" later in this document.

Prior to starting a BizTalk Server 2004 development it is good practice to ensure that a standard is created for new XML target namespaces. The actual standard is often less important than the uniformity it confers across the project. An example target namespace naming policy might be:

http://<organisationname>.com/namespaces/<system>/<operation>/<direction>

Where:

• <organizationname> is the name of the organization as used in the organization's domain name
  
• <system> is the business system that the message relates to
  
• <operation> is the operation on the interface
  
• <direction> is the direction of the message from the point of view of the system referred to by <system>
  
• <direction> is typically "incoming" or "outgoing" for unidirectional messages
  
• <direction> is typically "IncomingRequest", "OutgoingResponse", and so on, for bidirectional and synchronous systems
  
• Optionally a year, date, or version number can be used as part of the message standard. However be aware that changing these will result in rework for the BizTalk Server developers because the maps and orchestrations will need to be updated to point to the "new" schemas. This can be a significant cost in a large solution.
  

Many artifacts within a BizTalk solution have a standard .NET namespace associated with them. The MSDN paper "Standard guidance on .Net namespace naming" should be adhered to with BizTalk artifacts, namely:

CompanyName.TechnologyName.Feature

Note that these are Pascal-cased and nested namespaces will have dependencies on types in the containing namespace.

For more information about naming guidelines, see the Namespace Naming Guidelines article on the MSDN Web site at http://go.microsoft.com/FWLink/?LinkID=42405.

BizTalk project names and assembly names should often match the name of the associated namespace, such as the following name:

CompanyName.projectName.Function.dll

A division into assemblies such as the following will often be quite suitable for a BizTalk project:

MyCompany.MyProject.OrderProcessingProcessOrch.dll

MyCompany.MyProject.InvoiceBatchProcess.dll

MyCompany.MyProject.SharedSchemas.dll

MyCompany.MyProject.Pipelines.dll

MyCompany.MyProject.PipelineAssemblys.dll

When deployed, an orchestration "type name" is the name that is used and displayed by the BizTalk Server administration tools to refer to the orchestration. When creating a new orchestration, this property defaults to "orchestration_1". When creating a new orchestration, change this property to a descriptive name to help distinguish the orchestration.

All artifacts should be named with a Pascal convention unless mentioned otherwise for the specific artifact, although underscores are used to separate logical entities. For schemas, maps, orchestrations, and pipelines, ensure that the .NET type name matches the file name (without file extension).

The following table shows an example messaging artifact naming convention.

Table 16 Example messaging artifact naming convention

CRM_CustomerUpdateNotification

CRM_CustomerUpdate_ERP_MSMQT

Shippers

Note that the .NET type name of the artifacts listed above should match (without the file extension) the file name. The .NET namespace will likely match the assembly name.

Establishing and following naming conventions are good practices for designating variables, messages, multipart types, and so on, but they become even more important for the workflow shapes contained within an orchestration. The goal is to ensure that the intent of each shape is clear, and that the text associated with the shape conveys as much as possible given the space constraints. In this way, a non-technical audience will be able to use the orchestration as documentation.

Note

To add documentation to a group of related workflow shapes, use a Group shape. Group shapes display as much text as you care to associate with them, and can add quite a bit of documentation value to the diagram. However, if you intend to instrument the application by using BAM, be aware that a Group shape does not exist at run time and as such cannot be part of a BAM tracking profile. If this is the case, you could use a non-transactional scope shape instead.

The following table shows an example orchestration shape naming convention.

Table 17 Example orchestration shape naming convention

For documentation purposes, we recommend that developers add descriptive text to the shapes' description property. Third party BizTalk documenter tools (see "Documenting BizTalk Server 2004 Systems" below, can generate Microsoft Word documents or a compiled help file that contain these shape descriptions. These documents are used as the basis of system documentation.

The following table shows an example orchestration type naming convention.

Table 18 Example orchestration type naming

InvoiceReceipt

InvoiceHeader

debugString

SubmitPO
RequestPOStatus

ProcessPurchaseOrderPort

PurchaseOrderNumber

purchaseOrderNumber

When naming messages within orchestrations, you should use a standard naming convention to avoid the confusion that can arise when messages are traveling between multiple systems in both directions.

Consider naming messages from the point of view of the integration layer (that is, incoming means incoming to the integration layer, outgoing means leaving the integration layer). It may help to include underscores (_) in the names.

The following table shows an example message naming convention.

Table 19 Example message naming convention

<SystemName><OperationName>Incoming

<SystemName><OperationName>Outgoing

<SystemName><OperationName>OutRequest

<SystemName><OperationName>OutResponse

<SystemName><OperationName>InRequest

<SystemName><OperationName>InResponse

If the messages being described are traveling between multiple possible systems, then a naming convention based upon system names may not be meaningful. An alternative approach is to name the messages after their schema, with a description of the message usage in the orchestration, for example:

CRMCustomerUpdate_validate_Incoming
CRMCustomerUpdate_newAddress_Outgoing

Test data is a very significant resource when developing an integration solution. Without valid test data you often cannot test a business process fully. When planning an integration development, you must ensure that the project includes sufficient resources and time to obtain valid data to allow testing. This is particularly true when the test data needs to be produced from systems that have never previously been integrated.

If existing data flows already exist it can be extremely beneficial to the design and testing of the integration solution if example messages are captured for all existing business operations.

For integration environments, test harnesses and test stubs can be defined as the following:

• Test harness. Code or utilities used to allow the testing of an integration process. Typically a test harness is used to submit data to the integration layer to initiate a process.
  
• Test stub. Code or utilities used to simulate a system that is not available, but from which a response is required to allow the testing of a process. Typically a test stub is used to accept data as if it was the unavailable system and respond with the appropriate response, thereby allowing the process to continue despite the absence of a system.
  

Example test harnesses include:

• A Visual Studio .NET project simulating an unavailable system by making a Web service request into the integration layer using the WSDL "contract" file that describes the final SOAP calls between the system and the integration layer.
  
• An ASP.NET application simulating an unavailable system by performing an HTTP POST to the integration layer, passing a sample message and displaying the responding XML output and HTTP response code.
  
• Custom code that uses the System.Xml.XmlDocument classes to produce a specified number of test input XML files with varying values and sizes to allow the volume testing of a batch business process.
  

Example test stubs include:

• A Visual Studio .NET project that simulates an unavailable system by accepting incoming Web service requests from the integration layer and returning a response. The project will potentially use some simple logic to vary the response values for testing purposes. The Web services WSDL may be provided from a system that already exists or that is to be built using the WSDL as the agreed interface.
  
• An ASP.NET application that accepts HTTP POSTS from the integration layer and returns one of several possible XML messages based upon some simple logic.
  

It is generally recommended that test harnesses and test stubs are developed early in the project because they are a useful resource and they also help develop a deeper understanding of the actual interactions between the integration layer and the other systems.

For more information about example test stubs and harnesses, see "Useful Development Tools" later in this document.

Runtime Exception on Invoke When Calling into a BizTalk Server 2004 Generated Web Services Interface Errors

It is worth noting here that HAT can also be used for business operations monitoring as well as the developer-based tasks described above. It is common to set up saved queries that display key indicators. For example, creating a saved query that lists the number of a specific business transaction within the last hour can act as a simple method of monitoring for unexpected behavior (for example, zero messages in 24 hours may suggest a transport failure in an upstream system).

BizTalk Server provides scriptable management capability via Windows Management Instrumentation (WMI) classes. These classes are used to programmatically access the administrative functions available in Microsoft BizTalk Server 2004.

BizTalk provides a WMI Event, MSBTS_ServiceInstanceSuspendedEvent. You can set up a listener to take action when a message is suspended. The following code fragment provides an example of how to listen for these messages:

string scope = "root\\MicrosoftBizTalkServer";
string wqlQuery = "Select * from MSBTS_ServiceInstanceSuspendedEvent";
watcher = new ManagementEventWatcher(scope, wqlQuery);
watcher.EventArrived += new EventArrivedEventHandler(onEvent);
watcher.Start();

This code fragment assigns an event handler that can take action when an event is fired. There is also another event, MSBTS_MessageInstanceSuspendedEvent, but this only occurs for a BizTalk Message Queuing (MSMQT) message instance.

The event that is called when suspended messages occur can be used to write out the message to a file using another built-in BizTalk method, MSBTS_MessageInstance.SaveToFile. The following code provides a snippet of saving a message to file. After messages are saved off, they can be consumed by another receive location.

public void onEvent(object sender, EventArrivedEventArgs e)
{
 // Before calling the following code, query and return all the messages instances                         
 // associated with the particular service instance that was suspended.
// Construct full WMI path to the MSBTS_MessageInstance using the message guid
string strInstanceFullPath =              "root\\MicrosoftBizTalkServer:MSBTS_MessageInstance.MessageInstanceID='{" + MessageInstanceId.ToString() + "}'";
// Load the MSBTS_MessageInstance
ManagementObject objSvcInst = new ManagementObject(strInstanceFullPath);
// Invoke "SaveToFile" method to save the message out into the specified folder
objSvcInst.InvokeMethod("SaveToFile", new object[] {strOutputFolder});
}

It can be useful to have orchestration output information about the assembly that is currently running. The following example code displays information about the current assembly. You can use the example code during development to provide a generic approach to listing assembly information. This sample writes to the event log rather than to a trace or debug listener.

1. Within an orchestration add the following variables:
   
   var_Assembly of type System.Reflection.Assembly
   var_AssemblyName of type System.Reflection.AssemblyName
   var_version of type string.

2. Within the same orchestration add the following to an expression:
   
   var_Assembly = System.Reflection.Assembly.GetExecutingAssembly();
   var_AssemblyName = var_Assembly.GetName();
   var_Version = var_AssemblyName.Version.ToString();
   
   System.Diagnostics.EventLog.WriteEntry("BTS Sample", "Version is: " + var_Version);
   
   //Must set .net types to null to prevent attempted serialization if the orchestration dehydrates.
   
   var_Assembly = null;
   var_AssemblyName = null;
   

When developing maps, if map links or functoids do not seem to be producing the expected output or are producing errors, then consider examining the XSLT to work out what node data is being processed and where the results are being written. The XSLT is produced when validating a map and it represents the actual mapping that the BizTalk Server 2004 runtime will perform. By reading the generated XSLT it is sometimes possible to observe the reason that a map is producing unexpected output.

The XSLT is usually quite simple to follow, typically consisting of many simple XPATH queries. By reading the XPATH statements it is often possible to clearly see the input values and any operators followed by the nodes in which the output is written.

The XSLT is produced during a map validation and is located at

C:\Documents and Settings\<username>\Local Settings\Temp\_MapData

BizTalk Server 2004 supports the creation of maps that use the scripting functoid. Users can create their own .NET methods and use them from within the scripting functoid to allow better reuse of custom code and functionality. Debugging these functions when testing a map can be very useful to determine if your custom map functions are working properly, but the steps to debug these custom assemblies are not obvious. Here are the steps you need to take to directly debug your scripting assembly while testing your map:

1. Open your assembly class in its own Visual Studio .NET development environment. Build the assembly normally, making sure that the build is in debug mode and a symbols file is created.
   
2. Deploy your custom assembly to the global assembly cache normally. Make sure you deploy the version in bin\debug.
   
3. Open up your BizTalk project in a second Visual Studio .NET development environment, reference your custom assembly DLL in the same directory above, and configure your scripting functoid as normal (you should see it as a choice in the list of available assemblies).
   
4. Return to your custom assembly environment, and under processes, attach to your BizTalk DEVENV process. Initially, when you set a breakpoint, the environment will say "symbols not loaded". This is normal, because the assembly is not loaded until it is actually invoked by the mapper.
   
5. Return to your BizTalk project and test the map (using right-click, Test Map). If you watch your assembly environment the symbols get loaded and the "?" goes away, at which time your breakpoint should hit.
   
6. Debug in the normal fashion. Your breakpoint will be hit every time the functoid is called.
   

Error: "Map contains a reference to a schema node that is not valid"

This design-time error can occur when the map being opened uses a project dependency for one of its schema. If this error occurs ensure that the dependency has been recompiled to reflect any recent changes.

To understand why this error arises, consider the following scenario:

• Project Y references project X. Project Y uses schema X which are contained in Project X.
  
• The schema information used by the map editor in Project Y is actually contained within the compiled DLL produced by project X.
  
• This means that if the DLL from project X is deleted then the maps in project Y will not compile until project Y's DLL is recompiled.
  

This is significant when Visual SourceSafe is being used to store projects. Visual SourceSafe does not store DLLs by design, and when retrieving a BizTalk project containing schema the project will need to be recompiled to produce the DLLs that dependent projects need.

Error: "Element cannot contain text or white spaces. Content model is empty"

This runtime error can occur when using Complex Content elements (like <ANY> or <SEQUENCE>). Complex content elements are not allowed to contain text unless their 'Mixed' property is set to 'True'.

For example, if the schema uses complex content elements, the XML <Root> </Root> (note the space between the nodes) will produce the above error. The XML <Root/> will not because no white space exists. To avoid this error set the Mixed property of the root node of the schema to true, as shown in the following figure.

Figure 8 Schema root node mixed property

A common integration requirement is to a call a Web service from the orchestration, and then debug the Web service to determine the functionality taking place within the Web service when called from BizTalk Server 2004. The following steps describe how to debug this scenario. The orchestration is shown in the following figure. It receives a message from the MessageBox, transforms it into the message expected by the Web service, sends it to the Web service, and receives a response.

Figure 9 Orchestration calling a Web service

To debug the Web service, perform the following steps:

1. Open Visual Studio.
   
2. Open the solution (or project) that contains your Web service.
   
3. Set the breakpoint (in our example we set it at line 86).
   
4. On the Debug menu, click Processes. The Processes dialog box appears.
   Figure 10 Process dialog box
   
   
   
   
5. Select aspnet_wp.exe (The ASP.NET worker process represents the ASP.NET runtime environment. It consists of a Win32® unmanaged executable named aspnet_wp.exe, which hosts the .NET common language runtime (CLR). This process is the executable you need to attach to in order to debug ASP.NET applications.)
   
6. Select Attach. The Attach to Process dialog box appears.
   Figure 11 Attach to process dialog box
   
   
   
   
7. Select Common Language Runtime and then click OK.
   The Attach to Process dialog box closes.
   
8. In the Processes dialog box, click Close.
   

The Web service is now ready to be debugged. Send the message to the orchestration and Developer Studio will stop at the breakpoint.

Pipeline assemblies are often used in BizTalk Server 2004 solutions to provide special handling of files before they are sent into or out of the BizTalk MessageBox. Debugging pipeline assemblies in Visual Studio .NET is critical in order to quickly troubleshoot and fix problems.

Copying and Debugging Assemblies

After you build the pipeline assembly successfully, you will need to copy the files to the "Pipeline Assemblies" directory in the BizTalk Server installation directory (C:\Program Files\Microsoft BizTalk Server 2004\Pipeline Assemblies). If you are updating an assembly that has already been installed and you cannot copy over the existing assembly there are two possible causes:

• BizTalk process may have the assembly in use. First stop and start the BizTalk service before copying over the existing assembly.
  
• A BizTalk project with a pipeline that uses your assembly may have it in use. The Visual Studio .NET IDE may be using the design-time aspects of the pipeline assembly. To release it, close Visual Studio .NET. (It may be necessary to close all instances, not just the pipeline project.)
  

After the file has been copied, attach to the BizTalk process as follows:

1. With the pipeline assembly project open, on the Tools menu, click Debug Processes.
   
2. From the Available Processes list, select the BizTalk Server process (BTSSvc.exe) and click Attach.
   
3. In the Attach to Process dialog box, in the "Choose the program types that you want to debug" list, select Common Language Runtime is selected.
   
4. Click OK.
   
5. Click Close.
   

Note
After a changing a pipeline, the BizTalk Server 2004 runtime does not pick up the change until it refreshes its configuration. To test the changes immediately, recycle the appropriate hosts (using recyclehosts.vbs as described in Table 20 under "Redeployment Scripts").

Note
If the "redeploy" option is set to true this allows a modified pipeline to be redeployed without undeploying a previous version. However be aware that this redeploy action resets any send or receive ports that used this pipeline to "PassThrough". After the redeploy it is necessary to reassign the port to the custom pipeline.

BizTalk Server 2004 provides command-line and WMI interfaces to the BizTalk Server 2004 deployment functionality. This allows the creation of command and script files. These files can enable a developer to redeploy simple or complex solutions with a single operation.

These scripts are also beneficial when working with orchestrations that have dependencies upon other orchestrations. BizTalk Server 2004 enforces the dependencies when starting/stopping and deploying/undeploying orchestrations, and a script is an efficient way to ensure that the dependency order is always followed.

To aid the creation of simple redeployment scripts, the samples folder "Simple Redeployment Scripts" contains scripts that were created based upon the SDK samples or the WMI documentation. Where files were modified from the SDK samples, this was done to provide a more reusable or flexible version than the SDK original.

The following table lists the simple build and redeployment template scripts.

Table 20 Simple build and redeployment template scripts

To aid the reusability of the above scripts a team may wish to parameterize the deploy and undeployment scripts to accept paths for the DLL and binding file folder locations. In this way the same scripts can be reused from a deployment package that contains the final compiled DLLs and production binding files in alternative locations.

Notice that the order of the operations is reversed with the undeployment script. This extends to the order for stopping orchestrations and order of assembly uninstallation. This ensures that dependent orchestrations and assemblies are handled in the correct order to avoid undeployment errors.

The deploy.cmd and undeploy.cmd scripts rely on the GACUTIL.exe tool being available to install assemblies. The easiest way to achieve this on a developer workstation is to run the scripts with the "Visual Studio .NET 2003 Command Prompt," which has access to the .NET command-line tools. Alternatively GACUTIL.exe can be included in the scripts folder.

The sample scripts are provided as samples to demonstrate the steps required. You can optimize the scripts for performance on a local developer workstation by using a single BTSDEPLOY operation to deploy, add to the global assembly cache, and bind in one step and by removing the operations to delete ports.

A BizTalk project can be configured to allow the redeployment of an updated version of the project on top of a previously deployed version. This option can be found under "Project properties" in the "Configuration" section. However, the redeploy option still insists that the previous version of the orchestration is unenlisted. When developing a solution that requires the redeployment and testing of a single orchestration a simple process can be developed to allow quick deployment of a new version. This approach requires the VBScript scripts described in Table 20 under "Redeployment Scripts."

Ensure that the BizTalk Server Projects redeploy option is set to true. When a new version of the project needs to be deployed, run the following code from the command prompt:

Cscript ControlOrch.vbs orchname assmbname stop
<Deploy the solution (this will perform a build if required)>
Cscript ControlOrch.vbs orchname assmbname stop
Cscript RecycleHosts.vbs

By using the preceding approach you can redeploy a simple project and force the BizTalk Server runtime to use the new version.

When developing BizTalk Server 2004 solutions, there is no way to test a modified orchestration without actually deploying and binding the resulting assembly. This means that changing just one line of code requires you to stop, unbind, rebuild, redeploy, rebind, and restart an assembly. The redeployment scripts listed above provide an automated "one-step" operation to achieve the necessary functionality; however, you can use an alternative approach in some circumstances.

Note
The above approach is not officially supported, and should be restricted to local development workstations.

Assumptions and constraints:

• This approach assumes that an orchestration has been developed and has already been deployed to the global assembly cache and Configuration database, and the orchestrations have been bound.
  
• This approach only works when the changes to an orchestration do not affect the preconfigured binding information. For example, the modification cannot include adding a new port that would require additional binding information.
  

Steps to set up quick redeploy:

• Using Control Panel | System | Advanced | Environment Variable, set the system environment variable DEVPATH to the project binaries folder. For example:
  
  DEVPATH="C:\SysInteg2004\AccountUpdate\bin\development\"

  Note
  The path must include the trailing backslash.

• Edit the machine.config file (found under C:\WINDOWS\Microsoft.NET\Framework\<FrameworkVersion>\config) and set <developmentMode developerInstallation="true"/> under /configuration/runtime.
  

  Note
  You may need to add the <runtime> and <developmentMode> elements to the machine.config file.

• Restart the developer workstation to ensure that all changes take effect.
  

From this point on the assembly is loaded from the DEVPATH location, and not from the global assembly cache. To make a simple change to the assembly, simply recompile the updated solution and restart the BizTalk Server 2004 service or the BizTalk Host that is hosting the orchestration.

For more information about the DEVPATH environment variable and machine.config settings, see Locating Assemblies Using DEVPATH in the MSDN Library.

You can also use the following approach when making internal changes to an orchestration that does not require port binding changes. As in the quick redeploy option above, this approach is purely a development shortcut and is not officially supported. Perform the following steps:

• Make changes to project
  
• Rebuild project
  
• Shut down host instance
  
• Open assembly explorer (that is, c:\windows\assembly using Windows Explorer)
  
• Locate previous version of assembly and delete
  
• Drag and drop new version of assembly from project bin\development folder into assembly explorer
  
• Restart host instance
  
• Test new version
  

When developing BizTalk Server on a local workstation, it is common to make a change and then redeploy the updated assembly to retest the functionality. Because the BizTalk Server runtime loads assemblies into memory periodically, BizTalk Server does not load up the new version until it reloads the assemblies, unless the updated version has an updated assembly version. To ensure that the BizTalk Server runtime picks up the updated version immediately, stop and restart the BizTalk Server runtime hosts.

Use the recyclehosts.vbs script found in the "Simple Redeployment Scripts" samples folder that accompanies this document.

Alternatively, you can start and stop the BizTalk Server 2004 runtime by creating a command file called BTSreset.cmd that contains the following two lines of code:

net stop "BizTalk Service BizTalk Group : BizTalkServerApplication"
net start "BizTalk Service BizTalk Group : BizTalkServerApplication"

Recycling hosts is quicker than starting and stopping the BizTalk Server 2004 service and is recommended, unless you have modifications such as BizTalk Server 2004 runtime configuration changes that need to be picked up quickly.

As the "Team Development" section of this document discussed, a development team may wish to automate the updating of project version numbers and binding file version numbers. This section provides some tools to assist in these processes.

Patching Binding Files

Using PatchXml

patchxml In.xml Out.xml /BindingInfo/ModuleRefCollection/ModuleRef/@Version 2.0.0.0.

patchxml In.xml Out.xml //PrimaryTransport/Address http://localhost/bogus

Updating Project Version Number and Binding Using Scripts

Using BizTalk Server 2004 and Binding Versioning Scripts

The accompanying samples provide two scripts that can be run to modify the build number (that is, assembly version information) for all .btproj files in a file hierarchy and then change the version attributes in the binding files to match. These samples can be found in the samples under "Updating project version number and binding using scripts\BTPROJ and Binding File Versioning Scripts" folders. Remember to update any paths and solution names prior to using the sample.

The following table describes the version-updating scripts.

Table 21 Description of version-updating scripts

Script	Function
Localsetversion.vbs	Reads a build number from a file and looks for all .btproj files in a directory tree and sets the version number.
ChangeBindingFile.vbs	Changes various attributes of a binding file to suit builds or different environments (assembly version, send port, host, user group, port map version, etc. elements).
DEVENVbuild.cmd	A sample build file that uses the DEVENV command-line option to compile a solution.

Note
The build number changes to the *.btproj files will cause Visual SourceSafe issues if you try to open these projects in Visual Studio .NET to compile. To avoid these warnings compile your BizTalk projects by using DEVENV.exe from the command line or a batch file.

For more information about using DEVENV see "Devenv Command Line Switches" in Visual Studio .NET Help.

The following section provides a sample checklist for a team to complete the following common BizTalk Server build and deployment tasks:

1. Build a master BizTalk solution (composed of several BizTalk projects).
   
2. Create a deployment package from the results of the solution build.
   
3. Create a scripted deployment and undeployment to allow an automated install of the solution.
   
4. Deploy the solution to a test environment for system testing.
   

The preceding checklist makes the following assumptions:

• A "master build server" is available to perform the build operation.
  
• The test environment is a separate set of servers from the build environment with potentially different binding information.
  
• For simplicity the checklist assumes that the master build server has the BizTalk Server 2004 runtime installed and that the master build server can be used to perform a simple build validation test before creating a full deployment package.
  

Build and Deployment Checklist: One-Time Tasks

Build and Deployment Checklist: Tasks to Build Binding and Script Files

The automated build example described here is a simplified version of a typical build process used in a customer project. It is provided as an example from which a team could develop a fully automated nightly build process with related individual build processes for developers.

The main difference between the example provided here and a completely automated build process is that the full process also needs to contain scripts to manipulate Visual SourceSafe. Scripts can be written (using the Visual SourceSafe COM interfaces) to automate the extraction of the appropriate version of the source for the build required.

The process is described here as an example of the type of steps typically required, because an individual team's requirements will vary. All scripts mentioned in this section are included in the "Automated Build Example" folder of the accompanying samples.

The example assumes that a workstation or server is available as a build server and that the assembly version number is incremented with each build.

The objective of the build process is to pull the latest version (or specific labeled version) out of Visual SourceSafe onto a build server, perform a complete compile, and if the compile was successful, produce a deployment kit as outlined above.

To perform an automated build process:

1. Delete any previous version of source files.
   
2. Pull all source files from Visual SourceSafe.
   
3. Change build number.
   
4. Compile shared DLLs.
   
5. Compile process and other DLLs.
   
6. Create deployment kit from newly compiled source.
   
7. Change any references in source files to match new build number.
   

The following table shows the folder structure on the example build server.

Table 22 Folder structure on build server

The following list gives you additional information and hints about the automated build process:

• The structure of the build server has to reflect the structure under which the developers have developed the solution.
  
• In the example there are some shared, common DLLs that are referenced via a mapped drive (S:).
  
• The hints contained within the BTPROJ file for DLL references are relative paths for DLLs on the same drive and absolute paths for DLLs on another drive. This can cause issues if you try to compile the solution at a higher level of nested folders that it was originally developed. For example, if you develop the solution three folders deep, the relative path to the BizTalk DLLs would be "..\..\..\Program Files\Microsoft BizTalk Server 2004\". If you tried to compile the solution with folders four deep, it would not find the path to the Program Files directory.
  
• The common shared DLLs had a custom Visual Studio build configuration (called SharedBuildConfig) that placed the DLLs on the S: drive.
  

There are two versions of the build process:

• A nightly build process that is intended to run on the build server.
  
• A local build intended for developers to do a local compile on their workstations.
  

The main difference between the two processes is that the developer process leaves no trace on Visual SourceSafe whereas the actual build process increments the build number and other numbers.

The command file that drives the build process is called MasterBuildScript.bat. MasterBuildScript.bat is executed by passing a parameter that indicates whether it should run in build server mode or developer build mode. MasterBuildScript.bat is normally called by using MBS_Log.bat or localMBS_Log.bat, which redirects all output to a log file.

The following steps outline the process:

1. Set up environment variables dependent on which mode is running (master or local).
   
2. Clear out previous builds.
   
3. Call the appropriate script to extract source from Visual SourceSafe.
   
4. Put references for files such as .snk files back onto the S: drive.
   
5. Call the script to compile all projects using devenv.
   
6. Check for success indicator (a file called success.txt). If it exists, then build a deployment kit.
   
7. Create a new folder structure called "building". Then copy all the required files from the BuildWorkArea to that structure.
   
8. Call a script to manipulate the contents of "building" by changing all references in binding files to match the new build number. Then copy this kit to a directory name that is the same as the build number and the "Latest" directory.
   
9. Clean up the temporary folders underneath the "Building" folder.
   
10. If running on the build server, drop the S: drive and distribution shares before trying to update files located in them to remove any locks.
    

The following table describes the automated build files.

Table 23 Description of automated build files

The functionality of the example automated build could also be achieved by using alternative tools. A team wishing to develop an automated build process could also consider the information in the following table.

Table 24 Alternative automated build tools

Earlier sections of this document have described relatively simple approaches to creating a solution structure that includes reusable scripts that allow the creation of simple deployment and undeployment scripts. For a larger development team or a team with a particularly complex or large solution to deploy, these approaches may not be flexible or scalable enough. The deployment toolkit described here is provided as an alternative approach to allow greater control, at the cost of greater complexity to set up the initial processes and scripts.

This section provides an overview of a deployment toolkit developed as a template to enable BizTalk Server 2004 build managers to construct a scripted, automated deployment process. This toolkit is installed in the samples folder called BizTalk Server 2004 Deployment Toolkit.

The BizTalk Server 2004 deployment toolkit provides a structure for packaging a BizTalk solution—assemblies, binding files, helper classes, Web services, and so on—to allow a person with no previous BizTalk knowledge to configure and deploy a complete BizTalk solution. This kit also covers undeployment of most stages to leave a clean system.

All scripts and other files mentioned in this section are included in the accompanying samples in the BizTalk Server 2004 Deployment Toolkit folder.

This deployment kit was initially developed to support the rollout of a large BizTalk solution into the following environments:

• Development environment
  
• System test environment
  
• Integration test environment
  
• Production environment
  

The process has to be repeatable for a given configuration and needs to be done by users who are not BizTalk aware. The kit uses scripts to configure and deploy the runtime environment without any reliance on Visual Studio being deployed on production servers.