Microsoft BizTalk ESB Toolkit

BizTalk ESB Toolkit Logo

Summary

The ​Microsoft BizTalk ESB Toolkit 2.2 uses BizTalk Server 2013 R2 to support a loosely coupled messaging architecture. BizTalk Server includes a powerful publish/subscribe mechanism for messaging applications that works by creating and filling subscriptions, which provides a highly efficient and scalable platform for service-oriented architecture (SOA) applications.

The ​Microsoft BizTalk ESB Toolkit 2.2 extends the functionality of BizTalk Server to provide a range of new capabilities focused on building robust, connected, service-oriented applications that incorporate itinerary-based service invocation for lightweight service composition, dynamic resolution of endpoints and maps, Web service and WS-* integration, fault management and reporting, and integration with third-party SOA governance solutions.

Overview

The ​Microsoft BizTalk ESB Toolkit 2.2 provides architectural guidance, patterns, and a collection of BizTalk Server and .NET Framework components to simplify the development of an Enterprise Service Bus (ESB) on the Microsoft platform and to allow Microsoft customers to extend their own messaging and integration solutions.

Common Scenarios

The term Enterprise Service Bus (ESB) is widely used in the context of implementing an infrastructure for enabling a service-oriented architecture (SOA). However, real-world experience with the deployment of SOAs has shown that an ESB is only one of many building blocks that make up a comprehensive Service-Oriented Infrastructure (SOI). The term ESB has morphed in a number of different directions, and its definition depends on the interpretation of individual ESB and integration platform vendors and on the requirements of particular SOA initiatives.

Based on the experience Microsoft has gathered from many successful real-world SOI implementations, you can think of an ESB as a collection of architectural patterns based on traditional enterprise application integration (EAI), message-oriented middleware, Web services, .NET and Java interoperability, host system integration, and interoperability with service registries and asset repositories.

Figure 1 shows a high-level view of the type of interconnectivity that an ESB architecture can provide.

Figure 1

A high-level example of the connectivity provided the Enterprise Service Bus architecture

Audience Requirements

The ​Microsoft BizTalk ESB Toolkit 2.2 is intended for developers who create Microsoft BizTalk Server solutions or other solutions that use the ​Microsoft BizTalk ESB Toolkit 2.2 components. To take full advantage of the ​Microsoft BizTalk ESB Toolkit 2.2, developers should possess knowledge and experience working with the following:

  • BizTalk Server 2013 R2

  • Visual Studio 2013

  • Microsoft .NET development techniques, including the development of ASP.NET Web services and .NET Framework components

Design Goals

The ​Microsoft BizTalk ESB Toolkit 2.2 consists of a series of interoperating components that support and implement a loosely coupled messaging environment that makes it easier to build message-based enterprise applications. The services and components fall naturally into the following seven categories:

  • Web services.These expose internal services such as itinerary processing, exception management, resolution of endpoints and maps, BizTalk Server operations, and message transformation.

  • Itinerary services.These include orchestration-based and messaging-based services for performing itinerary-based routing for Microsoft BizTalk Server 2013 R2. You can create custom services for itinerary-based routing.

  • Itinerary on-ramps.These receive external messages, attach the appropriate itinerary for each message, and perform itinerary processing; they use the ​Microsoft BizTalk ESB Toolkit Resolver and Adapter Provider Framework for dynamic resolution of endpoints and metadata.

  • On-ramps.These receive external messages in a range of formats and transports, such as HTTP, JMS, WMQ, FTP, Flat File, and XML. They are typical BizTalk Server receive locations that optionally use the ​Microsoft BizTalk ESB Toolkit 2.2 interop pipeline components and the ​Microsoft BizTalk ESB Toolkit 2.2 Resolver and Adapter Provider Framework for dynamic resolution of endpoints and metadata.

  • Off-ramps.These implement send ports for the delivery of messages using formats and transports such as SOAP, WCF, JMS, WMQ, FTP, HTTP, Flat File, XML, or any other custom formats. They are typical BizTalk Server dynamic send ports that are direct-bound to the Message Box and that optionally use the ​Microsoft BizTalk ESB Toolkit 2.2 interop pipeline components and the ​Microsoft BizTalk ESB Toolkit 2.2 Resolver and Adapter Provider Framework for dynamic resolution of endpoints and metadata.

  • Exception Management Framework.This includes the exception Web service, the exception management API, and components that enrich, process, and pass exception details to the ESB Management Portal.

  • ESB Management Portal.This provides registry provisioning, exception mediation, alert notification, and analytics.

Many of these components and services rely on features implemented by BizTalk Server 2013 R2, such as the Orchestration, Transformation, and Business Rules engines and the Message Box database. Figure 2 shows a schematic view of the categories; the components and services typically occurring within each category; and the core BizTalk Server system components used by the ​Microsoft BizTalk ESB Toolkit 2.2.

Figure 2

The architecture and components of the ​Microsoft BizTalk ESB Toolkit 2.2

How the BizTalk ESB Toolkit 2.2 Works

The ​Microsoft BizTalk ESB Toolkit 2.2 accepts inbound messages and operates on them, perhaps (but not always) by performing processes such as transformation, delivery, or any other custom defined process. To specify the operations required, the core processing components require a message to contain associated instructions or metadata that define the processes to apply and the tasks to execute with the message content.

This approach provides loose coupling between services; this means that the ESB does not require prior knowledge of the specific processing for each message. It just has to know the possible range of processes and how to apply each process. The wide range of options for specifying the available processes and the mapping between the processes and the instructions within messages provides a flexible mechanism for configuring and adjusting behavior, without requiring changes to code and redeployment of components.

Getting Started

After installing the ​Microsoft BizTalk ESB Toolkit 2.2, you should read the "Getting Started" topic in the documentation to understand the architecture, message flow, and the core components of the ​Microsoft BizTalk ESB Toolkit 2.2. You should also install and run the samples included with the ​Microsoft BizTalk ESB Toolkit 2.2, which demonstrate the common use cases described in the "Getting Started" topic and other messaging scenarios. This approach will help you quickly grasp how the ​Microsoft BizTalk ESB Toolkit 2.2 works and how you can take advantage of its features in your own SOA applications.

Related Titles

  • BizTalk Enterprise Service Bus (ESB) Guidance(http://go.microsoft.com/fwlink/?LinkID=185955&clcid=0x409)

  • BizTalk Service Oriented Solutions(http://go.microsoft.com/fwlink/?LinkId=185956)

  • Using Web Services with BizTalk Server(http://go.microsoft.com/fwlink/?LinkId=185957)

© 2014 Microsoft Corporation. All rights reserved.


What's New

What’s New?

ESB Toolkit integrates more deeply with BizTalk Server 2013 R2. The BizTalk Server installer now provides the option of installing ESB Toolkit as well. The configuration process is also much simpler. For information on how to install and configure ESB Toolkit, see http://msdn.microsoft.com/library/jj684558(v=bts.80).aspx.


Introduction to the BizTalk ESB Toolkit

This documentation explains the architecture and contents of the Microsoft ​Microsoft BizTalk ESB Toolkit 2.2. The documentation also demonstrates how to apply an Enterprise Service Bus (ESB) architecture pattern to develop enterprise applications that enable flexible, secure, and reusable services and rapid organization of existing services into new end-to-end business processes.

What Is an Enterprise Service Bus?

The term Enterprise Service Bus is widely used in the context of implementing an infrastructure for enabling Service-Oriented Architecture (SOA). However, real-world experience with the deployment of SOA solutions has demonstrated that an ESB is only one of many components required to build a comprehensive Service-Oriented Infrastructure (SOI). The term "ESB" has evolved in a number of directions—its definition varies with the interpretation of individual ESB and integration platform vendors and with the requirements of particular SOA initiatives.

Based on the experience Microsoft has gathered from many successful real-world SOI implementations, Microsoft considers an Enterprise Service Bus to be a collection of architectural patterns based on traditional Enterprise Application Integration (EAI), message-oriented middleware, Web services, .NET and Java interoperability, host system integration, and interoperability with service registries and asset repositories. Figure 1 illustrates the architecture of an Enterprise Service Bus.

Figure 1

A high-level representation of the connectivity provided by the Enterprise Service Bus architecture

The Industry View of ESB

There are many sources of information about ESB design, architecture, infrastructure, and implementation available from industry suppliers, system integrators, and independent sources.

IBM defines ESB as a system that "...enables a business to make use of a comprehensive, flexible, and consistent approach to integration while also reducing the complexity of the applications being integrated. Due to the complex and varying nature of business needs, ESB is an evolutional progression that unifies message oriented, event driven and service oriented approaches for integrating applications and service." IBM describes the advantages as "...greater reuse of IT assets by separating application logics and integration tasks, so you can reduce the number, size, and complexity of integration interfaces," and the ability to "...add or change services with minimal interruption to existing IT environment; reduce cost and risk involved as business changes and new opportunities arise." For more information, see WebSphere software(http://go.microsoft.com/fwlink/?LinkId=185958)on the IBM Web site.

Sonic Solutions provide a comprehensive examination of ESB, discussing the principle aspects, and the IT and business benefits. They describe the requirement for ESB: "To integrate old and new, service-oriented architecture (SOA) needs an infrastructure that can connect any IT resource, whatever its technology or wherever it is deployed." For more information, see Enterprise Service Bus (ESB)(http://go.microsoft.com/fwlink/?LinkId=185959) on the Sonic Solutions Web site.

TIBCO Software define ESB as "...a standards-based communication layer in a service- oriented architecture (SOA) that enables services to be used across multiple communication protocols [to] simplify service deployment and management, and promote service reuse in a heterogeneous environment." They suggest, in order to provide these capabilities, ESBs "...support both open standards and proprietary technologies, including Web services and UDDI-based registries to discover and publish services, Java Message Service (JMS) and other widely deployed messaging protocols, standards-based (XML) transformations, and basic message routing." For more information, see Enterprise Service Bus (ESB)(http://go.microsoft.com/fwlink/?LinkId=185960) on the TIBCO Web site.

In the description of his book, Enterprise Service Bus, author David Chappell states that "Rather than conform to the hub-and-spoke architecture of traditional enterprise application integration products, ESB provides a highly distributed approach to integration." He adds "...with unique capabilities that allow individual departments or business units to build out their integration projects in incremental, digestible chunks, maintaining their own local control and autonomy, while still being able to connect together each integration project into a larger, more global integration fabric, or grid." For more information, see Enterprise Service Bus by David Chappell:

  • Chappell, David. Enterprise Service Bus. Sebastopol, CA: O'Reilly Media, Inc. 2004.

The BizTalk ESB Toolkit 2.2

This documentation, as a whole, introduces architects and developers to ESB architectural concepts as addressed by the ​Microsoft BizTalk ESB Toolkit 2.2, describes the installation procedures, and explains the functionality of the ESB components through a set of commonly accepted ESB use cases.

This section provides an introduction to the ​Microsoft BizTalk ESB Toolkit 2.2 and includes the following topics:

  • Overview of the BizTalk ESB Toolkit

  • Contents of the BizTalk ESB Toolkit

  • Target Audience for the BizTalk ESB Toolkit

  • Copyright

This documentation also includes the following topic sections:

  • Getting Started with the BizTalk ESB Toolkit

  • Key Scenarios and Development Tasks

  • Creating Itineraries Using Itinerary Designer

  • BizTalk ESB Toolkit Sample Applications

  • Modifying and Extending the BizTalk ESB Toolkit

  • Administration with the BizTalk ESB Toolkit

  • SOA Governance Integration

  • Appendices


Overview of the BizTalk ESB Toolkit

The ​Microsoft BizTalk ESB Toolkit extends the capabilities of BizTalk Server 2013 R2 to support a loosely coupled messaging architecture. Most developers are familiar with code-oriented, procedural, or object-oriented development paradigms; however, when starting to develop BizTalk solutions, developers tend to overlook the message-oriented capabilities of BizTalk Server.

BizTalk Server includes a powerful publish/subscribe mechanism that works by creating and filling subscriptions. When a new message arrives in the BizTalk Message Box database, a message agent identifies subscribers and sends the message to any endpoints that have subscriptions. Subscriptions can be created in several ways, including binding an orchestration to a receive port, having a correlated receive waiting for a message, or creating a send port with a filter condition that matches a property of the message (such as the type, the receive point, or the value of a routable property).

By providing this efficient and scalable approach, BizTalk Server enables developers to create a series of discrete sub-processes, define the types of messages that trigger their invocation, and not worry about the sequence. A process initiated by the arrival of a message performs its processing on the message; after it processes the message, it can deliver this or another message to the Message Box database, which, in turn, may activate one or more sub-processes.

Microsoft provides key building blocks that are required for building comprehensive Service-Oriented Infrastructures, including Windows Server, the .NET Framework, and BizTalk Server 2013 R2. The ​Microsoft BizTalk ESB Toolkit is based on BizTalk Server 2013 R2 because it provides the basis for the most common ESB services, including the following:

  • Message routing

  • Message validation

  • Message transformation

  • Extensible adapter framework for connectivity

  • Service orchestration

  • Business rules engine

  • Business activity monitoring

  • Web service and WS-* integration (WCF adapter)

The ​Microsoft BizTalk ESB Toolkit extends the functionality of BizTalk Server 2013 R2 to provide a range of new capabilities focused on building robust, connected, service-oriented applications. The ​Microsoft BizTalk ESB Toolkit treats BizTalk Server components as individual units of work that can be connected, as desired, to form loosely coupled solutions. The following are some of the core capabilities that the ​Microsoft BizTalk ESB Toolkit provides to enhance the capabilities of Microsoft BizTalk Server 2013 R2:

  • Policy driven mediation. The ​Microsoft BizTalk ESB Toolkit does the following:

    • It provides itinerary-based routing that supports lightweight service composition at the time of message publication. This approach allows dynamic discovery of service endpoints and mediation requirements for message routing using a service registry or the business rules policy.

    • It adds support for policy centralization for itinerary-based routing using server-side itineraries that are dynamically resolved and added to the message context after a message is received. Managing itineraries in a central location enables the processing of messages from clients that are completely unaware of how their requests are being routed.

    • It uses an enhanced version of the ​Microsoft BizTalk ESB Toolkit Resolver and Adapter Provider Framework, which enables dynamic resolution of endpoints and transformation requirements; this effectively decouples the consumer from the services.

  • Connecting systems. The ​Microsoft BizTalk ESB Toolkit does the following:

    • It provides pipeline components that normalize XML message namespaces.

    • It integrates with JMS through the WebSphere MQ adapter for Microsoft BizTalk Server 2013 R2.

    • It facilitates message exchange patterns that enable dynamic service aggregation, message routing, message validation, and message transformation.

    • It supports service endpoint discovery from registry and repository integration using UDDI 3.0.

    • It supports message routing through line-of-business (LOB) adapters by using the WCF-Custom BizTalk Adapter for BizTalk Server 2013 R2.

  • Management and monitoring. The ​Microsoft BizTalk ESB Toolkit does the following:

    • It provides exception management framework and tools.

    • It facilitates message repair and resubmission using a management portal, shipped as a sample application. This Web application also supports customizable e-mail notifications when a specific error occurs.

    • It allows BizTalk Server endpoint and registry integration, management, and publication.

    • It provides a centralized repository of versioned server-side itineraries.

    • It supports reporting and analytics for BizTalk Server 2013 R2 applications.

    • It includes Business Activity Monitoring components to track itinerary service execution, including start time, end time, and service mediation sequence.

  • SOA governance. The ​Microsoft BizTalk ESB Toolkit does the following:

    • It integrates with third-party SOA governance solutions, including embedded management agents for BizTalk Server 2013 R2 from AmberPoint and SOA Software.

For more information about Microsoft BizTalk Server 2013 R2, see the Microsoft BizTalk Server(http://go.microsoft.com/fwlink/?LinkId=185961)site.

For the latest news, forums, and support for the ​Microsoft BizTalk ESB Toolkit , see BizTalk ESB Toolkit Forums(http://go.microsoft.com/fwlink/?LinkID=185951&clcid=0x409)on the MSDN Forums.


Contents of the BizTalk ESB Toolkit

The ​Microsoft BizTalk ESB Toolkit 2.2 provides architectural guidance, patterns and practices, and a collection of BizTalk Server and .NET Framework components to simplify the development of enterprise-scale solutions on the Microsoft platform. The toolkit also provides capabilities to help developers extend existing messaging and integration solutions. The ​Microsoft BizTalk ESB Toolkit 2.2 consists of a collection of interoperating components that support and implement a loosely coupled messaging environment that simplifies the process of building dynamic message-based enterprise applications.

The ​Microsoft BizTalk ESB Toolkit 2.2 contains the following components:

  • ESB Web Services. These expose key capabilities to ESB consumers, such as itinerary-based routing, exception management, dynamic resolution of endpoints and maps, BizTalk operations, Universal Description, Discovery, and Integration (UDDI) interoperability, and transformation of message content.

  • ESB Management Portal. This provides support for exception and fault tracking, message resubmission, alerts and notifications, UDDI integration, reporting and analytics, and configuration capabilities.

  • ESB Pipeline Interop Components. These provide BizTalk Server pipeline components that facilitate interoperability with external systems.

  • Exception Management Framework. This captures and consolidates exceptions from both BizTalk Messaging and Orchestration subsystems and provides a single mechanism for handling fault messages. It includes the exception Web service, the exception management API, and components that enrich, process, and pass exception details to the ESB Management Portal.

  • ESB Resolver and Adapter Provider Framework. This implements a pluggable and configurable architecture for dynamically resolving endpoints and transform requirements and for routing messages.

  • Itinerary-Based Routing and Processing. The Itinerary Processing mechanism provides a lightweight capability for dynamically describing, submitting, and executing multiple service invocations or routing/transformation requests.

  • BizTalk ESB Toolkit Sample Applications. The included sample applications demonstrate possible implementations of the ​Microsoft BizTalk ESB Toolkit 2.2 and how you can use the ​Microsoft BizTalk ESB Toolkit 2.2 features in your own SOA and ESB applications.


ESB Web Services

The ​Microsoft BizTalk ESB Toolkit contains the following Web services:

  • Itinerary On-ramp Web services.These services accept external messages and submit the messages for processing. The content of an itinerary contains metadata and processing instructions that describe which services to execute. Routing services define the endpoints to which the message should be routed, while transformation services specify how messages should be transformed. These services support both one-way and two-way (request-response) processing; both ASMX and Windows Communication Foundation (WCF) implementations are provided. The Itinerary On-ramp Web services are not message type–specific, so they accept any message type.

  • Resolver Web service.This service allows external applications to call the Microsoft ESB Resolver Framework to look up ESB endpoints based on resolution mechanisms supported by the Resolver Framework. The service also offers both ASMX and WCF implementations.

  • Transformation Web service.This service allows execution of Microsoft BizTalk Server maps without the overhead of Message Box persistence, extending the capability of BizTalk Server map execution to applications that are not based on BizTalk Server. The service offers both ASMX and WCF implementations.

  • Exception Handling Web service.This service accepts exception messages from external sources and routes using the fault processor pipeline will normalize, track, and publish the exception message to the ESB Management Portal. The service offers both ASMX and WCF implementations.

  • UDDI Web service.This service enables applications and users to look up endpoints based on the service name, business provider, or business category; it also allows applications and users to manipulate the business providers, services, and categories stored in a UDDI repository. This is a key infrastructure service used by the ESB Management Portal and third-party providers.

  • BizTalk Operations Web service.This ASMX-based service exposes information about BizTalk Server hosts, orchestration, applications, and status, enabling users and third parties to easily query for application and host status, regardless of the location of computer(s) within the BizTalk Server group. Queries can include message status and flow, status changes, current service instances, and message details. The service can also update receive locations. This is a key infrastructure service used by the ESB Management Portal and third-party providers.

For more information about the Web services provided as part of the ​Microsoft BizTalk ESB Toolkit, see Using the BizTalk ESB Toolkit Web Services.


ESB Management Portal

The ​Microsoft BizTalk ESB Toolkit includes a comprehensive Web-based exception and fault message management framework that promotes consistent handling of both system and business exceptions. The included portal serves as a sample of how a portal application can provide metrics and visibility into ESB activities.

The ESB Management Portal provides exception mediation capabilities through an auditing and tracking mechanism. It also captures messages (including the context properties) that were "in flight" at the time that the exception occurred. This enables powerful exception recovery and "repair and resubmit" patterns.

To allow administrators and users to easily manage ESB applications, the portal also provides an alert and notification mechanism that can generate alerts based on custom conditions and send notifications to subscribers.

To monitor application performance and analyze fault trends, the portal can generate and display a range of charts and reports, configurable over specified periods of time, and include data from specified BizTalk applications.

Additionally, the portal integrates with a Microsoft UDDI 3.0 server to provide a graphical user interface for publishing BizTalk endpoints to UDDI, either automatically or through an administrator-controlled approval process.

For more information about the ESB Management Portal, see The Components of the Exception Management Framework.


ESB Pipeline Interop Components

The ​Microsoft BizTalk ESB Toolkit provides support components and services, including the following:

  • JMS pipeline components. These components recognize, validate, and expose metadata and the content of messages that conform to the JMS MQRFH2 format used by IBM MQ Series messaging systems. This functionality allows a ​Microsoft BizTalk ESB Toolkit application to receive messages from and send messages to JMS systems over MQ Series. The components automatically promote header information into, and demote it from, the message content.

  • Namespace pipeline components. These components can add or remove namespaces in the content of XML messages. This allows applications to repair conflicting namespaces or add missing namespaces to prevent namespace collisions within the Message Box database and application orchestrations. The components also allow BizTalk Server to consume POX (Plain Old XML) without modifying external publishing systems.

For more information about the ESB pipeline components, see Using the Pipeline Support Components.


Exception Management Framework

The ESB Exception Management Framework provides a unified message-oriented fault generation mechanism for managing all exceptions that may occur within a BizTalk Server 2013 R2 environment. The ESB Exception Management Framework can receive exception messages published through the Exception Publishing Service, in addition to messages from the BizTalk Server Failed Message Routing mechanism.

The framework provides an API for fault message creation, publication, and management from orchestration processes, replicating the BizTalk Server failed message routing feature first introduced with BizTalk Server 2006. In addition, the framework provides facilities for normalizing all exceptions, enriching them, applying Business Activity Monitoring (BAM) tracking, and publishing the final output to the Exception Management database for display and reporting in the ESB Management Portal.

The ​Microsoft BizTalk ESB Toolkit includes the following pipeline components that support the ESB Exception Management Framework:

  • Exception Fault processor pipeline component.This component is included as part of the pipeline associated with the ESB Exception Off-ramp. This off-ramp subscribes to all ESB-generated fault messages, in addition to exceptions generated by the BizTalk Server failed message routing mechanism. The component routes fault messages to the ESB exception management ESB Management Portal database, or it can be configured to route to another location. The pipeline component also enriches all fault messages and exceptions with metadata and normalizes them to a common format.

  • BAM Tracking pipeline component.This component intercepts and records exception information within the BizTalk Server BAM subsystem and is used exclusively by the Exception Fault Processor pipeline within the Exception Management Framework. Provided with ​Microsoft BizTalk ESB Toolkit is a sample that demonstrates using BAM as an optional tracking facility for exception information.

For more information about the Exception Management Framework, see Using ESB Exception Management.


ESB Resolver and Adapter Provider Framework

The Resolver and Adapter Provider Framework provides a comprehensive, pluggable architecture for dynamically resolving endpoint information and BizTalk Server 2013 R2 map types. It uses extensible components, which allow developers to change the behavior to suit their own requirements and extend the mechanism to support alternative resolution and routing methods.

The Resolver and Adapter Provider Framework provides support Universal Description, Discovery, and Integration (UDDI), Business Rule Engine (BRE), and XML Path Language (XPath). It also exposes developer interfaces (IResolveProvider and IAdapterProvider) to allow creation of custom resolver and adapter components. The following are the three main components of the Resolver and Adapter Provider Framework:

  • Resolvers. These are defined by a schema, connection string, and through the implementation of the IResolveProvider interface in a .NET Framework assembly. These are loaded and cached at run time and support a range of resolution types and connection strings.

  • Adapter providers. These are defined through the implementation of the IAdapterProvider interface within a .NET Framework assembly. These are registered by their BizTalk Server transport type, which set the endpoint information provided by a resolver on the appropriate BizTalk Server adapter.

  • Itinerary pipeline components. These parse resolution instructions from connection strings or from the ESB Itinerary SOAP headers, and they provide endpoint resolution or transformation execution capabilities using the Resolver and Adapter Provider Framework. The components can dynamically set the BizTalk Server endpoint properties or execute a BizTalk Server map transformation based on resolution instructions from the connection string or from the ESB Itinerary SOAP headers. These components are responsible for managing, updating, and persisting the itinerary across process and service boundaries. The optional Disassembler component provides native BizTalk Server parsing of the message and implements the ​Microsoft BizTalk ESB Toolkit feature of routing to multiple endpoints without the need for an orchestration service.

For more information about dynamic resolution and dynamic routing, see Using Dynamic Resolution and Routing and Using Dynamic Transformation. For information about the Resolution and Adapter Provider Framework, see Modifying and Extending the BizTalk ESB Toolkit.


Itinerary-Based Routing and Processing

The ​Microsoft BizTalk ESB Toolkit implements a routing slip pattern through the use of custom pipeline components. Message metadata and other factors are used to determine the appropriate routing slip, also known as an itinerary, to be used for each message. This routing slip can perform message transformation, invoke orchestration services, and define message routing steps that BizTalk Server 2013 R2 will execute, effectively decoupling message processing instructions from the core BizTalk Server engine.

For more information on how itineraries are processed, see Key Scenarios and Development Tasks.


Target Audience for the BizTalk ESB Toolkit

This guide is intended for developers who create BizTalk Server 2013 R2 solutions or other solutions that use the ​Microsoft BizTalk ESB Toolkit components. To take full advantage of the ​Microsoft BizTalk ESB Toolkit, developers should possess knowledge and experience working with the following:

  • BizTalk Server 2013 R2

  • Visual Studio 2013

  • Microsoft .NET development techniques, including the development of ASP.NET Web services and .NET Framework components


Getting Started with the BizTalk ESB Toolkit

This topic explains the concepts for the design and operation of the ​Microsoft BizTalk ESB Toolkit components and services used to build ESB-enabled solutions. This topic includes the following topic sections:

  • Architecture of the BizTalk ESB Toolkit

  • Understanding Message Flow

  • Typical Use Cases

Using the BizTalk ESB Toolkit Documentation

For additional information regarding specific topics related to ​Microsoft BizTalk ESB Toolkit, see the following resources.

Information | Link
To learn more about the concepts of an ESB architecture | Introduction to the BizTalk ESB Toolkit
To better understand the features and benefits of ​Microsoft BizTalk ESB Toolkit | Overview of the BizTalk ESB Toolkit
To see the components included as part of ​Microsoft BizTalk ESB Toolkit | Contents of the BizTalk ESB Toolkit
To learn more about the architecture of the ​Microsoft BizTalk ESB Toolkit | Architecture of the BizTalk ESB Toolkit
To explore key scenarios for the ​Microsoft BizTalk ESB Toolkit | Key Scenarios and Development Tasks
To examine common use cases for the ​Microsoft BizTalk ESB Toolkit | Typical Use Cases
To learn more about the ESB Web services | Using the BizTalk ESB Toolkit Web Services
To learn more about the ESB exception management system | Using ESB Exception Management
To learn more about the itineraries and the Itinerary Designer | Creating Itineraries Using Itinerary Designer
To learn more about developing with the Itinerary Designer | Development Activities
To integrate Java Message Service (JMS) MQ Series messaging systems with BizTalk Server | Installing and Running the JMS MQRFH2 Component Sample
To learn more about the monitoring and management features of the ​Microsoft BizTalk ESB Toolkit | Administration with the BizTalk ESB Toolkit
To examine sample applications included as part of ​Microsoft BizTalk ESB Toolkit | BizTalk ESB Toolkit Sample Applications
To integrate third-part service governance tools | SOA Governance Integration
To modify and extend the ​Microsoft BizTalk ESB Toolkit | Modifying and Extending the BizTalk ESB Toolkit


Architecture of the BizTalk ESB Toolkit

The ​Microsoft BizTalk ESB Toolkit consists of a series of interoperating components that support and implement a loosely coupled messaging environment that makes it easier to build message-based enterprise applications. The services and components fall naturally into the following seven categories:

  • Web services. These expose internal services such as itinerary processing, exception management, resolution of endpoints and maps, BizTalk Server 2013 R2 operations, Universal Description, Discovery, and Integration (UDDI) interoperation, and transformation of message content.

  • Itinerary services. These include orchestration-based and messaging-based services for performing transformations and message routing. You can create custom services that participate in Itinerary processing. These include orchestration-based and messaging-based services for performing transformations and message routing. You can create custom services that participate in Itinerary processing.

  • Itinerary on-ramps. These receive external messages, attach the appropriate itinerary for each message, and perform itinerary processing; they use the ​Microsoft BizTalk ESB Toolkit Resolver and Adapter Provider Framework for dynamic resolution of endpoints and metadata.

  • On-ramps. Unlike itinerary on-ramps, these receive external messages in a range of formats and transports, such as HTTP, Java Message Service (JMS), IBM WebSphere MQ (WMQ), File Transfer Protocol (FTP), Flat File, and XML. They are typical BizTalk Server receive locations that optionally use the ​Microsoft BizTalk ESB Toolkit interop pipeline components and the ​Microsoft BizTalk ESB Toolkit Resolver and Adapter Provider Framework for dynamic resolution of endpoints and metadata.

  • Off-ramps. These implement send ports for the delivery of messages using formats and transports such as WCF, JMS, WMQ, FTP, HTTP, Flat File, XML, or any other custom formats. They are typical BizTalk Server dynamic send ports that are direct-bound to the Message Box and optionally use the ​Microsoft BizTalk ESB Toolkit interop pipeline components and the ​Microsoft BizTalk ESB Toolkit Resolver and Adapter Provider Framework for dynamic resolution of endpoints and metadata.

  • Exception Management Framework. This includes the exception Web service, the exception management API, and components that enrich, process, and pass exception details to the ESB Management Portal.

  • ESB Management Portal. This sample application provides registry provisioning, exception mediation, alert notification, and analytics.

Many of these components and services rely on features implemented by BizTalk Server 2013 R2, such as the Orchestration, Transformation, and Business Rules engines and the Message Box database. Figure 1 shows a schematic view of the categories, the components and services typically occurring within each category, and the core BizTalk Server system components used by the ​Microsoft BizTalk ESB Toolkit.

Figure 1

The architecture and components of the ​Microsoft BizTalk ESB Toolkit

How the BizTalk ESB Toolkit Works

The ​Microsoft BizTalk ESB Toolkit accepts inbound messages and operates on them, perhaps (but not always) by performing processes such as transformation, routing, or any other custom defined process. To specify the operations required, the core processing components require each message to have a routing slip that contains associated instructions or metadata that define the processes to apply and the tasks to execute with the message content. These routing slips are referred to as itineraries and can be automatically resolved, retrieved from a central repository, and attached to a message when it is received by an on-ramp.

This routing slip approach provides loose coupling between services, meaning that the ESB does not require prior knowledge of the specific processing for each message. It just has to know what the possible range of processes is and how to apply each process. The wide range of options for specifying the available processes and the mapping between the processes and the instructions within messages provides a flexible mechanism for configuring and adjusting behavior, without requiring changes to code and redeployment of components.

Design Patterns

The architecture that ESB uses, where processes deposit messages in the Message Box database and subscribers pick them up based on a processing instruction in the message, effectively implements the state-machine design pattern. In addition, the ESB implements and exposes its core functionality in a services-oriented manner, including to external applications through a set of core Web services.

This loosely coupled approach to designing BizTalk Server and ​Microsoft BizTalk ESB Toolkit-based applications yields highly flexible solutions and has become an industry-accepted best practice.


Understanding Message Flow

This topic explains how messages flow through the ESB generated by the ​Microsoft BizTalk ESB Toolkit. It discusses the overall message flow and provides a detailed description of ESB itinerary-based routing, the routing slips used to define processing for each message.

This topic includes the following sections:

  • BizTalk ESB Toolkit Message Life Cycle

  • Itinerary-Based Routing

  • Processing Instructions in Detail


BizTalk ESB Toolkit Message Life Cycle

The following is the life cycle of a message that originates from an external system and traverses through the ESB to reach its final destination:

  1. An on-ramp receives the message. Depending on the submitting party or client, the message may or may not contain an itinerary that defines the processing instructions for the message.

  2. ESB pipeline components copy the itinerary (if present in the SOAP header) into the context of the message as promoted properties. If the message is received without an itinerary, a specific pipeline component can be configured to select the appropriate itinerary from a database, depending on message content or context, and then copy the itinerary into the context of the message. For the duration of the lifetime of the message, the itinerary is maintained within the message context.

  3. While still in the pipeline, the itinerary is evaluated and message-based itinerary services can process the message. These itinerary services may transform the message or configure routing endpoints.

  4. The message is published to the Microsoft BizTalk Server Message Box database.

  5. BizTalk Server evaluates the promoted properties of the message and queues the message for one or more subscribers.

  6. The subscriber(s) process the message using typical BizTalk Server mechanisms. A subscriber can be either of the following:

    • A BizTalk Server orchestration with a filter configured on a direct-bound receive port

    • A dynamic BizTalk Server send port, which is also referred to as an ESB off-ramp. The itinerary determines how the port will be configured to continue processing the message.

As an alternative to a message arriving through an itinerary on-ramp, BizTalk Server orchestrations can also publish messages to the Message Box for ESB processing:

  1. A message is created within a BizTalk Server orchestration.

  2. The message's context is populated with the ESB itinerary.

  3. The message is published through a direct-bound port to the Message Box database.


Itinerary-Based Routing

One of the core features of the ​Microsoft BizTalk ESB Toolkit is the provision of itinerary-based routing that simplifies the development of enterprise-level messaging applications and reduces the costs of maintaining a large number of static send ports and receive locations.

An itinerary consists of the list of services to execute (which can contain routing, transformation, and custom services) and the configuration information required to resolve the metadata necessary to execute each of these services. For example, one stage of the itinerary may be a routing service; the resolution instructions associated with this service may instruct the service to perform a Universal Description, Discovery, and Integration (UDDI) or Business Rules Engine (BRE) lookup for information about a specific target endpoint to which it will route the message.

Itineraries can be attached to an inbound message in the following ways:

  • The message submitted by a client does not contain any itinerary-related data. The receiving pipeline resolves, retrieves, and attaches the appropriate itinerary based on message content or context.

  • The message submitted by a client can contain a SOAP header that defines the itinerary reference data, which contains the itinerary name and version, as well as a unique identifier for Business Activity Monitoring (BAM) tracking. The receiving pipeline evaluates this information and retrieves the appropriate itinerary from the ESBItineraryDb database.

  • The message submitted by a client can have an itinerary SOAP header, which contains the entire content of the itinerary. This design is not recommended and should be used only for testing purposes.

After an itinerary is resolved for an inbound message, the receive pipeline promotes the itinerary data to the message context, thereby making the properties available to be accessed by any Microsoft BizTalk Server component that subscribes to this message. BizTalk Server components can obtain details of the current itinerary step, complete the required processing, and/or advance the itinerary to the next step. This causes the next service in the itinerary to process the message, according to the publish-subscribe functionality of BizTalk Server.

For information about the ESB dynamic resolution mechanism, transformations, itinerary processing, and message creation, see Key Scenarios and Development Tasks.


Processing Instructions in Detail

This topic describes the format and structure of the System-Properties.xsd property schema, which defines several context properties required for itinerary processing. These properties are promoted when a message is received and processed through BizTalk Server 2013 R2 pipelines; because they are promoted properties, they are accessible to BizTalk Server components. The following properties are defined in the System-Properties.xsd property schema:

  • ItineraryHeader. This property contains all the itinerary information and a list of itinerary services to be invoked through a sequence of itinerary steps. The Itinerary API uses this property internally.

  • ServiceName. This property contains the name of the current itinerary service to process.

  • ServiceState. This property contains the state of the current itinerary service: Pending, Complete, or Active. All services subscribe to an itinerary step that contains a ServiceState value of Pending.

  • ServiceType. This property defines the type of the itinerary step (Messaging or Orchestration).

  • IsRequestResponse. This property defines the messaging type (one-way or request-response).

The Itinerary service executes itinerary steps in one of two ways, depending on the value of the ServiceType property:

  • Itinerary pipeline components execute all itinerary steps with a ServiceType property of Messaging. Developers can extend this process using a custom pipeline and the Itinerary API.

  • When the ServiceType property is Orchestration, an orchestration, activated by a subscription to itinerary context properties, executes the itinerary step.

When an Itinerary service processes an itinerary step, the service is responsible for advancing the itinerary and dispatching the message with a new itinerary context for further processing using the publish-subscribe functionality of BizTalk Server. An itinerary service has full control of the itinerary in the message context and can advance to the appropriate step based on its internal logic and the message content.

The itinerary processing mechanism supports the combination of messaging and orchestration itinerary steps within a single itinerary. Developers can also define custom itinerary services and configure custom itinerary steps.

For more information about itineraries, see Installing and Running the Itinerary On-Ramp Sample.

For more information about custom itinerary services and custom itinerary steps, see Creating a Custom Itinerary Service.


Typical Use Cases

This section describes the most common use cases and scenarios identified for the ​Microsoft BizTalk ESB Toolkit. For each one, the topic discusses the processing required, the result, and a diagram of the process flow. Some of the scenarios equate to use case sample applications provided with the ​Microsoft BizTalk ESB Toolkit, and the topic explains how to install and run the corresponding sample.

The scenarios and use cases are as follows:

  • Point-to-Point Resolution of Endpoints and Transformation Requirements

  • Request-Response Resolution of Endpoints and Transformation Requirements

  • Transformation Without Persisting to the BizTalk Message Box Database

  • Defining Routing and Message Transformation Service Invocations Using Itineraries

  • Defining Routing and Message Transformation Through Multiple Orchestrations Using Itineraries

  • Defining Custom Orchestration Service Execution Using Itineraries

  • Transforming and Routing a Message to Disk Folder, Queue, or FTP Folder

  • Collecting Exceptions and Routing Messages for Repair and Resubmit

  • Collecting Exceptions and Persisting the Payload Using the ESB Exception Processor

  • Repairing and Resubmitting Messages Using the ESB Management Portal

  • Preserving JMS Headers When Routing Through an Orchestration

  • Handling Externally Submitted Exceptions Using a Custom Handler

  • Adding and Removing Namespaces in an XML Message Document

  • Implementing the Scatter-Gather Pattern for Multiple Web Service Invocations

  • Transforming and Routing a Message to Multiple Endpoints


Point-to-Point Resolution of Endpoints and Transformation Requirements

In this use case, a Web service client calls a Web service without going through the ESB. The two points communicate directly, but before the client makes the call, it must resolve the endpoint of the Web service. The call to the Web service can be either a one-way or a request-response. One way of achieving this is to use the dynamic resolution features of the ESB, as shown in Figure 1.

Point-to-Point Resolution of Endpoints

Figure 1

Resolving endpoints using UDDI

The Resolver Service sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. The sample shows how to call the ESB Resolver Service to perform resolution, which enables you to test resolution as you are developing the contents of the back-end stores, such as Universal Description, Discovery, and Integration (UDDI), XML Path Language (XPath), Static, or policies in the BizTalk Server Business Rules Engine.

For more information, see Installing and Running the Resolver Service Sample.


Request-Response Resolution of Endpoints and Transformation Requirements

In this use case, a client application submits a request message to an on-ramp and receives a response. The ​Microsoft BizTalk ESB Toolkit acts as mediator between the client and the target service endpoint and uses the ESB Resolver and Adapter Framework to perform the dynamic message transformation and routing in accordance with the on-ramp configuration, as illustrated in Figure 1.

Request-Response Resolution of Endpoints

Figure 1

Request-response resolution of endpoints and transformation requirements

The Dynamic Resolution sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It shows how to apply dynamic transformation and resolution for two-way scenarios using XML Path Language (XPath), Universal Description, Discovery, and Integration (UDDI), STATIC, or policies in the BizTalk Server Business Rules Engine.

For more information, see the two-way messaging scenario described in Installing and Running the Dynamic Resolution Sample.


Transformation Without Persisting to the BizTalk Message Box Database

In this use case, a call to a Web service performs real-time transformation of a message, based on run-time resolution of the appropriate map to apply, and returns the transformed result. Figure 1 illustrates a schematic view of the process.

Transformation Without Persisting

Figure 1

Transforming a message without persisting to the Microsoft BizTalk Server Message Box database

The Transformation Service sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. By using it, you can call the ESB Transformation Service; this enables you to test transformations and mappings as you are developing components and policies in the BizTalk Server Business Rules Engine.

For more information, see Installing and Running the Transformation Service Sample.

Note
Do not confuse the Transformation Service referred to here with the dynamic transformation operations performed by the BizTalk Server Transformation Agent. The Transformation Service is a high-performance Web service that significantly reduces latency by calling directly into BizTalk Server without going through the Message Box database.


Defining Routing and Message Transformation Service Invocations Using Itineraries

In this use case, a message submitted for processing contains an itinerary SOAP header that describes the list of services to execute and their resolution requirements. Specifically, a transformation and routing service are defined, each optionally requiring resolution through a Universal Description, Discovery, and Integration (UDDI), Business Rules Engine Policy, XML Path Language (XPath), or STATIC lookup. This use case can be extended by adding other services to the itinerary at the time of message publication.

The ​Microsoft BizTalk ESB Toolkit provides two types of itinerary on-ramps: those that support one-way communication and those that support request-response scenarios. Because the dynamic resolution mechanism can use information in the itinerary to look up endpoints or bind dynamically to endpoints, there is no requirement for Microsoft BizTalk Server to contain specific endpoint routing details. Figure 1 illustrates a schematic view of the process.

Defining Routing service Invocation

Figure 1

Defining routing and message transformation service invocations using itineraries

The Itinerary On-Ramp sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It shows how to create itineraries that contain resolution, routing, and service invocation instructions as a series of itinerary steps that define how the ​Microsoft BizTalk ESB Toolkit and BizTalk Server will process the message using the publish-subscribe functionality of BizTalk Server. One-way and request-response samples are included.

For more information, see Installing and Running the Itinerary On-Ramp Sample.


Defining Routing and Message Transformation Through Multiple Orchestrations Using Itineraries

In this use case, a message submitted for processing contains an itinerary SOAP header that describes the list of services to execute and their resolution requirements. The itinerary specifies one or more Microsoft BizTalk Server orchestrations through which the message will pass during the processing cycle. Optionally, the itinerary can contain dynamic routing information used to determine endpoints or transformation requirements for the message. Figure 1 illustrates a schematic view of the process.

Defining Routing Multiple Orchestrations

Figure 1

Defining routing and message transformation through multiple orchestrations using itineraries

The Itinerary On-Ramp sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It shows how to create itineraries that contain resolution, routing, and service invocation instructions as a series of itinerary steps that define how the ​Microsoft BizTalk ESB Toolkit and BizTalk Server will process the input message. One-way and request-response samples are included.

For more information, see Installing and Running the Itinerary On-Ramp Sample.


Defining Custom Orchestration Service Execution Using Itineraries

In this use case, a message submitted for processing contains an itinerary SOAP header that describes the list of services to execute and their resolution requirements. The itinerary specifies one or more custom orchestrations or processes through which the message will pass during the processing cycle. Custom orchestrations have full control of the itinerary and other custom properties exposed in the message context. Optionally, the itinerary can contain dynamic resolution information that determines transformation requirements and endpoints for the message. Figure 1 illustrates a schematic view of the process.

Defining Custom Orchestration

Figure 1

Defining custom orchestration service execution using itineraries

The Itinerary On-Ramp sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It shows how to create itineraries that contain resolution, routing, and service invocation instructions as a series of itinerary steps that define how the ESB and BizTalk Server 2013 R2 will process the input message. One-way and request-response samples are included.

For more information, see Installing and Running the Itinerary On-Ramp Sample.


Transforming and Routing a Message to Disk Folder, Queue, or FTP Folder

In this use case, the ESB transforms a message submitted through the Itinerary Web service or any on-ramp. A dynamic resolution lookup of type FILE, FTP, or queue location determines the map name (for transformation) and the target endpoint for the message, as illustrated in Figure 1.

Transforming Disk Folder

Figure 1

Transforming and routing a message to a disk folder

The Dynamic Resolution sample included with ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It shows how to use the components to dynamically resolve endpoint location, set routing properties, and resolve and execute BizTalk Server 2013 R2 maps at the messaging level, without using an orchestration. It also demonstrates both one-way and two-way messaging patterns.

An extension of this use case is a simple routing solution that routes an incoming message to a file, FTP, or queue location without the additional step of transformation.

For more information, see Installing and Running the Dynamic Resolution Sample.


Collecting Exceptions and Routing Messages for Repair and Resubmit

In this use case, a custom exception handler picks up a fault message received through a Web service and routes it to a disk file in a format compatible with an InfoPath template included with the ​Microsoft BizTalk ESB Toolkit. The user can open the file using Microsoft InfoPath, edit the message contents, and resubmit the message for processing, as illustrated in Figure 1.

Collecting Exceptions Repair

Figure 1

Routing a message for repair and resubmission

The Repair and Resubmit Custom Exception Handler sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. When a process in an orchestration encounters an error, the exception handler in that orchestration generates and publishes an ESB fault message. This fault message includes, in its payload, the messages (including their context properties that are related to BizTalk Server 2013 R2) that were "in flight" when the exception occurred, and the current exception caught by the BizTalk Orchestration engine. After an ESB fault message is published, it is de-queued to a subscribing orchestration (a custom exception handler) that extracts and inspects the in-flight messages and the system exception object, and routes the in-flight messages to a file folder, from which a user can edit the message using InfoPath and resubmit it to BizTalk Server for processing.

For more information, see Running the Repair and Resubmit Custom Exception Handler Sample.


Collecting Exceptions and Persisting the Payload Using the ESB Exception Processor

In this use case, either the exception handler for an orchestration publishes an ESB fault message to the BizTalk Server 2013 R2 Message Box or the BizTalk Failed Message Routing mechanism generates a fault message. A send port, preconfigured with the ESB Exception Encoder pipeline component, subscribes to both of the fault message types. It processes the fault messages and then persists them as disk files that you can view using InfoPath, as illustrated in Figure 1.

Collecting Exceptions Payload

Figure 1

Capturing a fault message and persisting it to a disk file

The ​Microsoft BizTalk ESB Toolkit includes the following:

  • A preconfigured send port that uses the ESB Fault Processor send pipeline. You can configure this send port according to your own specific requirements.

  • The Message Persisting Custom Exception Handler sample. This sample shows how a loosely coupled generic exception handler can receive fault messages, extract the BizTalk Server messages they contain, normalize and enrich the messages, and write them as disk files to the file system.

  • The BizTalk Failed Message Routing sample. This sample shows how the ESB Exception Management Framework can normalize and enrich fault messages natively generated by the Failed Message Routing mechanism in BizTalk Server.

For more information, see Running the Message Persisting Custom Exception Handler Sample and Running the BizTalk Failed Message Routing ESB Processing Sample.


Repairing and Resubmitting Messages Using the ESB Management Portal

In this use case, a preconfigured send port uses the ESB Fault Processor send pipeline to receive an ESB fault message generated by the exception handler in an orchestration or a fault message generated by the Failed Message Routing mechanism in Microsoft BizTalk Server. The ESB Fault Processor normalizes, enriches, and routes it to the ESB Management Portal database. The portal monitors the database for incoming fault messages and can generate alerts that notify subscribed users of the processing failure. A user can open the fault message in the portal Fault Viewer, edit the message contents, and resubmit the message for processing, as illustrated in Figure 1.

Figure 1

Repairing and resubmitting messages using the ESB Management Portal

The ESB Management Portal included as a sample with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It provides a full graphical environment for editing and resubmitting messages; it also supports alerts, notifications, and message resubmission auditing.

For more information, see Working with Exceptions and Fault Messages.


Preserving JMS Headers When Routing Through an Orchestration

In this use case, components provided with ​Microsoft BizTalk ESB Toolkit extract Java Message Service (JMS) headers from an incoming message and then reconstructs them in the outgoing message. This demonstrates JMS message header preservation and access to header context from inside an orchestration, as illustrated in Figure 1.

Figure 1

Preserving JMS header information throughout an ESB orchestration and processing

The JMS MQRFH2 Component sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case and consists of the following three parts:

  • Part 1 demonstrates full-fidelity header preservation as a message travels from IBM WebSphere MQ, through ESB and BizTalk Server, and back to IBM WebSphere MQ.

  • Part 2 demonstrates how code in an ESB orchestration can access MQRFH2 header properties. In this case, the code modifies a JMS header property to specify the destination queue name.

  • Part 3 demonstrates bulk loading a queue with messages and shows how the application routes messages to the destination queues specified as part of the message content.

For more information, see Installing and Running the JMS MQRFH2 Component Sample.


Handling Externally Submitted Exceptions Using a Custom Handler

In this use case, an external client submits an exception message through a Web service. A send port, preconfigured with the ESB Exception Encoder pipeline component, subscribes to the fault message; it processes and persists it as a disk file that you can view using Microsoft InfoPath, as shown in Figure 1.

Handling External Exceptions

Figure 1

Handling incoming exception or fault messages and persisting to a disk file

The Exception Handling Service Sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It shows how to use the ESB Exception Service as a universal mechanism to submit fault messages from external applications that will be stored in the ​Microsoft BizTalk ESB Toolkit exception management database. For more information, see Running the Exception Handling Service Sample.


Adding and Removing Namespaces in an XML Message Document

In this use case, the Namespace component provided with the ​Microsoft BizTalk ESB Toolkit adds namespaces to, or removes namespaces from, documents and messages, as illustrated in Figure 1. This prevents namespace clashes or errors arising when documents use default namespaces.

Adding Removing Namespaces

Figure 1

Adding and removing XML document and message namespaces

The Namespace Component sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It shows how to use the component to inject and remove namespaces in a document as part of the send and the receive process.

For more information, see Installing and Running the Namespace Component Sample.


Implementing the Scatter-Gather Pattern for Multiple Web Service Invocations

In this use case, a message contains an itinerary service step that specifies more than one external service that BizTalk Server 2013 R2 should access. It uses dynamic resolution to determine service locations and endpoints and any optional BizTalk Service maps for transforming the returned data. The orchestration implementing this service performs the transformation and invocations, and all service invocations occur asynchronously. After all service invocations complete, the itinerary service aggregates the responses into a single response message and sends the message to the client through a dynamically assigned endpoint. Figure 1 illustrates this use case.

Implementing Scatter Gather Pattern

Figure 1

Implementing the Scatter-Gather pattern for multiple Web service invocations

The Scatter-Gather sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case.

For more information, see Installing and Running the Scatter-Gather Sample.


Transforming and Routing a Message to Multiple Endpoints

In this use case, the ESB performs a transformation on a message submitted through the Itinerary Web service on-ramp. A dynamic resolution lookup determines the map name and transforms the inbound message. Additionally, the itinerary specifies n number of target endpoints that the Itinerary service will dynamically resolve and to which it will route the transformed message. All operations occur at the messaging layer, as illustrated in Figure 1.

Transforming Multiple Endpoints

Figure 1

Transforming and routing a message to multiple endpoints

The Dynamic Resolution sample included with the ​Microsoft BizTalk ESB Toolkit demonstrates this use case. It shows how to use ESB pipeline components, specifically the ESB Dispatch Disassembler component, to dynamically resolve endpoint location, set routing properties, and resolve and execute BizTalk Server 2013 R2 maps at the messaging level, without using an orchestration. It also demonstrates both one-way and two-way messaging patterns.

For more information, see Installing and Running the Dynamic Resolution Sample and Installing and Running the Multiple Web Services Sample.


Key Scenarios and Development Tasks

This topic describes the key scenarios for using the ​Microsoft BizTalk ESB Toolkit and demonstrates how developers can accomplish the key development activities. This topic includes the following scenarios:

  • Using Itinerary-Based Routing

  • Using Dynamic Resolution and Routing

  • Using Dynamic Transformation

  • Using ESB Exception Management

  • Using the BizTalk ESB Toolkit Web Services

  • Using the Pipeline Support Components

  • Using the Helper Classes

  • Using the BizTalk ESB Toolkit Utilities


Using Itinerary-Based Routing

The ​Microsoft BizTalk ESB Toolkit provides itinerary-based message routing by implementing the Routing Slip pattern to enable scenarios when the sequence of processing steps for a particular message is not known at design time and may vary for each message. The implementation of this pattern uses a routing slip to represent a collection of these steps in XML format and determines which steps need to occur during at run time. A state of the routing slip, frequently referred to as an "ESB itinerary," is an ordered set of declarative instructions that define the steps that must be executed for a message as it is being processed by ​Microsoft BizTalk ESB Toolkit components and the BizTalk Server runtime. A particular processing instruction specified in ESB itinerary is associated with the ​Microsoft BizTalk ESB Toolkit component, which is also referred to as the "ESB itinerary service." The purpose of the ESB itinerary service is to execute the processing instructions and to update the state of the routing slip to indicate the next pending instruction.

This section describes the itinerary-based processing features of the ​Microsoft BizTalk ESB Toolkit. It contains the following topics:

  • ESB Itinerary Management

  • On-Ramps and Off-Ramps

  • Choosing Between Messaging and Orchestration Itinerary Services

  • Using a Pipeline Component to Select an Existing Itinerary

  • Using a Pipeline Component to Read an Itinerary

  • Using a Pipeline Component to Cache an Itinerary for Solicit-Response

  • Creating Itinerary Subscribers

  • Executing an Itinerary Service

  • Itinerary-Based Routing Artifacts


ESB Itinerary Management

​Microsoft BizTalk ESB Toolkit offers two distinct options for ESB itinerary management: centralized and decentralized. This section discusses benefits and risks for each of these options.

Decentralized ESB Policy Management

In this scenario, the ESB client application provides the content of the ESB itinerary as an attachment for each submitted message to the ESB. The message contains a SOAP header with the itinerary contents; when a pipeline component receives the message, it decodes the message, and then it promotes the itinerary to the message context for further routing. Although this design provides the opportunity to easily implement a Routing Slip pattern, fully allowing the client to control the flow of a message presents the following challenges:

  • By allowing the client to determine which processes should be applied to a message, the details of available processes from which to choose are transparent to the ESB client application. This practice could potentially expose sensitive information from ESB itinerary to the client.

  • In addition to the potential security concerns, allowing the client to manage the itineraries for being submitted with each message does not enforce ESB itinerary as policy unless it is implemented for a specific client. Therefore, costs of change management for enforcing a new version of the itinerary are extremely high and will increase for each new specific type of a trusted client application.

  • By allowing the client to pass the entire itinerary with the submitted message, the client should always be located within the trusted subsystem; otherwise, the ESB itinerary could potentially specify malicious processing instructions that are no longer valid.

​Microsoft BizTalk ESB Toolkit supports processing itineraries submitted by the client; however, this option should only be used for backward compatibility and testing purposes.

For more information about enabling client-side itineraries, see Using a Pipeline Component to Read an Itinerary.

Centralized ESB Policy Management

There are potential security and synchronization concerns inherent with allowing a client to submit messages with itineraries attached, so the best practice is to manage ESB itineraries in a central repository implemented as a SQL database and included in ​Microsoft BizTalk ESB Toolkit for this purpose. By deploying itineraries to a central location, ESB itinerary policies can be easily managed and modified without the need to implement dramatic client-side changes, and the organization can control the processing of messages without exposing potentially sensitive information to the client.

Specialized pipeline components are provided to determine the appropriate ESB itinerary to attach to an inbound message. This approach provides two distinct options for submitting a message for itinerary-based routing:

  • Using the first option, the client application can still indicate a distinct ESB itinerary by providing ESB itinerary reference information in the SOAP header along with request message, instead of submitting a complete itinerary. This information includes ESB itinerary name and optional version. In this scenario, clients can still specify how message can be routed, but there is no risk of policy synchronization errors or security compromises by exposing content of the ESB itinerary to client applications.

  • The second option is to configure the ESB on-ramp to automatically determine the appropriate ESB itinerary, based on the content or context of the message, without requiring any header information from the submitting client. This scenario enables the organization to control the flow of a submitted message and eliminates the need for the client to be aware of how the message is being routed.


On-Ramps and Off-Ramps

In an environment where ​Microsoft BizTalk ESB Toolkit is deployed, a BizTalk receive location responsible for receiving ESB-destined messages is referred to as an "on-ramp." To configure a standard BizTalk receive location to an ESB on-ramp, associate the receive location with one of the pipelines provided as part of the toolkit, and then correctly configure the components of that pipeline to determine or read the itinerary for the inbound message, depending on your scenario.

An ESB "off-ramp" corresponds to a BizTalk dynamic send port. As an itinerary is being processed, values are promoted to the context properties of the associated message using the System-Properties.xsd schema. The BizTalk publish-subscribe mechanism uses these promoted properties to route a message through a dynamic send port (off-ramp) to complete a message delivery.

The following table lists the on-ramps that are provided by the ​Microsoft BizTalk ESB Toolkit.

Name | Message exchange pattern | Description
ESB.ItineraryServices | One-Way | ASMX on-ramp; expects ESB itinerary content in SOAP header.
ESB.ItineraryServices.Response | Request-Response | ASMX on-ramp; expects ESB itinerary content in SOAP header.
ESB.ItineraryServices.WCF | One-Way | Windows Communication Foundation (WCF) on-ramp; expects ESB itinerary reference in SOAP header.
ESB.ItineraryServices.Response.WCF | Request-Response | WCF on-ramp; expects ESB itinerary reference in SOAP header.
ESB.ItineraryServices.Generic.WCF | One-Way | WCF on-ramp; expects request message only.
ESB.ItineraryServices.Generic.Response.WCF | Request-Response | WCF on-ramp; expects request message only.

​Microsoft BizTalk ESB Toolkit on-ramps that are not ASMX should be configured to select ESB itineraries. For more information about how to select an ESB itinerary, see Using a Pipeline Component to Select an Existing Itinerary.


Choosing Between Messaging and Orchestration Itinerary Services

Itinerary services can be configured to occur in either the messaging subsystem or the orchestration subsystem of BizTalk Server 2013 R2. These ESB itinerary messaging services are configured to process the message and may be executed in a BizTalk Server pipeline (on-ramp or off-ramp). This option enables the developer to define exactly where in the pipeline the service will execute. Naturally, services configured to process in the orchestration subsystem will be executed in a BizTalk orchestration.

ESB Itinerary Messaging Services

When a message is being processed in a BizTalk Server pipeline, using ESB itinerary messaging services reduces message latency. By implementing back-to-back services in a single pipeline, it is possible to transform a message multiple times and route the message to its endpoints with only a single persistence to the Message Box database. Additionally, messaging-based processing eliminates the additional resource cost of orchestration processing. Generally speaking, messaging-based processing is less resource intensive and provides faster processing than orchestration-based processing. In pipelines, the ESB Dispatcher and ESB Dispatcher Disassemble pipeline components provided by ​Microsoft BizTalk ESB Toolkit act as message interceptors and execute messaging-based itinerary services, whether it is a routing, transformation, or a custom service. For more information about configuring these components, see The ESB Dispatcher Component and The ESB Dispatcher Disassemble Component.

ESB Itinerary Orchestration Services

If dynamic routing must occur between or after orchestration processes, use orchestration-based processing for the itinerary service. By default, the orchestration-based services receive the message as an XML document. The Routing orchestration uses the Resolver Manager to attempt to resolve the endpoints identified in the itinerary. The Adapter Manager uses the response from the Resolver Manager to promote the endpoint details into the message context, and the message is published to the Message Box database using a direct-bound logical port. At this point, regular BizTalk routing occurs, and the dynamic send port is configured using the message's promoted properties.

The included Itinerary Service orchestration provides a good starting point for creating custom orchestration-based itinerary services. For more information about creating custom itinerary services, see Modifying and Extending the BizTalk ESB Toolkit.


Using a Pipeline Component to Select an Existing Itinerary

ESB Itinerary Selector Pipeline Component

Messages submitted using generic itinerary on-ramps are submitted without an itinerary header. To resolve the appropriate itinerary and attach it to the incoming message, the on-ramp must provide a mechanism that can be configured to access itineraries from a central repository.

The ESB Itinerary Selector pipeline component uses a resolver connection string, in conjunction with specialized resolvers, to resolve the content of a server-side itinerary stored in a central repository (by default, SQL Server).

When the ESB Itinerary Selector pipeline component is used in WCF on-ramps in conjunction with the ITINERARY-STATIC resolver, the name and version of the itinerary requested by the client (as represented in the SOAP header) is retrieved from the message context and is used to select the appropriate itinerary.

By default, the ESB Itinerary Selector pipeline component resides in the following pipelines:

  • ItinerarySelectReceive

  • ItinerarySelectReceivePassthrough

  • ItinerarySelectReceiveXml

  • ItinerarySelectSendReceive

The following sections describe the steps performed by each component.

ESB Itinerary Selector Pipeline Component Processing Steps

The ESB Itinerary Selector pipeline component executes the following steps:

  • The submitting party submits a message for processing. The Itinerary Selector component uses a resolver specified as a property connection string, configured by the developer, to determine and select the appropriate itinerary from the itinerary store, based on message content or context.

  • It validates the itinerary and sets specific properties to preset default values if they are null in the itinerary; for example:

    • If Service count is less than 1, the component throws an exception.

    • The component sets the itinerary root attributes using the values for the Service count, the identifier (Uuid), the start time (BeginTime), and whether this is a one-way or two-way request (IsRequestResponse).

    • The component validates the services, sets the identifiers, sets the current service instance (the service to process next), and validates any associated resolvers.

    • The component sets the Microsoft BizTalk Server segment of the itinerary using the following properties:

      • correlationToken

      • reqRespTransmitPipelineID

      • interchangeId

      • receiveInstanceId

      • epmRRCorrelationToken

    • The component writes the modified itinerary to the BizTalk message context properties listed in the following table using the properties defined in the System-Properties.xsd schema.

      Properties

      Name = ItineraryHeader

      Namespace = http://schemas.microsoft.biztalk.practices.esb.com/itinerary/system-properties

    • The component promotes the four BizTalk context properties listed in the following table using the values defined in the System-Properties.xsd schema.

      Property Value

      ServiceName

      The name of the current service instance defined in the itinerary.

      ServiceType

      Set to either Orchestration or Messaging.

      IsRequestResponse

      Set to either True or False.

      ServiceState

      Set to Pending.

ESB Dispatcher Pipeline Component Process Steps

The ESB Dispatcher pipeline component executes the following steps:

  • It manages the execution of any itinerary steps of type Messaging and advances the itinerary. The ESB Dispatcher component is location-aware and executes logic based on its location in the messaging processing cycle, which could be Receive Inbound, Send Transmit, Send Inbound, or Receive Outbound. The ESB Dispatcher pipeline component invokes ESB itinerary messaging services specified in the Esb.config file. By default, the configuration properties of this component for routing and transformation are associated with the following services:

    • Microsoft.Practices.ESB.Services.Transform. This service executes BizTalk maps against the payload of an inbound message. The service validates transform requirements and updates the BizTalk context properties that contain the document specification name and the message type. The ESB Dispatcher executes this service only if this is the name of the transform service as it appears in the corresponding property of the ESB Dispatcher pipeline component.

    • Microsoft.Practices.ESB.Services.Routing. This service uses the Resolver and Adapter Provider Framework to set the appropriate endpoint routing information. The ESB Dispatcher executes this service only if this is the name of the routing service as it appears in the corresponding property of the ESB Dispatcher pipeline component.


Using a Pipeline Component to Read an Itinerary

A message that arrives in a receive pipeline can contain metadata in its SOAP header that defines its processing requirements (client-side itinerary). Figure 1 illustrates the use of the ESB Itinerary and ESB Dispatcher pipeline components.

Pipeline Component Read

Figure 1

Example of an ESB Itinerary pipeline component

An ESB Itinerary pipeline component can be used to capture the metadata from a message as context properties that can define the processing applied by the ESB.

The following sections describe the steps performed by each component.

ESB Itinerary Pipeline Component Process Steps

In the example shown in Figure 1, the ESB Itinerary pipeline component executes the following steps:

  • It reads the itinerary SOAP header. The submitting party sets the itinerary by populating the SOAP header when he or she submits the message. A series of BizTalk message context properties represent the SOAP header; these properties vary, depending on the type of Web service adapter that is used. The following are the relevant Web service adapters:

    • WCF adapter. This adapter parses the SOAP headers and populates the BizTalk message context properties listed in the following table.

      Properties

      Name = Itinerary

      Namespace = http://schemas.microsoft.biztalk.practices.esb.com/itinerary

      Note
      By default, the Windows Communication Foundation (WCF) adapter uses the root name of the schema named ItineraryDescription.xsd (this schema is used to generate the ESB Itinerary SOAP header) as the BizTalk context Name argument, and it uses the target namespace of the schema as the BizTalk context Namespace argument.

    • SOAP adapter. This adapter parses the SOAP headers and populates the BizTalk message context properties listed in the following table.

      Properties

      Name = Itinerary

      Namespace = http://schemas.microsoft.com/BizTalk/2003/SOAPHeader

      Note
      By default, the SOAP Adapter uses the root name of the schema named Itinerary.xsd (this schema is used to generate the ESB Itinerary SOAP header) as the BizTalk context Name argument, and it uses the namespace of the SOAP header as the BizTalk context Namespace argument.

  • It removes the original itinerary value from the message context.

  • It validates the itinerary and sets specific properties to preset default values if they are null in the itinerary; for example:

    • If Service count is less than 1, the component throws an exception.

    • The component sets the itinerary root attributes using the values for the Service count, the identifier (Uuid), the start time (BeginTime), and whether this is a one-way or two-way request (IsRequestResponse).

    • The component validates the services, sets the identifiers, sets the current service instance (the service to process next), and validates any associated resolvers.

    • The component sets the BizTalk Segment of the itinerary using the following properties:

      • correlationToken

      • reqRespTransmitPipelineID

      • interchangeId

      • receiveInstanceId

      • epmRRCorrelationToken

    • The component writes the modified itinerary to the BizTalk message context properties listed in the following table using the properties defined in the System-Properties.xsd schema.

      Properties

      Name = ItineraryHeader

      Namespace = http://schemas.microsoft.biztalk.practices.esb.com/itinerary/system-properties

    • The component promotes the four BizTalk context properties listed in the following table using the values defined in the System-Properties.xsd schema.

      Property Value

      ServiceName

      The name of the current service instance defined in the itinerary.

      ServiceType

      Set to either Orchestration or Messaging

      IsRequestResponse

      Set to either True or False

      ServiceState

      Set to Pending

ESB Dispatcher Pipeline Component Process Steps

In the example shown in Figure 1, the ESB Dispatcher pipeline component executes the following steps:

  • It manages the execution of any itinerary steps of type Messaging and advances the itinerary. The ESB Dispatcher component is location-aware and executes logic based on its location in the messaging processing cycle, which could be Receive Inbound, Send Transmit, Send Inbound, or Receive Outbound. The ESB Dispatcher pipeline component invokes ESB itinerary messaging services specified in the Esb.config file. By default, the configuration properties of this component for routing and transformation are associated with the following services:

    • Microsoft.Practices.ESB.Services.Transform. This service executes BizTalk maps against the payload of an inbound message. The service validates transform requirements and updates the BizTalk context properties that contain the document specification name and the message type. The ESB Dispatcher executes this service only if this is the name of the transform service as it appears in the corresponding property of the ESB Dispatcher pipeline component.

    • Microsoft.Practices.ESB.Services.Routing.This service uses the Resolver and Adapter Provider Framework to set the appropriate endpoint routing information. The ESB Dispatcher executes this service only if this is the name of the routing service as it appears in the corresponding property of the ESB Dispatcher pipeline component.


The ESB Itinerary Schema

The ESB Itinerary schema named Itinerary.xsd defines an itinerary as a set of processing instructions, generally referred to as itinerary services. An itinerary service may contain one or more itinerary services and the corresponding resolver connection strings, as shown in the following schema definition.

Xml Copy Code
<?xml version="1.0" encoding="utf-16"?>

<xs:schema xmlns:b="http://schemas.microsoft.com/BizTalk/2003" xmlns="http://schemas.microsoft.biztalk.practices.esb.com/itinerary" targetNamespace="http://schemas.microsoft.biztalk.practices.esb.com/itinerary" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:annotation>
    <xs:appinfo>
      <b:schemaInfo root_reference="Itinerary" xmlns:b="http://schemas.microsoft.con/BizTalk/2003" />
    </xs:appinfo>
  </xs:annotation>
  <xs:element name="Itinerary">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="BizTalkSegment">
          <xs:complexType>
            <xs:attribute name="interchangeId" type="xs:string" />
            <xs:attribute name="epmRRCorrelationToken" type="xs:string" />
            <xs:attribute name="receiveInstanceId" type="xs:string" />
            <xs:attribute name="messageId" type="xs:string" />
          </xs:complexType>
        </xs:element>
        <xs:element name="ServiceInstance">
          <xs:complexType>
            <xs:attribute name="uuid" type="xs:string" />
            <xs:attribute name="name" type="xs:string" />
            <xs:attribute name="type" type="xs:string" />
            <xs:attribute name="state" type="xs:string" />
            <xs:attribute name="position" type="xs:int" />
            <xs:attribute name="isRequestResponse" type="xs:boolean" />
            <xs:attribute name="stage" type="Stages" />
          </xs:complexType>
        </xs:element>
        <xs:element minOccurs="1" maxOccurs="unbounded" name="Services">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Services">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element minOccurs="0" maxOccurs="1" name="PropertyBag" nillable="true">
                      <xs:complexType>
                        <xs:sequence minOccurs="0" maxOccurs="1">
                          <xs:element minOccurs="0" maxOccurs="unbounded" name="Property">
                            <xs:complexType>
                              <xs:attribute name="name" type="xs:string" use="required" />
                              <xs:attribute name="value" type="xs:string" use="required" />
                            </xs:complexType>
                          </xs:element>
                        </xs:sequence>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                  <xs:attribute name="uuid" type="xs:string" />
                  <xs:attribute name="beginTime" type="xs:string" />
                  <xs:attribute name="completeTime" type="xs:string" />
                  <xs:attribute name="name" type="xs:string" />
                  <xs:attribute name="type" type="xs:string" />
                  <xs:attribute name="state" type="xs:string" />
                  <xs:attribute name="resolve" type="xs:boolean" />
                  <xs:attribute name="isRequestResponse" type="xs:boolean" />
                  <xs:attribute name="position" type="xs:int" />
                  <xs:attribute name="serviceInstanceId" type="xs:string" />
                  <xs:attribute name="isTrackingEnabled">
                    <xs:simpleType>
                      <xs:restriction base="xs:boolean" />
                    </xs:simpleType>
                  </xs:attribute>
                  <xs:attribute name="stage" type="Stages" />
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="ResolverGroups">
          <xs:complexType>
            <xs:sequence>
              <xs:element maxOccurs="unbounded" name="Resolvers">
                <xs:complexType>
                  <xs:simpleContent>
                    <xs:extension base="xs:string">
                      <xs:attribute name="serviceId" type="xs:string" />
                    </xs:extension>
                  </xs:simpleContent>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
      <xs:attribute name="uuid" type="xs:string" />
      <xs:attribute name="beginTime" type="xs:string" />
      <xs:attribute name="completeTime" type="xs:string" />
      <xs:attribute name="state" type="xs:string" />
      <xs:attribute name="isRequestResponse" type="xs:boolean" />
      <xs:attribute name="servicecount" type="xs:int" use="required" />
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="Stages">
    <xs:restriction base="xs:string">
      <xs:enumeration value="notSpecified" />
      <xs:enumeration value="receiveInbound" />
      <xs:enumeration value="receiveTransmit" />
      <xs:enumeration value="sendTransmit" />
      <xs:enumeration value="sendInbound" />
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

The ServiceInstance element corresponds to the current itinerary service and contains properties such as name, type, state, and position that the service promotes into the message context. The schema named System-Properties.xsd in the Microsoft.Practices.ESB.ItinerarySchemas assembly defines these properties.

The Services element represents a set of itinerary services, with each service defined by its state, begin time, completion time, type (Orchestration or Messaging), and, optionally, stage (receiveInbound, receiveTransmit, sendTransmit, sendInbound).

The ResolverGroups element contains multiple Resolvers elements, each of which defines one or more resolver connection strings that an itinerary references through the serviceid attribute.

The following shows a sample of a submitted itinerary SOAP header before it is processed by the ESB Itinerary Pipeline component.

Xml Copy Code
<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" uuid="" beginTime="" completeTime="" state="Pending" isRequestResponse="false" xmlns="http://schemas.microsoft.biztalk.practices.esb.com/itinerary">

  <ServiceInstance uuid="" name="Microsoft.Practices.ESB.Services.Transform" type="Messaging" state="Pending" position="0" isRequestResponse="false" xmlns="" />

  <Services xmlns="">
    <Service uuid="" beginTime="" completeTime="" name="Microsoft.Practices.ESB.Services.Transform" type="Messaging" state="Pending" isRequestResponse="false" position="0" serviceInstanceId="" />
  </Services>

  <Services xmlns="">
    <Service uuid="" beginTime="" completeTime="" name="DynamicResolutionSolicitResp" type="Messaging" state="Pending" isRequestResponse="true" position="1" serviceInstanceId="" />
  </Services>

  <ResolverGroups xmlns="">
    <Resolvers serviceId="DynamicResolutionSolicitResp1">&lt;![CDATA[BRE:\\policy=GetCanadaEndPoint;version=;useMsg=;]]&gt;</Resolvers>

    <Resolvers serviceId="Microsoft.Practices.ESB.Services.Transform0">&lt;![CDATA[BRE:\\policy=CanadaSubmitOrderMaps;version=;useMsg=;]]&gt;</Resolvers>
  </ResolverGroups>

</Itinerary>


Using a Pipeline Component to Cache an Itinerary for Solicit-Response

Messages submitted through a ​Microsoft BizTalk ESB Toolkit itinerary on-ramp can go through either a one-way itinerary or a two-way (request-response) itinerary. To support request-response itineraries, the itinerary mechanism must provide caching for BizTalk dynamic Solicit-Response send ports.

The ESB Itinerary Cache pipeline component places the itinerary stored in the outbound message context into the cache and attaches it to the response message; it is returned by the send port using the configurable caching key. This allows the itinerary service to process and execute subsequent services defined after the current service in the itinerary.

By default, the ESB Itinerary Cache pipeline component resides in the ItineraryReceiveSend BizTalk pipeline, as shown in Figure 1. This pipeline should be used only as the receive pipeline for a Solicit-Response send port.

Pipeline Component Cache

Figure 1

The ESB Itinerary Cache Pipeline component

Use the ESB Itinerary Cache Pipeline component in a BizTalk receive pipeline for a Solicit-Response send port.


Creating Itinerary Subscribers

BizTalk Server 2013 R2 automatically publishes messages arriving through a receive pipeline to the Message Box database; this makes the messages ready for pick-up by the relevant subscriber. This decoupled approach is the preferred way to develop BizTalk solutions because it provides maximum flexibility, scales well, and uses the publish-subscribe mechanism.

There are two ways to create an itinerary service subscriber:

  • Using a Send Port as an Itinerary Service Subscriber

  • Using an Orchestration as an Itinerary Service Subscriber


Using a Send Port as an Itinerary Service Subscriber

As an example of how to use a send port as an itinerary service subscriber, Figure 1 shows the filter conditions for a dynamic one-way sent port that picks up messages that meet the following conditions:

  • IsRequestResponse = False

  • ServiceName = DynamicTest

  • ServiceState = Pending

  • ServiceType = Messaging

Figure 1

Example of send port filters

Use send port filter expressions to specify the property and value sets of messages it will pick up from the Message Box database through the itinerary on-ramp.

Note
It is important to use filter conditions that are as specific and focused as possible; otherwise, there is a risk of picking up unintended messages, which could cause problems in a high-volume environment. The schema System-Properties.xsd defines the filter properties of subscriptions.


Using an Orchestration as an Itinerary Service Subscriber

Orchestrations can also act as itinerary services. To participate in an itinerary, you must first design the orchestration as direct-bound; to do this, use a filter subscription similar to that of the send port in the previous topic, Using a Send Port as an Itinerary Service Subscriber. Figure 1 shows an example of a filter expression for a suitable orchestration to pick up any message that meets the following conditions:

  • ServiceName = Microsoft.Practices.ESB.Services.Transform

  • ServiceState = Pending

  • ServiceType = Orchestration

Figure 1

Example filter expression for an orchestration that will participate in an itinerary as a subscriber

When messages arrive in Microsoft BizTalk Server through an ESB on-ramp, the validation step in the ESB pipeline writes the property values for the filter properties into the BizTalk context properties of the incoming message; this promotes them to the message context. The itinerary service always sets the ServiceName property for the currently active service to the name of the service to process next, and with a ServiceState property value of Pending. For a subscription, you must set at least the first three of the following properties:

  • ServiceName. This is the name of the service, as stored in the ESB itinerary, and can be any name. The itinerary uses this name to identify which service to execute.

  • ServiceState. This is the state of the current itinerary service step to execute. The current service step (for processing next) will always have the value Pending, set by either the ESB itinerary pipeline component, the ESB Itinerary Selector pipeline component, or code that calls the Advance method of the itinerary API.

  • ServiceType. This property defines the type of service, indicating whether it originates from the orchestration or the messaging subsystem in BizTalk.

  • IsRequestResponse. This optional property must have the same value as the IsRequestResponse property of the service.


Executing an Itinerary Service

An ESB itinerary can contain any itinerary service that may be implemented as orchestration or messaging to perform the following tasks:

  • It can receive the message containing the itinerary.

  • It can retrieve the current itinerary step.

  • It can process the service.

  • It can advance the itinerary on the outgoing message by calling the Advance method.

  • It can publish the processed message back into the Microsoft BizTalk Message Box database.

For example, an orchestration can receive a message that contains an itinerary by implementing a filter defined on the activated receive shape, as shown in Figure 1 of Using an Orchestration as an Itinerary Service Subscriber. However, messaging is slightly different: the pipeline component calls the GetItineraryStep method to determine whether an itinerary exists in an incoming message. It also examines the message properties to check whether it should process it.

Figure 1

Example filter expression for an orchestration that will participate in an itinerary as a subscriber

After the service obtains the message, it must call the GetItineraryStep method, which returns an instance of the ItineraryStep class. The following listings demonstrate how you can call the methods of the itinerary API from both an orchestration and a custom pipeline component. The following code executes the GetItineraryStep method from an orchestration Expression shape.

Copy Code
//XLANGs
// Retrieve the current itinerary step.
itinerary = new Microsoft.Practices.ESB.Itinerary.SerializableItineraryWrapper();
step = new Microsoft.Practices.ESB.Itinerary.SerializableItineraryStepWrapper();

itinerary.Itinerary = Microsoft.Practices.ESB.Itinerary.ItineraryOMFactory.Create(InboundMessage);
step.ItineraryStep = itinerary.Itinerary.GetItineraryStep(InboundMessage);

The following code shows how to execute the messaging service method from a custom pipeline component.

C# Copy Code
// Execute messaging step.
public IBaseMessage Execute(IPipelineContext context, IBaseMessage msg, string resolverString, IItineraryStep step)
{
    if (null != step
    && step.ServiceType == "Messaging"
    && step.ServiceName == "SomeService")
    {
        // If the service name matches the required name, process the message here.
    }
    else
    {
        // Do not process the message.
        return pInMsg;
    }
}

The instance of the IItineraryStep class contains all the metadata for the current service, including ambient properties of the current service execution environment. Two good examples of this are the ServiceInstanceID and the current MessageDirection properties for a pipeline component.

After a service calls the GetItineraryStep method, it can retrieve any associated resolvers. The ResolverCollection property of the ItineraryStep class returns a collection of resolvers that the service can enumerate through, as shown in the following example.

C# Copy Code
Microsoft.Practices.ESB.Itinerary.ResolverCollection resolvers;
resolvers = step.ItineraryStep.ResolverCollection;

Each item in the ResolverCollection represents a resolver connection string that matches one of the types supported by the Resolver and Adapter Framework. For example, an item in the collection could look like the following listing.

IDL Copy Code
BRE:\\policy=GetCanadaPurchaseEndPoint;version=;useMsg=;
UDDI:\\serverUrl=http://localhost/uddi;serviceName=OrderFileServiceWBindings;
STATIC:\\TransportLocation=http://localhost/ESB.CanadianServices/SubmitPOService.asmx;
TargetNamespace=http://globalbank.esb.dynamicresolution.com/canadianservices/;
XPATH:\\TransportType=; TransportLocation=/*[local-name()='OrderDoc' and namespace-
uri()='http://globalbank.esb.dynamicresolution.com/northamericanservices/']/*
[local-name()='ID' and namespace-
uri()='http://globalbank.esb.dynamicresolution.com/northamericanservices/'];
TargetNamespace=/*[local-name()='OrderDoc' and namespace-
uri()='http://globalbank.esb.dynamicresolution.com/northamericanservices/']/*
[local-name()='customerName' and namespace-
uri()='http://globalbank.esb.dynamicresolution.com/northamericanservices/'];

The resolver manager in the Resolver and Adapter Provider Framework can resolve the endpoints and set the endpoint properties of the message. For more information about how this occurs, see Using Dynamic Resolution and Routing.

After the service finishes processing the message, it must advance the itinerary on the outgoing message and publish the message back to the Message Box database. The following example shows the process for an orchestration Expression shape.

Xml Copy Code
//XLANGs
// Copy the context to the outbound message.
OutboundMessage = InboundMessage;
OutboundMessage(*) = InboundMessage(*);

// Call the method of the ItinerarySerializableWrapper to advance to the next step.
itinerary.Itinerary.Advance(OutboundMessage, step.ItineraryStep);

The following example shows how to indicate that ​Microsoft BizTalk ESB Toolkit core engine should advance itinerary for a custom pipeline component.

C# Copy Code
// Advance Itinerary
// <summary>
// Signals that the step should be advanced immediately following execution of the service.
// </summary>
// <param name="step">Current step</param>
// <param name="msg">Current message</param>
// <returns>True to advance the itinerary.</returns>
public bool ShouldAdvanceStep(IItineraryStep step, IBaseMessage msg)
{
    return true;
}


Itinerary-Based Routing Artifacts

The itinerary-based routing capabilities of the ​Microsoft BizTalk ESB Toolkit include a set of key artifacts defined in multiple assemblies. The following tables list these artifacts by category to assist developers when working with and extending the itinerary-based routing implementation with additional ESB itinerary service implementations.

ESB Itinerary Classes

The following table lists the assemblies and artifacts contained in the ESB.Itinerary project. The name of the containing assembly is Microsoft.Practices.ESB.Itinerary.dll.

Key artifact | Description
MessageHelper | Contains all the private functions called by other project artifacts.
IItineraryStep | The public class returned from the GetItineraryStep method.
ResolverCollection | Implements a collection of all the resolvers associated with a service. This class is exposed by the IItineraryStep interface and is populated by the GetItineraryStep method.
IMessagingService | Defines the interface implemented by messaging-based itinerary services.
IMessagingService | Factory for creating IMessagingService objects based on a name configured in Esb.config.

ESB Itinerary Messaging Services

The following table lists the classes defined in the Microsoft.Practices.ESB.Itinerary.Services.dll assembly in Microsoft.Practices.ESB.Itinerary.Services namespace.

Key artifact | Description
Routing | Implementation of the ESB itinerary messaging routing: invoked by ESB Dispatcher or Dispatcher Disassemble components using the Esb.config file.
Transform | Implementation of the ESB itinerary messaging transformation service: invoked by ESB Dispatcher or Dispatcher Disassemble components using the Esb.config file.

The following table lists the artifacts contained in the Microsoft.Practices.ESB.Itinerary.Services.Broker.dll assembly.

Key artifact | Description
MessagingBroker | Implementation of the ESB itinerary messaging service for routing by message context: invoked by ESB Dispatcher or Dispatcher Disassemble components using the Esb.config file.

These services are also defined in the BizTalk ESB Toolkit configuration file, Esb.config.

ESB Itinerary Orchestration Services

The following table lists the artifacts contained in the Microsoft.Practices.ESB.Agents.dll assembly.

Key artifact | Description
Delivery.odx | A sample routing orchestration itinerary service identified by the service name Microsoft.Practices.ESB.Services.Routing.
Transform.odx | A sample transformation orchestration itinerary service identified by the service name Microsoft.Practices.ESB.Services.Transform.

ESB Itinerary Pipeline Components

The following table lists the assemblies and artifacts contained in the Microsoft.Practices.ESB.Itinerary.PipelineComponents.dll assembly.

Key artifact | Description
Itinerary | The primary itinerary processing pipeline component that processes and validates the itinerary of incoming messages.
ItineraryCache | The itinerary caching pipeline component for use in Solicit-Response send ports.
ItinerarySelector | The itinerary selector pipeline component that resolves server-side itineraries in generic on-ramps.

ESB Itinerary Pipelines

The following table lists the assemblies and artifacts contained in the Microsoft.Practices.ESB.Itinerary.Pipelines.dll assembly.

Key artifact | Description
ItineraryReceive | The itinerary pipeline used in the Itinerary Web service on-ramp. Used as a receive pipeline for receive locations and contains the following pipeline components: ESB Itinerary, XML Disassembler, ESB Dispatcher
ItineraryReceivePassthrough |
ItineraryReceiveXml | The itinerary pipeline used in the Itinerary Web service on-ramp. Used as a receive pipeline for receive locations to route an incoming message to multiple endpoints and contains the following pipeline components: ESB Itinerary, ESB Dispatcher Disassembler
ItinerarySend | The itinerary pipeline used in the Itinerary off-ramp. Used as a send pipeline for a send port and contains the following pipeline components: ESB Dispatcher, XML Assembler, ESB Itinerary Cache
ItinerarySendPassthrough | The itinerary pipeline used in the Itinerary off-ramp. Used as a send pipeline for a send port and contains the following pipeline components: ESB Dispatcher, ESB Itinerary Cache
ItinerarySendReceive | The itinerary pipeline used in the Itinerary off-ramp. Used as a receive pipeline for a Solicit-Response send port and contains the following pipeline components: ESB Itinerary Cache, XML Disassembler, ESB Dispatcher
ItineraryForwarderSendReceive | The itinerary pipeline used in the Itinerary off-ramp. Used as a receive pipeline for a send port and contains the following pipeline components: ESB Itinerary Cache, XML Disassembler, ESB Dispatcher, Forwarder
ItineraryForwarderSendReceiveXml | The itinerary pipeline used in the Itinerary Web service on-ramp. Used as a receive pipeline for a send port and contains the following pipeline components: ESB Itinerary Cache, ESB Dispatcher Disassemble, Forwarder
ItinerarySelectReceive | The itinerary pipeline used in the Itinerary Web service on-ramp. Used as a receive pipeline for receive locations and contains the following pipeline components: ESB Itinerary Selector, XML Disassembler, ESB Dispatcher
ItinerarySelectReceivePassthrough | The itinerary pipeline used in the Itinerary Web service on-ramp. Used as a receive pipeline for receive locations and contains the following pipeline components: ESB Itinerary Selector, ESB Dispatcher
ItinerarySelectReceiveXml | The itinerary pipeline used in the Itinerary Web service on-ramp. Used as a receive pipeline for receive locations and contains the following pipeline components: XML Disassembler, ESB Itinerary Selector, ESB Dispatcher
ItinerarySelectSendReceive | The itinerary pipeline used in the Itinerary off-ramp. Used as a receive pipeline for a send port and contains the following pipeline components: ESB Itinerary Cache, ESB Itinerary Selector, XML Disassembler, ESB Dispatcher

ESB Itinerary Schemas

The following table lists the assemblies and artifacts contained in the Microsoft.Practices.ESB.Itinerary.Schemas.dll assembly.

Key artifact | Description
Itinerary.xsd | Defines the ESB itinerary SOAP headers used in Windows Communication Foundation (WCF)–based and SOAP–based Web service on-ramps.
ItineraryDescription.xsd | This scehma represents itinerary reference data and should be used for submitting message to WCF–based on-ramps.
System-Properties.xsd | Defines the ESB itinerary–related BizTalk Context properties.


Using Dynamic Resolution and Routing

In addition to itinerary-based routing, the ​Microsoft BizTalk ESB Toolkit supports dynamic resolution as configuration-based routing to avoid the requirement for hard-coded routing information in components and services. This section contains the following topics:

  • Dynamic Resolution and Routing Overview

  • The Resolver and Adapter Provider Framework

  • Using the Resolver Components in Your Code

  • Using Dynamic Routing


Dynamic Resolution and Routing Overview

The ESB Resolver classes support run-time resolution of the following:

  • Message delivery endpoints

  • Maps for transformation

  • Endpoint configuration

  • Custom service metadata

  • Server-side itineraries

The ​Microsoft BizTalk ESB Toolkit uses resolver connection strings to attempt resolution of maps and endpoints when messages arrive. These connections strings may exist in the itinerary SOAP header of messages when they arrive, or they may be set in a custom pipeline using one of the following pipeline components: ESB Itinerary Selector, ESB Dispatcher, or ESB Dispatcher Disassemble. Resolution occurs later in the processing life cycle using the "just-in-time" (JIT) resolution capabilities of the ESB Resolver and Adapter Provider Framework components.

For example, if the dynamic transformation agent receives a message that it must map, but the map name has not yet been determined, it will attempt to use the associated resolver to perform the resolution. If JIT resolution fails, which is classed as an error, the system generates an exception message.

The Resolver and Adapter Provider Framework can query the following data stores or resolution mechanisms:

  • Hard-coded maps or endpoints, in which case dynamic resolution does not occur

  • A Business Rules Engine (BRE) policy

  • A custom assembly implementing the IResolveProvider interface

  • An XPath query over the message

  • A Universal Description, Discovery, and Integration (UDDI) lookup


The Resolver and Adapter Provider Framework

The Resolver and Adapter Provider Framework supports itinerary, transformation, and endpoint resolution and routing. The framework can dynamically resolve endpoints and set outbound adapter properties. After a resolver component resolves an endpoint (for example, using Universal Description, Discovery, and Integration [UDDI] to look up an outbound Web service endpoint), an adapter provider component sets specific properties of registered BizTalk Server 2013 R2 adapters. For example, the WCF-BasicHttp adapter provider is responsible for setting the BizTalk-specific message context properties for the endpoint URI that will use the specific BizTalk adapter; the FTP adapter provider is responsible for setting the properties specific to the FTP adapter.

One goal of the Resolver and Adapter Provider Framework is to support resolution and routing at either the messaging level, without requiring the use of BizTalk orchestrations, or at the orchestration level. In both cases, the pluggable framework provides easy development, deployment, and registration of new resolvers and adapter providers. All resolvers and adapter providers implement well-defined interfaces and are demand-loaded at run time through registration in the configuration files.

Both the ESB Dispatcher and ESB Dispatcher Disassemble pipeline components use the Resolver and Adapter Provider Framework by passing the connection string from either the itinerary SOAP header or the pipeline configuration to the Resolver Manager.

The ​Microsoft BizTalk ESB Toolkit configuration contains details of all registered resolvers and adapter providers. At run time, the resolver managers and adapter managers read details of the registered resolvers and adapter providers from the configuration files, load the appropriate assemblies, and store them in a BizTalk host–level cache. This caching technique removes the requirement for repeated reading of configuration files and loading of assemblies for every submitted message.

For more information about how the Resolver and Adapter Provider Framework works and how you can extend it by creating custom resolvers and adapter providers, see Modifying and Extending the BizTalk ESB Toolkit.

Supported Resolution Mechanisms (Resolvers)

The BizTalk ESB Toolkit includes the following resolvers: STATIC, UDDI, UDDI3, XPATH, BRE, BRI, ITINERARY, ITINERARY-STATIC and LDAP.

A resolver's connection string always consists of a moniker (such as BRE) followed by ":\\" and the connection or processing details. The moniker matches the definition of the associated resolver in the configuration file. The properties associated with each connection string are unique, and not all properties are required. The schema for each of the resolvers can be found in the ESB.Resolvers.Schemas project.

The following are examples of connection strings:

  • STATIC

    STATIC:\\TransportType=;

    TransportLocation=http://localhost/ESB.CanadianServices/SubmitPOService.asmx;

    Action=;

    EndPointConfig=;

    JaxRpcResponse=false;

    MessageExchangePattern=;

    TargetNamespace=http://globalbank.esb.dynamicresolution.com/canadianservices/;

    TransformType=;

  • UDDI

    UDDI:\\serverUrl=http://localhost:9901/rmengine;

    serviceName=OrderPurchaseWebService;

    serviceProvider=Microsoft Practices ESB

  • XPATH

    \\TransportType=;

    TransportLocation=/*[local-name()='OrderDoc' and namespace-uri()='http://globalbank.esb.dynamicresolution.com/northamericanservices/']/*[local-name()='ID' and namespace-uri()='http://globalbank.esb.dynamicresolution.com/northamericanservices/'];

    Action=;

    EndPointConfig=;

    JaxRpcResponse=;

    MessageExchangePattern=;

    TargetNamespace=/*[local-name()='OrderDoc' and namespace-uri()='http://globalbank.esb.dynamicresolution.com/northamericanservices/']/*[local-name()='customerName' and namespace-uri()='http://globalbank.esb.dynamicresolution.com/northamericanservices/'];

    TransformType=;

  • BRE

    BRE:\\policy=GetCanadaEndPoint;

    version=;

    useMsg=;

  • BRI

    BRI:\\policy=ResolveItinerary;

    version=;

    useMsg=;

  • ITINERARY

    ITINERARY:\\name=TwoWayTestItinerary;

    version=;

  • ITINERARY-STATIC

    ITINERARY-STATIC:\\name=TwoWayTestItinerary;

    version=;

  • LDAP

    LDAP:\\TransportType=SMTP;

    TransportLocation={mail}

    Filter=(&amp;(objectClass=User)(|(userPrincipalName=yourname@domain.com)));

    SearchRoot=;

    SearchScope=Subtree;

    EndpointConfig=Subject=Itinerary Test Message to {mail}&amp;

    SMTPAuthenticate=0&amp;

    SMTPHost=127.0.0.1&amp;

    From=test@globalbank.com&amp;

    DeliveryReceipt=false&amp;

    MessagePartsAttachments=0&amp;

    ReadReceipt=false;

    ThrowErrorIfNotFound=false;

    Action=;

    JaxRpcResponse=false;

    MessageExchangePattern=;

    TargetNamespace=;

    TransformType=;

Not all attributes in the connection string are mandatory. In addition, EndPointConfig is a special attribute that any resolver can populate and return. Optionally, the resolver can store the name/value pairs that correspond to specific BizTalk Adapter Context properties, which it can, in turn, write to the context of the BizTalk message.

In this case, the ResolverDictionary instance that contains all the resolved properties returned from the resolution process then passes to the adapter manager. The adapter manager passes the dictionary to the specific adapter provider that will set all the adapter-specific and endpoint-specific BizTalk Context properties for the message. The resolvers look for the EndPointConfig property, extract the name/value pairs that correspond to their respective adapter properties, and then set these values on the message.

Supported Adapter Providers

The ​Microsoft BizTalk ESB Toolkit includes the following built-in adapter providers: FILE, FTP, SMTP,MQSeries, WCF-BasicHttp, WCF-WSHttp, and WCF-Custom. The name of each adapter provider is identical to the name of the associated adapter (transport type) in BizTalk Server.

A major advantage of the Resolver and Adapter Provider Framework is that you can extend it by creating and registering your own custom resolvers to resolve endpoint information and custom adapter providers to set specific properties of registered BizTalk adapters. For more information, see Modifying and Extending the BizTalk ESB Toolkit.


Using the Resolver Components in Your Code

The following code fragment from the dynamic transformation agent shows the default just-in-time (JIT) resolution functionality. You can easily implement resolution in your own application by using similar code.

Copy Code
//XLANGs
itinerary = new Microsoft.Practices.ESB.Itinerary.SerializableItineraryWrapper();
step = new Microsoft.Practices.ESB.Itinerary.SerializableItineraryStepWrapper();

itinerary.Itinerary = Microsoft.Practices.ESB.Itinerary.ItineraryOMFactory.Create(InboundMessage);
step.ItineraryStep = itinerary.Itinerary.GetItineraryStep(InboundMessage);
resolvers = step.ItineraryStep.ResolverCollection;
resolvers.MoveNext();
resolver = resolvers.Current;

// Pass the resolver configuration to the Resolver mgr for resolution.
resolverDictionary = Microsoft.Practices.ESB.Resolver.ResolverMgr.Resolve(InboundMessage, resolver);

// Set the transform type.
transformType = resolverDictionary.Item("Resolver.TransformType");

In the preceding listing, the Resolve method of the ResolverMgr class returns a Dictionary object that contains all the default resolution properties and their resolved values. Any custom resolver can add custom properties to the Dictionary object; doing this makes those properties available to any custom itinerary service. The following table shows the properties that can be optionally populated by the resolvers included in the ​Microsoft BizTalk ESB Toolkit. Any itinerary service can retrieve these property values by extracting them from the returned Dictionary object.

Properties
Resolver.Action | Resolver.ActionField | Resolver.DocumentSpecName
Resolver.Success | Resolver.EndpointConfig | Resolver.DocumentSpecStrongName
Resolver.FixJaxRpc | Resolver.InboundTransportType | Resolver.EpmRRCorrelationToken
Resolver.InterchangeId | Resolver.IsRequestResponse | Resolver.InboundTransportLocation
Resolver.MessageType | Resolver.MethodName | Resolver.MessageExchangePattern
Resolver.ReceivePortName | Resolver.TransportLocation | Resolver.OutboundTransportCLSID
Resolver.TransformType | Resolver.TargetNamespace | Resolver.ReceiveLocationName
Resolver.TransportType | Resolver.TransportNamespace | Resolver.WindowUserField
Resolver.CacheTimeout |  |

After the resolver manager returns the Dictionary object instance, the adapter manager sets the specific BizTalk Adapter Context properties of the message. The following code fragment from the routing agent demonstrates how you can use the adapter manager to set the endpoint properties of the outgoing message.

Copy Code
//XLANGs
// Set the transport properties.
transportLocation = resolverDictionary.Item("Resolver.TransportLocation");
transportType = resolverDictionary.Item("Resolver.TransportType");

// Create the delivery message.
DeliveryMessage = InboundMessage;

// Call the adapter manager to set all necessary properties on the message.
Microsoft.Practices.ESB.Adapter.AdapterMgr.SetEndpoint(
                                resolverDictionary,DeliveryMessage);

// Set the delivery port address.
DeliveryPort(Microsoft.XLANGs.BaseTypes.Address) = transportLocation;
DeliveryPort(Microsoft.XLANGs.BaseTypes.TransportType) = transportType;

The following code fragment from the routing agent demonstrates how to use the adapter manager from within a custom pipeline component to set the endpoint properties of an outgoing message.

C# Copy Code
// Resolve the configuration for routing.
ResolverDictionary = ResolverMgr.Resolve(info, pInMsg, pContext);

// Call the adapter manager to set all required message properties.
AdapterMgr.SetEndpoint(ResolverDictionary, pInMsg.Context);


Using Dynamic Routing

The ​Microsoft BizTalk ESB Toolkit supports dynamic routing of messages using a built-in process and a generic delivery agent; it also supports dynamic routing of messages at the messaging layer using the ESB Dispatcher or ESB Dispatcher Disassemble pipeline components.

Overview

The dynamic resolution mechanism in ​Microsoft BizTalk ESB Toolkit enables discovery of endpoints when a message arrives or immediately before a message is delivered.

How It Works

The generic delivery agent provided with the ​Microsoft BizTalk ESB Toolkit is both a sample and a guide to the development and usage of dynamic routing techniques. You can easily create additional delivery agents or implement delivery agents consisting of just a send port (which do not implement an orchestration). By default, the ESB Dispatch and ESB Dispatch Disassembler pipeline components offer a much more optimized dynamic routing capability.

The generic delivery agent itself implements an orchestration that subscribes to messages where the Name attribute of the current ServiceInstance element in the itinerary is Microsoft.Practices.ESB.Services.Routing. The agent performs the following sequence of operations:

  1. It receives an un-typed message (System.Xml.XmlDocument).

  2. It attempts to resolve n number of endpoints using the resolver manager.

  3. It uses the adapter manager to set the endpoint properties of the message context and the logical dynamic port.

  4. It publishes the message through the direct-bound send port, which triggers the BizTalk Server subscription on the dynamic send port for further message routing.

How to Configure Dynamic Routing

For more information about how to configure dynamic routing using the Itinerary Designer, see Creating Itineraries Using Itinerary Designer.

Dynamic Routing Errors

The dynamic routing mechanism will create and publish an ​Microsoft BizTalk ESB Toolkit Fault message in the following cases:

  • The delivery agent cannot determine the endpoint during just-in-time (JIT) resolution.

  • A delivery failure occurs.

  • No subscriber exists for the output message.

  • Any system exception occurs.


Using Dynamic Transformation

Overview

The ​Microsoft BizTalk ESB Toolkit supports three mechanisms for dynamic transformation:

  • A dynamic transformation agent implemented as an orchestration

  • A dynamic transformation Web service included with the core Web services

  • Transformations executed by ESB pipeline components

This section focuses on the transformation agent implemented as an orchestration. For information about the transformation Web service, see Using the BizTalk ESB Toolkit Web Services. For information about the ESB Dispatcher pipeline components, see Using the Pipeline Support Components.

How It Works

The transformation delivery agent is an orchestration that subscribes to messages where the Name attribute of the current ServiceInstance element in the itinerary is Microsoft.Practices.ESB.Services.Transform. The agent performs the following sequence of operations:

  1. It receives an un-typed message (System.Xml.XmlDocument).

  2. If the name of the map is available as a static value in the itinerary, the agent attempts to resolve the name of the map using the resolver manager.

  3. It applies the appropriate map to the inbound source message.

  4. It publishes the map output to the BizTalk Message Box database.

How to Configure Dynamic Transformation

For more information about how to configure Dynamic Transformation using Itinerary Designer, see Creating Itineraries Using Itinerary Designer.

Dynamic Transformation Errors

The dynamic transformation mechanism will create and publish an ESB fault message in the following cases:

  • The resolver component cannot determine which map to apply.

  • The specified map is not available (for example, you specified an incorrect map type or a map not yet deployed in BizTalk Server 2009).

  • A failure occurs during mapping (for example, the source document is not of the correct source type or the map references a custom function in an external assembly is not deployed to BizTalk).

  • An exception occurs during just-in-time (JIT) resolution of the map type.

  • No subscriber exists for the output message.

  • Any system exception occurs.

It is the developer's responsibility to provide the context information used to populate the exception messages and create handlers to react to the exception. Some of the data is automatically available, and a generic handler will pick up the exception message if no target handler is specified or available. For more information about handling dynamic transformation exceptions, see Using ESB Exception Management.


Using ESB Exception Management

Errors and exceptions can occur in a range of contexts and during a number of different processing stages in an ESB. This section provides information about handling exceptions and describes how you can publish details through the ESB Management Portal.

Overview

There are many ways to handle exceptions in a BizTalk Server 2013 R2 solution, including using frameworks such as the Enterprise Library. However, when developing with ESB and BizTalk Server, you are working in a message-based environment. Everything in a BizTalk solution is message-oriented, and BizTalk developers think in a message-oriented way. Therefore, the ​Microsoft BizTalk ESB Toolkit implements a message-oriented approach to exception handling.

The ESB Exception Management Framework follows a design pattern that provides a flexible approach to exception monitoring and enables error responses to originate from outside of the solution—perhaps at business-unit level.

The following topics discuss the ESB Exception Management Framework in more detail:

  • Design of the ESB Exception Management Framework

  • The Components of the Exception Management Framework

  • Using the Exception Management Framework

  • Creating Custom Exception Handlers


Design of the ESB Exception Management Framework

Consistent and re-usable patterns for managing exceptions are a core consideration of any development project; they help to maximize maintainability and make it easier to support the application after deployment.

A typical BizTalk application might use the BizTalk messaging features, optionally start processing an orchestration, call the Business Rule Engine, interact with several line-of-business (LOB) or enterprise resource planning (ERP) systems, and return a response to a separate third-party system. In addition, the run-time location of these components, including the BizTalk subsystems, may reside on one or more servers distributed throughout the current environment. This is a typical scenario and requires the system to support catching and reporting exceptions that may occur in any of the ESB or BizTalk decoupled subsystems or in the various third-party LOB systems, each of which has its own exception handling constraints. For example, the mainframe may reject an order sent from a Web site during a normal processing cycle; the Web site must compensate for this error and notify the user.

Because of the complexity of ESB applications and their environment, development of a consistent solution for application exception management should embody the following common design goals:

  • Provide a standardized approach for detecting and handling exceptions that occur in the BizTalk Server environment (that is, in the messaging and orchestration subsystems).

  • Provide common patterns that allow automated processes to react to and manage application exceptions.

  • Provide a loosely coupled exception management pattern that facilitates reuse.

  • Provide a common reporting mechanism for application exceptions and their available message states that can apply to any BizTalk subsystem.

To understand why the ​Microsoft BizTalk ESB Toolkit provides a custom error mechanism, namely the Exception Management Framework, and how it works, it is necessary to understand the exception management features available in BizTalk Server and why these features are not fully capable of meeting the preceding design goals.

BizTalk Server Exception Reporting

BizTalk Server supports the following exception handling and reporting mechanisms:

  • Failed Message Routing

  • BizTalk Server Administration Console

  • Microsoft Event Log

  • Custom development options

By default, BizTalk Server's capabilities for handling exceptions rely a great deal on operator intervention. For example, consider the situation where a user submits a message to BizTalk Server that causes an exception during the validation stage. By default, the message is published to the Message Box database, where it is routed to a suspended queue. This means that an operator must do the following:

  • Independently detect that an exception occurred.

  • Manually save the failed message to disk using the BizTalk Server 2013 R2 Administration Console.

  • Manually edit and correct the message and re-submit it to the system. In some instances, this process has the potential for losing important context information.

To resolve these issues, BizTalk Server 2013 R2 provides the Failed Message Routing mechanism. Developers and administrators can use this to create orchestration processes or messaging send ports configured to subscribe to any exceptions that occur in the messaging subsystem. This provides an automated error-detection and routing mechanism that preserves the original message state and solves the problem of detecting exceptions.

Because automatic failed message routing is not provided for orchestration processes, the developer must account for errors by adding exception handler blocks to orchestration scope shapes. With this solution, each orchestration can have its own exception handling, but there is no mechanism for reusing exception handling functionality across multiple orchestrations.

This means that there are now two very different ways in which messaging exceptions are processed and managed in a BizTalk Server system, and a third way in which orchestration exceptions are processed. Therefore, developers must customize the exception handling mechanism to suit their own requirements if they want to implement a system that matches the requirements described earlier in this section.

BizTalk Server Administration Console

The BizTalk Server 2013 R2 Administration Console provides a set of Group Overview pages, referred to as the BizTalk Group Hub. Using these pages, administrators can query for suspended messages and exceptions grouped by application, service name, error code, or URI, as shown in Figure 1.

Figure 1

The BizTalk Server 2013 R2 Administration Console Group Overview pages

Although the Group Overview feature provides a common user interface to view exceptions, the views are limited to "live" service instances. Examining the state can be a cumbersome task because administrators must drill down through the tree to each item. In addition, several other factors limit the BizTalk Server Administration Console capabilities as an application exception-reporting tool:

  • There is no capability for mining the data for business intelligence. For example, you cannot query for the worst offending applications on a monthly basis or examine quarterly trends for application exceptions.

  • The business may require alerts to be raised when certain application exceptions occur or when reaching specific thresholds, but there is no facility to subscribe to these types of exception events.

  • The Microsoft Management Console (MMC) that the Administration Console uses as its user interface (UI) mechanism is not an ideal interface, and it is not always convenient to access in production environments. At minimum, it requires users to be members of the BizTalk Operators role; and, in production environments, access to the MMC is usually only possible through Terminal Server.

  • The console displays only unhandled exceptions (suspended service instances). If the developer handles the exception in the orchestration, allowing the orchestration to complete normally, the exception information will never appear in the Administration Console.

The ​Microsoft BizTalk ESB Toolkit addresses these limitations through the ESB Failed Orchestration Exception Routing mechanism. This closely resembles the Failed Message Routing mechanism of BizTalk Server 2013 R2. In addition, the ​Microsoft BizTalk ESB Toolkit includes a pipeline component in a send port that subscribes to messages generated from both the ESB Failed Orchestration Exception Routing mechanism and the Failed Message Routing mechanism and normalizes them.

The ESB Exception Management Framework takes advantage of other features in BizTalk Server, such as the subscription model, and event-based Business Activity Monitoring (BAM). This means that the ESB Exception Management Framework can track the exception data points with BAM, and then publish them to the BizTalk BAM Portal for monitoring.


The Components of the Exception Management Framework

The ESB Exception Management Framework includes several core features. The following topics describe each of these features:

  • The ESB Failed Orchestration Exception Routing Mechanism

  • The ESB Fault Processor Pipeline

  • The ESB Management Portal and Fault Message Viewer

  • The InfoPath Message Template


The ESB Failed Orchestration Exception Routing Mechanism

The ESB Failed Orchestration Exception Routing mechanism provides the following features:

  • Creating fault messages that capture ambient properties. The CreateFaultMessage method generates a fault message that contains the orchestration service name and service instance ID, the currently activated orchestration shape, the name of the application to which the orchestration is deployed, the name of the server processing the orchestration, and the exception date and time (UTC format). It also implicitly adds the current System.Exception object generated in the exception handler of the current orchestration shape.

  • Adding existing orchestration messages to a fault message. The AddMessage method preserves the XLANG setting of the orchestration message and all the message context properties in the fault message.

  • Explicitly adding an existing Exception object to a fault message. The SetFaultMsgException method serializes the object as a System.Exception and preserves it in the fault message.

  • Retrieving an enumerated collection of type-less messages from a fault message received by a subscriber. The GetMessages method retrieves all persisted messages from the failed orchestration as XLANG messages. It returns all the original context properties of each persisted message in each XLANG message.

  • Retrieving a strongly typed XLANG orchestration message from a fault message received by a subscriber. The GetMessage method retrieves a persisted message of a specific type from the fault message as an XLANG message. It returns all the original context properties of the persisted message in the XLANG message. It also supports retrieval of the System.Exception object generated by the failed orchestration and retrieves a persisted System.Exception object from the fault message.


The ESB Fault Processor Pipeline

The ​Microsoft BizTalk ESB Toolkit installs a send port named ALL.Exceptions that uses the ESBFaultProcessor send pipeline. Figure 1 shows the properties of the ALL.Exceptions send port.

All Exceptions Send Port

Figure 1

The configuration of the ALL.Exceptions send port, including its use of the ESBFaultProcessor pipeline

The ESBFaultProcessor pipeline contains the following pipeline components: ESB Exception Encoder, ESB Business Activity Monitoring (BAM) Tracker, and ESB Transform.

The ALL.Exceptions send port subscribes to all ESB fault messages and to all messages generated by the BizTalk Failed Message Routing mechanism. Figure 2 shows the filter property settings of the ALL.Exceptions send port.

Filter Send Port

Figure 2

The filter property of the ALL.Exceptions send port defines the port subscription

The Fault Processor Pipeline Exception Encoder Component

The ESB Exception Encoder pipeline component normalizes fault messages generated in the ESB Failed Orchestration Exception Routing mechanism and the BizTalk Failed Message Routing mechanism into canonical messages that comply with the ESB Exception Reporting schema.

For a Failed Orchestration Exception Routing exception, the component enriches and serializes all fault message properties, XLANG messages, context properties, and System.Exception information into an XML message.

For a Failed Message Routing exception, the component enriches the data by adding the application name and other ambient properties, and it applies the schema namespace to the outbound XML message content.

Optionally, the ESB Exception Encoder pipeline component can also apply Microsoft InfoPath processing instructions to the outbound message. You can modify the InfoPath instructions by setting the properties of the pipeline component in design view. The following three design time properties affect the run-time behavior of the ESB Exception Encoder pipeline component:

  • EscapeCDATA. This property determines whether the component will escape any CDATA sections found in persisted messages so that InfoPath can display them correctly.

  • FaultDocumentNamespace. This property has a default value of http://schemas.microsoft.biztalk.practices.esb.com/exceptionhandling. This can be modified to use a custom outbound namespace for the persisted messages.

  • ProcessingInstruction. This property can contain any InfoPath processing instruction that complies with the ESB Exception Reporting fault schema. The ​Microsoft BizTalk ESB Toolkit includes an InfoPath template that conforms to the following processing instruction.

    Copy Code
    <?mso-infoPathSolution solutionVersion="1.0.0.346" productVersion="11.0.6565"
PIVersion="1.0.0.0"
href=file:///\\localhost\publish\Microsoft.Practices.ESB.ExceptionHandling.InfoPath.Reporting.xsn
name="urn:schemas-microsoft-com:office:infopath:
Microsoft-Practices-ESB-ExceptionHandling-InfoPath-Reporting:
http---schemas-microsoft-biztalk-practices-esb-com-exceptionhandling"
language="en-us" ?><?mso-application progid="InfoPath.Document"?>

The Fault Processor Pipeline BAM Tracker Component

The ESB BAM Tracker pipeline component receives the message from the ESB Exception Encoder component and writes selected fault data to the BAM primary import tables created during the installation of the ESB Exception Management Framework.

The ESB BAM Tracker component uses the GetEventStream method of the pipeline context to add the following fields as an activity record to the BAM Primary Import database:

  • Application

  • Description

  • FaultSeverity

  • ServiceName

  • ErrorType

  • FaultCode

  • MachineName

  • MessageID

  • DateTime

  • FaultDescription

  • Scope

  • FailureCategory

  • FaultGenerator

  • ServiceInstanceID

The ESB BAM Tracker component uses the message identifier (the MessageID property) value of the ESB fault message as the BAM activity ID. The ESB BAM Tracker component exposes two design time properties that you can set to change its run-time behavior:

  • Enabled. This property determines whether the component will process the message and write it to the BAM database. When set to False, the component just sends the message to the next component in the pipeline.

  • FaultDocumentNamespace. This property has a default value of http://schemas.microsoft.biztalk.practices.esb.com/exceptionhandling.

The Fault Processor Pipeline Transform Component

The ESB Fault Processor pipeline uses the ESB Transform pipeline component to execute a BizTalk map that translates the encoded ESB fault message into a format that matches the schema for the BizTalk SQL Adapter (ExceptionSql.xsd). The component then passes the transformed message to the SQL Adapter, which inserts the ESB fault message into the ESB Management Portal database.

The ESB Transform pipeline component exposes three design-time properties that can be modified to change its run-time behavior:

  • Enabled. This property enables or disables the component.

  • Validate. This property specifies whether a message needs to be validated.

  • MapName. This property contains the name of the map that must be executed to translate the message for storage in the ESB Management Portal database. The following is the default value.

    Copy Code
    Microsoft.Practices.ESB.ExceptionHandling.Maps.FaultMessage_to_ExceptionSql,
Microsoft.Practices.ESB.ExceptionHandling.Maps,
Version=2.0.0.0,
Culture=neutral,
PublicKeyToken=c2c8b2b87f54180a

After all the pipeline components finish executing, the BizTalk SQL Server database adapter inserts the fault message into the ESB Management Portal database.


The ESB Management Portal and Fault Message Viewer

A major component of the ​Microsoft BizTalk ESB Toolkit is a Web-based portal that provides a wide range of exception management and alert notification features; in addition, it acts as a useful configuration management and Universal Description, Discovery, and Integration (UDDI) registration interface. Figure 1 shows the home page of the portal, which provides an overview of the health of the currently running applications.

Portal Home Page

Figure 1

The home page of the ESB Management Portal

Users can select a fault message displayed in the ESB Management Portal to view the ambient and static properties of the fault and a list of the original messages contained in the fault message, as shown in Figure 2.

Faul tViewer Page

Figure 2

The ESB Fault Viewer page of the ESB Management Portal

ESB Fault messages displayed in the ESB Management Portal may be the result of an error in the values of the original message when submitted for processing. The ​Microsoft BizTalk ESB Toolkit supports "repair and resubmit" functionality, which allows administrators or users to edit failed messages and to submit them to an on-ramp for processing.

Selecting one of the contained messages opens the Message View page in Message Details view, as shown in Figure 3. In this view, users can see the message content, download the message, or click Edit to switch to Edit view, where they can repair and resubmit the message.

Message Viewer Page

Figure 3

The ESB Message Viewer showing the Fault Details view

For a complete description and usage options of the ESB Management Portal, including the Fault Viewer, the message resubmission process, and the techniques used for listing, sorting, and analyzing faults, see Administration with the BizTalk ESB Toolkit.


The InfoPath Message Template

As an alternative to viewing ESB fault messages in the ESB Management Portal, users can take advantage of a Microsoft InfoPath message template named the ESB Exception Message Viewer, provided with the ​Microsoft BizTalk ESB Toolkit.

The ESB Exception Management Framework can persist messages in a serialized format that, together with the ESB Exception Message Viewer template, will display several views of the fault message and the original messages it contains. The ESB Exception Message Viewer provides the following views:

  • General view

  • Exception Object view

  • Messages view

Figure 1 shows the General view of the ESB Exception Message Viewer, which displays most ambient properties of the exception.

Exception Message General View

Figure 1

The ESB Exception Message Viewer showing the General view

Figure 2 shows the Exception Object view, which displays the properties and the stack trace from the System.Exception object.

Exception Message Exception Object

Figure 2

The ESB Exception Message Viewer showing the Exception Object view

Figure 3 shows the Messages view, which provides a drop-down list from which the user can select from available persisted messages. The view displays the values of the context properties of the persisted message and the XML message content.

Exception Message Messages View

Figure 3

The ESB Exception Message Viewer showing the Messages view


Using the Exception Management Framework

The ​Microsoft BizTalk ESB Toolkit uses exceptions to communicate failures (for example, a non-deployed map or rules that do not return a map name) for dynamic transformations and routing. When a transformation or routing process fails, the ESB creates an exception message and submits it through a direct-bound port to the Message Box database. The ESB also implements a send port named ALL.Exceptions that subscribes to and retrieves exception messages and publishes them to the ESB Management Portal.

In addition, all orchestration samples use the ESB Failed Orchestration Exception Routing API to handle exceptions. You can use this API in any orchestration project you deploy. The ESB Failed Orchestration Exception Routing feature provides a standard way to trap and report all exceptions in a BizTalk Server environment.

The ​Microsoft BizTalk ESB Toolkit contains several sample projects that demonstrate how to use the ESB Exception Management Framework. The following two projects encapsulate the ESB Failed Orchestration Exception Routing API:

  • ESB.ExceptionHandling. This project contains all the public methods for handling fault message processing in orchestrations. You must register the assembly in this project in the global assembly cache on the local server.

  • ESB.ExceptionHandling.Schemas.Faults. This project contains the fault message schema defined by the namespace http://schemas.microsoft.biztalk.practices.esb.com/exceptionhandling and the system property schema. You must deploy this project to the Microsoft.Practices.ESB application container.

All projects that use the ESB Failed Orchestration Exception Routing API must reference the core assemblies:

  • Microsoft.Practices.ESB.ExceptionHandling.dll

  • Microsoft.Practices.ESB.ExceptionHandling.Schemas.Faults.dll

The following sections provide more information about using the ESB Exception Management Framework:

  • The ESB Exception API Members

  • Creating and Publishing Fault Messages

  • Subscribing to and Extracting Messages

  • Scenario Solution Steps


The ESB Exception API Members

The ESB.ExceptionHandling assembly exposes public methods to create fault messages and to manage and retrieve them for processing, as described in the following table.

Member and use case Description

CreateFaultMessage [Exception handler scope]

public static XLANGMessage CreateFaultMessage() Takes no parameters. Returns an instance of the ESB fault message as an XLANGMessage instance populated with the current orchestration name, orchestration instance ID (a GUID), System.Exception instance, and other ambient properties.

Note
This Application Programming Interface (API) needs to be called only from an exception block within the XLANG.

AddMessage [Exception handler scope]

public static void AddMessage(faultMessage, existingMessage) Takes as parameters two XLANGMessage instances; the first is a newly-created ESB fault message, and the second is any existing message instance in the orchestration. The method persists the existing message instance and its message context properties into the fault message and makes it available for retrieval using the GetMessage method. No return value.

SetException [Exception handler scope]

public static void SetException(faultMessage, exception) Takes as parameters an ESB fault message as an XLANGMessage instance and Exception as an Object instance. The method persists the exception into the existing fault message and makes it available for retrieval using the GetException method. No return value.

GetMessage [Subscriber/processor]

public static XLANGMessage GetMessage(faultMessage, messageName) Takes as parameters an ESB fault message received from a subscription as an XLANGMessage instance and the (String) name of the message previously added to the fault message (in the exception handler of the originating orchestration shape). Returns an XLANGMessage instance that matches the message name and that contains all the original context properties, including any custom promoted properties.

GetMessages [Subscriber/processor]

public static MessageCollection GetMessages(faultMessage) Takes as the single parameter an ESB fault message received from a subscription as an XLANGMessage instance. Returns a MessageCollection instance populated with all the XLANGMessage instances previously added to the fault message (in the exception handler of the originating orchestration shape). Each XLANGMessage instance contains all the original context properties, including any custom promoted properties.

GetException [Subscriber/processor]

public static System.Exception GetException(faultMessage) Takes as the single parameter a fault message received from a subscription as an XLANGMessage instance. Returns the System.Exception object previously added to the fault message (in the exception handler of the originating orchestration shape).

FaultSeverity [Exception handler scope and subscriber/processor]

Public read/write property of the ESB fault message XLANGMessage class that exposes the severity of a fault message. A value from the FaultCodes enumeration: Information (0), Warning (1), Error (2), Severe (3), or Critical (4).

MessageCollection [Subscriber/processor]

A collection of the messages returned by the GetMessages method. This class derives from ArrayList and implements an enumerator to allow iteration using the MoveNext method.


Creating and Publishing Fault Messages

To help you understand how to use the features of the Exception Management Framework to manage exceptions, this section presents a common scenario based on the submission of a message to an ESB application.

The scenario consists of a user submitting an invoice to the system. During the course of processing the invoice in an orchestration, the BizTalk Business Rules Engine throws an application exception because some part of the data is incorrect. The business process should catch the exception, send the offending message to another person or system that can correct the message, and then resubmit the message for processing.

When using the ESB Failed Orchestration Exception Routing feature, the process steps are the following:

  1. Code in the exception handler detects the error and creates a fault message by calling the CreateFaultMessage method, as shown in the following code example.

    C# Copy Code
    // Create fault exception message.
faultMsg = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.CreateFaultMessage();
  2. The ESB Exception mechanism automatically inserts the error description into the fault message context (for example, "The Business Rules Engine threw a divide by zero error while processing the LoanProcessing policy.").

  3. The ESB Exception mechanism automatically promotes failure-specific properties and application-specific properties into the fault message context and sets the values from the current environment. These properties are the following:

    • Application (auto-populated)

    • DateTime (auto-populated as a UTC value)

    • Description (auto-populated—the exception message)

    • ErrorType (auto-populated—the exception type)

    • MachineName (auto-populated—the current server name)

    • Scope (auto-populated—the Scope shape that contains the current exception handler)

    • ServiceName (auto-populated—the orchestration name)

    • ServiceInstanceID(auto-populated—the orchestration instance ID as a GUID)

  4. Code in the exception handler sets other properties of the fault message as required, as shown in the following code example.

    C# Copy Code
    // Set fault message properties.
faultMsg.Body.FailureCategory = "MessageBuild";
faultMsg.Body.FaultCode = 1000;
faultMsg.Body.FaultDescription = "Some error occurred";
faultMsg.Body.FaultSeverity =
   Microsoft.Practices.ESB.ExceptionHandling.FaultSeverity.Severe;
  5. The ESB Exception mechanism automatically serializes the current Exception object into the fault message.

  6. Optionally, code in the exception handler can add current orchestration messages to the ESB fault message using the AddMessage(faultMsg, messageToAdd) method. This method serializes and persists the message, including all the context properties, as shown in the following code example.

    C# Copy Code
    // Add other current orchestration messages to the fault message.
Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.AddMessage(
                            faultMsg, approvedRequestMsg);
Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.AddMessage(
                            faultMsg, DeniedRequestMsg, @"c:\temp");
  7. Code in the exception handler publishes the ESB fault message to the Message Box database using a direct bound port.

  8. If publishing succeeds, the following events occur:

    • Orchestration or send port subscriptions can process the ESB fault message and extract any added messages, complete with their context property values.

    • A global exception handler (a send port) automatically publishes the ESB fault message to the ESB Management Portal.


Subscribing to and Extracting Messages

Orchestration can contain code to subscribe to and extract messages from an ESB fault message. For example, the following code uses the GetMessage and GetException methods to extract two strongly typed messages and the System.Exception object from an ESB fault message.

C# Copy Code
// Retrieve two messages from the fault message.
requestMsg = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.GetMessage(
                                    faultMsg, "ApprovedRequest");
deniedMsg = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.GetMessage(
                                    faultMsg, "DeniedRequest");

// Retrieve the System.Exception object.
newExc = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.GetException(
                                    faultMsg);

To extract type-less messages, the following code uses the GetMessages method to extract all the messages and then iterate through them.

C# Copy Code
Microsoft.Practices.ESB.ExceptionHandling.MessageCollection msgs;
msgs = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.GetMessages(faultMsg);
System.Xml.XmlDocument tmpMsg;
while (msgs.MoveNext())
{
  tmpMsg = msgs.Current;
}


Scenario Solution Steps

The ESB Exception Management Framework provides a simple solution for handling an exception when an invoice message contains invalid data that causes an error during processing, as described earlier in this topic. The following is one approach you could take:

  1. Assign responsibility for the recently deployed Financial Reporting application based on Microsoft BizTalk to a developer on your team.

  2. A new ESB fault message arrives in the ESB Management Portal; the message indicates a data integrity issue in an orchestration in the Financial Reporting BizTalk application.

  3. The administrator or operator notifies the developer of the new exception, or the developer registers for automatic notification when an exception occurs. This notification may occur for one of the following reasons:

    • It may occur because the exception exceeded a threshold predefined in event-based Business Activity Monitoring (BAM).

    • It may occur because a BizTalk subscription exists for the specific application, service, scope, and fault code that forwards the exception to the developer.

  4. The developer examines the fault message, the individual orchestration messages, and their persisted context property values. Developers can view this information through the ESB Management Portal or by using Microsoft Outlook through a BizTalk subscription.

  5. The developer determines that this is a common error. It will require manual intervention and correction by the Finance team, followed by resubmission to the system.

  6. The developer creates and deploys an independent BizTalk orchestration project that subscribes to the specific application and exception type.

  7. The orchestration project retrieves the invalid message from the ESB fault message, sends the message to the Finance team for correction, correlates the corrected message back to the orchestration, and resubmits it.

  8. A week later, the developer navigates to the ESB Management Portal to discover that application exception trends for invalid messages have decreased dramatically since this solution was deployed.


Creating Custom Exception Handlers

For an application to detect and react to exceptions, developers must provide an exception handler. This exception handler can subscribe to a single type of exception message or to exception messages generated from some or all parts of a system or an application. For example, you may require only a single handler for all messages from a particular system (such as any exceptions occurring in the payroll system), or you may instead require targeted handlers for specific failures (such as detecting if the check print process fails).

To subscribe to a specific type of exception, use an orchestration that has a filter on the activating Receive shape, as shown in the following example.

C# Copy Code
Microsoft.Practices.ESB.ExceptionHandling.Schemas.Property.FaultCode == "1000";

You may also have a filter condition on a send port that sends a message to the file system or via e-mail if the message meets a specific filter condition.

Sample Exception Handling Projects

The ​Microsoft BizTalk ESB Toolkit includes several sample BizTalk applications that demonstrate exception handling. These samples can be found in the \Source\Samples\Exception Handling folder.

There are also four BizTalk projects, located in the GlobalBank.ESB.Samples.ExceptionHandling solution, that demonstrate how to use the ESB Failed Orchestration Exception Routing mechanism. These projects are preconfigured to deploy into the GlobalBank.ESB BizTalk application. The projects are the following:

  • ESB.ExceptionHandling.Schemas. This project contains the schemas used for the sample orchestrations.

  • ESB.ExceptionHandling.Pipelines. This project contains the send pipeline configured with the exception processor, used in a send port that subscribes to all exceptions. This includes exceptions generated by BizTalk and exceptions generated by the Exception Management Framework.

  • ESB.ExceptionHandling.Processes. This project contains the EAIProcess.odx orchestration, which simulates an exception by attempting to divide by zero and calls the CreateFaultMessage and AddMessage methods to generate a suitable fault message, as shown in Figure 1.

    Orchestration Processes Sample

    Figure 1

The EAIProcess.odx orchestration in the Processes sample project

  • ESB.ExceptionHandling.Handlers. This project contains the EAIGenericHandler.odx orchestration, which calls the GetMessages method and iterates through the MessageCollection using the MoveNext method, as shown in Figure 2.

Orchestration Handlers Sample Generic

Figure 2

The EAIGenericHandler.odx orchestration in the Handlers sample project

The ESB.ExceptionHandling.Handlers project also contains the EAIProcessHandler.odx orchestration, which calls the GetMessage and GetException methods, as shown in Figure 3.

Orchestration Handlers Sample Process

Figure 3

The EAIProcessHandler.odx orchestration in the Handlers sample project


Using the BizTalk ESB Toolkit Web Services

The ​Microsoft BizTalk ESB Toolkit exposes all its core features as Web services; this enables entities outside of the ESB, perhaps running on non-Microsoft platforms, to participate in ESB exchanges and take advantage of the ESB capabilities. All the Web services are located in separate subfolders of the \Web folder of the ESB installation directory. The ​Microsoft BizTalk ESB Toolkit includes the following ESB Web services:

  • The Itinerary On-Ramp Web Services

  • The Resolver Web Service

  • The Transformation Web Service

  • The Exception Handling Web Service

  • The BizTalk Operations Web Service


The Itinerary On-Ramp Web Services

The Itinerary Web service is an itinerary on-ramp that exposes a method that allows clients to submit messages for processing by the Itinerary Service and then onward to the target Microsoft BizTalk or ESB operations.

The Itinerary Web service passes the payload to the ESB Itinerary pipeline components, which validates the itinerary to verify that these services are defined in the ​Microsoft BizTalk ESB Toolkit configuration. Then the component adds special context properties to the message containing the validated itinerary.

In the case of a generic itinerary on-ramp, a SOAP header containing an itinerary is not provided during message submission. Accordingly, the ESB Itinerary Selector pipeline component is used in place of the ESB Itinerary pipeline component. The ESB Itinerary Selector pipeline component resolves the itinerary based on a pre-defined resolver connection string, and it provides the same validation that the ESB Itinerary pipeline component provides.

The ​Microsoft BizTalk ESB Toolkit includes two variations of the Itinerary service to support both one-way and request-response message-exchange patterns. The ​Microsoft BizTalk ESB Toolkit contains an ASP.NET (ASMX) and a Windows Communication Foundation (WCF) version of both of these services, and it provides generic versions of the WCF services.

The names of the provided one-way itinerary services are ESB.ItineraryService, ESB.ItineraryServices.WCF, and ESB.ItineraryServices.Generic.WCF.

The names of the provided two-way itinerary services are ESB.ItineraryServices.Response, ESB.ItineraryServices.Response.WCF, and ESB.ItineraryServices.Generic.Response.WCF.

Each of the Itinerary Web services exposes the following methods:

  • SubmitRequest. For the ASMX-based service, this method takes an instance of the XmlNode class that contains the message to submit. For the WCF-based service, this method takes an XML string that contains the message to submit.

  • SubmitRequestResponse. For the ASMX-based service, this method takes a reference to an instance of the XmlNode class that contains the message to submit and returns the response message in the instance of the XmlNode passed to it. For the WCF-based service, this method takes a reference to an Object type that is an XML string that contains the message to submit and returns an array of XmlNodes in the Object that was passed to it.

For more information about using the Itinerary Web services, see Installing and Running the Itinerary On-Ramp Sample.

Note
By default, the Itinerary Web services are not configured to require Secure Sockets Layer (SSL) when accessed by clients. You should configure the service to require SSL for client access and protect the connection between the Internet Information Services (IIS) Web service host computer and the server that hosts the ESBExceptions database using a network-level IPSec and appropriate file-level access control list (ACL) permissions.


The Resolver Web Service

The Resolver Web service is a gateway into the ESB dynamic resolution mechanism. ​Microsoft BizTalk ESB Toolkit includes two versions of this service: an ASP.NET (ASMX) version and a Windows Communication Foundation (WCF) version. The service names are ESB.ResolverServices and ESB.ResolverServices.WCF, respectively, and the services expose the following methods:

  • Resolve. This method takes as its single parameter a String that contains the resolver connection string for the request, which conforms to the standard connection strings for registered resolvers such as STATIC, BRE, UDDI, XPATH, ITINERARY, ITINERARY-STATIC, BRI, or LDAP.

  • ResolveMessage. This method takes as its first parameter a String that contains the resolver connection string for the request, which conforms to the standard connection strings for registered resolvers such as STATIC, BRE, UDDI, XPATH, ITINERARY, ITINERARY-STATIC, BRI, or LDAP. In addition, the method accepts an optional second parameter as a String that contains an XML message document that the service can use as optional facts to assist in a resolution; for example, the BRE resolver may require a message body that encapsulates facts.

For more information about the Resolver and ResolverDictionary classes and their usage, see Using the Helper Classes.

Resolver Connection Strings

The ESB dynamic resolution mechanism uses a connection string preceded by a moniker that indicates the type of resolution to perform. The supported monikers include STATIC, BRE, UDDI, UDDI3, XPATH, ITINERARY, ITINERARY-STATIC, BRI, and LDAP. The following connection string shows an example of a UDDI moniker:

Copy Code
//UDDI
UDDI:\\serverUrl=http://localhost/uddi;serviceName=PurchaseOrder;serviceProvider=Microsoft.Practices.ESB

For information about the types of connections strings supported by the dynamic resolution mechanism, see Using Dynamic Resolution and Routing.

Note
You must configure this service to use either Windows Integrated Security and to run under the built-in NETWORK SERVICE account.

By default, the Resolver Web services are not configured to require Secure Sockets Layer (SSL) when accessed by clients. You should configure the service so that it requires SSL for client access and protect the connection between the Internet Information Services (IIS) Web service host computer and your BizTalk Server using network-level IPSec and appropriate file-level access control list (ACL) permissions. To avoid security risks, it is not recommended to expose this service outside the boundary of the trusted subsystem.


The Transformation Web Service

The Transformation Web service enables external applications to submit a document to an ESB application and have it transformed using a deployed Microsoft BizTalk map. Unlike the transformation agent, this service does not route messages through the BizTalk Message Box database.

The ​Microsoft BizTalk ESB Toolkit contains two versions of this service: an ASP.NET (ASMX) version and a Windows Communication Foundation (WCF) version. The service names are ESB.TransformServices and ESB.TransformServices.WCF, respectively, and the services expose a single method:

  • Transform. This method takes as parameters a String that contains the message to transform and a String that contains the fully qualified name of a map deployed in BizTalk. The method returns a String that contains the transformed document. The use of string parameters reduces the risk of interoperability issues in a heterogeneous environment; however, keep in mind that this is a Web service, so you should avoid using it to transform large documents (the Transformation Service in BizTalk is better suited for large documents).

Note
By default, the Transformation Web services are not configured to require Secure Sockets Layer (SSL) when accessed by clients. You should configure the service so that it requires SSL for client access and protect the connection between the Internet Information Services (IIS) Web service host computer and your BizTalk Server using network-level IPSec and appropriate file-level access control list (ACL) permissions.


The Exception Handling Web Service

The Exception Handling Web service accepts a fault message and publishes it to the ESB Exception Portal. A client application can create exception messages and submit them to the ESB, where any handler configured for that exception type, or a generic handler, can process the exception. The major benefit of this service is that it allows entities outside an ESB application to participate in the ESB exception handling mechanism.

The ​Microsoft BizTalk ESB Toolkit contains two versions of this service: an ASP.NET (ASMX) version and a Windows Communication Foundation (WCF) version. The service names are ESB.ExceptionHandlingServices and ESB.ExceptionHandlingServices.WCF, respectively, and the services expose a single method:

  • SubmitFault. This method takes an instance of the FaultMessage class and has no return value.

For information about the way the exception handling mechanism works, see Using ESB Exception Management.

Note
By default, the Exception Handling Web services are not configured to require Secure Sockets Layer (SSL) when accessed by clients. You should configure the service so that it requires SSL for client access and protect the connection between the Internet Information Services (IIS) Web service host computer and the server that hosts the ESBExceptions database using network-level IPSec and appropriate file-level access control list (ACL) permissions.


The BizTalk Operations Web Service

The Microsoft BizTalk Operations Web service exposes information about the objects and messages in BizTalk Server. The service name is ESB.BizTalkOperationsService, and the service exposes a wide range of methods that return items such as a list of hosts, orchestrations, applications, and the BizTalk application status.

The following methods are available:

  • Applications. This method takes no parameters, and it returns the name and description of all installed BizTalk applications as a collection of BTApplication objects.

  • ApplicationStatus. This method takes as a parameter the application name, and it returns information about the specified BizTalk application as a BTSysStatus instance. This information includes orchestrations, send ports, receive locations, and host details.

  • GetLiveMessageBody. This method takes as parameters a message ID and an instance ID, and it returns the body of that message from the live environment as a BTMsgBody instance.

  • GetMessageInstances. This method takes as a parameter the message type, and it returns all matching messages as a collection of BTMsgInstance objects.

  • GetOrchestrationInstances. This method takes as parameters the name of an orchestration, and it returns a collection of BTOrchestrationInstance object that contain details of the matching orchestrations.

  • GetTrackedMessageBody. This method takes as a parameter a message GUID, and it returns the body of that message as a BTMsgBody instance after it is processed in BizTalk.

  • Hosts. This method takes as a parameter the name of a host, and it returns information about the specified host instance as a collection of BTHost instances. Use an empty string for the host name parameter to return information about all host instances.

  • MessageFlowTree. This method takes as a parameter an instance ID, and it returns details of the message flow for that message as a RouteTreeNode instance.

  • Orchestrations. This method takes as a parameter the name of an orchestration, and it returns all the information for that orchestration as a BTSysStatus instance. Use an empty string for the orchestration name parameter to return information about all orchestrations.

  • ReceiveLocations. This method takes as a parameter the name of a receive location, and it returns all the information for matching locations as a BTSysStatus instance. Use an empty string for the receive locations name parameter to return information about all locations.

  • ReceiveLocationsByDescription. This method takes as a parameter the description of a receive location, and it returns all the information for matching locations as a BTSysStatus instance. Use an empty string for the description parameter to return information about all locations.

  • SendPorts. This method takes as a parameter the name of a send port, and it returns all the information for matching ports as a BTSysStatus instance. Use an empty string for the send port name parameter to return information about all ports.

  • SendPortsByDescription. This method takes as a parameter the description of a send port, and it returns all the information for matching ports as a BTSysStatus instance. Use an empty string for the description parameter to return information about all ports.

  • StatusChanged. This method takes as a parameter a timestamp, and it returns details of BizTalk objects (such as ports, hosts, and orchestrations) modified since the specified timestamp as a BTSysStatus instance.

  • SystemStatus. This method takes no parameters, and it returns full details of the BizTalk system status as a BTSysStatus instance.

  • UpdateReceiveLocationDescription. This method updates the description of a specified receive location using parameter values that contain the application name, the receive port name, the receive location name, and the receive location description. It returns a String that indicates the result of the operation. Note that the test client application reads this information from its App.config file.

  • UpdateSendPortDescription. This method updates the description of a specified send port using parameter values that contain the send port name and the send port description. It returns a String that indicates the result of the operation. Note that the test client application reads this information from its App.config file.

Configuring the BizTalk Operations Web Service

The BizTalk Operations Web service either communicates directly with the BizTalk Server management databases using Windows Management Instrumentation (WMI) or it uses the BizTalk Operations and Explorer API to obtain the information it requires. Therefore, you must make sure that your system meets the following conditions and that you configure the following security permission settings:

  • Set the allowOverride attribute in the machine-level Web.config file to false to make sure developers cannot change the trust level of their applications.

  • By default, the BizTalk Operations Web service is not configured to require Secure Sockets Layer (SSL) when accessed by clients. You should configure the service so that it requires SSL for client access, and protect the connection between the Internet Information Services (IIS) Web service host computer and the computer running SQL Server that hosts the BizTalkMgmtDb database using network-level IPSec and appropriate file-level access control list (ACL) permissions.

  • Users accessing the BizTalk Operations Web service must be members of the default BizTalk Server Administrators group for some methods and members of the default BizTalk Application Users group for other methods.

  • You must make sure that the BizTalk Operations Web service resides in an IIS virtual directory named ESB.BizTalkOperationsService that has anonymous access disabled.

  • Users must have SELECT permission in SQL Server for several tables located in the BizTalkMgmtDb database and the BizTalkMsgBoxDb database. Use SQL Server Management Studio to set the following permissions:

    • In the BizTalkMgmtDb database, configure the BTS_ADMIN_USERS database role with SELECT permission on the following tables:

      • adm_Server2HostMapping

      • adm_Server

      • adm_hostInstance

    • In the BizTalkMsgBoxDb database, configure the BTS_ADMIN_USER database role with SELECT permission on the ProcessHeartbeats table.

In SQL Server Management Studio, you can configure the required permissions. To do this, expand Security in the left pane tree view of Object Explorer, expand Roles, expand DatabaseRoles, select the BTS_ADMIN_USERS role, and then edit the properties for this role, as shown in Figure 1.

SQL Server Mgmt Studio

Figure 1

Editing permissions for the BTS_ADMIN_USERS database role in Microsoft SQL Server Management Studio

Note
You must configure this service to use Windows Integrated Security and run under the built-in NETWORK SERVICE account. You must also enable Kerberos authentication on your IIS Web server so that it sends the header Negotiate,NTLM to the client. For more information, see How to configure IIS to support both the Kerberos protocol and the NTLM protocol for network authentication(http://go.microsoft.com/fwlink/?LinkId=186430).

By default, the BizTalk Operations Web service is not configured to require SSL when accessed by clients. You should configure the service so that it requires SSL for client access and protect the connection between the IIS Web service host computer and the server that hosts the UDDI service using network-level IPSec and appropriate file-level ACL permissions.


Using the Pipeline Support Components

The ​Microsoft BizTalk ESB Toolkit includes the following pipeline components:

  • ESB Itinerary Selector. You can use this component on the receive side (in a receive pipeline) to select a server-side itinerary for a message to follow. For more information, see The ESB Itinerary Selector Component.

  • ESB Itinerary. You can use this component on the receive side (in a receive pipeline) to promote ESB metadata properties from SOAP headers into the message context. For more information, see The ESB Itinerary Component.

  • ESB Itinerary Forwarder. For more information, see The ESB Itinerary Forwarder Component.

  • ESB Itinerary Cache. You can use this component to cache itineraries and reapply them to response messages received in Solicit-Response send ports. For more information, see The ESB Itinerary Component.

  • ESB JMS Decoder. You can use this component on the receive side (in a receive location) of an orchestration or a send port to parse out IBM JMS (MQRFH2) headers and preserve them as context properties. You can then access these context properties and modify them in the same way as any other BizTalk context properties. For more information, see The ESB JMS Encoder and Decoder Components.

  • ESB JMS Encoder. You can use this component in a send port to write IBM JMS (MQRFH2) headers to messages. For more information, see The ESB JMS Encoder and Decoder Components.

  • ESB Add Namespace. You can use this component in either a receive location or a send port to add namespaces to XML documents. For more information, see The ESB Add Namespace and Remove Namespace Components.

  • ESB Remove Namespace. You can use this component in either a receive location or a send port to remove namespaces from XML documents. For more information, see The ESB Add Namespace and Remove Namespace Components.

  • ESB Exception Encoder. You can use this component to send fault messages to the file system, Microsoft InfoPath, or Microsoft SharePoint. This component is part of the ESB exception handling mechanism, and it normalizes and enriches all exceptions processed by a send port. The component serializes exception information (including embedded persisted messages and context properties) into a canonical format so that all contained messages and the exception itself are available.

  • ESB Transform. You can use this component to transform message from one format to another by specifying BizTalk map.

  • ESB BAM Tracker. You can use this component to intercept the fault message emitted from the ESB Exception Encoder and insert the data in the message into the BAM Primary Import table (using the BAM Event Stream in the pipeline). This component is part of the ESB exception handling mechanism.

  • ESB Dispatcher. You can use this component in a receive location (inbound pipeline) to dynamically set endpoint location properties for outbound messages. You can also use this component in the send pipeline to execute itinerary messaging services. For more information, see The ESB Dispatcher Component.

  • ESB Dispatcher Disassemble. You can use this component in a receive location (inbound pipeline) to dynamically set endpoint location properties for outbound messages. The behavior of this component is similar to the ESB Dispatcher component, except that it transforms the result message (if you specify a value for the MapName property). The message passes through the XML Disassembler, which promotes properties and message types. The ESB Dispatcher Disassemble component also supports batched dispatch of multiple messages to different endpoints. For more information, see The ESB Dispatcher Disassemble Component.


The ESB Itinerary Selector Component

The ESB Itinerary Selector component allows incoming messages that do not have the itinerary SOAP header to pass through the ESB by selecting an appropriate server-side itinerary for the message with the help of a resolver. The component is also used for messages that use a SOAP header to define the name and version of an itinerary, as requested by the client.

Installation

Installing the ESB Core automatically installs the ItinerarySelector component in the BizTalk Server Pipeline Components folder.

How It Works

The ESB Itinerary Selector component is a Microsoft BizTalk pipeline component that can reside only in a receive pipeline. The component selects a server-side itinerary for use in processing a message. As the message passes through the component in a receive pipeline, the component reads its configuration and uses the ResolverConnectionString property to call the correct resolver to look up the appropriate itinerary to use when processing the message. The Itinerary Selector component then performs the same steps as the Itinerary pipeline component to validate the message and promote the properties necessary to ensure the message continues to the next processing stage.

Using the ESB Itinerary Selector Component

You can add the ESB Itinerary component to a receive pipeline and then use the pipeline in a receive location. When this component is configured with the ITINERARY-STATIC resolver in WCF on-ramp, the name and version of the itinerary requested by the client (as represented in the SOAP header) will be retrieved from the message context and used to select the appropriate itinerary.

Component Properties

The ESB Itinerary Selector component exposes three public properties:

  • IgnoreErrorKey. This property defines whether, if an error is returned by the resolver, the message should be processed without the itinerary (when set to True) or suspended.

  • ItineraryFactKey. This represents the key in the dictionary returned by the resolver that contains the actual XML of the Itinerary selected. Generally, Resolver.Itinerary, unless a custom resolver is used.

  • ResolverConnectionString. This is a resolver connection string that contains name-value pairs that a resolver can use to select and/or look-up an itinerary.


The ESB Itinerary Component

The ESB Itinerary component sets the context properties from the SOAP header sent along with the message to an ESB itinerary on-ramp.

Installation

Installing the ESB Core automatically installs the Itinerary pipeline component in the BizTalk Server Pipeline Components folder.

How It Works

The ESB Itinerary component is a Microsoft BizTalk pipeline component that can reside only in a receive pipeline. It promotes values from either SOAP message headers or component settings into the message context as properties. You can find an example of promoting SOAP headers in the Itinerary On-Ramp Web services provided with ​Microsoft BizTalk ESB Toolkit. These Web services expose SOAP headers as part of their contracts, and client applications must set the headers. As the message passes through the component in a receive pipeline, the component reads the SOAP header values and promotes (writes) them to the message context properties.

Using the ESB Itinerary Component

You can add the ESB Itinerary component to a receive pipeline and then use the pipeline in a receive location. The component automatically promotes SOAP header values or component settings into the context properties of the incoming message.

For an example of how to use this component, see Installing and Running the Itinerary On-Ramp Sample.


The ESB Itinerary Forwarder Component

The ESB Itinerary Forwarder component is used when an itinerary must sequentially invoke multiple Web services. The component can be used in receive pipelines that are associated with the response side of a two-way off-ramp.

Installation

Installing the ESB Core automatically installs the Itinerary Forwarder component in the BizTalk Server Pipeline Components folder.

How It Works

When Microsoft BizTalk receives a message through a two-way receive port as the message is published to the Message Box database, an instance subscription is created. This subscription consists of the EpmRRCorrelationToken promoted property and a RouteDirectToTP promoted property. When the subscriber (orchestration or two-way send port) returns the response message, these promoted properties match the subscription and the response is immediately returned through the send pipeline of the receive port.

The ESB Itinerary Forwarder should be used in the response pipeline for a two-way off-ramp where the off-ramp is calling a request-response Web service. The component interferes with the typical BizTalk process by changing the RouteDirectToTP promoted property to False, thus ensuring that the response will not be returned to the initiating receive port. After the last step in the itinerary is reached, the RouteDirectToTP property is changed back to True, thus returning the result to the initiating on-ramp.

Using the ESB Itinerary Forwarder Component

Add the ESB ItineraryForwarder component to a receive pipeline and then use the pipeline with the response portion of a two-way off-ramp. Create an itinerary that chains multiple Web services, with or without transformation itinerary services, before or between the services. For an example of how to use the ESB Itinerary Forwarder Component, see the Installing and Running the Multiple Web Services Sample.


The ESB JMS Encoder and Decoder Components

Some integration solutions involve Java Message Service (JMS) and SOAP messages sent to or from IBM WebSphere MQ; ​Microsoft BizTalk ESB Toolkit includes two JMS pipeline components written in managed code for use in these situations. The components read or write the JMS portion of the MQ message header using the values of context properties associated with the message. Currently, there are more than 60 different types of JMS headers in use with WebSphere MQ Series systems; the ESB JMS components work only with MQRFH2 headers.

Installation

Installing the ESB Core automatically installs the JMS Encoder and JMS Decoder components in the BizTalk Server Pipeline Components folder.

How It Works

The JMS pipeline components inspect the message headers and operate only on messages that have the MQMD_Format header set to RFH (MQRFH2). However, even when this property is set, the components inspect the headers to confirm that they do conform to the IBM RFH2 format. If the header does not conform to this format, the components generate a parse error that indicates the MQMD_Format parameter was set to RFH (MQRFH2), but the structure of the header did not comply with the RFH2 standard. If inbound message header parsing fails, the decoder component allows the message to pass, but it sets a message context property named MQRFH2_ParseError to True.

The MQRFH2 property schema deployed in BizTalk with the JMS components exposes all of the MQRFH2 header properties. After demoting the headers of an incoming message, the data from the headers resides in an XML document stored in the MQRFH2_NameValueData context property of the message. The encoder adjusts the length of the NameValueData folder to ensure it is the correct length. To understand the usage of these headers, and the impact when changing the values, review the appropriate IBM documentation.

Using the JMS Encoder and Decoder Components

To use the JMS Encoder and Decoder components, developers add them to pipelines in a BizTalk application. For a send pipeline, the JMS Encoder component should reside in the Encode stage. For a receive pipeline, the JMS Decoder component should reside in the Decode stage. The JMS components will not install in any other stages of a pipeline.

When installed in the Encode stage, the JMS Encoder component reads the values in the JMS MQRFH2 headers and writes (promotes) them into the message context properties. When installed in the Decode stage, the JMS Decoder component reads (demotes) the context property values and inserts them into the JMS MQRFH2 headers. This means that all the MQ header values are available as context properties of the message in the pipeline.

To detect and manage header-parsing errors, developers can include code that examines the value of the MQRFH2_ParseError property. They can implement a recovery process that subscribes to failed messages or specify send ports that filter on the MQRFH2_ParseError property to persist the message. Subscribers that work with JMS messages should include a filter condition that specifies the value False for the MQRFH2_ParseError property to prevent the subscriber from receiving messages that failed the header parsing process.

Developers can also update the context property values (for example, change the MQRFH2_Encoding property value), and the component will reflect these changes in the MQ message headers so that they are set when the message arrives at its ultimate destination. The component automatically ignores invalid values and sets "safe" default values where required headers are missing. For example, if the developer specifies an invalid value for the MQRFH2_Encoding property, the outbound message will have the MQRFH2_Encoding header set to UNKNOWN. If the developer removes a value from a context property, but the MQMD_Format property is still set to RFH, the component will add a header containing the default value, as per the IBM specification.

For an example of how to use these components, see Installing and Running the JMS MQRFH2 Component Sample.


The ESB Add Namespace and Remove Namespace Components

Many companies were early adopters of XML technologies at the time when standards were still emerging and document sharing was uncommon. Therefore, they did not strictly enforce the requirements for including unique root namespaces, which is usually the case today.

However, Microsoft BizTalk Server performs document identification based on a combination of the root node namespace and the root node name, so documents that have no namespace for the root node are difficult to positively identify if several different document types use the same root node name.

The Add Namespace and Remove Namespace components solve this problem by making it possible to add namespaces to documents when they are received and to remove the namespace from the documents before they are delivered. Therefore, documents can reside in the default namespace (or in a namespace common to several different document types) when they are sent and received but reside in a transient unique root namespace during processing within the ESB and BizTalk.

The components are also useful when integrating legacy systems that use a Document Type Definition (DTD) instead of an XML Schema definition or that use legacy XML parsers that cannot create documents that contain a root namespace.

Installation

Installing the ESB Core automatically installs the Add Namespace and Remove Namespace components in the BizTalk Server Pipeline Components folder.

How It Works

The Add Namespace component adds a specified namespace to an XML document. The component can add only a single namespace to a document. Using the Add Namespace component on a document that already has a root node namespace is not a supported scenario because a single unique namespace is all that is required.

The components are not namespace-aware and do not persist any of the namespace values. However, the Add Namespace component compares the requested namespace in the existing namespace of the message and simply returns the original message to the pipeline if they match.

Developers include the Add Namespace component in a receive pipeline or a send pipeline and set the appropriate properties. The following validation is performed at run time:

  • The XPaths property or the NamespaceBase property must contain a value.

  • The Separator property can contain only valid characters (such as / or \) or an empty string.

  • The NamespacePrefix property value cannot be one of the reserved values (ns0 to ns6) and must be alpha numeric.

Any variation from these rules causes the component to throw an exception at run time, suspend the message (marked as Suspended – Resumable), and write an entry in Windows Application Event Log.

The Remove Namespace component removes all root namespaces from an XML document. The number of namespaces that the component can remove from a single document is constrained by the physical memory available to hold the current node during processing. However, the component uses standard BizTalk Server 2009 pipeline message streaming processes and loads only the current node in the document into memory instead of loading the entire document.

The Remove Namespace component also re-encodes the document to the specified encoding (ascii, unicode/utf16, or utf8) and can remove the Byte Order Mark (BOM) from the beginning of the stream, if required.

Using the Add Namespace and Remove Namespace Components

Developers might use the Add Namespace component in any of the following circumstances:

  • The inbound message has no root namespace.

  • The inbound message uses element data or attribute data to describe the message type.

  • The data describing the message type is consistent and available using XPath queries.

The Add Namespace and Remove Namespace components can reside in any stage of a receive pipeline or a send pipeline. You can chain instances of the component if required, such as if you are using the Remove Namespace component followed by the Add Namespace component to change the root namespace of a document.

If you have multiple receive locations that require the use of these components, you can create a single pipeline and use the BizTalk Server "per instance" component configuration to set the component properties for each instance of the send or receive pipeline. Using BizTalk Server 2009, you can set properties on a per-instance basis for pipelines, which means that you can reuse a single pipeline across multiple receive locations and perhaps have different component properties for each instance. This is a run-time setting that allows administrators to make the change using the BizTalk Server Administration Console without requiring changes to the code or redeployment.

Component Properties

The Add Namespace component exposes five public properties:

  • NamespacePrefix. This is the prefix of the namespace, inserted between the xmlns: part and the following equals sign ( = ). To avoid conflicts with standard BizTalk Schema namespace prefixes, avoid using the values ns0 through ns9.

  • NamespaceBase. This is the static section of the namespace that will prefix the result generated by the values in the Separator and XPaths properties.

  • ExtractionNodeXPath. This is an XPath statement that resolves to a single element in the document that contains the element or attribute values you want to use for the generated parts of the namespace.

  • XPaths. This is a pipe (| ) delimited list of XPath queries used to extract each of the components that will combine to form the namespace.

  • Separator. This is the separator to use between the namespace segments. The most common value is a forward slash (/ ), but it can be an empty string, if required.

Note
All XML nodes, such as element and attribute names, are case sensitive.

The Remove Namespace component exposes two public properties:

  • Encoding. This is the encoding for the output message, one of the following values: ascii, unicode/utf16, or utf8.

  • RemoveByteOrderMark. This is a Boolean property that indicates whether the component should remove the byte order mark (usually 0xEFBB, 0xBFFFFE, or 0xFEFF) from the beginning of the XML document stream.

For an example of how to use these components, see Installing and Running the Namespace Component Sample.


The ESB Dispatcher Component

Messaging-based itinerary services are executed inside the ESB Dispatcher component. The Dispatcher component can also dynamically set endpoint location properties for outbound messages and dynamically transform messages.

Component Properties

The Dispatcher component has six properties:

  • RoutingServiceName. This property specifies the registered name for the messaging-based routing service. The default value is Microsoft.Practices.ESB.Services.Routing.

  • TransformServiceName. This property specifies the registered name for the messaging-based transform service. The default value is Microsoft.Practices.ESB.Services.Transform.

  • Validate. This property specifies whether a message needs to be validated.

  • Enabled. This property enables or disables the component.

  • Endpoint. This property is a resolver connection string in a format registered with BizTalk ESB Toolkit.

  • Map Name. This property is either the fully qualified name of a map or a connection string format registered with ​Microsoft BizTalk ESB Toolkit:

    • The following is an example of a map name:

      Copy Code
      GlobalBank.ESB.DynamicResolution.Transforms.SubmitOrderRequestNA_To_SubmitOrderRequestCN, GlobalBank.ESB.DynamicResolution.Transforms, Version=1.0.0.0, Culture=neutral, PublicKeyToken=c2c8b2b87f54180a


The ESB Dispatcher Disassemble Component

The ESB Dispatcher Disassemble component can dynamically set endpoint location properties for outbound messages in a similar way to the Dispatcher component. This pipeline component combines Microsoft BizTalk message de-batching functionality (by inheriting from the XML disassembler class named XmlDasmComp) with the message dispatching mechanism that can execute ESB itinerary messaging services in a BizTalk pipeline.


Using the Helper Classes

​Microsoft BizTalk ESB Toolkit includes a set of helper classes used by the other processes, services, and components in the toolkit. Because these helper classes are also public, you can use them in your own code as required.

In some cases, you must use them to provide parameters of the appropriate type for methods of other classes in the ESB. For example, the Resolver Web service methods return a generic collection of instances of the Resolver class.

The following sections describe the helper classes are included in ​Microsoft BizTalk ESB Toolkit:

  • The MapHelper Class

  • The Resolver Class

  • The ResolverDictionary Class

  • The Resolver Manager (ResolverMgr) Class


The MapHelper Class

Use the MapHelper class to perform transformations directly without using the transformation Web service.

The ​Microsoft BizTalk ESB Toolkit installer installs and registers the assembly Microsof.Practices.ESB.Transform.dll with the MapHelper class in the global assembly cache.

The MapHelper class exposes two public methods:

  • TransformMessage. This method takes as parameters a string that contains the message to transform and a string that contains the fully qualified name of a map deployed in BizTalk. The method returns a string containing the transformed document.

  • TransformMessageStream. This method takes as parameters a stream that contains the message to transform and a string that contains the fully qualified name of a map deployed in BizTalk. The method returns a string that contains the transformed document.


The Resolver Class

The Resolver class is a simple structure that exposes a name/value pair. The Resolver Web service returns a generic collection of instances of this class from its methods.

The ESB Core installer installs and registers the Microsoft.Practices.ESB.Resolver.dll assembly with Resolver class in the global assembly cache.

The use of a dictionary-based name/value approach makes it easier to add new items in future releases and minimizes the size of the resolution result by avoiding inclusion of non-relevant properties that depend on the resolution method and the current resolver type.

The Resolver class exposes two properties:

  • Name. This is the name of a name/value pair that contains information that is returned after a connection string is resolved.

  • Value. This is the value that corresponds to the name of the name/value pair.


The ResolverDictionary Class

The ResolverDictionary class is a Dictionary-based class that can store instances of the Resolver class as String name/value pairs. When creating instances of the ResolverDictionary class, you must provide a reference to an existing Dictionary instance. The ResolverDictionary class provides the data that the Resolver class uses when it performs run-time resolution.

The ​Microsoft BizTalk ESB Toolkit installer installs and registers the Microsoft.Practices.ESB.Resolver.dll assembly with the ResolverDictionary class in the global assembly cache.

The ResolverDictionary class exposes one method and one property:

  • Item( key ). This method takes a string value that contains a key name. It returns the corresponding string value or an empty string if the item does not exist in the underlying Dictionary instance.

  • BaseDictionary. This property returns a reference to the underlying Dictionary instance.


The Resolver Manager (ResolverMgr) Class

The Transform and Routing messaging services use the ResolverMgr class to perform resolution. The ESB dynamic transformation and dynamic delivery agents also use the ResolverManager class to perform just-in-time (JIT) resolution.

The ESB Core installer installs and registers the Microsoft.Practices.ESB.Resolver.dll assembly with the ResolverMgr class in the global assembly cache.

You can use this class in your own code where you need to perform dynamic resolution of endpoints or maps. You can also extend this class to use a custom resolution method. However, keep in mind that the class already supports a resolution mechanism that can use any custom resolver assembly, which should accommodate any alternative resolution algorithm you may require.

The following code example shows how to use the ResolverMgr class to resolve an endpoint.

C# Copy Code
// Move to retrieve the first resolver.
resolvers = itineraryStep.ResolverCollection;
resolver = resolvers.Current;

// Pass the resolver configuration to the Resolver Manager for resolution.
resolverDictionary = Microsoft.Practices.ESB.Resolver.ResolverMgr.Resolve(InboundMessage, resolver);

// Set transport properties.
transportLocation = resolverDictionary.Item("Resolver.TransportLocation");
transportType = resolverDictionary.Item("Resolver.TransportType");

Usually, your resolver connection string specifies the property values for at least one resolution method, such as a rules policy, custom assembly, XPath statement, or Universal Description, Discovery, and Integration (UDDI) label and server name. Finally, it returns a dictionary object with a collection of resolver facts, which can be easily populated with custom facts from a concrete resolver.

For more information about how the ESB resolution mechanism works, see Using Dynamic Resolution and Routing.


Using the BizTalk ESB Toolkit Utilities

This section describes various utilities included as part of the ​Microsoft BizTalk ESB Toolkit.

ESB Itinerary Import Utility

This utility is located under the \bin directory of the ​Microsoft BizTalk ESB Toolkit and is named EsbImportUtil.exe. This utility can be used to publish or deploy the itinerary XML into the ESBItineraryDB database.

The syntax for the utility is as follows:

Copy Code
>EsbImportUtil <Parameter1> <Value> <parameter2> <Value>...

The various parameters it can accept are the following:

/?: <Show the parameters help>

/f: <Itinerary xml file path>

/c: <published | deployed>

/n: <Default Itinerary name>

/v: <Default Itinerary version (format 'major.minor')>

/o: <Silent overwrite>

The following are examples of how to use this utility.

To publish to the Itinerary database:

Copy Code
>EsbImportUtil /f:myitinerary.xml /c:published

To deploy to the Itinerary database:

Copy Code
>EsbImportUtil  /f:myitinerary.xml /c:deployed

SSO Configuration Persist Utility

This utility is located under the \bin directory of the ​Microsoft BizTalk ESB Toolkit and is named Microsoft.Practices.ESB.PersistConfigurationTool.exe. This utility can be used to persist the ESB configuration information into the BizTalk SSO database. This can also be used to view configuration information and remove the configuration information from the SSO database.

The syntax for the utility is as follows:

To add a configuration section:

Copy Code
>Microsoft.Practices.ESB.PersistConfigurationTool  /P /F:app.config /S:SectionName /A:ApplicationName

Note
If /S is not provided, the following sections will be added: connectionStrings, esb, esb.resolver and cachingConfiguration.

To remove a section:

Copy Code
>Microsoft.Practices.ESB.PersistConfigurationTool  /R /S:SectionName

To view an existing section, use the application and section switches with the /V switch.

To set the administrator group name, use the AG:AdminGroupName switch.

To set the user group name, use the UG:UserGroupName switch.


Creating Itineraries Using Itinerary Designer

You can use the ​Microsoft BizTalk ESB Toolkit Itinerary Designer to create ESB mediation policies, named itineraries, used at run time for itinerary-based routing. The tool provides several shapes, or model elements, that correspond to different actions that you may perform while designing an itinerary.

This section provides conceptual information and guidelines to help you understand how to develop itineraries using the Itinerary Designer. It includes the following topics:

  • About Itineraries

  • Working in Itinerary Designer

  • Implementing Design Patterns in Itineraries

  • Development Activities


About Itineraries

An itinerary is a representation of an ESB mediation policy for executing a sequence of processing instructions based on the ​Microsoft BizTalk ESB Toolkit extensible format. An itinerary can be viewed as a high-level mediation language that describes a sequence of declarative itinerary services that are associated with mediation components by configuration of the ​Microsoft BizTalk ESB Toolkit core engine. You can design mediation flows to describe how messages should be processed, and you can organize the entire flow as a visual drawing. At run time, the ​Microsoft BizTalk ESB Toolkit core engine executes the itinerary produced by Itinerary Designer.

The Itinerary Designer Surface

The Itinerary Designer surface is a visual designer that is used to create ​Microsoft BizTalk ESB Toolkit itineraries and to export these itineraries into run-time format. It is a canvas to which you can drag items from the Toolbox, as illustrated in Figure 1.

Figure 1

Itinerary Designer surface

The name of the itinerary is displayed on the top tab of the Itinerary Designer and in the Microsoft Visual Studio title bar. The design surface itself is a single area and contains model elements that describe the actual message flow of the itinerary. The ItineraryDSL enables you to modify the model element properties using the Visual Studio Properties window.

Itinerary Designer Toolbox

The Visual Studio Toolbox contains tabs, which represent sets of tools. When you open a Visual Studio project that uses Itinerary Designer, the Toolbox contains two tabs: the General tab and the ItineraryDsl tabs. The ItineraryDsl tab contains the following tools:

  • Itinerary Service tool. This model element corresponds to the itinerary mediation service and represents a processing instruction.

  • Connector tool. This model element defines the relationship between individual model elements on the Itinerary Designer surface.

  • Off-Ramp tool. This model element corresponds to the off-ramp that sends a message. The Itinerary Designer allows multiple off-ramps per model.

  • On-Ramp tool. This model element corresponds to an on-ramp that receives a message. The Itinerary Designer allows only one on-ramp per model.

  • Itinerary Broker Service tool. This model element corresponds to the itinerary mediation service that allows defined message flow with multiple inputs and multiple outputs.

  • Itinerary Broker Output port. This model element corresponds to the single output port of the Itinerary Broker Service. The Itinerary Broker Service model element allows multiple output ports.

Steps in Itinerary Development

To develop an itinerary, which represents ESB mediation flow, you should typically perform the following actions:

  • Add model elements to represent the message processing steps for your itinerary. The Itinerary Designer provides a toolbox that contains shapes used to represent different actions or key abstractions.

  • Specify itinerary model properties, which include a connection string to the Microsoft BizTalk Server management database and model exporter configuration.

  • Bind on-ramp and off-ramp model elements to physical BizTalk receive locations and send ports by associating these model elements with corresponding technology extenders.

  • Associate itinerary services model elements with extenders and define technology-specific properties required by an extender. These properties may vary for a particular type of the extender; they can represent itinerary mediation service properties and BizTalk-specific properties associated with its run-time components and artifacts.

  • Identify custom components that you might want to reference as itinerary mediation services. For example, you may develop an orchestration as the itinerary service.

  • Verify resolver model element settings against ​Microsoft BizTalk ESB Toolkit run-time configuration by invoking resolver service from the designer surface.

  • Validate and export the itinerary run-time policy using an exporter. The ​Microsoft BizTalk ESB Toolkit provides two exporters with the Itinerary Designer: file exporter and database exporter. Alternatively, you can implement a custom exporter.

  • Test your itinerary using test client applications or BizUnit framework.

Security Considerations for Developing Itineraries

When you design itineraries, you should consider potential security issues:

  • Avoid specifying user credentials without using a certificate from the model properties.

  • Do not refer to BizTalk receive ports with receive locations that allow anonymous access.

  • Protect the message or transport channel if the itinerary message contains sensitive data.

  • Protect messages in the Message box with a pipeline component if the messages contain sensitive data that needs to be protected while in transit.


Working in Itinerary Designer

After you create a Microsoft Visual C# project, you can create new itinerary models and add existing itineraries to the project. The following steps describe how to create a new itinerary, add an existing itinerary model, or change the name of an itinerary.

Note
Before working with the Itinerary Designer, you must install the Microsoft.Practices.ESB.CORE Windows Installer (.msi file) from the ​Microsoft BizTalk ESB Toolkit install folder. This step installs the required run-time assemblies to the global assembly cache.

Basic Operations

To create an itinerary

  1. In Solution Explorer, right-click the C# project name, point to Add, and then click New Itinerary.

  2. In the Name box at the bottom of the dialog box, type the name for the itinerary, and then click Add.

    Note
    The new itinerary is created and displayed in Itinerary Designer, and a corresponding .itinerary file is created and displayed in Solution Explorer.

To add an existing itinerary to the project

  1. In Solution explorer, right click the C# project name, point to Add, and then click Existing Item.

  2. In the Add Existing Item dialog box, navigate to the directory that contains the itinerary, click the itinerary, and then click Add.

    Note
    The itinerary is added to the project.

To change the name of an itinerary

  1. In Solution Explorer, right-click the .itinerary file you want to rename, and then click Rename.

  2. Type the new file name, and then press ENTER.

To save an itinerary

  • On the File menu, click Save <itinerary name>.

    Note
    Itinerary files are saved as DSL models in corresponding XML format.

To set itinerary export properties

  1. In the Properties window, type a Name property.

  2. In the Properties window, type a Version property.

  3. In the Properties window, specify the Is Request Response property using the drop-down list. Set this property to true if the ​Microsoft BizTalk ESB Toolkit client application communicates with an on-ramp using request-response message exchange pattern.

  4. In the Properties window, set the Export Mode property to Default or Strict.

    Note
    When creating ​Microsoft BizTalk ESB Toolkit itineraries using the Itinerary Designer, the Export Mode property can be used to define where the service will execute. Setting the Export Mode property to Strict ensures that the itinerary service executes in its prescribed container; in this case, each itinerary service in the XML itinerary has a stage property that specifies the pipeline in which the service executes. If this property is set to Default, an itinerary compatible with Microsoft ESB is created, with no stage specified, and the itinerary service executes in the order prescribed, but not necessarily in the pipeline stage desired.

To export an itinerary to a file

  1. In the Properties window, click XML Itinerary Exporter in the Model Exporter drop-down list.

  2. In the Properties window, set the Itinerary XML file property to a new value.

To export an itinerary to a database

  1. In the Properties window, click Database Itinerary Exporter in the Model Exporter drop-down list.

  2. In the Properties window, set the Itinerary Database property connection string to point to the itinerary database.

  3. In the Properties window, set the Itinerary Status property to Published or Deployed.

    Note
    When an itinerary is exported to a database with Itinerary Status set to Published, the itinerary will not become effective for the ​Microsoft BizTalk ESB Toolkit run time until after the property is set to Deployed.

Security Operations

By using the Itinerary Designer, you can protect sensitive information, such as passwords and other credentials stored in a ​Microsoft BizTalk ESB Toolkit itinerary, by encrypting this information using X.509 certificates.

To select the X.509 certificate for an itinerary

  1. In the Itinerary Designer Properties window, expand the Encryption Certificate property, and then click the Store Location drop-down list, and select the CurrentUser or LocalMachine. This associates the X.509 certificate store with the current user or the local computer.

  2. In the Properties window, click the Store Name drop-down list and select the value which corresponds to your certificate store.

  3. In the Properties window, click the ellipsis button (...) next to the Encryption Certificate property, and then select the X.509 certificate in the Select Certificate dialog box.

To remove the X.509 certificate from an itinerary

  • In the Itinerary Designer Properties window, expand the Encryption Certificate property, and then set the Store Location property to a different value. This disassociates the old certificate with the ​Microsoft BizTalk ESB Toolkit itinerary model.

To disable the X.509 certificate validation

  • In the Registry Editor, navigate to the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\BizTalk ESB Toolkit\2.0\Designer, and then set the RequireX509Certificate property value to false.

    Note
    If you installed the ​Microsoft BizTalk ESB Toolkit on an operating system that has 64-bit support, the subkey is HKEY_LOCAL_MACHINE\SOFTWARE\SysWOW64\Microsoft\BizTalk ESB Toolkit\2.0\Designer.


Implementing Design Patterns in Itineraries

This topic describes common service-oriented architecture (SOA) patterns and categories that can be implemented using the ​Microsoft BizTalk ESB Toolkit. Each pattern category includes a description of each related pattern and links to more detailed information. The description of each individual pattern includes references to related ​Microsoft BizTalk ESB Toolkit sample applications that implement the patterns and links to development activities designed to show developers how to create ESB solutions to implement these patterns. This section includes the following topic sections:

  • Message Routing Patterns

  • Message Transformation Patterns

  • Service Mediation Patterns

  • Service Management Patterns


Message Routing Patterns

Message routing patterns define proven guidelines for routing a message to its target endpoint(s). Routing can be the result of static configuration, or it can be dynamically configured based on a number of criteria and using a number of methods.

Message Router

The Message Router pattern determines the recipient of the message based on a set of conditions. For a detailed description of this pattern, see Message Router (http://go.microsoft.com/fwlink/?LinkId=186844) on the Enterprise Integration Patterns site.

The implementation of this pattern in the Itinerary Designer is a combination of the ​Microsoft BizTalk ESB Toolkit itinerary routing service and a single content-based resolver. The itinerary routing service is responsible for promoting message routing properties in Microsoft BizTalk message context or for explicit routing of a message.

You can choose the itinerary routing service provided by the ​Microsoft BizTalk ESB Toolkit as follows:

  • Define the itinerary routing service with a messaging extender to execute in a BizTalk pipeline using Itinerary Designer.

  • Define the itinerary routing service with an orchestration extender to execute as an orchestration using Itinerary Designer that performs routing using BizTalk send ports.

The resolver associated with the itinerary routing service determines the recipient of the message, based on the message content. You can choose from the resolvers that support content-based routing provided by the ​Microsoft BizTalk ESB Toolkit, or you can implement your own resolver.

For an example of implementing this pattern in the ​Microsoft BizTalk ESB Toolkit, see the following resources:

  • How to: Resolve a Service Endpoint Using a UDDI Binding Key Search

  • How to: Resolve a Service Endpoint Using a UDDI Category Search

Content-Based Router

The Content-Based Router pattern determines the recipient of a message based on message content. For a detailed description of this pattern, see Content-Based Router (http://go.microsoft.com/fwlink/?LinkId=186839) on the Enterprise Integration Patterns site.

The implementation of this pattern in Itinerary Designer is a combination of the ​Microsoft BizTalk ESB Toolkit itinerary routing service and a single content-based resolver. The itinerary routing service is responsible for promoting message routing properties in the BizTalk message context or for explicitly routing a message.

You can choose the itinerary routing service provided by the ​Microsoft BizTalk ESB Toolkit as follows:

  • Define an itinerary routing service with a messaging extender to execute in a BizTalk pipeline using Itinerary Designer.

  • Define an itinerary routing service with an orchestration extender to execute as an orchestration using Itinerary Designer, which performs routing using BizTalk send ports.

  • Define an itinerary broker service with a broker messaging extender to execute in a BizTalk pipeline using Itinerary Designer.

The resolver associated with itinerary routing service determines the recipient of the message based on the message content. You can choose from the following resolvers that support content-based routing provided by the ​Microsoft BizTalk ESB Toolkit:

  • XPATH resolver. By using this resolver, you can route message content using XPATH queries.

  • BRE resolver. By using this resolver, you can retrieve routing information from message content using the BizTalk Rules Engine.

  • Message Context resolver. By using this resolver, you can retrieve the content of a message from the BizTalk message context when it is associated with a ​Microsoft BizTalk ESB Toolkit itinerary broker service.

    Note
    In addition to the preceding implementation scenarios, you can develop a custom content-based resolver and itinerary routing solution as a messaging-based or orchestration-based service. In this case, you may need to implement extenders for the ​Microsoft BizTalk ESB Toolkit resolver and itinerary service to interoperate with the Itinerary Designer.

For example of this implementation, see the following resources:

  • Installing and Running the Itinerary On-Ramp Sample

  • How to: Implement Content-Based Routing Using a Business Rules Policy for a Known Message Type

  • How to: Dynamically Route a Message Based on Message Context Using a Business Rules Policy

Routing Slip

The Routing Slip pattern describes a scenario in which a message must be routed through a series of components in a pre-defined order, which may not be known at the design time. For a detailed description of this pattern, see Routing Slip (http://go.microsoft.com/fwlink/?LinkId=186840) on the Enterprise Integration Patterns site.

The implementation of this pattern is provided by the ​Microsoft BizTalk ESB Toolkit; its implementation depends on the type of client application that submits a message for itinerary-based processing:

  • Service proxy. With this type of application, configure the ​Microsoft BizTalk ESB Toolkit on-ramp with the Itinerary Selector pipeline component and associate an itinerary resolver to select the appropriate ​Microsoft BizTalk ESB Toolkit itinerary. The itinerary properties may be configured as static properties using ITINERARY resolver, or they can be configured as dynamic properties using BizTalk Rules Engine and BRI resolver.

  • Advanced client. With this type of application, configure the ​Microsoft BizTalk ESB Toolkit on-ramp with the Itinerary Selector pipeline component and the ITINERARY-STATIC resolver. The client application sends a message with an itinerary reference header, which contains the itinerary name, version, and tracking identifier.

  • Adaptive client. With this type of application, the client application invokes the resolver service, which, in turn, identifies the itinerary reference by passing the client state as a request message. If the itinerary is resolved, the client application submits a message with itinerary references in the same way as in the preceding advanced client scenario.

For more information about implementing this pattern, see the following resources:

  • How to: Select an Itinerary Using a Business Rules Policy

  • How to: Transform a Message and Route the Resulting Message to a File Location Using an Itinerary Routing Slip

    Note
    In addition to the preceding scenarios, you can develop a custom itinerary resolver and itinerary routing services. You may consider creating designer extenders for custom itinerary services for use in the Itinerary Designer.

Scatter-Gather

The Scatter-Gather pattern enables messages to be sent to multiple recipients and to aggregate their responses; this results in a single message. For a detailed description of this pattern, see Scatter-Gather (http://go.microsoft.com/fwlink/?LinkId=186841) on the Enterprise Integration Patterns site.

For an example of implementing this pattern, see the Installing and Running the Scatter-Gather Sample sample.

Recipient List

The Recipient List pattern addresses the scenario solution in which a message is routed to one or more recipients. The recipient list can be defined either statically (meaning it has a fixed list of recipients) or dynamically. For a detailed description of this pattern, see Recipient List (http://go.microsoft.com/fwlink/?LinkId=186842) on the Enterprise Integration Patterns site.

The implementation of this pattern in Itinerary Designer is a combination of the ​Microsoft BizTalk ESB Toolkit itinerary routing service and multiple resolvers. The itinerary routing service is responsible for cloning a message and then using its BizTalk message context properties to explicitly route a message.

You can choose the itinerary routing service provided by the ​Microsoft BizTalk ESB Toolkit as follows:

  • Define the itinerary routing service with a messaging extender to execute in the BizTalk pipeline using Itinerary Designer.

  • Define the itinerary routing service with a messaging extender to execute as an orchestration using Itinerary Designer, which performs routing using BizTalk send ports.

The resolver associated with itinerary routing service determines the recipient of the message based on the message content. You can choose the set of resolvers provided by the ​Microsoft BizTalk ESB Toolkit to implement this scenario. For more information about implementing this pattern, see the following resource:

  • How to: Route a Single Message to Multiple Recipients Using an Itinerary Routing Slip

Splitter

The Splitter pattern addresses the problem when a single message needs to be split into multiple messages. For a detailed description of this pattern, see Splitter (http://go.microsoft.com/fwlink/?LinkId=186843) on the Enterprise Integration Patterns site. For more information about implementing this pattern, see the following resource:

  • How to: Split an Interchange and Route the Resulting Messages to Multiple File Locations Using Distinct Itineraries


Message Transformation Patterns

Message transformation patterns define proven guidelines for transforming messages for additional processing or to match the expected document format of the service to which the message will be sent. A message may require transformation because the structure of the received message is not in the expected standard or because the message must be converted from a non-standard format to XML.

Message Translator

The Message Translator pattern defines a solution for communication between systems that use incompatible data formats. For example, a client application may send a flat file request message that must be converted to XML before additional processing can occur. For a detailed description of this pattern, see Message Translator (http://go.microsoft.com/fwlink/?LinkId=186845) on the Enterprise Integration Patterns site.

The implementation of this pattern in Itinerary Designer is a combination of the ​Microsoft BizTalk ESB Toolkit transformation service and a single resolver. The itinerary transformation service is responsible for transforming a message using resolver properties that define the artifacts required for transformation. The resolver implementation is responsible for providing transformation settings, which can be defined statically or dynamically, depending on the resolver configuration.

For an example implementation of the Message Translator pattern, see the following resources:

  • Installing and Running the Itinerary On-Ramp Sample

  • How to: Transform a Message and Route to a Service Endpoint Using a Request-Response Message Exchange Pattern

Normalizer

The Normalizer pattern is an extension of the Data Model Transformation pattern. This pattern defines a solution in which messages received from multiple sources are semantically equivalent, but the messages arrive in different formats. For a detailed description of this pattern, see Normalizer (http://go.microsoft.com/fwlink/?LinkId=186847) on the Enterprise Integration Patterns site.

The implementation of this pattern in Itinerary Designer is a combination of the ​Microsoft BizTalk ESB Toolkit transformation service and a single resolver. The itinerary transformation service is responsible for transforming a message using resolver properties that define the artifacts required for transformation. The resolver implementation is responsible for dynamically resolving the appropriate Microsoft BizTalk map for a specified type of message.

For an example implementation of the Normalizer pattern, see the Installing and Running the Itinerary On-Ramp Sample.

Content Enricher

The Content Enricher pattern defines a solution in which a received message may not include all the data required for the target system to appropriately process the message. For example, the sending service may include a ZIP code without a redundant state code, but the receiving service expects a message that includes both a state code and a ZIP code; additional data is required before the receiving service can process the received message. For a detailed description of this pattern, see Content Enricher (http://go.microsoft.com/fwlink/?LinkId=186848) on the Enterprise Integration Patterns site.

For an example implementation of the Content Enricher pattern, see the Installing and Running the Message Enrichment Sample application.


Service Mediation Patterns

VETO/VETRO

The VETRO pattern is a common composite pattern that combines multiple actions taken on a message when it is received. The term VETRO is an acronym that stands for Validate, Enrich, Transform, Route, Operate. In the ​Microsoft BizTalk ESB Toolkit, these actions can be handled as individual stages in the pipeline associated with the receive location. For more information about how each of these stages can be implemented, see Key Scenarios and Development Tasks.

Request-Response

The Request-Response pattern defines a solution in which a service or party sends a request message and expects a reply message in return from the destination service. For a detailed description of this pattern, see Request-Reply (http://go.microsoft.com/fwlink/?LinkId=186849) on the Enterprise Integration Patterns site.

For more information about how to implement this pattern, see the following resources:

  • How to: Transform a Message and Route to a Service Endpoint Using a Request-Response Message Exchange Pattern

  • Installing and Running the Itinerary On-Ramp Sample


Service Management Patterns

Repair and Resubmit

The Repair and Resubmit pattern defines a solution in which a service is unable to process a message and needs to gracefully externalize its state in the form of the failed message, enabling the message content to be available for repair and then resubmit it to a service to continue processing the message.

​Microsoft BizTalk ESB Toolkit includes mechanisms by which Microsoft BizTalk messaging and orchestration exceptions can be normalized and exposed for additional action. When designing an ESB solution, it is important to account for how exceptions will be handled. The ​Microsoft BizTalk ESB Toolkit includes a sample ESB Management Portal application that demonstrates how exceptions can be viewed and managed. For detailed information about repairing and resubmitting exceptions using the ESB Management Portal sample application, see Repairing and Resubmitting Messages.


Development Activities

This section describes development activities for ​Microsoft BizTalk ESB Toolkit scenarios that use the Itinerary Designer and contains the following topics:

  • Prerequisites for the Development Activities

  • How to: Dynamically Route a Message Based on Message Context Using a Business Rules Policy

  • How to: Route a Single Message to Multiple Recipients Using an Itinerary Routing Slip

  • How to: Transform a Message and Route the Resulting Message to a File Location Using an Itinerary Routing Slip

  • How to: Transform a Message and Route to a Service Endpoint Using a Request-Response Message Exchange Pattern

  • How to: Select an Itinerary Using a Business Rules Policy

  • How to: Split an Interchange and Route the Resulting Messages to Multiple File Locations Using Distinct Itineraries

  • How to: Convert a Text Document to XML and Route to a File Location Using an Itinerary Routing Slip

  • How to: Create an Itinerary to Dynamically Route a Message to an Email Address Using an LDAP Query

  • How to: Implement Content-Based Routing Using a Business Rules Policy for a Known Message Type

  • How to: Validate a Message Using an ESB On-Ramp

  • How to: Publish a Service to the UDDI 3.0 Registry

  • How to: Resolve a Service Endpoint Using a UDDI Category Search

  • How to: Resolve a Service Endpoint Using a UDDI Binding Key Search

  • How to: Enable BAM Tracking in an ESB Itinerary Service

  • How to: Implement Content-Based Routing Using Message Context Properties


Prerequisites for the Development Activities

This section describes how to prepare your environment to complete the steps in the development activities that are included as part of the ​Microsoft BizTalk ESB Toolkit. Complete the following setup before you attempt any of the procedures in the development activities:

To set up your computer to perform the procedures in the BizTalk ESB Toolkit development activities

  1. Install and deploy the Itinerary sample application, the Dynamic Resolution sample application, and the Multiple Web Services sample application. For more information about installing and deploying these applications, see BizTalk ESB Toolkit Sample Applications.

  2. Run the UDDI Publisher Utility.

  3. On your development computer, in Windows Explorer, create the following paths:

    • C:\HowTos

    • C:\HowTos\Itineraries

    • C:\HowTos\DropFolder

    • C:\HowTos\Out

  4. Ensure that your BizTalk Server 2013 R2 service account has Full Control permissions to the C:\HowTos directory structure.

  5. Ensure that your Microsoft BizTalk Server service account has Write permissions to C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Test\Filedrop\Out.

  6. Copy the following test message to the C:\HowTos folder:

    • C:\Projects\Microsoft.Practices.ESB\Source\Samples\Itinerary\Test\Data\NAOrderDoc.xml

  7. In the C:\HowTos folder, create a shortcut to the Itinerary Test Client application, found at the following location:

    • C:\Projects\Microsoft.Practices.ESB\Source\Samples\Itinerary\Source\ESB.Itinerary.Test\bin\Debug\ESB.Itinerary.Test.exe

To create the Visual Studio solution

  1. In Visual Studio 2013, on the File menu, point to New, and then click Project.

  2. In the New Project dialog box, in the Project types pane, click Visual C#, and then click Class Library in the Templates pane.

  3. In the Name box, type ItineraryLibrary.

  4. In the Location box, type C:\HowTos.

  5. Select the Create directory for solution check box.

  6. In the Solution Name box, type Patterns, and then click OK to create the solution.

  7. Delete the Class1.cs file from the ItineraryLibrary project.


How to: Dynamically Route a Message Based on Message Context Using a Business Rules Policy

Goal

This section demonstrates how to create an itinerary that determines message endpoints, based on message context properties, using a BizTalk Server 2013 R2 Business Rules Engine (BRE) policy, and then routes the message using the BizTalk Server 2013 R2 FILE adapter.

In this How-to topic, you will complete the following steps:

  • Create a business rules policy to evaluate message type.

  • Create an itinerary routing slip to dynamically route using a business rules policy.

  • Test the itinerary using the Itinerary Test Client sample application.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

Steps

To create a BRE policy to route a message using message context properties

  1. Click Start on the taskbar, point to All Programs, point to BizTalk Server 2013 R2, and then click Business Rule Composer.

  2. In Policy Explorer, right-click Policies, and then click Add New Policy. Name the policy RouteBasedOnMessageType.

To add a routing rule for North American orders

  1. In the RouteBasedOnMessageType policy, right-click Version 1.0 (not saved), and then click Add New Rule. Name the rule SetNAOrderEndpoint.

  2. In the Rule window, right-click Conditions, point to Predicates, and then click Equal.

  3. In Facts Explorer, expand the ESB.ContextInfo vocabulary, expand Version 1.0, and then drag the Context Message Type fact to the argument1 node under Conditions.

    Note
    The ​Microsoft BizTalk ESB Toolkit includes several vocabularies that can be used for creating rules. Some of these should be replaced or augmented with your own vocabularies. For example, the DynamicRunTimeMaptypes policy has definitions for the maps provided in the GlobalBank samples.

  4. Click the argument2 node, and then type http://globalbank.esb.dynamicresolution.com/northamericanservices/#OrderDoc

  5. In Facts Explorer, expand the ESB.EndPointInfo vocabulary, expand Version 1.0, and then drag the Set End Point Outbound Transport Location definition to Actions.

  6. Click <empty string>, and then type C:\HowTos\Out\NorthAmerica%MessageID%.xml

  7. From Facts Explorer, drag the Set End Point Outbound Transport Type definition to Actions.

  8. In Facts Explorer, expand the ESB.TansportTypes vocabulary, expand Version 1.0, and then drag the Adaptor Providers definition to <empty string>.

  9. In the Actions pane, expand the Adaptor Providers drop-down list, and then click FILE.

To publish and deploy the policy

  1. In Policy Explorer, under the RouteBasedOnMessageType policy, right click Version 1.0 (not saved), and then click Publish.

  2. In Policy Explorer, under the RouteBasedOnMessageType policy, right click Version 1.0 - Published, and then click Deploy.

To create an ESB itinerary domain-specific language (DSL) model

  1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

  2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

  3. In the Name box, type MessageType, and then click Add.

To configure the properties of the itinerary

  1. In Visual Studio, click the design surface of MessageType.itinerary. In the MessageType Properties window, configure the following properties:

    1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

    2. In the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

    3. In the Select XML File dialog box, in the File name box, type C:\HowTos\Itineraries\MessageType, and then click Save.

      Note
      This step enables you to export the itinerary as XML to a local file location. Exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

To define the structure of the itinerary

  1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

    1. Click the Name property, and then type ReceiveOrders.

    2. In the Extender drop-down list, click On-Ramp ESB Extender.

    3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

    4. In the Receive Port drop-down list, click OnRamp.Itinerary.

  2. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it to the right of the On-Ramp model element. In the ItineraryService1 Properties window, configure the following properties:

    1. Click the Name property, and then type BreRoute.

    2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

      Note
      This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Extender.

    3. In the Container drop-down list, expand ReceiveOrders, and then click Receive Handlers.

    4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing.

  3. Right-click the Resolver collection of the BreRoute model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

    1. Click the Name property, and then type ByMessageType.

    2. In the Resolver Implementation drop-down list, click Bre Resolver Extension.

    3. In the Policy drop-down list, click RouteBasedOnMessageType v 1.0.

  4. In the Toolbox, click Connector. Drag a connection from the ReceiveOrders model element to the BreRoute model element.

  5. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the BreRoute model element. In the OffRamp1 Properties window, configure the following properties:

    1. Click the Name property, and then type SendBasedOnType.

    2. In the Extender drop-down list, click Off-Ramp ESB Extender.

    3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

    4. In the Send Port drop-down list, click DynamicResolutionOneWay.

  6. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the BreRoute model element and the SendBasedOnType model element. In the ItineraryService1 Properties window, configure the following properties:

    1. Click the Name property, and then type SendPortFilter.

    2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

    3. In the Off-Ramp drop-down list, expand SendBasedOnType, and then click Send Handlers.

  7. In the Toolbox, click Connector. Drag a connection from the BreRoute model element to the SendPortFilter model element.

  8. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendBasedOnType model element.

To export the model for use with the Itinerary Test Client

  1. In Visual Studio, right-click the design surface of the MessageType itinerary, and then click Export Model.

    Note
    The XML version of the itinerary opens in Visual Studio.

  2. Save all project artifacts.

  3. In Windows Explorer, browse to C:\HowTos\Itineraries and notice the creation of your itinerary XML (MessageType.xml).

To test the itinerary

  1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

  2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

  3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select MessageType.xml, and then click Open to load the itinerary.

  4. Click OK to clear the Itinerary Loaded Successfully message.

  5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

  6. In the Select XML Document to load dialog box, browse to C:\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

  7. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

  8. In Windows Explorer, browse to C:\HowTos\Out\. Verify that the NorthAmerica%MessageID%.xml message has been written to the directory.

Additional Resources

For more information, see the following related topics:

  • How to: Select an Itinerary Using a Business Rules Policy

  • How to: Transform a Message and Route the Resulting Message to a File Location Using an Itinerary Routing Slip

  • How to: Implement Content-Based Routing Using a Business Rules Policy for a Known Message Type

  • Development Activities

  • Message Routing Patterns

  • Using Dynamic Resolution and Routing


How to: Route a Single Message to Multiple Recipients Using an Itinerary Routing Slip

Goal

This section demonstrates how to use the Designer domain-specific language (DSL) to create an itinerary that routes a message to three distinct recipients using a static resolver and the BizTalk Server 2013 R2 FILE adapter.

In this How-to topic, you will complete the following steps:

  • Create an itinerary with three static resolvers to route messages to multiple recipients.

  • Test the itinerary using the Itinerary Test Client sample application.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Steps

    To create an ESB itinerary DSL model

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click ItineraryLibrary, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, click ItineraryDsl in the Templates pane.

    4. In the Name box, type RecipientList, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of RecipientList.itinerary. In the RecipientList Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

      2. In the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

      3. In the Select XML File dialog box, in the File name box, type C:\HowTos\Itineraries\RecipientList, and then click Save.

        Note
        This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp Extender.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it to the right of the On-Ramp model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type RouteToThreeRecipients.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

        Note
        This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Extender.

      3. In the Container drop-down list, expand ReceiveNaOrderDoc, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing.

    3. Right-click the Resolver collection of the RouteToThreeRecipients model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type FirstResolver.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\First%MessageID%.xml.

        Note
        You have added the first of three resolvers for this itinerary service. You will now add two more resolvers to route the message to additional recipients.

    4. Right-click the Resolver collection of the RouteToThreeRecipients model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type SecondResolver.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\Second%MessageID%.xml.

    5. Right-click the Resolver collection of the RouteToThreeRecipients model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type ThirdResolver.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\Third%MessageID%.xml.

    6. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the RouteToThreeRecipients model element.

    7. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the RouteToThreeRecipients model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendThreeMessages.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    8. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the RouteToThreeRecipients model element and the SendThreeMessages model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilter.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand SendThreeMessages, and then click Send Handlers.

    9. In the Toolbox, click Connector. Drag a connection from the RouteToThreeRecipients model element to the SendPortFilter model element.

    10. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendThreeMessages model element.

    To export the model for use with the Itinerary Test Client

    1. In Visual Studio, right-click the design surface of the RecipientList itinerary, and then click Export Model.

      Note
      The XML version of the itinerary opens in Visual Studio.

    2. Save all project artifacts.

    3. In Windows Explorer, browse to C:\HowTos\Itineraries, and then notice the creation of your itinerary XML (RecipientList.xml).

    To test the itinerary

    1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

    2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

    3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select RecipientList.xml, and then click Open to load the itinerary.

    4. Click OK to clear the "Itinerary Loaded Successfully: message.

    5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

    6. In the Select XML Document to load dialog box, browse to C:\Patterns. Select NAOrderDoc.xml, and then click Open to load the test message.

    7. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

    8. In Windows Explorer, browse to C:\HowTos\Out\. Verify that the following messages have been written to the directory:

      • First%MessageID%.xml

      • Second%MessageID%.xml

      • Third%MessageID%.xml

    Additional Resources

    For more information, see the following related topics:

    • Development Activities

    • Message Routing Patterns

    • Using Dynamic Resolution and Routing


How to: Transform a Message and Route the Resulting Message to a File Location Using an Itinerary Routing Slip

Goal

This section demonstrates how to use the ESB Designer domain-specific language (DSL) to create an itinerary that implements message transformation by invoking a BizTalk map, and then it routes the messages using the ​Microsoft BizTalk ESB Toolkit FILE adapter.

In this How-to topic, you will complete the following steps:

  • Create an itinerary routing slip with a transform itinerary service that implements a BizTalk map.

  • Configure the itinerary to route the transformed message to a file location.

  • Test the itinerary using the Itinerary Test Client sample application.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Steps

    To create an ESB itinerary DSL model

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, click ItineraryDsl in the Templates pane.

    4. In the Name box, type DataModelTransformation, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of DataModelTransformation.itinerary. In the DataModelTransformation Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

      2. In the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

      3. In the Select XML File dialog box, in the File name box, type C:\HowTos\Itineraries\DataModelTransformation, and then click Save.

        Note
        This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it to the right of the On-Ramp model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type MapNAOrderToCNOrder.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

        Note
        This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Transform.

    3. Right-click the Resolver collection of the MapNAOrderToCNOrder model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type StaticallySpecifyTheMap.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transform Type drop-down list, click GlobalBank.ESB.DynamicResolution.Transforms.SubmitOrderRequestNA_To_SubmitOrderRequestCN.

      4. In the Transport Name drop-down list, click FILE.

    4. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the MapNAOrderToCNOrder model element.

    5. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the MapNAOrderToCNOrder model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendCNOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    6. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the MapNAOrderToCNOrder model element and the SendCNOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilter.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand SendCNOrder, and then click Send Handlers.

    7. Right-click the Resolver collection of the SendPortFilter model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type ConfigureFolderSettings.

      2. In the Transport Name drop-down list, click FILE.

      3. Click the Transport Location property, and then type C:\HowTos\Out\%MessageID%.xml.

        Note
        Each off-ramp will have an Itinerary Service associated with it; the combination of the Itinerary Service properties and the properties of the off-ramp define the subscription of the dynamic send port.

    8. In the Toolbox, click Connector. Drag a connection from the MapNAOrderToCNOrder model element to the SendPortFilter model element.

    9. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendCNOrder model element.

    To export the model for use with the Itinerary Test Client

    1. In Visual Studio, right-click the design surface of the DataModelTransformation itinerary, and then click Export Model.

      Note
      The XML version of the itinerary opens in Visual Studio.

    2. Save all project artifacts.

    3. In Windows Explorer, browse to C:\HowTos\Itineraries and notice the creation of your itinerary XML (DataModelTransformation.xml).

    To test the itinerary

    1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

    2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

    3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select DataModelTransformation.xml, and then click Open to load the itinerary.

    4. Click OK to clear the Itinerary Loaded Successfully message.

    5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

    6. In the Select XML Document to load dialog box, browse to C:\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

    7. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

    8. In Windows Explorer, browse to C:\HowTos\Out. Verify that the %MessageID%.xml message has been written to the directory.

    Additional Resources

    For more information, see these related topics:

    1. How to: Split an Interchange and Route the Resulting Messages to Multiple File Locations Using Distinct Itineraries

    2. Development Activities

    3. Message Transformation Patterns


How to: Transform a Message and Route to a Service Endpoint Using a Request-Response Message Exchange Pattern

Goal

This section demonstrates how to use the ESB Designer domain-specific language (DSL) to create a request-response itinerary that can be used with a two-way on-ramp. You will create a routing slip to receive a message, transform the message, submit the message to a service, and return the service response message to the submitter of the original message.

In this How-to topic, you will complete the following steps:

  • Create an itinerary routing slip with a transform itinerary service that implements a Microsoft BizTalk Server map.

  • Configure the itinerary to route the transformed message to a service endpoint.

  • Configure the itinerary to return the service response message to the original sending party.

  • Test the itinerary using the Itinerary Test Client sample application.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Steps

    To create an ESB itinerary DSL model

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, in the Name box, type RequestResponse, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of RequestResponse.itinerary. In the RequestResponse Properties window, configure the following properties:

      1. In the Is Request Response drop-down list, click True.

      2. In the Model Exporter drop-down list, click XML Itinerary Exporter.

      3. In the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

      4. In the Select XML File dialog box, in the File name box, type C:\HowTos\Itineraries\RequestResponse, and then click Save.

        Note
        This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.Response.

    2. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it to the right of the On-Ramp model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type MapNAOrderToCNOrder.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

        Note
        This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Transform.

    3. Right-click the Resolver collection of the MapNAOrderToCNOrder model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type StaticallySpecifyTheMap.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transform Type drop-down list, click GlobalBank.ESB.DynamicResolution.Transforms.SubmitOrderRequestNA_To_SubmitOrderRequestCN.

    4. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the MapNAOrderToCNOrder model element.

    5. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it to the right of the MapNAOrderToCNOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type RouteToCNService.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

        Note
        This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing.

    6. Right-click the Resolver collection of the RouteToCNService model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type StaticallySpecifyTheService.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click WCF-BasicHttp.

      4. Click the Transport Location property, and then type http://localhost/ESB.CanadianServices/SubmitPOService.asmx.

      5. Click the Target Namespace property, and then type http://globalbank.esb.dynamicresolution.com/canadianservices.

      6. Click the Action property, and then type submitOrder.

    7. In the Toolbox, click Connector. Drag a connection from the MapNAOrderToCNOrder model element to the RouteToCNService model element.

    8. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the RouteToCNService model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type InvokeCNService.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionSolicitResp.

    9. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the RouteToCNService model element and the InvokeCNService model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilter.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand InvokeCNService, and then click Send Handlers.

    10. In the Toolbox, click Connector. Drag a connection from the RouteToCNService model element to the SendPortFilter model element.

    11. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the InvokeCNService model element.

    12. Right-click the design surface, and then click Validate.

      Note
      The itinerary validates; it is not necessary to connect the off-ramp back to the on-ramp in order to send the response message back to the requesting party. By using a two-way on-ramp, the final message is automatically returned to the requesting party.

    To export the model for use with the Itinerary Test Client

    1. In Visual Studio, right-click the design surface of the RequestResponse itinerary, and then click Export Model.

      Note
      The XML version of the itinerary opens in Visual Studio.

    2. Save all project artifacts.

    3. In Windows Explorer, browse to C:\HowTos\Itineraries. Notice the creation of your itinerary XML (RequestResponse.xml).

    To test the itinerary

    1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

    2. In the Itinerary Test Client, clear the Use WCF Service check box.

    3. In the Web Service Options section, select the Two Way Service check box, and then click Load Itinerary.

    4. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select RequestResponse.xml, and then click Open to load the itinerary.

    5. Click OK to clear the Itinerary Loaded Successfully message.

    6. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

    7. In the Select XML Document to load dialog box, browse to C:\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

    8. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

    9. In the Results box, notice the message's root node is submitOrderResponse and the default namespace is ... canadianservices.

      Note
      If the response message requires additional transformation before the response is sent to the requesting party, you must use a pipeline that contains the ESB Forwarder component. For an example of this functionality, see the Installing and Running the Multiple Web Services Sample.

    Additional Resources

    For more information, see the following related topics:

    • How to: Transform a Message and Route the Resulting Message to a File Location Using an Itinerary Routing Slip

    • Development Activities

    • Message Routing Patterns

    • Installing and Running the Multiple Web Services Sample


How to: Select an Itinerary Using a Business Rules Policy

Goal

This section demonstrates how to create business rules that can be used to select an itinerary based on the content of a received message and how to configure the Itinerary Selector pipeline component within a generic itinerary on-ramp to call these rules. This section describes a business scenario in which messages are routed differently, based on the region in which the customer resides.

In this How-to topic, you will complete the following steps:

  • Model itineraries for the Western and Eastern divisions of customer Global Bank.

  • Create business rules policies that will be used to select an itinerary for processing request.

  • Configure the Itinerary Selector pipeline component to use a business rules policy to select the appropriate itinerary.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Before You Begin

    Complete the following tasks before you perform the steps later in this How-to topic:

    • Create the GlobalBank West test message.

    • Create the GlobalBank East test message.

    The following procedures describe how to do each of these.

    To create the GlobalBank West test message

    1. In Windows Explorer, browse to C:\HowTos.

    2. Create a copy of NAOrderDoc.xml, and then name the copy West.xml.

    3. In Notepad, open West.xml, and then change the value of the customerName element to GlobalBankWest.

    4. Save West.xml as UTF-8, and then close Notepad.

    To create the GlobalBank East test message

    1. In Windows Explorer, browse to C:\HowTos.

    2. Create a copy of NAOrderDoc.xml, and then name the copy East.xml.

    3. In Notepad, open East.xml, and then change the value of the customerName element to GlobalBankEast.

    4. Save East.xml as UTF-8, and then close Notepad.

    Steps

    To create a Business Rules Engine (BRE) policy to select an itinerary using custom message properties

    1. Click Start on the taskbar, point to All Programs, point to BizTalk Server 2013 R2, and then click Business Rule Composer.

    2. In Policy Explorer, right-click Policies, and then click Add New Policy. Name the policy ResolveItineraryBasedOnCustomer.

      Note
      This How-to topic uses the same business rules policy and itineraries as those created in the topic How to: Split an Interchange and Route the Resulting Messages to Multiple File Locations Using Distinct Itineraries. If you have already completed that section, you can skip to the procedure, "To create and configure an ESB on-ramp" later in this topic.

    To add a selection rule for customer GlobalBank West

    1. In the ResolveItineraryBasedOnCustomer policy, right-click Version 1.0 (not saved), and then click Add New Rule. Name the rule SetGlobalBankWestItinerary.

    2. In Facts Explorer, click the XML Schemas tab, right-click Schemas, and then click Browse.

    3. In the Schema Files dialog box, browse to C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Source\ESB.DynamicResolution.Schemas, select NAOrderDoc.xsd, and then click Open.

      Note
      This is the schema that defines the NAOrderDoc.xml message, which was used to create the West and East messages you will use for testing.

    4. In Facts Explorer, click NAOrderDoc.xsd, click the Document Type property in the Properties pane, and then type GlobalBank.ESB.DynamicResolution.Schemas.NAOrderDoc.

      Note
      This is the fully qualified name of the schema.

    5. In Facts Explorer, expand NAOrderDoc.xsd, and then expand OrderDoc.

    6. In the Rule window, right-click Conditions, point to Predicates, and then click Equal.

    7. From Facts Explorer, drag the customerName element to the argument1 node under Conditions.

    8. Click the argument2 node, and then type GlobalBankWest.

    9. In Facts Explorer, click the Vocabularies tab. Expand the ESB.Itinerary vocabulary, expand Version 1.1, and then drag the Set Itinerary Name definition to Actions.

    10. Click <empty string>, and then type GlobalBankWestItinerary.

      Note
      Later in this How-to topic, you will create this itinerary to process messages from GlobalBank West.

    To add a selection rule for Customer GlobalBank East

    1. In Policy Explorer, right-click the SetGlobalBankWestItinerary rule, and then click Copy.

    2. Right-click Version 1.0 (not saved), and then click Paste.

    3. In the New Rule Name dialog box, type SetGlobalBankEastItinerary, and then click OK.

    4. In Policy Explorer, click the SetGlobalBankEastItinerary rule.

    5. In the Conditions section, right-click GlobalBankWest, and then click Reset argument.

    6. Click argument2, and then type GlobalBankEast.

    7. In the Actions section, right-click GlobalBankWestItinerary, and then click Reset argument.

    8. Click <empty string> and then type GlobalBankEastItinerary.

      Note
      Later in the How-to topic, you will create this itinerary to process messages from GlobalBank East.

    To publish and deploy the policy

    1. In Policy Explorer, under the ResolveItineraryBasedOnCustomer policy, right click Version 1.0 (not saved), and then click Publish.

    2. In Policy Explorer, under the ResolveItineraryBasedOnCustomer policy, right click Version 1.0 - Published, and then click Deploy.

    To create an ESB itinerary domain-specific language (DSL) model for GlobalBank West messages

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, in the Templates pane, click ItineraryDsl.

    4. In the Name box, type GlobalBankWestItinerary, and then click Add.

    To configure the properties of the GlobalBank West itinerary

    1. In Visual Studio, click the design surface of GlobalBankWestItinerary.itinerary. In the GlobalBankWestItinerary Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click Database Itinerary Exporter.

      2. Click the ellipsis button (...) next to the Itinerary Database property.

      3. In the Connection Properties dialog box, choose the SQL Server that hosts the itinerary repository database, and then specify the name of the database (the default name is EsbItineraryDb).

    2. In the Itinerary Status drop-down list, click Deployed.

      Note
      This step enables you to export the itinerary to a central repository; itineraries can be selected and attached from this repository upon message reception. You will later configure the Itinerary Selector pipeline component to use the Business Rules Engine resolver (BRI) to evaluate inbound messages and select the appropriate itinerary from this repository.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the ReceiveNAOrder model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendNAOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    3. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the ReceiveNAOrder model element and the SendNAOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type RouteMessage.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Itinerary Service Extension.

      3. In the Off-Ramp drop-down list, expand SendNAOrder, and then click Send Handlers.

    4. Right-click the Resolver collection of the RouteMessage model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type StaticResolver.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\West%MessageID%.xml.

    5. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the RouteMessage model element.

    6. In the Toolbox, click Connector. Drag a connection from the RouteMessage model element to the SendNAOrder model element.

    To export the model to the itinerary database

    1. In Visual Studio, right-click the design surface of the GlobalBankWestItinerary itinerary, and then click Export Model.

      Note
      The itinerary has been exported to the itinerary database and can now be used by the Itinerary Selector component.

    2. Save all project artifacts.

    To create an ESB itinerary DSL model for GlobalBank East message

    1. In Visual Studio 2013, open C:\HowTos\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, in the Templates pane, click ItineraryDsl.

    4. In the Name box, type GlobalBankEastItinerary, and then click Add.

    To configure the properties of the GlobalBank East itinerary

    1. In Visual Studio, click the design surface of GlobalBankEastItinerary.itinerary. In the GlobalBankEastItinerary Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click Database Itinerary Exporter.

      2. Click the ellipsis button (...) next to the Itinerary Database property.

      3. In the Connection Properties dialog box, choose the SQL Server that hosts the itinerary repository database, and then specify the name of the database (the default name is EsbItineraryDb).

    2. In the Itinerary Status drop-down list, click Deployed.

      Note
      This step enables you to export the itinerary to a central repository; itineraries can be selected and attached from this repository when messages are received. You will later configure the Itinerary Selector pipeline component to use the BRI resolver to evaluate inbound messages and select the appropriate itinerary from this repository.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the ReceiveNAOrder model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendNAOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    3. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the ReceiveNAOrder model element and the SendNAOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type RouteMessage.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Itinerary Service Extension.

      3. In the Off-Ramp drop-down list, expand SendNAOrder, and then click Send Handlers.

    4. Right-click the Resolver collection of the RouteMessage model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type StaticResolver.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\East%MessageID%.xml.

    5. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the RouteMessage model element.

    6. In the Toolbox, click Connector. Drag a connection from the RouteMessage model element to the SendNAOrder model element.

    To export the model to the itinerary database

    1. In Visual Studio, right-click the design surface of the GlobalBankEastItinerary itinerary, and then click Export Model.

      Note
      The itinerary has been exported to the itinerary database and can now be used by the Itinerary Selector component.

    2. Save all project artifacts.

    To create and configure an ESB on-ramp

    1. Click Start on the taskbar, point to All Programs, point to BizTalk Server 2013 R2, and then click BizTalk Server Administration.

    2. In the BizTalk Server 2013 R2 Administration Console, expand BizTalk Group, expand Applications, and then expand Microsoft.Practices.ESB.

    3. Right-click Receive Locations, point to New, and then click One-way Receive Location.

    4. In the Select a Receive Port dialog box, click OnRamp.Itinerary, and then click OK.

    5. In the Receive Location Properties dialog box, in the Name box, type OnRamp.Itinerary.HowTo.

    6. In the Type drop-down list, click FILE, and then click Configure.

    7. In the FILE Transport Properties dialog box, in the Receive folder box, type C:\HowTos\DropFolder, and then click OK.

    To configure the Itinerary Selector pipeline component

    1. In the Receive Location Properties dialog box, in the Receive pipeline drop-down list, click ItinerarySelectReceiveXml, and then click the ellipsis button (...).

    2. Use the Configure Pipeline dialog box to configure the following Itinerary Selector component properties:

      1. Click the ItineraryFactKey property, and then type Resolver.Itinerary.

      2. Click the ResolverConnectionString property, and then type BRI:\\policy=ResolveItineraryBasedOnCustomer;useMsg=true;recognizeMessageFormat=true;

      3. Click OK to close the Configure Pipeline dialog box.

    3. Click OK to close the Receive Location Properties dialog box.

    4. In the BizTalk Server 2013 R2 Administration Console, right-click the OnRamp.Itinerary.HowTo receive location, and then click Enable.

    To test the itinerary selector and business rules

    1. In Windows Explorer, browse to C:\HowTos.

    2. Copy (do not move) the files East.xml and West.xml to the DropFolder folder.

    3. Browse to C:\HowTos\Out. Verify that the East%MessageID%.xml and West%MessageID%.xml messages have been written to the directory.

      Note
      Though identical except for the value of the customer element, the messages were processed using different itineraries, based on the resolution of the Itinerary Selector pipeline component.

    4. In the BizTalk Server 2013 R2 Administration Console, right-click the OnRamp.Itinerary.HowTo receive location, and then click Disable.

    5. After the OnRamp.Itinerary.HowTo receive location is disabled, right-click it, and then click Delete. In the Confirm delete receive location dialog box, click Yes.

    Additional Resources

    For more information, see the following related topics:

    • How to: Split an Interchange and Route the Resulting Messages to Multiple File Locations Using Distinct Itineraries

    • Development Activities

    • Installing and Running the Dynamic Resolution Sample

    • Using Dynamic Resolution and Routing

    • Message Routing Patterns


How to: Split an Interchange and Route the Resulting Messages to Multiple File Locations Using Distinct Itineraries

Goal

This section demonstrates how to create an ESB on-ramp that uses the ItinerarySelectReceiveXml pipeline and how to configure the pipeline's components to split an inbound interchange and select the appropriate routing slip for each resulting message, based on message context. Itinerary selection will be resolved using a business rules policy, and messages will be routed differently based on the region in which the customer resides.

In this How-to topic, you will complete the following steps:

  • Create an ESB on-ramp that splits an XML interchange.

  • Configure the Itinerary Selector pipeline component to use a business rules policy to select the appropriate itinerary.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Before You Begin

    Complete the following tasks before you perform the steps later in this How-to topic:

    • Create the required artifacts.

    • Add a schemas project to the Patterns solution.

    • Add the artifacts to the Schemas project.

    • Create a BRE policy to select an itinerary using custom message properties.

    • Add a selection rule for customer GlobalBank West.

    • Add a selection rule for customer GlobalBank East.

    • Publish and deploy the policy.

    • Create an ESB itinerary domain-specific language (DSL) model for GlobalBank West messages.

    • Configure the properties of the GlobalBank West itinerary.

    • Define the structure of the GlobalBank West itinerary.

    • Export the GlobalBank West model to the itinerary database.

    • Create an ESB itinerary DSL model for GlobalBank East messages.

    • Configure the properties of the GlobalBank East itinerary.

    • Define the structure of the GlobalBank East itinerary.

    • Export the GlobalBank East model to the itinerary database.

      The following procedures describe how to do each of these.

    To create the required artifacts

    1. In Windows Explorer, browse to C:\HowTos.

    2. Create a new text document named OrderDocEnvelope.xsd.

    3. Open the OrderDocEnvelope.xsd schema in Notepad.

    4. Edit the document using the following code.

      Copy Code
      <?xml version="1.0" ?>
<xs:schema xmlns:ns0="http://globalbank.esb.dynamicresolution.com/northamericanservices/" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" xmlns="http://ESB.BizUnit.Map.Test" targetNamespace="http://ESB.BizUnit.Map.Test" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:import schemaLocation="GlobalBank.ESB.DynamicResolution.Schemas.NAOrderDoc" namespace="http://globalbank.esb.dynamicresolution.com/northamericanservices/" />
  <xs:annotation>
    <xs:appinfo>
      <b:schemaInfo is_envelope="yes" xmlns:b="http://schemas.microsoft.com/BizTalk/2003" />
      <b:references>
        <b:reference targetNamespace="http://globalbank.esb.dynamicresolution.com/northamericanservices/" />
      </b:references>
    </xs:appinfo>
  </xs:annotation>
  <xs:element name="OrderEnvelope">
    <xs:annotation>
      <xs:appinfo>
        <b:recordInfo body_xpath="/*[local-name()='OrderEnvelope' and namespace-uri()='http://ESB.BizUnit.Map.Test']" />
      </xs:appinfo>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="ns0:OrderDoc" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

    5. Save OrderDocEnvelope.xsd as UTF-8, and then close Notepad.

    6. In the C:\HowTos folder, create a new text document named Batch.xml.

    7. In Notepad, open Batch.xml.

    8. Edit the document using the following code.

      Copy Code
      <?xml version="1.0" ?>
<ns0:OrderEnvelope xmlns:ns0="http://ESB.BizUnit.Map.Test">
  <ns0:OrderDoc xmlns:ns0="http://globalbank.esb.dynamicresolution.com/northamericanservices/">
    <ns0:customerName>GlobalBankWest</ns0:customerName>
    <ns0:ID>ns0:ID_0</ns0:ID>
    <ns0:requestType>10</ns0:requestType>
  </ns0:OrderDoc>
  <ns0:OrderDoc xmlns:ns0="http://globalbank.esb.dynamicresolution.com/northamericanservices/">
    <ns0:customerName>GlobalBankEast</ns0:customerName>
    <ns0:ID>ns0:ID_0</ns0:ID>
    <ns0:requestType>11</ns0:requestType>
  </ns0:OrderDoc>
  <ns0:OrderDoc xmlns:ns0="http://globalbank.esb.dynamicresolution.com/northamericanservices/">
    <ns0:customerName>GlobalBankEast</ns0:customerName>
    <ns0:ID>ns0:ID_0</ns0:ID>
    <ns0:requestType>12</ns0:requestType>
  </ns0:OrderDoc>
</ns0:OrderEnvelope>

    9. Save and close Batch.xml.

    To add a schemas project to the Patterns solution

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click Solution 'Patterns', point to Add, and then click New Project.

    3. In the Add New Project dialog box, in the Project types pane, click BizTalk Projects, and then do the following:

      1. In the Templates pane, click Empty BizTalk Server Project.

      2. In the Name box, type Patterns.Schemas, and then click OK.

    4. In Solution Explorer, right-click Patterns.Schemas, and then click Properties.

    5. In the Properties window, on the Signing tab, select the Sign the assembly check box.

    6. In the Choose a strong name key file drop-down list, click <New...>.

    7. In the Create Strong Name Key dialog box, configure the following properties:

      1. In the Key file name box, type Splitting.

      2. Clear the Protect my key file with a password check box, and then click OK.

    8. In the Properties window, on the Deployment tab, in the Application Name box, type Microsoft.Practices.ESB.

    9. Close the Properties window.

    To add the artifacts to the Schemas project

    1. In Solution Explorer, right-click Patterns.Schemas, and then click Add Reference.

    2. On the Browse tab of the Add Reference dialog box, browse to and select C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Source\ESB.DynamicResolution.Schemas\bin\Debug\GlobalBank.ESB.DynamicResolution.Schemas.dll, and then click OK.

    3. In Solution Explorer, right-click Patterns.Schemas, point to Add, and then click Existing Item.

    4. In the Add Existing Item dialog box, browse to and select C:\HowTos\OrderDocEnvelope.xsd, and then click Add.

    5. Save all solution artifacts.

    6. In Solution Explorer, right-click Patterns.Schemas, and then click Deploy.

      Note
      This How-to topic uses the same business rules policy and itineraries as those created in the How to: Select an Itinerary Using a Business Rules Policy topic. If you have not already completed that section, please complete the following additional steps. If you have completed that section, continue directly to the "Steps" section.

    To create a Business Rules Engine (BRE) policy to select an itinerary using custom message properties

    1. Click Start on the taskbar, point to All Programs, point to BizTalk Server 2013 R2, and then click Business Rule Composer.

    2. In Policy Explorer, right-click Policies, and then click Add New Policy. Name the policy ResolveItineraryBasedOnCustomer.

    To add a selection rule for customer GlobalBank West

    1. In the ResolveItineraryBasedOnCustomer policy, right-click Version 1.0 (not saved), and then click Add New Rule. Name the rule SetGlobalBankWestItinerary.

    2. In Facts Explorer, click the XML Schemas tab, right-click Schemas, and then click Browse.

    3. In the Schema Files dialog box, browse to C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Source\ESB.DynamicResolution.Schemas, select NAOrderDoc.xsd, and then click Open.

      Note
      This is the schema that defines the NAOrderDoc.xml message, which was used to create the West and East messages you will use for testing.

    4. In Facts Explorer, click NAOrderDoc.xsd, click the Document Type property in the Properties pane, and then type GlobalBank.ESB.DynamicResolution.Schemas.NAOrderDoc.

      Note
      This is the fully qualified name of the schema.

    5. In Facts Explorer, expand NAOrderDoc.xsd, and then expand OrderDoc.

    6. In the Rule window, right-click Conditions, point to Predicates, and then click Equal.

    7. From Facts Explorer, drag the customerName element to the argument1 node under Conditions.

    8. Click the argument2 node, and then type GlobalBankWest.

    9. In Facts Explorer, click the Vocabularies tab. Expand the ESB.Itinerary vocabulary, expand Version 1.1, and then drag the Set Itinerary Name definition to Actions.

    10. Click <empty string> and then type GlobalBankWestItinerary.

      Note
      Later in this How-to topic, you will create this itinerary to process messages from GlobalBank West.

    To add a selection rule for customer GlobalBank East

    1. In Policy Explorer, right-click the SetGlobalBankWestItinerary rule, and then click Copy.

    2. Right-click Version 1.0 (not saved), and then click Paste.

    3. In the New Rule Name dialog box, type SetGlobalBankEastItinerary, and then click OK.

    4. In Policy Explorer, click the SetGlobalBankEastItinerary rule.

    5. In the Conditions section, right-click GlobalBankWest, and then click Reset argument.

    6. Click argument2, and then type GlobalBankEast.

    7. In the Actions section, right-click GlobalBankWestItinerary, and then click Reset argument.

    8. Click <empty string> and then type GlobalBankEastItinerary.

      Note
      Later in this How-to topic, you will create this itinerary to process messages from GlobalBank East.

    To publish and deploy the policy

    1. In Policy Explorer, under the ResolveItineraryBasedOnCustomer policy, click Version 1.0 (not saved), and then click Publish.

    2. In Policy Explorer, under the ResolveItineraryBasedOnCustomer policy, click Version 1.0 - Published, and then click Deploy.

    To create an ESB itinerary DSL model for GlobalBank West messages

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, in the Templates pane, click ItineraryDsl.

    4. In the Name box, type GlobalBankWestItinerary, and then click Add.

    To configure the properties of the GlobalBank West itinerary

    1. In Visual Studio, click the design surface of GlobalBankWestItinerary.itinerary. In the GlobalBankWestItinerary Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click Database Itinerary Exporter.

      2. Click the ellipsis button (...) next to the Itinerary Database property.

      3. In the Connection Properties dialog box, choose the SQL Server that hosts the itinerary repository database, and then specify the name of the database (the default name is EsbItineraryDb).

    2. In the Itinerary Status drop-down list, click Deployed.

      Note
      This step enables you to export the itinerary to a central repository; itineraries can be selected and attached from this repository when messages are received. You will later configure the Itinerary Selector pipeline component to use the BRI resolver to evaluate inbound messages and select the appropriate itinerary from this repository.

    To define the structure of the GlobalBank West itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the ReceiveNAOrder model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendNAOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    3. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the ReceiveNAOrder model element and the SendNAOrder model element. In the ItineraryService1 properties window, configure the following properties:

      1. Click the Name property, and then type RouteMessage.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Itinerary Service Extension.

      3. In the Off-Ramp drop-down list, expand SendNAOrder, and then click Send Handlers.

    4. Right-click the Resolver collection of the RouteMessage model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type StaticResolver.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\West%MessageID%.xml.

    5. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the RouteMessage model element.

    6. In the Toolbox, click Connector. Drag a connection from the RouteMessage model element to the SendNAOrder model element.

    To export the GlobalBank West model to the itinerary database

    1. In Visual Studio, right-click the design surface of the GlobalBankWestItinerary itinerary, and then click Export Model.

      Note
      The itinerary has been exported to the itinerary database and can now be used by the Itinerary Selector component.

    2. Save all project artifacts.

    To create an ESB itinerary DSL model for GlobalBank East message

    1. In Visual Studio 2013, open C:\HowTos\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, in the Templates pane, click ItineraryDsl.

    4. In the Name box, type GlobalBankEastItinerary, and then click Add.

    To configure the properties of the GlobalBank East itinerary

    1. In Visual Studio, click the design surface of GlobalBankEastItinerary.itinerary. In the GlobalBankEastItinerary Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click Database Itinerary Exporter.

      2. Click the ellipsis button (...) next to the Itinerary Database property.

      3. In the Connection Properties dialog box, choose the SQL Server that hosts the itinerary repository database, and then specify the name of the database (the default name is EsbItineraryDb).

    2. In the Itinerary Status drop-down list, click Deployed.

      Note
      This step enables you to export the itinerary to a central repository; itineraries can be selected and attached from this repository when messages are received. You will later configure the Itinerary Selector pipeline component to use the BRI resolver to evaluate inbound messages and select the appropriate itinerary from this repository.

    To define the structure of the GlobalBank East itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the ReceiveNAOrder model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendNAOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    3. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the ReceiveNAOrder model element and the SendNAOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type RouteMessage.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Itinerary Service Extension.

      3. In the Off-Ramp drop-down list, expand SendNAOrder, and then click Send Handlers.

    4. Right-click the Resolver collection of the RouteMessage model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type StaticResolver.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\East%MessageID%.xml.

    5. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the RouteMessage model element.

    6. In the Toolbox, click Connector. Drag a connection from the RouteMessage model element to the SendNAOrder model element.

    To export the GlobalBank East model to the itinerary database

    1. In Visual Studio, right-click the design surface of the GlobalBankEastItinerary itinerary, and then click Export Model.

      Note
      The itinerary has been exported to the itinerary database and can now be used by the Itinerary Selector component.

    2. Save all project artifacts.

    Steps

    To create and configure an ESB on-ramp

    1. Click Start on the taskbar, point to All Programs, point to BizTalk Server 2013 R2, and then click BizTalk Server Administration.

    2. In the BizTalk Server 2013 R2 Administration Console, expand BizTalk Group, expand Applications, and then expand Microsoft.Practices.ESB.

    3. Right-click Receive Locations, point to New, and then click One-way Receive Location.

    4. In the Select a Receive Port dialog box, click OnRamp.Itinerary, and then click OK.

    5. In the Receive Location Properties dialog box, in the Name box, type OnRamp.Itinerary.HowTo.

    6. In the Type drop-down list, click FILE, and then click Configure.

    7. In the FILE Transport Properties dialog box, in the Receive folder box, type C:\HowTos\DropFolder, and then click OK.

    To configure the Itinerary Selector pipeline component

    1. In the Receive Location Properties dialog box, click ItinerarySelectReceiveXml in the Receive pipeline drop-down list, and then click the ellipsis button (...).

    2. Use the Configure Pipeline dialog box to configure the following Itinerary Selector component properties:

      1. Click the ItineraryFactKey property, and then type Resolver.Itinerary.

      2. Click the ResolverConnectionString property, and then type BRI:\\policy=ResolveItineraryBasedOnCustomer;useMsg=true;recognizeMessageFormat=true;

      3. Click OK to close the Configure Pipeline dialog box.

        Note
        Because this receive location is disassembling an XML interchange, no XML Disassembler component configuration is required.

    3. Click OK to close the Receive Location Properties dialog box.

    4. In the BizTalk Server 2013 R2 Administration Console, right-click the OnRamp.Itinerary.HowTo receive location, and then click Enable.

    To test the Itinerary Selector and business rules

    1. In Windows Explorer, browse to C:\HowTos.

    2. Copy (do not move) Batch.xml to the DropFolder folder.

    3. Browse to C:\HowTos\Out. Verify that one West%MessageID%.xml message and two East%MessageID%.xml messages have been written to the directory.

      Note
      Although the messages are identical except for the value of the customer element, they were processed using different itineraries, based on the resolution of the Itinerary Selector pipeline component.

    4. In the BizTalk Server 2013 R2 Administration Console, right-click the OnRamp.Itinerary.HowTo receive location, and then click Disable.

    5. After the OnRamp.Itinerary.HowTo receive location is disabled, right-click it, and then click Delete. In the Confirm delete receive location dialog box, click Yes.

    Additional Resources

    For more information, see the following related topics:

    • How to: Select an Itinerary Using a Business Rules Policy

    • Development Activities

    • Installing and Running the Dynamic Resolution Sample

    • Using Dynamic Resolution and Routing

    • Message Routing Patterns


How to: Convert a Text Document to XML and Route to a File Location Using an Itinerary Routing Slip

Goal

The section demonstrates how to create a pipeline that will convert a text document to XML and then select the appropriate itinerary and route the message to a FILE location.

In this How-to topic, you will complete the following steps:

  • Use a pipeline to receive a flat file document and convert it to XML.

  • Configure the Itinerary Selector pipeline component to resolve the appropriate routing slip.

  • Create an on-ramp that uses the custom pipeline.

  • Test itinerary-based routing of a flat file message.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Before You Begin

    Complete the following tasks before you perform the steps later in this How-to topic:

    • Deploy the DataFormatTransformation itinerary.

    • Create the test message.

    The following procedures describe how to do each of these.

    To deploy the DataFormatTransformation itinerary

    1. In Visual Studio 2013, open C:\Projects\Microsoft.Practices.ESB\Source\Samples\DataFormatTransformation\DataFormatTransformation.sln.

    2. In Solution Explorer, in the Itinerary.Library project, double-click DataFormatTransformation.itinerary to open it in the Itinerary Designer.

    3. In Visual Studio, click the design surface of DataFormatTransformation.itinerary. In the DataFormatTransformation.itinerary Properties window, configure the following properties:

      1. In the Itinerary Status drop-down list, click Deployed.

      2. In the Model Exporter drop-down list, click Database Itinerary Exporter.

      3. Click the ellipsis button (...) next to the Itinerary Database property.

      4. In the Connection Properties dialog box, choose the SQL Server that hosts the itinerary repository database, and then specify the name of the database (the default name is EsbItineraryDb).

    4. Save all project artifacts.

    5. In Visual Studio, right-click the design surface of the DataModelTransformation itinerary, and then click Export Model.

    To create the receive pipeline

    1. In Visual Studio, right-click DataFormatTransformation.Schemas, and then click Properties. Click Application, and then type GlobalBank.ESB.DataFormatTransformation.Schemas in the Assembly name box.

    2. Right-click DataFormatTransformation.Schemas, and then click Properties. Click Signing, and then verify that the Sign the assembly check box is selected and that the assembly location points to .\..\..\..\..\..\keys\Microsoft.Practices.ESB.snk.

    3. Right-click DataFormatTransformation.Pipelines, and then click Remove.

    4. Right-click DataFormatTransformation, point to Add, and then click New Project. Click Biztalk Projects, and then click Empty Biztalk Server Project. In the Name box, type DataFormatTransformationReceive.Pipeline.

    5. Right-click DataFormatTransformationReceive.Pipeline, and then click Properties. Click Signing, and then verify that the Sign the assembly check box is selected and that the assembly location points to C:\projects\Microsoft.Practices.ESB\keys\Microsoft.Practices.ESB.snk.

    6. Right-click DataFormatTransformationReceive.Pipeline, point to Add, and then click New Item.

    7. In the Add New Item dialog box, click Receive Pipeline in the Templates pane. In the Name box, type ItinerarySelectReceiveFF, and then click Add.

    8. Right-click References for the DataFormatTransformationReceive.Pipeline project, and then click Add Reference. Click the Projects tab, and then click DataFormatTransformation.Schemas. Click OK to add the reference.

    9. From the Toolbox, drag a Flat file disassembler pipeline component to the Disassemble stage of the pipeline.

    10. In the Properties window for the flat file disassemble, click DataModelTransformation.Schemas.NAOrderDocFF in the Document schema drop-down list.

    11. From the Toolbox, drag an ESB Itinerary Selector pipeline component to the Resolve Party stage of the pipeline.

    12. From the Toolbox, drag an ESB Dispatcher pipeline component to the Resolve Party stage of the pipeline, and then place it under the ESB Itinerary Selector pipeline component.

    13. Save all project artifacts.

    To create the test message

    1. Click once in the NAOrderDocFF.xsd schema file of the DataFormatTransformation.Schemas project. In the Properties pane of Visual Studio, change the following two properties:

      • Generate Instance Output Type. Click the drop-down list for this property to change it to Native.

      • Output Instance Filename. Click the ellipsis button (…) for this property and accept the default path of C:\Projects\Microsoft.Practices.ESB\Source\Samples\DataFormatTransformation. In the File name box, type NAOrderDocFF, and then click Save.

    2. Right-click NAOrderDocFF.xsd under DataFormatTransformation.Schemas, and then click Generate Instance. At this point, you should have a new file generated in the C:\Projects\Microsoft.Practices.ESB\Source\Samples\DataFormatTransformation directory.

    3. Copy (do not move) the file NAOrderDocFF.txt from C:\Projects\Microsoft.Practices.ESB\Source\Samples\DataFormatTransformation to C:\HowTos.

      Note
      This is the message you will receive and convert to XML. This document represents a flat file version of North American Order document.

    Steps

    To deploy the receive pipeline and the schema

    1. Right-click DataFormatTransformationReceive.Pipeline, and then click Properties. Click Deployment, and then type Microsoft.Practices.ESB in the Application Name box.

    2. Right-click the DataFormatTransformation.Schemas project, and then click Properties. Click Deployment, and then type Microsoft.Practices.ESB in the Application Name box.

    3. Close the Properties panes for both DataFormatTransformationReceive.Pipeline and DataFormatTransformation.Schemas.

    4. In Solution Explorer, right-click the DataFormatTransformation project, and then click Deploy Solution.

    To create and configure an ESB on-ramp

    1. Click Start on the taskbar, point to All Programs, point to BizTalk Server 2013 R2, and then click BizTalk Server Administration.

    2. In the BizTalk Server 2013 R2 Administration Console, expand BizTalk Group, expand Applications, and then click Microsoft.Practices.ESB.

    3. Right-click Receive Locations, point to New, and then click One-way Receive Location.

    4. In the Select a Receive Port dialog box, click OnRamp.Itinerary, and then click OK.

    5. In the Receive Location Properties dialog box, in the Name box, type OnRamp.Itinerary.FlatFile.FILE.

    6. In the Type drop-down list, click FILE, and then click Configure.

    7. In the FILE Transport Properties dialog box, in the Receive Folder box, type C:\HowTos\DropFolder.

    8. In the FILE Transport Properties dialog box, in the File mask box, type *.txt, and then click OK.

    To configure the Itinerary Selector pipeline component

    1. In the Receive Location Properties dialog box, click ItinerarySelectReceiveFF in the Receive pipeline drop down list, and then click the ellipsis button (...).

    2. Use the Configure Pipeline dialog box to configure the following Itinerary Selector component properties:

      1. Click the ItineraryFactKey property, and then type Resolver.Itinerary.

      2. Click the ResolverConnectionString property, type ITINERARY:\\name=DataFormatTransformation; and then click OK.

    3. Click OK to close the Receive Location Properties dialog box.

    4. In the BizTalk Server 2013 R2 Administration Console, right-click the OnRamp.Itinerary.FlatFile.FILE receive location, and then click Enable.

    To test itinerary-based routing of a flat file message

    1. In Windows Explorer, browse to C:\HowTos.

    2. Copy (do not move) NAOrderDocFF.txt to C:\HowTos\DropFolder.

    3. Browse to C:\HowTos\Out. Verify that the DFT%MessageID%.xml message has been written to the directory.

    4. In the BizTalk Server 2013 R2 Administration Console, right-click the OnRamp.Itinerary.FlatFile.FILE receive location, and then click Disable.

    5. After the OnRamp.Itinerary.FlatFile.FILE receive location is disabled, right-click it, and then click Delete. In the Confirm delete receive location dialog box, click Yes.

    Additional Resources

    For more information, see the following related topics:

    • How to: Transform a Message and Route the Resulting Message to a File Location Using an Itinerary Routing Slip

    • How to: Route a Single Message to Multiple Recipients Using an Itinerary Routing Slip

    • Development Activities

    • Message Transformation Patterns


How to: Create an Itinerary to Dynamically Route a Message to an Email Address Using an LDAP Query

Goal

This section demonstrates how to create an itinerary that queries an e-mail address through LDAP (Lightweight Directory Access Protocol) and then sends an e-mail message to the resolved endpoint using the BizTalk Server 2013 R2 SMTP adapter.

In this How-to topic, you will complete the following steps:

  • Create an itinerary routing slip to dynamically route a message using an LDAP query.

  • Test the itinerary using the Itinerary Test Client sample application.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

The computer on which you will complete this section must have Microsoft Active Directory directory service configured and running (it is not required that the computer is the domain controller, but it must be connected to the domain). Also, an SMTP server must be configured and running; in order to test the outcome of this How-to topic, you must have a client with which to check the e-mail sent by the ESB.

The instructions in this section assume an organization named Global Bank, with a domain of globalbank.com, with an Active Directory Organizational Unit named Employees that contains a user named John Evans with a valid e-mail address in his profile (such as johne@globalbank.com). It is not necessary to replicate these environmental factors; however, for purposes of recreating this implementation in your environment, please account for these factors and make substitutions as necessary.

    Steps

    To create an ESB itinerary domain-specific language (DSL) model

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, type LdapResolution in the Name box, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of LdapResolution.itinerary. In the LdapResolution Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

      2. Under the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

      3. In the Select XML File dialog box, type C:\HowTos\Itineraries\LdapResolution in the File name box, and then click Save.

        Note
        This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it to the right of the On-Ramp model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type RouteMessageEmail.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

        Note
        This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing.

    3. Right-click the Resolver collection of the RouteMessageEmail model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type LdapResolver.

      2. In the Resolver Implementation drop-down list, click LDAP Resolver Extension.

      3. In the Transport Name drop-down list, click SMTP.

      4. Click the Transport Location property, and then type {mail}

      5. Click the SearchRoot property, and then type ou=Employees,dc=globalbank,dc=com

        Note
        If you have not set up your environment according to the specifications in the "Prerequisites" section, replace the values in the preceding property with ones that are appropriate for your environment.

      6. Click the Filter property, and then change the value to (&(objectClass=User)(|(givenName=john)))

        Note
        Type the preceding value to replace the existing text.

      7. In the ThrowErrorIfNotFound drop-down list, click True.

    4. In the Properties window, click the Endpoint Configuration property, and then click the ellipsis button (...).

      1. In the Endpoint Configuration dialog box, click the EmailBodyText property, and then type Order is ready to be processed.

      2. Click the From property, and then type orders@globalbank.com.

      3. Click the MessagePartsAttachment property, and then type 2.

      4. Click the Subject property, and then type Order for {givenName}.

      5. Configure the SMTPAuthentication, SMTPHost, UserName, and Password properties using the connection information for your local environment.

      6. Click OK to close the Endpoint Configuration dialog box.

    5. Right-click the LdapResolver resolver, and then click Test Resolver Configuration.

    6. In the Output window, verify the subject in the resolved Endpoint Configuration value is Order for John, and then verify that the resolved Transport Location is the e-mail address associated with the user's account in Active Directory (for example, johne@globalbank.com).

    7. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the RouteMessageEmail model element.

    8. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the RouteMessageEmail model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type EmailNAOrderDoc.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    9. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the RouteMessageEmail model element and the EmailNAOrderDoc model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilter.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand EmailNAOrderDoc, and then click Send Handlers.

    10. In the Toolbox, click Connector. Drag a connection from the RouteMessageEmail model element to the SendPortFilter model element.

    11. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the EmailNAOrderDoc model element.

    To export the model for use with the Itinerary Test Client

    1. In Visual Studio, right-click the design surface of the LdapResolution itinerary, and then click Export Model.

      Note
      The XML version of the itinerary opens in Visual Studio.

    2. Save all project artifacts.

    3. In Windows Explorer, browse to C:\HowTos\Itineraries and notice the creation of your itinerary XML (LdapResolution.xml).

    To test the itinerary

    1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

    2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

    3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select LdapResolution.xml, and then click Open to load the itinerary.

    4. Click OK to clear the Itinerary Loaded Successfully message.

    5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

    6. In the Select XML Document to load dialog box, browse to C:\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

    7. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

    8. Open Microsoft Outlook Express (or the mail client of your choice) and verify delivery of the message to the e-mail of John Evans.

    Additional Resources

    For more information, see the following related topics:

    • Development Activities

    • Using Dynamic Resolution and Routing


How to: Implement Content-Based Routing Using a Business Rules Policy for a Known Message Type

Goal

This section demonstrates how to create an itinerary that dynamically routes a message, based on the content of a known message type (schema deployed to the Microsoft BizTalk Server Configuration database), using a business rules policy.

In this How-to topic, you will complete the following steps:

  • Create a business rules policy that will be used to route a message based on content.

  • Create an itinerary routing slip with a BRE resolver to dynamically route a message.

  • Test the itinerary using the Itinerary Test Client sample application.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Before You Begin

    Complete the following tasks before you perform the steps later in this How-to topic:

    • Create the GlobalBank West test message.

    • Create the GlobalBank East test message.

    The following procedures describe how to do each of these.

    To create the GlobalBank West test message

    1. In Windows Explorer, browse to C:\HowTos.

    2. Create a copy of NAOrderDoc.xml, and then name the copy West.xml.

    3. In Notepad, open West.xml, and then change the value of the customerName element to GlobalBankWest.

    4. Save West.xml as UTF-8, and then close Notepad.

    To create the GlobalBank East test message

    1. In Windows Explorer, browse to C:\HowTos.

    2. Create a copy of NAOrderDoc.xml, and then name the copy East.xml.

    3. In Notepad, open East.xml, and then change the value of the customerName element to GlobalBankEast.

    4. Save East.xml as UTF-8, and then close Notepad.

    Steps

    To create a BRE policy to route using custom message properties

      This rule will use the customer's name to dynamically set the endpoint used to route the message.

      1. Click Start on the taskbar, point to All Programs, point to BizTalk Server 2013 R2, and then click Business Rule Composer.

      2. In Policy Explorer, right-click Policies, and then click Add New Policy. Name the policy RouteBasedOnCustomerKnownType.

      To add a routing rule for customer GlobalBank West

      1. In the RouteBasedOnCustomerKnownType policy, right-click Version 1.0 (not saved), and then click Add New Rule. Name the rule SetWestEndpoint.

      2. In Facts Explorer, click the XML Schemas tab, right-click Schemas, and then click Browse.

      3. In the Schema Files dialog box, browse to C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Source\ESB.DynamicResolution.Schemas, select NAOrderDoc.xsd, and then click Open.

        Note
        This is the schema that defines the NAOrderDoc.xml message, which was used to create the West and East messages you will use for testing.

      4. In Facts Explorer, click NAOrderDoc.xsd, and then in the Properties pane, click the Document Type property, and then type GlobalBank.ESB.DynamicResolution.Schemas.NAOrderDoc.

        Note
        This is the fully qualified name of the schema.

      5. In Facts Explorer, expand NAOrderDoc.xsd, and then expand OrderDoc.

      6. In the Rule window, right-click Conditions, point to Predicates, and then click Equal.

      7. From Facts Explorer, drag the customerName element to the argument1 node under Conditions.

      8. Click the argument2 node, and then type GlobalBankWest.

      9. In Facts Explorer, click the Vocabularies tab, expand ESB.EndPointInfo, and then expand Version 1.0.

        Note
        The ​Microsoft BizTalk ESB Toolkit includes several vocabularies that can be used for creating rules for use in the ESB. Some of these should be replaced or augmented with your own vocabularies. For example, the DynamicRunTimeMaptypes has definitions for the maps provided in the GlobalBank samples.

      10. From Facts Explorer, drag the Set End Point Outbound Transport Location definition to Actions.

      11. Click <empty string> and then type C:\HowTos\Out\West%MessageID%.xml.

      12. From Facts Explorer, drag the Set End Point Outbound Transport Type definition to Actions.

      13. In Facts Explorer, expand ESB.TransportTypes, expand Version 1.0, and then drag the Adaptor Providers definition to <empty string>.

      14. In the Actions pane, expand the Adaptor Providers drop-down list, and then click FILE.

      To add a routing rule for customer GlobalBank East

      1. In Policy Explorer, right-click the SetWestEndpoint rule, and then click Copy.

      2. Right-click Version 1.0 (not saved), and then click Paste.

      3. In the New Rule Name dialog box, type SetEastEndpoint, and then click OK.

      4. In Policy Explorer, click the SetEastEndpoint rule.

      5. In the Conditions section, right-click GlobalBankWest, and then click Reset argument.

      6. Click argument2, and then type GlobalBankEast.

      7. In the Actions section, right-click C:\HowTos\Out\West%MessageID%.xml, and then click Reset argument.

      8. Click <empty string>, and then type C:\HowTos\Out\East%MessageID%.xml.

      To add a routing rule for unknown customers

      1. In the RouteBasedOnCustomerKnownType policy, right-click Version 1.0 (not saved), and then click Add New Rule. Name the rule SetUnknownCustomerEndpoint.

      2. In the Rule window, right-click Conditions, and then click Add logical AND.

      3. In the Rule window, right-click AND, point to Predicates, and then click NotEqual.

      4. In Facts Explorer, click the XML Schemas tab, expand NAOrderDoc.xsd, and then expand OrderDoc.

      5. From Facts Explorer, drag the customerName element to the argument1 node under Conditions.

      6. Click the argument2 node, and then type GlobalBankWest.

      7. In the Rule window, right-click AND, point to Predicates, and then click NotEqual.

      8. From Facts Explorer, drag the customerName element to the argument1 node under Conditions.

      9. Click the argument2 node, and then type GlobalBankEast.

      10. In Facts Explorer, click the Vocabularies tab, expand ESB.EndPointInfo, and then expand Version 1.0.

      11. From Facts Explorer, drag the Set End Point Outbound Transport Location definition to Actions.

      12. Click <empty string>, and then type C:\HowTos\Out\CustomerUnknown%MessageID%.xml.

      13. From Facts Explorer, drag the Set End Point Outbound Transport Type definition to Actions.

      14. In Facts Explorer, expand ESB.TransportTypes, expand Version 1.0, and then drag the Adaptor Providers definition to <empty string>.

      15. In the Actions pane, expand the Adaptor Providers drop-down list, and then click FILE.

      To publish and deploy the policy

      1. In Policy Explorer, under the RouteBasedOnCustomerKnownType policy, right click Version 1.0 (not saved), and then click Publish.

      2. In Policy Explorer, under the RouteBasedOnCustomerKnownType policy, right click Version 1.0 - Published, and then click Deploy.

      To create an ESB itinerary DSL model

      1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

      2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

      3. In the Add New Item dialog box, in the Name box, type CbrKnownType, and then click Add.

      To configure the properties of the itinerary

      1. In Visual Studio, click the design surface of CbrKnownType.itinerary. In the CbrKnownType Properties window, configure the following properties:

        1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

        2. In the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

        3. In the Select XML File dialog box, type C:\HowTos\Itineraries\CbrKnownType in the File name box, and then click Save.

          Note
          This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

      To define the structure of the itinerary

      1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

        1. Click the Name property, and then type ReceiveNAOrder.

        2. In the Extender drop-down list, click On-Ramp ESB Extender.

        3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

        4. In the Receive Port drop-down list, click OnRamp.Itinerary.

      2. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the ReceiveNAOrder model element. In the OffRamp1 Properties window, configure the following properties:

        1. Click the Name property, and then type SendRegionalOrders.

        2. In the Extender drop-down list, click Off-Ramp ESB Extender.

        3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

        4. In the Send Port drop-down list, click DynamicResolutionOneWay.

      3. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the ReceiveNAOrder model element and the SendRegionalOrders model element. In the ItineraryService1 Properties window, configure the following properties:

        1. Click the Name property, and then type SendPortFilter.

        2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

        3. In the Off-Ramp drop-down list, expand SendRegionalOrders, and then click Send Handlers.

      4. Right-click the Resolver collection of the SendPortFilter model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

        1. Click the Name property, and then type RouteRegionalOrders.

        2. In the Transport Name drop-down list, click BRE.

        3. In the Resolver Implementation drop-down list, click Bre Resolver Extension.

        4. In the Policy drop-down list, click RouteBasedOnCustomerKnownType.

        5. In the Recognize Message Format drop-down list click True.

        6. In the UseMsg drop-down list, click True.

          Note
          If you use the BRE Resolver Extension from orchestration, the recognizeMessageFormat property must be set to False.

      5. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the SendPortFilter model element.

      6. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendRegionalOrders model element.

      To export the model for use with the Itinerary Test Client

      1. In Visual Studio, right-click the design surface of the CbrKnownType itinerary, and then click Export Model.

        Note
        The XML version of the itinerary opens in Visual Studio.

      2. Save all project artifacts.

      3. In Windows Explorer, browse to C:\HowTos\Itineraries and notice the creation of your itinerary XML (CbrKnownType.xml).

      To test the itinerary and business rules

      1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

      2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

      3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select CbrKnownType.xml, and then click Open to load the itinerary.

      4. Click OK to clear the Itinerary Loaded Successfully message.

      5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

      6. In the Select XML Document to load dialog box, browse to C:\HowTos. Select West.xml, and then click Open to load the test message.

      7. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

      8. In Windows Explorer, browse to C:\HowTos\Out. Verify that the West%MessageID%.xml message has been written to the directory.

      9. Repeat the test process using the East.xml message.

      10. In Windows Explorer, browse to C:\HowTos\Out. Verify that the East%MessageID%.xml message has been written to the directory.

      11. Repeat the test process using the NAOrderDoc.xml message.

      12. In Windows Explorer, browse to C:\HowTos\Out. Verify that the CustomerUnknown%MessageID%.xml message has been written to the directory.

      Additional Resources

      For more information, see the following related topics:

      • How to: Select an Itinerary Using a Business Rules Policy

      • How to: Dynamically Route a Message Based on Message Context Using a Business Rules Policy

      • Development Activities

      • Message Routing Patterns


How to: Validate a Message Using an ESB On-Ramp

Goal

This section demonstrates how to configure the ESB Dispatcher Disassemble pipeline component to perform message validation for XML messages submitted to an ESB on-ramp.

In this How-to topic, you will complete the following steps:

  • Create an ESB on-ramp that uses the ItinerarySelectReceiveXml pipeline.

  • Configure the ESB Dispatcher Disassemble pipeline component to validate message content.

  • Configure the Itinerary Selector pipeline component to resolve the appropriate itinerary.

  • Test message validation using a valid message and an invalid message.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Before You Begin

    Complete the following tasks before you perform the steps later in this How-to topic:

    • Create an invalid test message.

    • Create an ESB itinerary domain-specific language (DSL) model.

    • Configure the properties of the itinerary.

    • Define the structure of the itinerary.

    • Export the model to the Itinerary database.

    The following procedures describe how to do each of these.

    To create an invalid test message

    1. In Windows Explorer, browse to C:\HowTos.

    2. Create a copy of NAOrderDoc.xml, and then rename the copy Invalid.xml.

    3. In Notepad, open Invalid.xml.

    4. Change <ns0:requestType>10</ns0:requestType> to <ns0:requestType>TEN</ns0:requestType>.

    5. Save Invalid.xml as UTF-8, and then close Notepad.

      Note
      By changing the numerical value of this element to text, the message will no longer be valid according to the schema.

    To create an ESB itinerary DSL model

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click ItineraryLibrary, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, type Validation in the Name box, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of Validation.itinerary. In the Validation Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click Database Itinerary Exporter.

      2. Click the ellipsis button (...) next to the Itinerary Database property.

      3. In the Connection Properties dialog box, choose the SQL Server that hosts the itinerary repository database, and then specify the name of the database (the default name is EsbItineraryDb).

    2. In the Itinerary Status drop-down list, click Deployed.

      Note
      This step enables you to export the itinerary to a central repository; itineraries can be selected and attached from this repository when the message is received. You will later configure the Itinerary Selector pipeline component to use a static resolver to select the appropriate itinerary from this repository.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the existing model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendNAOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    3. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the ReceiveNAOrder model element and the SendNAOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilter.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand SendNAOrder, and then click Send Handlers.

    4. Right-click the Resolver collection of the SendPortFilter element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type ConfigureOffRamp.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\Validated%MessageID%.xml.

    5. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the SendPortFilter model element.

    6. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendNAOrder model element.

    To export the model to the itinerary database

    1. In Visual Studio, right-click the design surface of the Validation itinerary, and then click Export Model.

      Note
      The itinerary has been exported to the itinerary database and can now be used by the Itinerary Selector pipeline component.

    2. Save all project artifacts.

    Steps

    To create and configure an ESB on-ramp

    1. Click Start on the taskbar, point to All Programs, point to BizTalk Server 2013 R2, and then click BizTalk Server Administration.

    2. In the BizTalk Server 2013 R2 Administration Console, expand BizTalk Group, expand Applications, and then expand Microsoft.Practices.ESB.

    3. Right-click Receive Locations, point to New, and then click One-way Receive Location.

    4. In the Select a Receive Port dialog box, click OnRamp.Itinerary, and then click OK.

    5. In the Receive Location Properties dialog box, type OnRamp.Itinerary.HowTo in the Name box.

    6. In the Type drop-down list, click FILE, and then click Configure.

    7. In the FILE Transport Properties dialog box, type C:\HowTos\DropFolder in the Receive folder box, and then click OK.

    To configure the on-ramp to perform message validation

    1. In the Receive Location Properties dialog box, in the Receive pipeline drop-down list, click ItinerarySelectReceiveXml, and then click the ellipsis button (...).

    2. Use the Configure Pipeline dialog box to configure the following XML disassembler component properties:

      1. Expand the GlobalBank.Esb application, and then click Schemas. Right-click GlobalBank.ESB.DynamicResolution.Schemas.NAOrderDoc, and then click Properties. Copy the Name and Assembly properties and paste them into a text file.

      2. In the Disassemble component, click True in the ValidateDocument drop-down list.

      3. Click the DocumentSpecNames property, and then type the fully qualified name of the schema. The fully qualified name starts with the name and is followed by a comma and the assembly information extracted in step a. The following is an example:

        GlobalBank.ESB.DynamicResolution.Schemas.NAOrderDoc, GlobalBank.ESB.DynamicResolution.Schemas, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c2c8b2b87f54180a

        Note
        This is the fully qualified name of the schema to be validated; it is comprised of the schema name and four assembly properties: assembly name, version, culture, and public key token. Multiple values are allowed; separate multiple schemas with a pipe (|) symbol.

    To configure the Itinerary Selector Pipeline component

    1. In the Configure Pipeline dialog box, configure the following Itinerary Selector component properties:

      1. Click the ItineraryFactKey property, and then type Resolver.Itinerary.

      2. Click the ResolverConnectionString property, and then type ITINERARY:\\name=Validation;.

      3. Click OK to close the Configure Pipeline dialog box.

    2. Click OK to close the Receive Location Properties dialog box.

    3. In the BizTalk Server 2013 R2 Administration Console, right-click the OnRamp.Itinerary.HowTo receive location, and then click Enable.

    To test the message validation and itinerary selection

    1. In Windows Explorer, browse to C:\HowTos.

    2. Copy (do not move) NAOrderDoc.xml to the DropFolder folder.

    3. Browse to C:\HowTos\Out. Verify that Validated%MessageID%.xml has been written to the directory.

      Note
      The valid message completed its itinerary-based routing, as expected.

    4. Delete Validated%MessageID%.xml from the Out folder.

    5. In Windows Explorer, browse to C:\HowTos.

    6. Copy (do not move) Invalid.xml to the DropFolder folder.

    7. Browse to C:\HowTos\Out. Verify that no new message has been delivered.

      Note
      The message could not be validated; therefore, itinerary-based routing could not be completed.

    8. Click Start on the taskbar, point to Administrative Tools, and then click Event Viewer.

    9. In Event Viewer, expand Windows Logs, and then click Application.

    10. Locate a recent event where the Source is BizTalk Server 2013 R2, and the Event ID is 5719.

      Note
      The submission and failure of the invalid message resulted in an exception entry to the application event log.

    11. In the BizTalk Server 2013 R2 Administration Console, right-click the OnRamp.Itinerary.HowTo receive location, and then click Disable.

    12. After the OnRamp.Itinerary.HowTo receive location is disabled, right-click it, and then click Delete. In the Confirm delete receive location dialog box, click Yes.

    Additional Resources

    For more information, see the following related topics:

    • How to: Select an Itinerary Using a Business Rules Policy

    • Development Activities

    • Installing and Running the Dynamic Resolution Sample


How to: Publish a Service to the UDDI 3.0 Registry

Goal

This section demonstrates how to use the UDDI Service site to publish a Web service endpoint that can be resolved from within an itinerary for the purpose of routing an ESB message. You will duplicate the existing PurchaseOrderSubmitOrderService service presently published to the registry.

In this How-to topic, you will complete the following steps:

  • Publish a service to the Universal Description, Discovery, and Integration (UDDI) 3 registry using the UDDI Publisher tool.

  • Test the service publication using an itinerary routing slip that resolves the service endpoint using a UDDI3 resolver.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities and the execution of the UDDI Publisher tool (you can install it at %ESB Install Folder%\Bin\Microsoft.Practices.ESB.UDDIPublisher.exe).

    Steps

    To create the NewPOService in the UDDI registry

    1. In Internet Explorer, browse to the UDDI Service site (by default, the URL for this is http://localhost/uddi).

    2. On the uddi Services page, click Publish.

    3. In the Publish pane, right-click Microsoft.Practices.ESB, and then click Add Service.

    4. On the following page, select Specify a key to use, and then click Continue.

    5. On the following page, click the esb key partition. In the Key Suffix box, type newposervice, and then click Continue.

    6. On the following page, next to (New Service Name), click Edit. Name the service NewPOService, and then click Update.

    7. Click Add Description, type a description for the service (for example, Sample Service), and then click Update.

    To add a binding for the NewPOService

    1. Click the Bindings tab, and then click Add Binding.

    2. Select Specify a key to use, and then click Continue.

    3. On the following page, click the esb key partition. In the Key Suffix box, type newposervicebinding, and then click Continue.

    4. Under Access Point, click Edit, and then complete the following:

      1. In the Access Point box, type http://localhost/ESB.CanadianServices/SubmitPOService.asmx.

      2. In the Use Type drop-down list, click endpoint, and then click Update.

    To configure the binding instance information

    1. Click the Instance Info tab, and then click Add Instance Info.

    2. In the Search for tModel names containing box, type %esb% and then click Search.

    3. Locate and click the tModel for transporttype.

      Note
      To complete the remaining steps in this procedure, you may be required to change between page 1 and page 2.

    4. In the Descriptions section, click Add Description.

    5. In the Description box, type Transport Type for ESB Itinerary Use, and then click Update.

    6. Click the Instance Details tab, and then click Edit.

    7. In the Instance Parameters box, type WCF-BasicHttp, and then click Update.

    8. In the Descriptions section, click Add Description.

    9. In the Description box, type WCF Basic HTTP Transport, and then click Update.

    10. In the Publish pane, under NewPOService, click http://localhost/esb.canadianservices/submitposervice.asmx.

    11. On the Instance Info tab, click Add Instance Info.

    12. Using the steps described earlier, add the following instance information, according to the values shown in the following table.

      tModel Description Parameter Parameter description

      microsoft-com:esb:runtimeresolution:messageexchangepattern

      Message Exchange Pattern

      Two-Way

      Two-way operation

      microsoft-com:esb:runtimeresolution:cachetimeout

      Cache Timeout

      -1

      Currently disabled

      microsoft-com:esb:runtimeresolution:jaxrpcresponse

      JaxRpcResponse

      false

      microsoft-com:esb:runtimeresolution:action

      Service Action

      submitOrder

      Specifies the service method to invoke

      microsoft-com:esb:runtimeresolution:targetnamespace

      Service Namespace

      http://globalbank.esb.dynamicresolution.com/canadianservices

      Target namespace

    To configure the binding categorization

    1. In the Publish pane, under NewPOService, click http://localhost/esb.canadianservices/submitposervice.asmx.

    2. On the Categories tab, click Add Custom Category.

    3. In the Search box, type %esb% and then click Search.

    4. Locate and click the microsoft-com:esb:runtimeresolution:biztalkapplication tModel.

    5. In the Key Name box, type BizTalk Application.

    6. In the Key Value box, type Microsoft.Practices.ESB, and then click Add Category.

    7. Using the steps described earlier, add the following custom categories, according to the values shown in the following table.

      tModel Key name Key value

      microsoft-com:esb:runtimeresolution:portname

      Port Name

      NewPOService

      microsoft-com:esb:runtimeresolution:transporttype

      Transport Type

      WCF-BasicHttp

    To locate the service in the UDDI registry

    1. In Internet Explorer, on the uddi Services page, click Search.

    2. Click the Services tab.

    3. In the Service Name box, type %PO%, and then click Search.

    4. In the Search pane, on the Results tab, click NewPOService.

      Note
      This confirms the service was successfully published to the registry.

    To create an itinerary model to test the UDDI service publication

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, in the Name box, type NewBindingKeySearch, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of NewBindingKeySearch.itinerary. In the NewBindingKeySearch Properties window, configure the following properties:

      1. In the Is Request Response drop-down list, click True.

      2. In the Model Exporter drop-down list, click XML Itinerary Exporter.

      3. In the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

      4. In the Select XML File dialog box, type C:\HowTos\Itineraries\NewBindingKeySearch in the File name box, and then click Save.

        Note
        This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.Response.

    2. From the Toolbox, drag an Itinerary Service model element to the design surface. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type TransformNAOrder.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Transform.

    3. Right-click the Resolver collection of the TransformNAOrder model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type NAOrder_to_CNOrder.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transform Type drop-down list, click GlobalBank.ESB.DynamicResolution.Transforms.SubmitOrderRequestNA_To_SubmitOrderRequestCN.

    4. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the TransformNAOrder model element.

    5. From the Toolbox, drag an Itinerary Service model element to the design surface. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type BindingKeyRoute.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing.

    6. Right-click the Resolver collection of the BindingKeyRoute model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type BindingKeySearch.

      2. In the Resolver Implementation drop-down list, click Uddi3 Resolver Extension.

      3. In the Resolver Moniker drop-down list, click UDDI3.

      4. Click the Binding key property, and then type uddi:esb:newposervicebinding. To find the key value, click the http://localhost/ESB.CanadianServices/SubmitPOService.asmx service in UDDI, and then click More Details.

    7. Right-click the BindingKeySearch resolver, and then click Test Resolver Configuration.

      Note
      Verify the output displayed in the Output window.

    8. In the Toolbox, click Connector. Drag a connection from the TransformNAOrder model element to the BindingKeyRoute model element.

    9. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the BindingKeyRoute model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendCNOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionSolicitResp.

    10. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the BindingKeyRoute model element and the SendCNOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilter.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand SendCNOrder, and then click Send Handlers.

    11. In the Toolbox, click Connector. Drag a connection from the BindingKeyRoute model element to the SendPortFilter model element.

    12. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendNAOrder model element.

    To export the model for use with the Itinerary Test Client

    1. In Visual Studio, right-click the design surface of the NewBindingKeySearch itinerary, and then click Export Model.

      Note
      The XML version of the itinerary opens in Visual Studio.

    2. Save all project artifacts.

    3. In Windows Explorer, browse to C:\HowTos\Itineraries and notice the creation of your itinerary XML (NewBindingKeySearch.xml).

    To test the itinerary

    1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

    2. In the Itinerary Test Client, in the Web Service Options group, clear the Use WCF Service box and then select the Two-Way Service check box.

    3. Click the Load Itinerary button.

    4. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select NewBindingKeySearch.xml, and then click Open to load the itinerary.

    5. Click OK to clear the Itinerary Loaded Successfully message.

    6. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

    7. In the Select XML Document to load dialog box, browse to C:\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

    8. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

    9. Verify that the correct response message appears in the Result text box of the Itineray Test Client.

    Additional Resources

    For more information, see the following related topics:

    • How to: Resolve a Service Endpoint Using a UDDI Binding Key Search

    • How to: Resolve a Service Endpoint Using a UDDI Category Search

    • Development Activities


How to: Resolve a Service Endpoint Using a UDDI Category Search

Goal

This section demonstrates how to use the ESB Designer domain-specific language (DSL) to create an itinerary-based routing slip that uses the Universal Description, Discovery, and Integration (UDDI) 3 resolver to locate a service endpoint using a category search. In this scenario, the service endpoint will be a file endpoint published in UDDI.

In this How-to topic, you will complete the following steps:

  • Create an itinerary routing slip to resolve a service endpoint.

  • Configure the itinerary to route the message to a service endpoint using a UDDI 3 resolver.

  • Test the itinerary using the Itinerary Test Client sample application.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Steps

    To create an itinerary model

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, type UDDI3CategorySearch in the Name box, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of UDDI3CategorySearch.itinerary. In the UDDI3CategorySearch Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

      2. Under the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

      3. In the Select XML File dialog box, type C:\HowTos\Itineraries\UDDI3CategorySearch in the File name box, and then click Save.

        Note
        This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Itinerary Service model element to the design surface. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type CategoryRoute.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing

    3. Right-click the Resolver collection of the CategoryRoute model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type CategorySearch.

      2. In the Resolver Implementation drop-down list, click Uddi3 Resolver Extension.

      3. In the Resolver Moniker drop-down list, click UDDI3.

      4. Click the Category Search property, and then click the ellipsis button (…).

      5. In the Name Value Property Editor dialog box, click Add.

      6. Click the Name property, and then type uddi:esb:biztalkapplication.

      7. Click the Value property, and then type GlobalBank.ESB.

      8. In the Name Value Property Editor dialog box, click Add.

      9. Click the Name property, and then type uddi:esb:portname.

      10. Click the Value property, and then type OrderFileServicev3.

      11. In the Name Value Property Editor dialog box, click Add.

      12. Click the Name property, and then type uddi:esb:version.

      13. Click the Value property, and then type 1.

      14. Click OK to close the Name Value Property Editor dialog box.

    4. Right-click the CategorySearch resolver, and then click Test Resolver Configuration.

      Note
      Verify the output displayed in the Output window.

    5. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the CategoryRoute model element.

    6. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the CategoryRoute model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendNAOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    7. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the CategoryRoute model element and the SendNAOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilter.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand SendNAOrder, and then click Send Handlers.

    8. In the Toolbox, click Connector. Drag a connection from the CategoryRoute model element to the SendPortFilter model element.

    9. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendNAOrder model element.

    To export the model for use with the Itinerary Test Client

    1. In Visual Studio, right-click the design surface of the UDDI3CategorySearch itinerary, and then click Export Model.

      Note
      The XML version of the itinerary opens in Visual Studio.

    2. Save all project artifacts.

    3. In Windows Explorer, browse to C:\HowTos\Itineraries and notice the creation of your itinerary XML (UDDI3CategorySearch.xml).

    To test the itinerary

    1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

    2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

    3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select UDDI3CategorySearch.xml, and then click Open to load the itinerary.

    4. Click OK to clear the Itinerary Loaded Successfully message.

    5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

    6. In the Select XML Document to load dialog box, browse to C:\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

    7. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

    8. In Windows Explorer, browse to C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Test\Filedrop\Out and verify that the %MessageID%.xml message has been written to the directory.

    Additional Resources

    For more information, see the following related topics:

    • How to: Resolve a Service Endpoint Using a UDDI Binding Key Search

    • Development Activities

    • Using Dynamic Resolution and Routing


How to: Resolve a Service Endpoint Using a UDDI Binding Key Search

Goal

This section demonstrates how to use the ESB Designer domain-specific language (DSL) to create an itinerary-based routing slip that uses the Universal Description, Discovery, and Integration (UDDI) 3 resolver to locate a service endpoint using a binding key search. In this scenario, the service endpoint will be a file endpoint published in UDDI.

In this How-to topic, you will complete the following steps:

  • Create an itinerary routing slip to resolve a service endpoint.

  • Configure the itinerary to route the message to a service endpoint using a UDDI 3 resolver.

  • Test the itinerary using the Itinerary Test Client sample application.

    Prerequisites

    The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

      Steps

      To create an itinerary model

      1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

      2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

      3. In the Add New Item dialog box, in the Name box, type UDDI3BindingKeySearch, and then click Add.

      To configure the properties of the itinerary

      1. In Visual Studio, click the design surface of UDDI3BindingKeySearch.itinerary. In the UDDI3BindingKeySearch Properties window, configure the following properties:

        1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

        2. Under the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

        3. In the Select XML File dialog box, type C:\HowTos\Itineraries\UDDI3BindingKeySearch in the File name box, and then click Save.

          Note
          This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

      To define the structure of the itinerary

      1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

        1. Click the Name property, and then type ReceiveNAOrder.

        2. In the Extender drop-down list, click On-Ramp ESB Extender.

        3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

        4. In the Receive Port drop-down list, click OnRamp.Itinerary.

      2. From the Toolbox, drag an Itinerary Service model element to the design surface. In the ItineraryService1 Properties window, configure the following properties:

        1. Click the Name property, and then type BindingKeyRoute.

        2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

        3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

        4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing.

      3. Right-click the Resolver collection of the BindingKeyRoute model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

        1. Click the Name property, and then type BindingKeySearch.

        2. In the Resolver Implementation drop-down list, click Uddi3 Resolver Extension.

        3. In the Resolver Moniker drop-down list, click UDDI3.

        4. Click the Binding key property, and then type uddi:esb:orderfileservicev3.1.

      4. Right-click the BindingKeySearch resolver, and then click Test Resolver Configuration.

        Note
        Verify the output displayed in the Output window.

      5. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the BindingKeyRoute model element.

      6. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the BindingKeyRoute model element. In the OffRamp1 Properties window, configure the following properties:

        1. Click the Name property, and then type SendNAOrder.

        2. In the Extender drop-down list, click Off-Ramp ESB Extender.

        3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

        4. In the Send Port drop-down list, click DynamicResolutionOneWay.

      7. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the BindingKeyRoute model element and the SendNAOrder model element. In the ItineraryService1 Properties window, configure the following properties:

        1. Click the Name property, and then type SendPortFilter.

        2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

        3. In the Off-Ramp drop-down list, expand SendNAOrder, and then click Send Handlers.

      8. In the Toolbox, click Connector. Drag a connection from the BindingKeyRoute model element to the SendPortFilter model element.

      9. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendNAOrder model element.

      To export the model for use with the Itinerary Test Client

      1. In Visual Studio, right-click the design surface of the UDDI3BindingKeySearch itinerary, and then click Export Model.

        Note
        The XML version of the itinerary opens in Visual Studio.

      2. Save all project artifacts.

      3. In Windows Explorer, browse to C:\HowTos\Itineraries and notice the creation of your itinerary XML (UDDI3BindingKeySearch.xml).

      To test the itinerary

      1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

      2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

      3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select UDDI3BindingKeySearch.xml, and then click Open to load the itinerary.

      4. Click OK to clear the Itinerary Loaded Successfully message.

      5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

      6. In the Select XML Document to load dialog box, browse to C:\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

      7. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

      8. In Windows Explorer, browse to C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Test\Filedrop\Out. Verify that the %MessageID%.xml message has been written to the directory.

      Additional Resources

      For more information, see the following related topics:

      • How to: Resolve a Service Endpoint Using a UDDI Category Search

      • Development Activities

      • Using Dynamic Resolution and Routing


How to: Enable BAM Tracking in an ESB Itinerary Service

Goal

This section demonstrates how to enable Business Activity Monitor (BAM) tracking for an existing itinerary.

In this How-to topic, you will complete the following steps:

  • Enable the property used for tracking Itinerary Services using Business Activity Monitor.

  • Test BAM tracking using the Itinerary Test Client sample application.

  • Verify the BAM results using a SQL query.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Before You Begin

    Complete the following tasks before you perform the steps later in this How-to topic:

    • Create an ESB itinerary domain-specific language (DSL) model.

    • Configure the properties of the itinerary.

    • Define the structure of the itinerary.

    The following procedures describe how to do each of these.

    To create an ESB itinerary DSL model

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, click ItineraryDsl in the Templates pane.

    4. In the Name box, type BamTracking, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of BamTracking.itinerary. In the BamTracking Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

      2. In the Extender Settings section, next to the Itinerary XML file property, click the ellipsis button (...).

      3. In the Select XML File dialog box, in the File name box, type C:\HowTos\Itineraries\BamTracking and then click Save.

        Note
        This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, enables testing of the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it to the right of the On-Ramp model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type MapNAOrderToCNOrder.

      2. In the Itinerary Service Extender drop-down list, click Messaging Itinerary Service Extension.

        Note
        This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Itinerary Service Extension.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Transform.

    3. Right-click the Resolver collection of the MapNAOrderToCNOrder model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type StaticallySpecifyTheMap.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transform Type drop-down list, click GlobalBank.ESB.DynamicResolution.Transforms.SubmitOrderRequestNA_To_SubmitOrderRequestCN.

      4. In the TransportName drop-down list, click FILE.

    4. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the MapNAOrderToCNOrder model element.

    5. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the MapNAOrderToCNOrder model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendCNOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Service Extension.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    6. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the MapNAOrderToCNOrder model element and the SendCNOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilter.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Itinerary Service Extension.

      3. In the Off-Ramp drop-down list, expand SendCNOrder, and then click Send Handlers.

    7. Right-click the Resolver collection of the SendPortFilter model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type ConfigureFolderSettings.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type C:\HowTos\Out\BAM%MessageID%.xml

        Note
        Each off-ramp will have an itinerary service associated with it; the combination of the itinerary service properties and the properties of the off-ramp define the subscription of the dynamic send port.

    8. In the Toolbox, click Connector. Drag a connection from the MapNAOrderToCNOrder model element to the SendPortFilter model element.

    9. In the Toolbox, click Connector. Drag a connection from the SendPortFilter model element to the SendCNOrder model element.

    10. Save all project artifacts.

    Steps

    To modify the itinerary

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, double-click BamTracking.itinerary.

    3. Click the MapNAOrderToCNOrder itinerary service element.

    4. In the MapNAOrderToCNOrder Properties window, click True in the Tracking Enabled drop-down list.

    5. Click the SendPortFilter itinerary service element.

    6. In the SendPortFilter Properties window, click True in the Tracking Enabled drop-down list.

    To export the model for use with the Itinerary Test Client

    1. In Visual Studio, right-click the design surface of the BamTracking itinerary, and then click Export Model.

      Note
      The XML version of the itinerary opens in Visual Studio.

    2. Save all project artifacts.

    3. In Windows Explorer, browse to C:\HowTos\Itineraries and notice the creation of your itinerary XML (BamTracking.xml).

    To test the itinerary

    1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

    2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

    3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select BamTracking.xml, and then click Open to load the itinerary.

    4. Click OK to clear the Itinerary Loaded Successfully message.

    5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

    6. In the Select XML Document to load dialog box, browse to C:\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

    7. Click the Submit Request button. When the test completes, click OK to dismiss the confirmation that appears.

    8. In Windows Explorer, browse to C:\HowTos\Out. Verify that the BAM%MessageID%.xml message has been written to the directory.

    To verify message tracking

    1. Click Start on the taskbar, point to All Programs, point to SQL Server 2014 or SQL Server 2012 SP1, and then click SQL Server Management Studio.

    2. Click New Query.

    3. In the query pane, type the following:

      Copy Code
      SELECT *
FROM [BAMPrimaryImport].[dbo].[bam_ItineraryServiceActivity_Completed]
GO

    4. Click Execute.

    5. In the Results pane, use the TimeStamp column to locate the most recent entry.

    Additional Resources

    For more information, see the following related topics:

    • Development Activities

    • Message Routing Patterns

    • Using Dynamic Resolution and Routing


How to: Implement Content-Based Routing Using Message Context Properties

Goal

This section demonstrates how to use the ​Microsoft BizTalk ESB Toolkit Itinerary Designer to create an itinerary that selects a message recipient based on the message context property and then routes a message to that recipient using the Itinerary Broker messaging service.

In this topic, you will complete the following steps:

  • Create an itinerary with an itinerary broker and two routing services with static resolvers.

  • Test the itinerary using the Itinerary Test Client sample application.

Note
No orchestration-based broker service is provided in the current implementation.

Prerequisites

The procedures in this How-to topic require the completion of the Prerequisites for the Development Activities.

    Steps

    To create an ESB Itinerary DSL model

    1. In Visual Studio 2013, open C:\HowTos\Patterns\Patterns.sln.

    2. In Solution Explorer, right-click ItineraryLibrary, point to Add, and then click New Itinerary.

    3. In the Add New Item dialog box, click ItineraryDsl in the Templates pane.

    4. In the Name box, type ChoiceRouter, and then click Add.

    To configure the properties of the itinerary

    1. In Visual Studio, click the design surface of the ChoiceRouter itinerary. In the ChoiceRouter Properties window, configure the following properties:

      1. In the Model Exporter drop-down list, click XML Itinerary Exporter.

      2. In the Extender Settings section, click the ellipsis button (...) next to the Itinerary XML file property.

      3. In the Export Mode property drop-down list, click Strict.

      4. In the Select XML File dialog box, type C:\HowTos\Itineraries\ChoiceRouter in the File name box, and then click Save.

      Note
      This step enables you to export the itinerary as XML to a local file location. By exporting an itinerary to a local file location, instead of to the itinerary database, you can test the itinerary using the ESB Test Client application. You will complete this process later in this How-to topic.

    To define the structure of the itinerary

    1. From the Toolbox, drag an On-Ramp model element to the design surface. In the OnRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type ReceiveNAOrder.

      2. In the Extender drop-down list, click On-Ramp Extender.

      3. In the BizTalk Application drop-down list, click Microsoft.Practices.ESB.

      4. In the Receive Port drop-down list, click OnRamp.Itinerary.

    2. From the Toolbox, drag an Itinerary Broker Service model element to the designer surface, and then place it to the right side of the On-Ramp model element. In the ItineraryBrokerService1, configure the following properties:

      1. Click the Name property, and then type RouteBrokerService.

      2. In the Extender drop-down list, click Messaging Broker Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Itinerary.Services.Broker.MessagingBroker.

    3. Right-click the Filter collection, and then click Add new Filter. In the Filter1 Properties window, configure the following properties:

      1. Click the Name property, and then type ASMXFilter.

      2. Click the Filter Implementation drop-down list, and then click XPath Filter.

      3. Click the Expression property, and then type count(/ContextProperties/Property[@name='InboundTransportLocation'][contains(., 'ProcessItinerary.asmx')]) > 0.

    4. Right-click the Filter collection, and then click Add new Filter. In the Filter1 Properties window, configure the following properties:

      1. Click the Name property, and then type WCFFilter.

      2. Click the Filter Implementation drop-down list, and click XPath Filter.

      3. Click the Expression property, and then type count(/ContextProperties/Property[@name='InboundTransportLocation'][contains(., 'ESB.ItineraryServices.WCF')]) > 0.

    5. Right-click the Resolver collection of the RouteBrokerService model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type ResolverBrokerRoute.

      2. In the Resolver Implementation drop-down list, click MessageContext Resolver Extension.

    6. In the Toolbox, click Connector. Drag a connection from the ReceiveNAOrder model element to the RouteBrokerService model element.

    7. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it under the RouteBrokerService model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type RouteToFileFromASMX.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

        Note
        This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing.

    8. Right-click the Resolver collection of the RouteToFileFromASMX model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type ResolverFromAsmx.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type c:\howtos\out\asmx%MessageId%.xml.

    9. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the RouteToFileFromASMX model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendASMXOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    10. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the RouteToFileFromASMX model element and the SendASMXOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilterASMX.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand SendASMXOrder, and then click Send Handlers.

    11. In the Toolbox, click Connector. Drag a connection from the RouteToFileFromASMX model element to the SendPortFilterASMX model element.

    12. In the Toolbox, click Connector. Drag a connection from the SendPortFilterASMX model element to the SendASMXOrder model element.

    13. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it to the right of RouteBrokerService model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type RouteToFileFromWCF.

      2. In the Itinerary Service Extender drop-down list, click Messaging Extender.

        Note
        This property defines that the process will take place in a pipeline (messaging). Alternately, if the process will take place in an orchestration, set the Itinerary Service Extender property to Orchestration Extender.

      3. In the Container drop-down list, expand ReceiveNAOrder, and then click Receive Handlers.

      4. In the Service Name drop-down list, click Microsoft.Practices.ESB.Services.Routing.

    14. Right-click the Resolver collection of the RouteToFileFromWCF model element, and then click Add new Resolver. In the Resolver1 Properties window, configure the following properties:

      1. Click the Name property, and then type ResolverFromWCF.

      2. In the Resolver Implementation drop-down list, click Static Resolver Extension.

      3. In the Transport Name drop-down list, click FILE.

      4. Click the Transport Location property, and then type c:\howtos\out\wcf%MessageId%.xml.

    15. From the Toolbox, drag an Off-Ramp model element to the design surface, and then place it to the right of the RouteToFileFromWCF model element. In the OffRamp1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendWCFOrder.

      2. In the Extender drop-down list, click Off-Ramp ESB Extender.

      3. In the BizTalk Application drop-down list, click GlobalBank.ESB.

      4. In the Send Port drop-down list, click DynamicResolutionOneWay.

    16. From the Toolbox, drag an Itinerary Service model element to the design surface, and then place it between the RouteToFileFromWCF model element and the SendWCFOrder model element. In the ItineraryService1 Properties window, configure the following properties:

      1. Click the Name property, and then type SendPortFilterWCF.

      2. In the Itinerary Service Extender drop-down list, click Off-Ramp Extender.

      3. In the Off-Ramp drop-down list, expand SendWCFOrder, and then click Send Handlers.

    17. In the Toolbox, click Connector. Drag a connection from the RouteToFileFromWCF model element to the SendPortFilterWCF model element.

    18. In the Toolbox, click Connector. Drag a connection from the SendPortFilterWCF model element to the SendWCFOrder model element.

    19. From the Toolbox, drag an Itinerary Outport model element to right border of RouteBrokerService. In the ItineraryBrokerOutPort1 Properties window, configure the following properties:

      1. Click the Name property, and then type WCF Port.

      2. In the Filter drop-down list, click WCFFilter.

      3. In the Resolver drop-down list, click ResolverBrokerRoute.

    20. From the Toolbox, drag an Itinerary Outport model element to the bottom border of RouteBrokerService. In the ItineraryBrokerOutPort1 Properties window, configure the following properties:

      1. Click the Name property, and then type ASMX Port.

      2. In the Filter drop-down list, click ASMXFilter.

      3. In the Resolver drop-down list, click ResolverBrokerRoute.

    21. In the Toolbox, click Connector. Drag a connection from the WCF Port model element to the RouteToFileFromWCF model element.

    22. In the Toolbox, click Connector. Drag a connection from the ASMX Port model element to the RouteToFileFromASMX model element.

    To export the model for use with the Itinerary Test Client

      Note
      You will need to export the itinerary twice: one time in XML and one time to the database to test the routing through the broker.

      1. In Visual Studio, right-click the design surface of the ChoiceRouter itinerary, and then click Export Model.

        Note
        The XML version of the itinerary opens in Visual Studio.

      2. In Windows Explorer, browse to C:\HowTos\Itineraries, and then notice the creation of your itinerary XML (ChoiceRouter.xml).

      3. In Visual Studio, right-click the design surface of the ChoiceRouter itinerary, and then click Export Model.

      4. In the Properties window, click Database Itinerary Exporter in the Model Exporter drop-down list.

      5. In the Properties window, set the Itinerary Database property connection string to point to the itinerary database.

      6. In the Itinerary Status property drop-down list select Deployed.

      7. In Visual Studio, right-click the design surface of the ChoiceRouter itinerary, and then click Export Model.

      To test the itinerary

      1. Open the Itinerary Test Client sample application using the shortcut created during the Prerequisites for the Development Activities (C:\HowTos\ESB.Itinerary.Test.exe - Shortcut).

      2. In the Itinerary Test Client, clear the Use WCF Service check box, and then click Load Itinerary.

      3. In the Open Itinerary File dialog box, browse to C:\HowTos\Itineraries. Select ChoiceRouter.xml, and then click Open to load the itinerary.

      4. Click OK to close the "Itinerary Loaded Successfully" message.

      5. In the Itinerary Test Client, click the ellipsis button (...) next to the Load Message box.

      6. In the Select XML Document to load dialog box, browse to C:\Patterns\HowTos. Select NAOrderDoc.xml, and then click Open to load the test message.

      7. Click the Submit Request button. When the test completes, click OK to close the confirmation message that appears.

      8. In Windows Explorer, browse to C:\HowTos\Out. Verify that the ASMX%MessageID%.xml messages have been written to this directory.

      9. Click the Itinerary Test client Use WCF Service check box. In the Itinerary Name box, type ChoiceRouter, and then click the Submit Request button. When the test completes, click OK to close the confirmation message.

      10. In Windows Explorer, browse to C:\HowTos\Out. Verify that the WCF%MessageID%.xml messages have been written to this directory.

      Additional Resources

      For more information, see the following related topics:

      • How to: Select an Itinerary Using a Business Rules Policy

      • How to: Dynamically Route a Message Based on Message Context Using a Business Rules Policy

      • Development Activities

      • Message Routing Patterns


BizTalk ESB Toolkit Sample Applications

The ​Microsoft BizTalk ESB Toolkit includes several sample applications that you can install and run to see how the ESB works and how it uses some of the ESB pipeline components. You can adapt and modify the code and techniques used in the samples for your own applications.

To install the sample applications

  1. Create a folder named Projects in the root of your C: drive, and create a subfolder named Microsoft.Practices.ESB within this folder.

    Note
    In the current release, the supported installation is for the files to reside in the folder C:\Projects\Microsoft.Practices.ESB. The BizTalk binding files that ship with the samples depend on this path.

  2. When you install the BizTalk ESB Toolkit(http://go.microsoft.com/fwlink/?LinkId=187592), it includes a .zip file called ESBSource.zip in the installation location you specified (by default, C:\Program Files\​Microsoft BizTalk ESB Toolkit). Uncompress the ESBSource.zip file into the C:\Projects\Microsoft.Practices.ESB folder. This will create folders named Keys and Source that contain the sample key and the samples with source code. The Source folder contains the source code for the sample application, and the Keys folder contains the public keys used to sign the assemblies in the sample applications.

  3. Before you run the samples, remove the read-only attribute on the C:\Projects\Microsoft.Practices.ESB\ folder so that the samples install correctly.

  4. If you have not used PowerShell scripts before, you must open PowerShell as an Administrator and run the following command:

    Copy Code
    set-executionpolicy unrestricted
    Note
    For more information about PowerShell, see the Windows PowerShell Blog (http://go.microsoft.com/fwlink/?LinkId=187593) and Windows PowerShell (http://go.microsoft.com/fwlink/?LinkId=187594) on MSDN.

  5. Open a command prompt as an administrator and run the following command to ensure WCF script maps are registered:

    Copy Code
    C:\Windows\Microsoft.NET\Framework\v3.0\Windows Communication Foundation>ServiceModelReg.exe -r -y
Note
You need to open the ESBSource.zip file in order to get an access to the Samples code.

The following topics describe the sample applications and include additional installation instructions where applicable:

  • Installing the Exception Management Samples

  • Running the Repair and Resubmit Custom Exception Handler Sample

  • Running the Message Persisting Custom Exception Handler Sample

  • Running the BizTalk Failed Message Routing ESB Processing Sample

  • Installing and Running the Itinerary On-Ramp Sample

  • Installing and Running the JMS MQRFH2 Component Sample

  • Installing and Running the Namespace Component Sample

  • Installing and Running the Transformation Service Sample

  • Installing and Running the Dynamic Resolution Sample

  • Installing and Running the BizTalk Operations Sample

  • Installing and Running the Resolver Service Sample

  • Installing and Running the Scatter-Gather Sample

  • Installing and Running the Message Enrichment Sample

  • Installing and Running the Multiple Web Services Sample

  • Installing and Running the Designer Extensibility Sample

  • Running the Exception Handling Service Sample


Installing the Exception Management Samples

This section describes the process for installing the ESB Exception Management samples into the Microsoft BizTalk Server GlobalBank.ESB application. You can install the ESB Exception Management samples using the install scripts included with the ​Microsoft BizTalk ESB Toolkit. This section contains the following topics:

  • Installing the Exception Management Samples Using Install Scripts

  • Assemblies and Artifacts Installed by the Exception Management Samples

Note
The ​Microsoft BizTalk ESB Toolkit sample applications reside in a BizTalk application named GlobalBank.ESB. To make sure that this application exists, install the Dynamic Resolution sample first.

For information about how to run the samples and how they work, see the following topics:

  • Running the Repair and Resubmit Custom Exception Handler Sample

  • Running the Message Persisting Custom Exception Handler Sample

  • Running the BizTalk Failed Message Routing ESB Processing Sample


Installing the Exception Management Samples Using Install Scripts

This section describes how you can install the Exception Management samples from the install scripts provided with the ​Microsoft BizTalk ESB Toolkit.

To install the ESB Exception Management samples from the install scripts

  1. On the Start menu, click Run.

  2. In the Run dialog box, type cmd, and then press ENTER to open a command prompt.

  3. Run the following command, replacing the <path> parameter with the full path to the .cmd file you want to install (the default path and name in this release is \Source\Samples\Exception Handling\Install\Scripts\):

    Copy Code
    <path>\Setup_bin.cmd


Assemblies and Artifacts Installed by the Exception Management Samples

The following table lists the assemblies and other artifacts installed for the ESB Exception Management sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | GlobalBank.ESB.ExceptionHandling.Processes.EAIProcess
 |  | GlobalBank.ESB.ExceptionHandling.Handlers.EAIGenericHandler
 |  | GlobalBank.ESB.ExceptionHandling.Handlers.EAIProcessHandler
BizTalk application GlobalBank.ESB | Send Ports | EAIProcessHandler.RepairSubmit
 |  | EAIGenericHandler.PostTmpMsg
 |  | EAIProcess.PostApproval
 |  | EAIProcessHandler.PostDecline
 |  | ALL.Exceptions_FILE (references the GlobalFaultProcessor pipeline)
BizTalk application GlobalBank.ESB | Receive Ports | EAIProcess.RequestPort
BizTalk application GlobalBank.ESB | Receive Locations | EAIProcess.RequestPort_FILE
 |  | EAIProcess.ReSubmit_HTTP
BizTalk application GlobalBank.ESB | Schemas | GlobalBank.ESB.ExceptionHandling.Schemas.System_Properties Version 2.0.0.0
 |  | GlobalBank.ESB.ExceptionHandling.Schemas.Request Version 2.0.0.0
 |  | GlobalBank.ESB.ExceptionHandling.Schemas.RequestDenied Version 2.0.0.0
BizTalk application GlobalBank.ESB | Pipelines | GlobalBank.ESB.ExceptionHandling.Pipelines.GlobalFaultProcessor Version 2.0.0.0
BizTalk application GlobalBank.ESB | Resources | GlobalBank.ESB.ExceptionHandling.Handlers Version 2.0.0.0
 |  | GlobalBank.ESB.ExceptionHandling.Processes Version 2.0.0.0
 |  | GlobalBank.ESB.ExceptionHandling.Schemas Version 2.0.0.0
 |  | GlobalBank.ESB.ExceptionHandling.Pipelines Version 2.0.0.0
BizTalk application GlobalBank.ESB | Policies |
BizTalk application GlobalBank.ESB | Maps | GlobalBank.ESB.ExceptionHandling.Schemas.MapToReqDenied Version 2.0.0.0
Global assembly cache | Assemblies | GlobalBank.ESB.ExceptionHandling.Handlers Version 2.0.0.0
 |  | GlobalBank.ESB.ExceptionHandling.Processes Version 2.0.0.0
 |  | GlobalBank.ESB.ExceptionHandling.Schemas Version 2.0.0.0
 |  | GlobalBank.ESB.ExceptionHandling.Pipelines Version 2.0.0.0
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components |


Running the Repair and Resubmit Custom Exception Handler Sample

The Repair and Resubmit Custom Exception Handler sample demonstrates an extremely effective technique for integrating human intervention into ESB and Microsoft BizTalk–based application processes and implements a useful design pattern. The sample code integrates seamlessly into the ESB exception management system.

The sample shows how you can use a custom exception handler in an orchestration. When a process in the orchestration (EAIProcess.odx) encounters an error, the exception handler generates and publishes an ESB fault message. This fault message includes in its payload the messages (including their BizTalk-related context properties) that were "in flight" when the exception occurred and the current System.Exception instance caught by the BizTalk Orchestration engine. When this occurs, a "Denied" message and an "Approved" message are persisted with the fault message.

A second orchestration named EAIProcessHandler.odx, which is deployed in a decoupled manner and acts as a custom exception handler, subscribes to the specific fault code generated in the EAIProcess.odx orchestration and consumes the fault message. This exception handler extracts the original messages (as typed documents) and the System.Exception instances originally persisted in the fault message.

The original messages now become available for processing with all their original context properties. The custom exception handler (EAIProcessHandler.odx) then writes both the "Denied" and the "Approved" messages to the file system in the following locations:

  • Approved message:

    • \Source\Samples\Exception Handling\Test\Filedrop\EAIProcess.PostApproval

  • Denied message for repair and resubmit:

    • \Source\Samples\Exception Handling\Test\Filedrop\EAIProcessHandler.RepairSubmit

  • Denied message:

    • \Source\Samples\Exception Handling\Test\Filedrop\EAIProcessHandler.PostDecline

The exception handler serializes the "Denied" message for Repair and Resubmit to the file system using a Microsoft InfoPath processing instruction. An InfoPath template allows the user to edit the form and resubmit the result (see Figure 1), which starts the EAIProcess.odx orchestration that validates the message.

Figure 1

A test message generated by the InfoPath Repair and Resubmit template

Additionally, there is a generic send port named ALL.Exceptions_FILE that is configured to use the GlobalFaultProcessor pipeline. This port subscribes to all exceptions in the system, both BizTalk failed message routing messages and ESB fault messages. The Exception Management Framework normalizes them all to a single format and serializes them using an InfoPath processing instruction to the folder \Source\Samples\Exception Handling\Test\Filedrop\All_Exceptions.

Installation

All the exception management samples use the same set of core services and BizTalk application artifacts. Therefore, you have to install the exception management sample artifacts only once to be able to run all the exception management samples. For information about how to install the exception management samples, see Installing the Exception Management Samples.

Running the Sample Application

To run the Repair and Resubmit Custom Exception Handler sample

  1. Before you run this sample for the first time, make sure that the receive location and send port URLs point to the appropriate directories in the \Source\Samples\Exception Handling\Test\Filedrop folder. The receive location should specify the folder EAIProcess.RequestPort, and the send port URLs should specify the folders EAIProcess.PostApproval and EAIProcessHandler.PostDecline.

  2. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  3. Start the sample by copying the sample file named Request_EAIProcessHandler.xml, located in the \Source\Samples\Exception Handling\Test\Data folder, to the folder specified for the EAIProcess.RequestPort_FILE receive location: \Source\Samples\Exception Handling\Test\Filedrop\EAIProcess.RequestPort.

  4. Open the folder named EAIProcessHandler.PostDecline (in the \Source\Samples\Exception Handling\Test\Filedrop folder). You will see the "Declined*" message generated by the exception handling orchestration.

  5. Open the folder named EAIProcessHandler.RepairSubmit (in the \Source\Samples\Exception Handling\Test\Filedrop folder). You will see a "RepairSubmit" message generated by the exception handling orchestration.

  6. Double-click the RepairSubmit file to open it in the appropriate InfoPath template. You will see the message ready for edit and resubmission.

  7. Change the value of the Unit Price field from 0 to 2, and then click the Submit button located on the toolbar of the InfoPath form to submit the edited document back to BizTalk for processing. The submit process uses a BizTalk-configured HTTP receive location.

  8. Navigate to the EAIProcess.PostApproval folder (in the \Source\Samples\Exception Handling\Test\Filedrop folder). You will now see the "Approval*" document containing the updated value for the unit price.

How the Sample Works

The message you submit activates the EAIProcess orchestration. When the EAIProcess orchestration processes the message, it attempts to divide 1 by the unit price. Because the unit price is zero, a divide-by-zero exception occurs. Code in the event handler of the orchestration catches this exception and creates a fault message. The order quantity in the message is greater than 10, so the business logic dictates that this exception has a FaultCode field value of 1000.

The EAIProcess orchestration then publishes the fault message to the BizTalk Message Box through a direct-bound port, and the orchestration ends.

A custom fault handler orchestration named EAIProcessHandler, which subscribes to messages with a FaultCode field value of 1000, picks up the new fault message. The code in the orchestration creates the "Denied" message and the InfoPath file, and then it places this into the EAIProcessHandler.PostDecline and EAIProcessHandler.RepairSubmit folders ready for human intervention.


Running the Message Persisting Custom Exception Handler Sample

The Message Persisting Custom Exception Handler sample demonstrates a loosely coupled, generic handler that receives fault messages, extracts the Microsoft BizTalk messages they contain, and writes them as disk files to the file system.

The sample shows how you can use a custom exception handler in an orchestration. When a process in the orchestration (EAIProcess.odx) encounters an error, the exception handler generates and publishes an ESB fault message. This fault message includes in its payload the messages (including their BizTalk-related context properties) that were "in flight" when the exception occurred, as well as the current System.Exception instance caught by the BizTalk Orchestration engine. When this occurs, a "Denied" message and an "Approved" message are persisted with the fault message.

A second orchestration named EAIGenericHandler.odx, which is deployed in a decoupled manner and acts as a custom exception handler, subscribes to the specific fault code generated in the EAIGenericHandler.odx orchestration and consumes the fault message. This exception handler extracts the original messages (as type-less documents) and the System.Exception instances originally persisted in the fault message.

The Message Persisting Custom Exception Handler sample differs from the Repair and Resubmit Custom Exception Handler sample in that the EAIGenericHandler.odx orchestration used in this sample does not have a dependency on the schemas used in the fault publishing orchestration process (EAIProcess.odx). Specifically, the EAIGenericHandler.odx orchestration retrieves the original messages from the fault message as System.Xml.XmlDocument instances instead of typed messages based on the schemas used in the EAIProcess.odx orchestration. It also returns the messages as a collection that code can easily enumerate.

The custom exception handler (EAIGenericHandler.odx) then writes both the "Denied" and the "Approved" messages to the file system location \Source\Samples\Exception Handling\Test\Filedrop\EAIGenericHandler.PostTmpMsg.

Additionally, there is a generic send port named ALL.Exceptions_FILE configured to use the GlobalFaultProcessor pipeline installed as part of the ​Microsoft BizTalk ESB Toolkit Exception Management Framework. This port subscribes to all exceptions in the system, both BizTalk failed message routing messages and ESB fault messages. The Exception Management Framework normalizes them all to a single format and serializes them using a Microsoft InfoPath processing instruction to the location \Source\Samples\Exception Handling\Test\Filedrop\All_Exceptions.

Installation

All the exception management samples use the same set of core services and BizTalk application artifacts. Therefore, you have to install the exception management sample artifacts only once to be able to run all the exception management samples. For information about how to install the exception management samples, see Installing the Exception Management Samples.

Running the Sample Application

To run the Message Persisting Custom Exception Handler sample

  1. Before you run this sample for the first time, make sure that the receive location and send port URL point to the appropriate directories in the \Source\Samples\Exception Handling\Test\Filedrop folder. The receive location should specify the folder EAIProcess.RequestPort, and the send port URL should specify the folder EAIGenericHandler.PostTmpMsg.

  2. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  3. Start the sample by copying the sample file named Request_EAIGenericHandler.xml, located in the \Source\Samples\Exception Handling\Test\Data folder, to the folder specified for the EAIProcess.RequestPort_FILE receive location: \Source\Samples\Exception Handling\Test\Filedrop\EAIProcess.RequestPort.

  4. Open the folder named EAIGenericHandler.PostTmpMsg (in the \Source\Samples\Exception Handling\Test\Filedrop\ folder). You will see the original message.

How the Sample Works

The message you submit activates the EAIProcess orchestration. When the EAIProcess orchestration processes the message, it attempts to divide 1 by the unit price. Because the unit price is zero, a divide-by-zero exception occurs. Code in the event handler of the orchestration catches this exception and creates a fault message. The order quantity in the message is less than 10, so the business logic dictates that this exception has a FaultCode field value of 2000.

The EAIProcess orchestration then publishes the fault message to the BizTalk Message Box through a direct-bound port, and the orchestration ends.

A custom fault handler orchestration named EAIGenericHandler, which subscribes to messages with a FaultCode field value of 2000, picks up the new fault message. The code in the orchestration extracts all the messages from the exception (fault) message and writes them to disk files.


Running the BizTalk Failed Message Routing ESB Processing Sample

The Microsoft BizTalk Failed Message Routing ESB Processing sample demonstrates how you can use the ​Microsoft BizTalk ESB Toolkit Exception Management Framework as a universal mechanism to manage, serialize, and render exceptions occurring under all conditions in BizTalk Server 2013 R2. This includes exceptions generated by the BizTalk Failed Message Routing mechanism and fault messages generated by the Exception Management Framework from within an orchestration.

The BizTalk Failed Message Routing mechanism is the error-handling facility of BizTalk Server 2013 R2; by using it, the designer can designate automated handling of messaging failures as an alternative to the traditional (now default) behavior of placing failed messages in the "Suspended" queue. This automated handling routes an error message to any subscribing routing destination, such as a send port or an orchestration. The error message is a clone of the original message with all previously promoted properties demoted and with selected properties related to the specific messaging failure promoted into the message context.

To enable the BizTalk Failed Message Routing mechanism on a receive port or a send port, select the Enable routing for failed messages check box, as shown in Figure 1.

Figure 1

Enabling the BizTalk Failed Message Routing mechanism

However, there is not a similar mechanism for errors or failures occurring in an orchestration. Instead, code within the exception handler of an orchestration can take advantage of the Exception Management Framework API to emulate the functionality of the BizTalk Failed Message Routing mechanism.

In this sample, the receive location named EAIProcess.RequestPort_FILE picks up files copied to the location \Source\Samples\Exception Handling\Test\Filedrop\EAIProcess.RequestPort.

Additionally, there is a generic send port named ALL.Exceptions_FILE configured to use the GlobalFaultProcessor pipeline installed as part of the Exception Management Framework. This port subscribes to all exceptions occurring in the system, both BizTalk failed message routing messages and ESB fault messages, as shown in Figure 2.

Figure 2

The ALL.Exceptions send port subscription for all types of failure or exception

The Exception Management Framework normalizes all exceptions to a single format and serializes them using a Microsoft InfoPath processing instruction to the location \Source\Samples\Exception Handling\Test\Filedrop\All_Exceptions.

Installation

All the exception management samples use the same set of core services and BizTalk application artifacts. Therefore, you have to install the exception management sample artifacts only once to be able to run all the exception management samples. For information about how to install the exception management samples, see Installing the Exception Management Samples.

Running the Sample Application

To run the BizTalk Failed Message Routing ESB Processing sample

  1. Before you run this sample for the first time, make sure that the receive location and send port URL point to the appropriate directories in the \Source\Samples\Exception Handling\Test\Filedrop folder. The receive location should specify the folder EAIProcess.RequestPort, and the send port URL should specify the folder All_Exceptions.

  2. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  3. Copy the file named FlatFileReceive_in.txt from the folder \Source\Samples\Exception Handling\Test\Data into the receive location folder named EAIProcess.RequestPort (in the \Source\Samples\Exception Handling\Test\Filedrop folder).

  4. This message is a text file, and it will cause an exception. Open the folder named All_Exceptions (in the \Source\Samples\Exception Handling\Test\Filedrop folder), and then double-click the fault message to open it into InfoPath using the appropriate template. You will see that the ESB Exception Handling mechanism serializes the content appropriately to allow InfoPath to render it.

  5. Next, copy the file named soapmessage[1].xml from the folder \Source\Samples\Exception Handling\Test\Data into the EAIProcess.RequestPort receive location folder.

  6. This message is an XML document that contains a CDATA section, and it will cause an exception. Open the All_Exceptions output folder and double-click the fault message to open it into InfoPath. You will see that the ESB Exception Handling mechanism serializes this content appropriately to allow InfoPath to render it.

  7. Finally, copy the file named Csqzav01.pdf from the folder \Source\Samples\Exception Handling\Test\Data into the EAIProcess.RequestPort receive location.

  8. This message is a PDF file, and it will cause an exception. Open the All_Exceptions output folder and double-click the fault message to open it in InfoPath. You will see that the ESB Exception Handling mechanism serializes and Base-64 encodes the content to allow InfoPath to render it.


Installing and Running the Itinerary On-Ramp Sample

The Itinerary On-Ramp sample demonstrates how you can configure the ESB itinerary properties and run one-way and request-response messaging scenarios, such as the following:

  • Executing an itinerary that uses messaging services

  • Executing an itinerary that uses orchestrations

  • Executing a combination of itinerary steps that use messaging services and orchestrations

The Itinerary On-Ramp sample uses a Windows Forms test client application to execute the methods of the Itinerary Web service and display returned messages. You can open the test client project to run it and to examine the code to see how you can use the Itinerary Web service in your own service-oriented architecture (SOA) and ESB applications.

This section contains the following topics:

  • Installing the Itinerary On-Ramp Sample

  • Running the Itinerary On-Ramp Sample


Installing the Itinerary On-Ramp Sample

The Itinerary On-Ramp sample depends on the ​Microsoft BizTalk ESB Toolkit core solution, the Dynamic Resolution sample, and the Resolver Service sample. Installing the ​Microsoft BizTalk ESB Toolkit core automatically copies and installs the core assemblies required by this sample to the correct locations. Installing the Dynamic Resolution sample and Resolver Service sample ensures that the Web services and Business Rules Engine policies used by the Itinerary On-Ramp Sample are correctly installed and configured.

Note
You must install the Installing the Dynamic Resolution Sample and the Installing the Resolver Service Sample before you install this sample.

The ESB sample applications reside a Microsoft BizTalk application named GlobalBank.ESB. In addition, this sample use artifacts installed in the core Microsoft.Practices.ESB application. Before you install the Itinerary On-Ramp sample, you must add a reference to the Microsoft.Practices.ESB application to the GlobalBank.ESB application.

You can install the Itinerary On-Ramp sample using the install scripts included with the ​Microsoft BizTalk ESB Toolkit. This section contains the following topics:

  • Install the Itinerary On-Ramp Sample Using the Install Scripts

  • Assemblies and Artifacts Installed by the Itinerary On-Ramp Sample


Install the Itinerary On-Ramp Sample Using the Install Scripts

This section describes how you can install the Itinerary On-Ramp sample from the install scripts provided with the ​Microsoft BizTalk ESB Toolkit.

To install the Itinerary On-Ramp sample from the install scripts

  1. On the Start menu, click Run.

  2. In the Run dialog box, type cmd, and then press ENTER to open a command prompt.

  3. Run the following command, replacing the <path> parameter with the full path to the .cmd file you want to install (the default path in this release is \Source\Samples\Itinerary\Install\Scripts\):

    Copy Code
    <path>\Setup_bin.cmd


Assemblies and Artifacts Installed by the Itinerary On-Ramp Sample

The following table lists the assemblies and artifacts installed by the ​Microsoft BizTalk ESB Toolkit Itinerary On-Ramp sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | GlobalBank.ESB.Itinerary.Processes.ProcessAndRespond
BizTalk application GlobalBank.ESB | Send Ports | (none)
BizTalk application GlobalBank.ESB | Receive Ports | (none)
BizTalk application GlobalBank.ESB | Receive Locations | (none)
BizTalk application GlobalBank.ESB | Schemas | (none)
BizTalk application GlobalBank.ESB | Pipelines | (none)
BizTalk application GlobalBank.ESB | Resources | (none)
BizTalk application GlobalBank.ESB | Policies | (none)
BizTalk application GlobalBank.ESB | Maps | (none)
BizTalk application GlobalBank.ESB | Assemblies | (none)
BizTalk application GlobalBank.ESB | Pipeline components | (none)


Running the Itinerary On-Ramp Sample

The Itinerary On-Ramp sample uses a Windows Forms test client application (the Itinerary Test Client) to demonstrate the features of the Itinerary service, and it includes 20 predefined itinerary use cases you can execute.

This section contains the following topics:

  • Run a Predefined Itinerary On-Ramp Sample

  • The Sample Itinerary Scenarios

  • Execute a Custom Itinerary Scenario

  • How the Itinerary On-Ramp Sample Works


Run a Predefined Itinerary On-Ramp Sample

The ​Microsoft BizTalk ESB Toolkit includes 20 predefined Itinerary use cases you can execute. For a list of these use cases, see The Sample Itinerary Scenarios.

Note
Before you run any of the samples, you must manually import the appropriate itinerary binding file from the \Source\Samples\Itinerary\Install\Binding folder into the GlobalBank.ESB BizTalk application. This binding file resets the properties on the two dynamic send ports. Import the binding file named GlobalBank.ESB.Itinerary_Bindings.xml.

To run one of the pre-defined Itinerary On-Ramp samples

  1. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  2. In Windows Explorer, open the subfolder \Source\Samples\Itinerary\Source\ESB.Itinerary.Test\bin\Debug where you installed the BizTalk ESB Toolkit samples, and then start the application named Esb.Itinerary.Test.exe.

  3. Click the LoadItinerary button, and then select the sample itinerary named TwoWay-OrchTransform-OrchRoutingGroup-OrchTwoWayCustom.xml from the \Source\Samples\Itinerary\Itineraries folder.

  4. In the Web Service Options section, select the Two-Way Service check box. This instructs the test client to perform a request-response itinerary service operation.

  5. (Optional) Select the Use WCF Service check box if you want the application to use the OnRamp.Itinerary.Response.WCF receive location instead of the default OnRamp.Itinerary.Response.SOAP receive location.

  6. Click the LoadMessage button, and then select the NAOrderDoc.xml sample message from the \Source\Samples\Itinerary\Test\Data folder.

  7. Click the SubmitRequest button to send the request to the Itinerary On-Ramp service. Figure 1 shows the result.

Itinerary On Ramp

Figure 1

The Itinerary On-Ramp client application running one of the Itinerary On-Ramp samples

The name of the service specified in the itinerary definition corresponds directly to the ServiceName property of the service to which the sample subscribes. In the itinerary sample executed in the previous procedure (TwoWay-OrchTransform-OrchRoutingGroup-OrchTwoWayCustom.xml), the first service executed is an orchestration-based service that performs a transformation. The following section of the itinerary specifies this service.

Copy Code
<Service uuid="" beginTime="" completeTime=""
    name="Microsoft.Practices.ESB.Services.Transform"
    type="Orchestration" state="Pending" isRequestResponse="false"
    position="0" serviceInstanceId="" />

The orchestration service in this <Service> element specifies the direct-bound orchestration that has the filter properties shown in Figure 2. Notice that the orchestration subscribes only to messages that have the value Microsoft.Practices.ESB.Services.Transform for the ServiceName context property, the value Pending for the ServiceState context property, and the value Orchestration for the ServiceType context property.

Figure 2

The filter expression for the direct-bound orchestration used in the Itinerary On-Ramp sample


The Sample Itinerary Scenarios

The following table lists all the predefined Itinerary files included with the Itinerary On-Ramp sample. These are located in the \Source\Samples\Itinerary\Itineraries folder.

File name | Description
Disassembler_OneWay-MessageTransform-MessageRouting-MessgeSendPort.xml | This itinerary demonstrates a predefined message flow that, when submitted to the Itinerary on-ramp, instructs Microsoft BizTalk to execute a map against the submitted message and then route the transformed message to n number of locations through a custom dynamic send port. The number of resolvers associated with the service determines the number of routes. All transformation and routing occurs at the BizTalk Messaging layer, using an optional routing message service supported by the ESB Dispatcher pipeline components. The resolvers associated with the service within the itinerary determine the routing locations. Running this itinerary generates the following messages:
 | 2 messages in the folder \Source\Samples\DynamicResolution\Test\Filedrop\Out
 | 1 message in the FTP folder: FTP://localhost/out/%MessageID%.xml
 | 1 message in the MQSeries queue: MQS://localhost/ESB.DEP.Sample.QueueManager/TEST.OUT/%MessageID.xml
Disassembler_OneWay-MessageTransform-MessgeSendPort.xml | This itinerary demonstrates a predefined message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message and then route the transformed message to n number of locations through a custom dynamic send port. The number of resolvers associated with the service determines the number of routes. All transformation and routing occurs at the BizTalk Messaging layer. The resolvers associated with the service within the itinerary determine the routing locations. Running this itinerary generates the following messages:
 | 2 messages in the folder \Source\Samples\DynamicResolution\Test\Filedrop\Out
 | 1 message in the FTP folder: FTP://localhost/out/%MessageID%.xml
 | 1 message in the MQSeries queue: MQS://localhost/ESB.DEP.Sample.QueueManager/TEST.OUT/%MessageID.xml
OneWay-MessageTransform-MessageRouting-MessgeSendPort.xml | This itinerary demonstrates a predefined message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message and then route the transformed message to a single location through a custom dynamic send port. All transformation and routing occurs at the BizTalk Messaging layer, using an optional routing message service supported by the ESB Dispatcher pipeline components. Running this itinerary generates a single message in the \Source\Samples\DynamicResolution\Test\Filedrop\Out folder.
OneWay-MessageTransform-MessgeSendPort.xml | This itinerary demonstrates a predefined message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message and then route the transformed message to a single location through a custom dynamic send port. All transformations and routing occurs at the BizTalk Messaging layer. Running this itinerary generates a single message in the \Source\Samples\DynamicResolution\Test\Filedrop\Out folder.
OneWay-MessgeSendPort.xml | This itinerary demonstrates a predefined message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to route the message to a single location through a custom dynamic send port. All routing occurs at the BizTalk Messaging layer. Running this itinerary generates a single message in the \Source\Samples\DynamicResolution\Test\Filedrop\Out folder.
OneWay-OrchTransform-OrchRoutingGroup-MessgeSendPort.xml | This itinerary demonstrates an example of a predefined message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message using a custom orchestration service. A second custom orchestration service then processes the output and routes four messages to three locations. The resolvers associated with this service determine the following routing locations:
 | 2 messages in the folder \Source\Samples\DynamicResolution\Test\Filedrop\Out
 | 1 message in the FTP folder: FTP://localhost/out/%MessageID%.xml
 | 1 message in the MQSeries queue: MQS://localhost/ESB.DEP.Sample.QueueManager/TEST.OUT/%MessageID.xml
 | Finally, the itinerary routes the original message to a single location (the \Source\Samples\DynamicResolution\Test\Filedrop\Out folder) through a custom dynamic send port. All transformations and routing occur through a combination of BizTalk Messaging and orchestration services. Running this itinerary sample generates five messages.
TwoWay-MessageTransform-MessageRouting-MessageTwoWaySendPort.xml | This itinerary demonstrates a predefined two-way (request/response) message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message and then route the transformed message to a Web service through a custom dynamic two-way send port. This example uses an optional routing message service supported by the ESB Dispatcher pipeline components. All transformations and routing occur at the BizTalk Messaging layer. Running this Itinerary sample generates a single response message, which the itinerary routes to the original caller, in this case the Itinerary Test Client.
TwoWay-MessageTransform-MessageRouting-MessageTwoWaySendPort-MessageTransform.xml | This itinerary demonstrates a predefined two-way (request/response) message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message and then route the transformed message to a Web service through a custom dynamic two-way send port. When the response returns from the Web service, the itinerary instructs BizTalk to execute a map against the response message. This example uses an optional routing message service supported by the ESB Dispatcher pipeline components. All transformations and routing occur at the BizTalk Messaging layer. Running this Itinerary sample generates a single response message, which the itinerary routes to the original caller, in this case the Itinerary Test Client.
TwoWay-MessageTransform-MessageTwoWaySendPort.xml | This itinerary demonstrates a predefined two-way (request/response) message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message and then route the transformed message to a Web service through a custom dynamic two-way send port. All transformations and routing occur at the BizTalk Messaging layer. Running this Itinerary sample generates a single response message, which the itinerary routes to the original caller, in this case the Itinerary Test Client.
TwoWay-MessageTransform-MessageTwoWaySendPort-MessageTransform.xml | This itinerary demonstrates a predefined two-way (request/response) message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message and then route the transformed message to a Web service through a custom dynamic two-way send port. When the response returns from the Web service, the Itinerary instructs BizTalk to execute a map against the response message. All transformations and routing occur at the BizTalk Messaging layer. Running this Itinerary sample generates a single response message, which the itinerary routes to the original caller (in this case, the Itinerary Test Client).
TwoWay-MessageTransform-OrchRoutingGroup-OrchTwoWayCustom.xml | This itinerary demonstrates a predefined two-way (request/response) message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message using the Messaging service. The itinerary then passes the output to a custom orchestration service that processes it. The resolvers associated with the service determine the following four routing locations:
 | 2 messages in the folder \Source\Samples\DynamicResolution\Test\Filedrop\Out
 | 1 message in the FTP folder: FTP://localhost/out/%MessageID%.xml
 | 1 message in the MQSeries queue: MQS://localhost/ESB.DEP.Sample.QueueManager/TEST.OUT/%MessageID.xml
 | Finally, the itinerary passes the original message to another custom two-way direct-bound orchestration service that routes the response message back to the original caller (in this case, the Itinerary Test Client). All transformation and routing occurs through a combination of BizTalk Messaging and Orchestration services.
TwoWay-OrchTransform-OrchRoutingGroup-OrchTwoWayCustom.xml | This itinerary demonstrates a predefined two-way (request/response) message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a map against the submitted message using a custom orchestration service. The itinerary then passes the output to a custom orchestration service that processes it. The resolvers associated with the service determine the following four routing locations:
 | 2 messages in the folder \Source\Samples\DynamicResolution\Test\Filedrop\Out
 | 1 message in the FTP folder: FTP://localhost/out/%MessageID%.xml
 | 1 message in the MQSeries queue: MQS://localhost/ESB.DEP.Sample.QueueManager/TEST.OUT/%MessageID.xml
 | Finally, the itinerary routes the original message to another custom two-way direct-bound orchestration service that routes the response message back to the original caller (in this case, the Itinerary Test Client). All transformations and routing occurs through a combination of BizTalk Messaging and Orchestration services.
TwoWay-TwoWayCustom (Direct Bound).xml | This itinerary demonstrates a predefined two-way (request/response) message flow that, when submitted to the Itinerary on-ramp, instructs BizTalk to execute a custom two-way direct-bound orchestration service. This service routes the response message back to the original caller, in this case the Itinerary Test Client.


Execute a Custom Itinerary Scenario

You can use the Itinerary Test Client application execute custom itinerary scenarios.

To execute a custom itinerary scenario using the Itinerary Test Client application

  1. In Windows Explorer, open the folder \Source\Samples\Itinerary\Source\ESB.Itinerary.Test\bin\Debug where you installed the ​Microsoft BizTalk ESB Toolkit samples and start the application named Esb.Itinerary.Test.exe.

  2. Select a service type in the ServiceType drop-down list, specify a name for the request, and then select the IsRequestResponse check box if this is a request/response operation. You can specify a two-way operation and choose to use the WCF version of the Itinerary Web service; to do this, select the check boxes in the Web Service Options section at the top of the application window.

  3. To specify the resolvers to use with the selected service in the AddResolversfortheService section of the window, select a resolver type from the drop-down list, and then click AddResolver. You can add more than one resolver if required. After you add all the required resolvers, click the AddService button to add this service invocation to the itinerary.

  4. If you want to add more service invocations to the itinerary, repeat steps 2 and 3. You can also use the RemoveService and ClearServices buttons to modify the list of services in the itinerary.

  5. If you want to repeat the current itinerary at another time, save the complete current itinerary to disk by clicking the SaveItinerary button. You can load it again by clicking the LoadItinerary button. This means that you do not have to specify the services and resolvers in the itinerary every time you execute this scenario with different messages or Itinerary Web service settings.

  6. Load a suitable message. To do this, either type the path and name of the message in the LoadMessage text box or click the ellipsis button (...), and then select the required message file.

  7. Click the SubmitRequest button to submit the message for processing with the itinerary settings you specified. If the processing returns a result, this will appear in the Result text box.


How the Itinerary On-Ramp Sample Works

The sample Itinerary Test Client application builds a set of SOAP headers that contain the itinerary that you create using the controls in the client application window, loads the specified message file from disk, appends the itinerary headers to the message, and submits it to the ESB through an Itinerary on-ramp for processing. If the itinerary generates a response, the application collects the response and displays it in the application window.

You can choose from several sample itinerary configuration files to see one-way and two-way scenarios that use orchestrations, messaging, or a combination of both.

To help you understand how the Itinerary service uses the itinerary information in a message, the following XML shows the sample itinerary configuration file named TwoWay-OrchTransform-OrchRoutingGroup-OrchTwoWayCustom.xml used in the earlier example. The first section of this itinerary specifies three service invocation steps.

Xml Copy Code
<Itinerary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" uuid="" beginTime="" completeTime="" state="Pending" isRequestResponse="false" servicecount="0" xmlns="http://schemas.microsoft.biztalk.practices.esb.com/itinerary">
  <BizTalkSegment interchangeId="" epmRRCorrelationToken="" receiveInstanceId="" messageId="" xmlns="" />
  <ServiceInstance name="Microsoft.Practices.ESB.Services.Transform" type="Orchestration" state="Pending" position="0" isRequestResponse="false" xmlns="" />
  <Services xmlns="">
    <Service uuid="92d3b293-e6d4-44a1-b27d-c42b48aec667" beginTime="" completeTime="" name="Microsoft.Practices.ESB.Services.Transform" type="Orchestration" state="Pending" isRequestResponse="false" position="0" serviceInstanceId="" />
  </Services>
  <Services xmlns="">
    <Service uuid="774488bc-e5b9-4a4e-9ae7-d25cdf23fd1c" beginTime="" completeTime="" name="Microsoft.Practices.ESB.Services.Routing" type="Orchestration" state="Pending" isRequestResponse="false" position="1" serviceInstanceId="" />
  </Services>
  <Services xmlns="">
    <Service uuid="" beginTime="" completeTime="" name="ProcessAndRespond" type="Orchestration" state="Pending" isRequestResponse="true" position="2" serviceInstanceId="" />
  </Services>
  ...

Following the list of service invocation steps in the itinerary is the section containing details of the resolvers (represented by connection strings) that allow the Itinerary service to locate or provide resolution information for each service defined in the itinerary.

Xml Copy Code
  ...
<ResolverGroups xmlns="">
    <Resolvers serviceId="Microsoft.Practices.ESB.Services.Transform0">&lt;![CDATA[BRE:\\Policy=ResolveMap;Version=1.0;UseMsg=False;]]&gt;</Resolvers>
    <Resolvers serviceId="Microsoft.Practices.ESB.Services.Routing1">&lt;![CDATA[STATIC:\\TransportType=FILE;TransportLocation=C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Test\Filedrop\OUt\%MessageID%.xml;Action=;EndpointConfig=;JaxRpcResponse=False;MessageExchangePattern=;TargetNamespace=;TransformType=;]]&gt;&lt;![CDATA[UDDI3:\\ServerUrl=http://localhost/uddi;SearchQualifiers=andAllKeys;CategorySearch=;BindingKey=uddi:esb:orderfileservicev3.1;]]&gt;</Resolvers>
    <Resolvers serviceId="ProcessAndRespond2" />
  </ResolverGroups>
</Itinerary>
Note
The actual content of each <Resolvers> element does not contain the white space characters used to wrap the lines in the preceding listing.

The following are the three steps defined in the itinerary preceding configuration:

  1. Execute the Microsoft.Practices.ESB.Services.Transform orchestration to transform the message with the ResolverMap policy using BizTalk Business Rules Engine (BRE).

  2. Execute the Microsoft.Practices.ESB.Services.Routing orchestration to route the transformed message to multiple locations using the routing Microsoft.Practices.ESB.Services.Routing1. The <ResolverGroups> section contains a <Resolvers> element with this identifier, which defines the connection strings.

  3. Execute the ProcessAndRespond orchestration provided with this sample. The implementation of this orchestration sends as the response a copy of the request message back to the Itinerary Test Client.

With the completion of each service, the service advances the itinerary and promotes the next service defined in the itinerary to be the current service instance, with its state set to Pending.

Note
The Itinerary On-Ramp sample uses dynamic resolution to send messages to the output folder. This is why there is no static send port defined for this sample.

The following is the sequence of events that occur after the test client application submits the message:

  • The OnRamp.Itinerary receive port receives the message.

  • The ItineraryReceiveXml pipeline extracts the itinerary from the SOAP header, validates and pre-processes it, writes the itinerary as a message context property into the inbound message, and publishes the message to the BizTalk Message Box database.

  • A subscription for the Microsoft.Practices.ESB.Services.Transform service orchestration triggers invocation of this orchestration. The orchestration first retrieves the current itinerary step by passing the current message as a parameter, as shown in the following code.

    C# Copy Code
    itineraryStep =   itinerary.Itinerary.GetItineraryStep(InboundMessage);
  • The ItineraryStep object contains all the information about the current service instance for execution, as well as any resolvers associated with it.

  • The Resolver object is retrieved from the ItineraryStep instance and the ESB Resolver Framework is used to resolve the full name of the transformation map, as shown in the following code.

    C# Copy Code
    resolverDictionary =
   Microsoft.Practices.ESB.Resolver.ResolverMgr.Resolve(InboundMessage,
                                                        resolver);

// Set the transform type.
transformType = resolverDictionary.Item("Resolver.TransformType");
  • The ​Microsoft BizTalk ESB Toolkit Resolver and Adapter Framework accomplishes this by loading the appropriate resolver from the cache (in this example, the BizTalk Business Rules Engine resolver), which invokes the ResolverMap policy and populates the ResolverDictionary object.

  • After the orchestration completes, the code calls the AdvanceItinerary method, as shown in the following code.

    C# Copy Code
    // Call the Itinerary helper to advance to the next step.
itinerary.Itinerary.Advance(OutboundMessage, itineraryStep.ItineraryStep);
  • This advances the current itinerary by updating its properties and promoting the next service defined in the itinerary as the one to execute next. The method copies the itinerary into the outbound message, which the service publishes back into the Message Box database through a direct-bound send port.

  • A subscription for the Microsoft.Practices.ESB.Services.Delivery service orchestration triggers invocation of this orchestration. This orchestration follows a similar process to the first one, obtaining the current Itinerary step. However, this orchestration iterates through a collection of resolvers returned by the ItineraryStep instance. For each resolver in the collection, the delivery orchestration uses the ​Microsoft BizTalk ESB Toolkit Resolver and Adapter Framework to resolve the transport locations and promote them as context properties within the outgoing message, as shown in the following code.

    C# Copy Code
    // Move to retrieve the first resolver.
resolver = resolvers.Current;

// Pass the resolver configuration to the Resolver Manager
// for resolution.
resolverDictionary =
   Microsoft.Practices.ESB.Resolver.ResolverMgr.Resolve(InboundMessage,
                                                        resolver);

// Set the transport properties.
transportLocation =
   resolverDictionary.Item("Resolver.TransportLocation");
transportType =
   resolverDictionary.Item("Resolver.TransportType");

// Call the Adapter Manager to set all necessary properties.
Microsoft.Practices.ESB.Adapter.AdapterMgr.SetEndpoint(
                                resolverDictionary, DeliveryMessage);

// Set the delivery port address and type.
DeliveryPort(Microsoft.XLANGs.BaseTypes.Address) = transportLocation;
DeliveryPort(Microsoft.XLANGs.BaseTypes.TransportType) = transportType;
  • A subscription for the ProcessAndRespond orchestration triggers invocation of this orchestration because of a match of the message context properties defined for the filter expression properties.

    Copy Code
    (Microsoft.Practices.ESB.Itinerary.Schemas.ServiceName == :"ProcessAndRespond")
&& Microsoft.Practices.ESB.Itinerary.Schemas.ServiceState == "Pending")
&& (Microsoft.Practices.ESB.Itinerary.Schemas.ServiceType == "Orchestration")
  • The ProcessAndRespond orchestration advances the itinerary and sends the original request message back to the on-ramp service to the Itinerary Test Client application as the response.


Installing and Running the JMS MQRFH2 Component Sample

The JMS MQRFH2 Component sample consists of three parts that demonstrate how you can use the ​Microsoft BizTalk ESB Toolkit JMS MQRFH2 Component to read and write IBM WebSphere MQ message headers in an ESB application. This section includes the following topics:

  • Installing the JMS MQRFH2 Component Sample

  • JMS MQRFH2 Sample Dependencies and Strong Key Name Definition

  • Running the JMS MQRFH2 Component Sample


Installing the JMS MQRFH2 Component Sample

To use this sample with the ​Microsoft BizTalk ESB Toolkit, you must also install the following:

  • IBM WebSphere MQ 5.3 (with CSD12), WebSphere MQ 6.x or WebSphere MQ 7.0

  • The IBM "RfhUtil" JMS test utility for queuing and retrieving messages

The JMS MQRFH2 Component sample requires the JMS MQRFH2 component to reside in the PipelineComponents folder of your Microsoft BizTalk Server installation folder and the corresponding schemas to reside in the global assembly cache. Installing the ​Microsoft BizTalk ESB Toolkit core automatically copies and installs the assemblies to the correct locations. However, if required, you can manually perform these tasks.

To manually install the JMS MQRFH2 component and schemas

  1. Copy the assembly Microsoft.Practices.ESB.JMS.PipelineComponents.dll to the PipelineComponents folder of your BizTalk Server installation folder.

  2. Add the schema assembly Microsoft.Practices.ESB.JMS.Schemas.Property.dll to the global assembly cache using the .NET Framework Configuration Tool located in the Administrative Tools section of the Start menu.

This section describes the process for installing the JMS MQRFH2 sample into the GlobalBank.JMS BizTalk application. Before you install this sample, you must install the ESB Toolkit Core as described in Installing the BizTalk ESB Toolkit Core (http://go.microsoft.com/fwlink/?LinkId=187612).

You can install the JMS MQRFH2 Component sample from the solution project or use the Windows Installer file included with the ​Microsoft BizTalk ESB Toolkit. This section contains the following topics:

  • Install the JMS MQRFH2 Sample Using the Install Scripts

  • Assemblies and Artifacts Installed by the JMS MQRFH2 Component Sample

  • Test the JMS MQRFH2 Sample Installation


Install the JMS MQRFH2 Sample Using the Install Scripts

This section describes how you can install the JMS MQRFH2 sample using the install scripts provided with the ​Microsoft BizTalk ESB Toolkit.

To install the JMS MQRFH2 samples from the install scripts

  1. Using WebSphere Explorer, create a Queue Manager with the name ESB.JMS.Sample.QueueManager.

  2. Using WebSphere Explorer, create the following four queues within ESB.JMS.Sample.QueueManager:

    • ESB.JMS.SAMPLE.DYNAMICQ1

    • ESB.JMS.SAMPLE.DYNAMICQ2

    • ESB.JMS.SAMPLE.REPLY

    • ESB.JMS.SAMPLE.SENDTOBIZTALK

  3. On the Start menu, click Run.

  4. In the Run dialog box, type cmd, and then press ENTER.

  5. Run the following command, replacing the <path> parameter with the full path to the .cmd file you want to install (the default path in this release is \Source\Samples\JMS\Install\Scripts\):

    Copy Code
    <path>\Setup_bin.cmd


Assemblies and Artifacts Installed by the JMS MQRFH2 Component Sample

The following table lists the assemblies and artifacts installed by the ​Microsoft BizTalk ESB Toolkit JMS MQRFH2 Component sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | GlobalBank.ESB.JMS.Processes.JMSRouter
BizTalk application GlobalBank.ESB | Send Ports | GlobalBank.ESB.JMS.Processes_1.0.0.0_GlobalBank.ESB.JMS.Processes.JMSRouter_DestinationProcessing_c2c8b2b87f54180a
BizTalk application GlobalBank.ESB | Receive Ports | JMSRouter.MessageProcessing
BizTalk application GlobalBank.ESB | Receive Locations | JMSRouter.MessageProcessing_MQS
BizTalk application GlobalBank.ESB | Schemas |
BizTalk application GlobalBank.ESB | Pipelines | GlobalBank.ESB.JMS.Pipelines.JMS_PassthroughReceive Version 1.0.0.0
 |  | GlobalBank.ESB.JMS.Pipelines.JMS_PassthroughSend Version 1.0.0.0
 |  | GlobalBank.ESB.JMS.Pipelines.JMS_XMLReceive Version 1.0.0.0
 |  | GlobalBank.ESB.JMS.Pipelines.JMS_XMLSend Version 1.0.0.0
BizTalk application GlobalBank.ESB | Resources | GlobalBank.ESB.JMS.Pipelines Version 1.0.0.0
 |  | GlobalBank.ESB.JMS.Processes Version 1.0.0.0
BizTalk application GlobalBank.ESB | Policies |
BizTalk application GlobalBank.ESB | Maps |
Global assembly cache | Assemblies | GlobalBank.ESB.JMS.Pipelines Version 1.0.0.0
 |  | GlobalBank.ESB.JMS.Processes Version 1.0.0.0
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components |


Test the JMS MQRFH2 Sample Installation

You can check for successful installation and operation of the ​Microsoft BizTalk ESB Toolkit JMS MQRFH2 sample before you execute any of the sample scenarios.

To test the JMS MQRFH2 sample installation

  1. Use the "RFHUtil" JMS test utility to write the test messages in the \Source\Samples\JMS\Test\Data\Load folder to the queue named ESB.JMS.SAMPLE.SENDTOBIZTALK.

  2. The sample sends the message to the destination queue and a copy of the message to the reply queue.


JMS MQRFH2 Sample Dependencies and Strong Key Name Definition

The Visual Studio 2013 project ESB.JMS.PipelineComponents depends on the following folder:

  • <BizTalk Server Installation Directory>. This folder provides access to the following namespaces:

    • Microsoft::BizTalk::Message::Interop

    • Microsoft::BizTalk::Component::Interop

The Strong Name Key Definition

Usually, the strong-name key definition resides in the AssemblyInfo.cpp file. However, this would conflict with the C++ manifest file that the compiler adds to the assembly after it reads the AssemblyInfo.cpp file. This conflict would prevent any attempt to place the file in the global assembly cache. Instead, the linker controls the strong name key file by specifying the key file located at ../../../../../../Keys/Microsoft.Practices.ESB.snk. To edit this value, navigate to the following option setting:

ESB.JMS.Schemas

- Project

- - Properties

- - - Configuration Properties

- - - - Linker

- - - - - Advanced

- - - - - - Key File

Note
If you construct a JMS Pipeline Component, you must edit the AssemblyInfo.cpp file to remove any references to the strong-name key file, as described earlier. After you do that, edit the Key File option in the advanced properties of the Linker to specify the path and name of the strong-name key file.


Running the JMS MQRFH2 Component Sample

The JMS MQRFH2 Component sample consists of three parts:

  • Running the JMS MQRFH2 Header Preservation Sample. This part demonstrates full-fidelity header preservation as a message travels from IBM WebSphere MQ, through ESB and Microsoft BizTalk Server, and back to IBM WebSphere MQ.

  • Running the Header Property Access from an Orchestration Sample. This part demonstrates how code within an ESB orchestration can access MQRFH2 header properties. In this case, the code uses a header property to specify the destination queue name.

  • Running the Bulk Load Content-Based Routing Sample. This part demonstrates bulk loading a queue with messages, and it shows how the application routes messages to the destination queues specified as part of the message content.


Running the JMS MQRFH2 Header Preservation Sample

This part of this sample deposits a message into a WebSphere queue. The ESB picks up this message and deposits it into an outbound WebSphere queue. This demonstrates that the ESB and Microsoft BizTalk preserve full-fidelity RFH2 headers as a message travels through BizTalk Server.

To run the Header Preservation sample

  1. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  2. Run the IBM RfhUtil utility, and then select the queue manager named ESB.JMS.Sample.QueueManager in the first drop-down list to connect to this queue manager.

  3. In the second drop-down list, select the target outbound queue named ESB.JMS.SAMPLE.SENDTOBIZTALK, as shown in Figure 1.

    Figure 1

    Connecting to the queue manager and the outbound queue in RfhUtil

  4. If the drop-down list does not contain any queues, make sure that the queue manager is running by checking the WebSphere MQ Services item, as shown in Figure 2.

    Figure 2

    Checking that the queue manager is running in the WebSphere Services item

  5. Click the ReadFile button in the RfhUtil utility and navigate to the test message file named TEST-000128.JMS located in the subfolder named \Source\Samples\JMS\Test\Data\Load\. This file contains a batch of 128 test messages, but the utility loads only the first one.

  6. Click the RFH tab, and then make sure that only the JMS check box is selected.

  7. Click the jms tab, and then make sure that the selected Reply To queue is ESB.JMS.SAMPLE.DYNAMICQ1 and that the selected Destination Queue is ESB.JMS.SAMPLE.DYNAMICQ2.

  8. Click the Main tab, and then click the Write Q button to write the message into the queue.

  9. After a delay while the application executes, the ESB output message appears in the ESB.JMS.SAMPLE.DYNAMICQ1 and ESB.JMS.SAMPLE.DYNAMICQ1 queues. Open the WebSphere Queue Explorer and browse the queues to confirm this.

  10. Go back to the RfhUtil utility and connect to the queues to see the messages. Click the MQMD, RFH, and jms tabs to verify that the input and output values are unchanged for the message in the Destination Queue, and that the message in the Reply To queue is the same except that, instead of being a standard JMS message, the message is marked as "other".


Running the Header Property Access from an Orchestration Sample

This part of the sample demonstrates how the ESB promotes JMS header metadata into message context properties, which code and components in orchestrations within Microsoft BizTalk can access. The sample includes a receive pipeline that contains an instance of the ESB JMS component that promotes JMS header metadata into message context properties.

The receive port passes the message to an orchestration named JMSRouter that retrieves the queue name assigned by the RfhUtil utility (and sent in the header metadata) from the context properties of the message. The orchestration assigns this queue name to a dynamic send port and sends the message to that port.

A send pipeline for the port contains an instance of the ESB JMS component that demotes the message context properties into the JMS header metadata.

To run the Header Property Access sample

  1. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  2. Run the IBM RfhUtil utility; select the queue manager named ESB.JMS.Sample.QueueManager in the first drop-down list to connect to this queue manager, as in Part 1 of this sample.

  3. In the second drop-down list, select the target outbound queue named ESB.JMS.SAMPLE.SENDTOBIZTALK.

  4. Click the ReadFile button in the RfhUtil utility, and then navigate to the test message file named TEST-000128.JMS located in the subfolder named \Source\Samples\JMS\Test\Data\Load\. This file contains a batch of 128 test messages, but the utility loads only the first one.

  5. Click the RFH tab, and then make sure that only the JMS check box is selected.

  6. Click the jms tab, and then make sure that the selected Reply To queue is ESB.JMS.SAMPLE.REPLY and that the selected Destination Queue is ESB.JMS.SAMPLE.DYNAMICQ2.

  7. Click the Main tab, and then click the Write Q button to write the message into the queue.

  8. After a delay while the application executes, the ESB output message appears in the ESB.JMS.SAMPLE.DYNAMICQ2 queue. Open the WebSphere Queue Explorer and browse the queues to confirm this.

How the Sample Works

Inside the orchestration, code can access the values that were in the JMS headers by loading the message into an XmlDocument instance, as shown in the following code.

C# Copy Code
if (null != InboundMsg(
    Microsoft.Practices.ESB.JMS.Schemas.Property.MQRFH2_NameValueData))
{
  jmsInfo.LoadXml(InboundMsg(
     Microsoft.Practices.ESB.JMS.Schemas.Property.MQRFH2_NameValueData));
  if (null != jmsInfo)
  {
    if (null != jmsInfo.SelectSingleNode("//Dst"))
    {
      xElement = jmsInfo.SelectSingleNode("//Dst");
      destinationQueue = xElement.InnerText.ToUpper(
                         System.Globalization.CultureInfo.CurrentCulture);
    }
    if (null != jmsInfo.SelectSingleNode("//Rto"))
    {
      xElement = jmsInfo.SelectSingleNode("//Rto");
      replyToQueue = xElement.InnerText.ToUpper(
                     System.Globalization.CultureInfo.CurrentCulture);
    }
  }
}

In addition, the code can access all of the MQMD context properties of the message.


Running the Bulk Load Content-Based Routing Sample

This part of the sample demonstrates bulk loading a queue with messages that the ESB and Microsoft BizTalk will route to different destination queues based on the queue name specified in each message. It uses the features of the sample that you have seen in the previous two parts.

To run the Bulk Load Content-based Routing Access sample

  1. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  2. Run the IBM RfhUtil utility, and then select the queue manager named ESB.JMS.Sample.QueueManager in the first drop-down list to connect to this queue manager, as in Part 2 of this sample.

  3. In the second drop-down list, select the target outbound queue named ESB.JMS.SAMPLE.SENDTOBIZTALK, as in Part 2 of this sample.

  4. Click the Load Q button in the RfhUtil utility, and then navigate to the test message file named TEST-000128.JMS located in the subfolder named \Source\Samples\JMS\Test\Data\Load\. This file contains a batch of 128 test messages that the sample will send to the ESB.

  5. In the Load dialog box, leave all values set to their default values.

  6. In the Load dialog box, click OK to add all the messages to the input queue.

  7. After a delay while the application executes, the ESB output messages appear in various destination queues, depending on the values in their JMS headers. However, all specify the same Reply To queue, so all the replies appear in the ESB.JMS.SAMPLE.REPLY queue. Open the WebSphere Queue Explorer and browse the queues to confirm this.


Installing and Running the Namespace Component Sample

The Namespace Component sample demonstrates typical usage scenarios for the ESB Namespace component. It shows how you can use the component to inject and remove namespaces in a document as part of the send and the receive process.

This section contains the following topics:

  • Installing the Namespace Component Sample

  • Running the Namespace Component Sample


Installing the Namespace Component Sample

The Namespace Component sample requires the Namespace component (in the assembly Microsoft.Practices.ESB.Namespace.PipelineComponents.dll) to reside in the PipelineComponents folder of your Microsoft BizTalk Server installation folder. Installing the ​Microsoft BizTalk ESB Toolkit core automatically copies the assembly to the correct location.

This section describes the process for installing the Namespace Component sample into the GlobalBank.ESB BizTalk application. You can install the Namespace Component sample from the solution project or use the Windows Installer file included with the ​Microsoft BizTalk ESB Toolkit. This section contains the following topics:

  • Install the Namespace Component Sample Using the Install Scripts

  • Assemblies and Artifacts Installed by the Namespace Component Sample


Install the Namespace Component Sample Using the Install Scripts

This section describes how you can install the Namespace Component sample from the Windows Installer file provided with the ​Microsoft BizTalk ESB Toolkit.

To install the Namespace Component sample from the install scripts

  1. On the Start menu, click Run.

  2. In the Run dialog box, type cmd, and then press ENTER to open a command prompt.

  3. Run the following command, replacing the <path> parameter with the full path to the .cmd file you want to install (the default path in this release is \Source\Samples\Namepace\Install\Scripts\):

    Copy Code
    <path>\Setup_bin.cmd


Assemblies and Artifacts Installed by the Namespace Component Sample

The following table lists the assemblies and artifacts installed by the ​Microsoft BizTalk ESB Toolkit Namespace Component sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | (none)
BizTalk application GlobalBank.ESB | Send Ports | NamespaceSendPortAdd_to_Remove
 |  | NamespaceSendPortAdd_to_PassThrough
 |  | NamespaceSendPortPassthrough_to_Remove
 |  | NamespaceSendPortAddViaExtraction_to_PassThrough
BizTalk application GlobalBank.ESB | Receive Ports | NamespaceReceivePortAdd_to_PassThrough
 |  | NamespaceReceivePortAdd_to_Remove
 |  | NamespaceReceivePortPassThrough_to_Remove
 |  | NamespaceReceivePortAddViaExtraction_to_PassThrough
BizTalk application GlobalBank.ESB | Receive Locations | NamespaceReceivePortAdd_to_PassThrough
 |  | NamespaceReceivePortAdd_to_Remove
 |  | NamespaceReceivePortPassThrough_to_Remove
 |  | NamespaceReceivePortAddViaExtraction_to_PassThrough
BizTalk application GlobalBank.ESB | Schemas | (none)
BizTalk application GlobalBank.ESB | Pipelines | GlobalBank.ESB.Namespace.Pipelines.NamespaceSampleReceivePipeline Version 2.0.0.0
 |  | GlobalBank.ESB.Namespace.Pipelines.NamespaceSampleSendPipeline Version 2.0.0.0
BizTalk application GlobalBank.ESB | Resources | GlobalBank.ESB.Namespace.Pipelines Version 2.0.0.0
BizTalk application GlobalBank.ESB | Policies | (none)
BizTalk application GlobalBank.ESB | Maps | (none)
Global assembly cache | Assemblies | GlobalBank.ESB.Namespace.Pipelines Version 2.0.0.0
Pipeline components | (none) | (none)


Running the Namespace Component Sample

The Namespace Component sample application contains four receive location/send port pairs. Each pair represents a test. The following are the four tests:

  • Add to Pass-through. This test adds a namespace to an XML message document and writes the message directly to a file so that you can see the new namespace. The input file for this test is TEST_Add_to_PassThrough.0000.ns.xml. This test uses the NamespaceSampleReceivePipeline that contains an AddNamespace component.

  • Add to Remove. This test adds a namespace to an XML document message and then removes it. It then writes the message directly to a file. The input file for this test is TEST_ Add_to_Remove.0000.ns.xml. This test uses the NamespaceSampleReceivePipeline that contains an AddNamespace component and the NamespaceSampleSendPipeline that contains a RemoveNamespace component.

  • Pass-through to Remove. This test removes all namespaces from an XML document message and writes the message directly to a file so that you can confirm this. The input file for this test is TEST_PassThrough_to_Remove.0000.ns.xml. This test uses the NamespaceSampleSendPipeline that contains a RemoveNamespace component.

  • Add Via Extraction to Pass-through. This test extracts the OrderDetails element of an XML document message and writes a new message containing this element directly to a file. The input file for this test is TEST_AddViaExtraction_to_PassThrough.0000.ns.xml. This test uses the NamespaceSampleReceivePipeline that contains an AddNamespace component with the ExtractionNodeXPath property set to /CanonicalOrder/OrderDetails (any valid XPath that returns an element will suffice for this property).

The underlying receive locations in the sample application have file masks that are appropriate for each of the test types, and the related send ports filter on the receive port name. Therefore, to execute a test, you just drop the appropriately named message into the input folder. The sample application executes the test and drops the updated message into the output folder using a name appropriate for the current test, and including the Message ID.

This section contains the following topics:

  • Running the Namespace Component Tests

  • How the Add Namespace Sample Works

  • How the Remove Namespace Sample Works


Running the Namespace Component Tests

The following procedure shows how you can run all four of the test scenarios for the ​Microsoft BizTalk ESB Toolkit Namespace Component sample.

To run the Namespace Component sample test scenarios

  1. Before you run this sample for the first time, make sure that the receive location and send port URL point to the appropriate subfolders in the source distribution files. Specify the subfolder \Source\Samples\Namespace\Test\Filedrop\In for the receive location and the subfolder \Source\Samples\Namespace\Test\Filedrop\Out for the send port URL.

  2. If the GlobalBank.ESB application is not already running, use the Microsoft BizTalk Administration Console to start it.

  3. Make a copy of the file named TEST_Add_to_PassThrough.0000.ns.xml (located in the \Source\Samples\Namespace\Test\Data\ subfolder of your ESB installation folder), and rename the copy by removing the "TEST_" prefix.

  4. Copy the renamed file into the \Source\Samples\Namespace\Test\Filedrop\In subfolder.

  5. The ESB picks up the message, adds a namespace to it, and drops the updated message into the \Source\Samples\Namespace\Test\Filedrop\Out subfolder. Open the input and output files in a text editor to see the effect of this test.

  6. Now run the second test. Make a copy of the file named TEST_Add_to_Remove.0000.ns.xml and rename it by removing the "TEST_" prefix.

  7. Copy the renamed file into the \Source\Samples\Namespace\Test\Filedrop\In subfolder.

  8. The ESB picks up the message, adds a namespace to it, removes the new namespace, and drops the updated message into the \Source\Samples\Namespace\Test\Filedrop\Out subfolder. Open the input and output files in a text editor to see the effect of this test.

  9. Now run the third test. Make a copy of the file named TEST_PassThrough_to_Remove.0000.ns.xml and rename it by removing the "TEST_" prefix.

  10. Copy the renamed file into the \Source\Samples\Namespace\Test\Filedrop\In subfolder.

  11. The ESB picks up the message, removes the existing namespace, and drops the updated message into the \Source\Samples\Namespace\Test\Filedrop\Out subfolder. Open the input and output files in a text editor to see the effect of this test.

  12. Finally, run the fourth test. Make a copy of the file named TEST_AddViaExtraction_to_PassThrough.0000.ns.xml and rename it by removing the "TEST_" prefix.

  13. Copy the renamed file into the \Source\Samples\Namespace\Test\Filedrop\In subfolder.

  14. The ESB picks up the message, extracts the element specified in the ExtractionNodeXPath property, creates a message from this element with the specified namespace values, and drops the updated message into the \Source\Samples\Namespace\Test\Filedrop\Out subfolder. Open the input and output files in a text editor to see the effect of this test.


How the Add Namespace Sample Works

The first, second, and fourth tests use the Add Namespace component located in the NamespaceSampleReceivePipeline pipeline. It takes as input a document with no namespace on the root node, such as the following:

Copy Code
<CanonicalOrder OrderID="OrderID_0" OrderDate="OrderDate_1" Status="Status_2">

The following table shows the property values set for the Add Namespace component.

Property | Type | Value
ExtractionNodeXPath | Static | (empty)
NamespaceBase | Static | http://schemas.microsoft.biztalk.esb.test.com/test
NamespacePrefix | Static | esbTest
Separator | Static | /
XPaths | Dynamic | /CanonicalOrder/@OrderID|/CanonicalOrder/@OrderDate

The property settings shown in the table cause the component to search the XML document by executing the two XPath queries /CanonicalOrder/@OrderID and /CanonicalOrder/@OrderDate (the two queries specified for the XPaths property, separated by a "pipe" character). These queries return the values of the OrderID and OrderDate attributes of the root node of the document; in this example, the two values are "OrderID_0" and "OrderDate_1".

The component then uses these values, and the values of the other properties, to construct the new root namespace. It combines the NamespaceBase, the NamespacePrefix, the Separator, and the values from the two XPath queries in the following format:

Copy Code
xmlns:{NamespacePrefix}="{NamespaceBase}{Separator}{XPaths[1]}{Seperator}
                         {XPaths[2]}{Separator}...{XPaths[n]}"

This produces the new namespace, as shown here:

Copy Code
xmlns:esbTest="http://schemas.microsoft.biztalk.esb.test.com/test
               /OrderID_0/OrderDate_1"

Therefore, the updated document after processing by the NamespaceSampleReceivePipeline pipeline is the following:

Copy Code
<esbTest:CanonicalOrder xmlns:esbTest=
    "http://schemas.microsoft.biztalk.esb.test.com/test/OrderID_0
    /OrderDate_1" OrderID="OrderID_0" OrderDate="OrderDate_1"
    Status="Status_2">

Using the ExtractionNodeXPath Property

By default, the Add Namespace component uses the root element of the XML document within the message when adding namespace and prefix information. If you want to use only a subset of the XML document as the message body (useful in certain envelope scenarios or when only a portion of an inbound document has relevance), you can set the ExtractionNodeXPath property to force the Add Namespace component to seek the specified element for use as the resultant message. For example, if you know that a received CanonicalOrder message will have only one OrderDetails element that is relevant for consumers of this message contained within it, you can set the ExtractionNodeXPath property to specify the path to the OrderDetails element. You can see an example of this process in the Add Via Extraction to Pass-through test described earlier.

Note
The ExtractionNodeXPath property must be an XPath that returns only one element. The component will raise an exception if the result is not an element or if the XPath query returns more than one element.


How the Remove Namespace Sample Works

The second and third tests use the Remove Namespace component located in the NamespaceSampleSendPipeline pipeline. It takes as input a document with a namespace on the root node, such as the following:

Copy Code
<ns0:CanonicalOrder OrderID="OrderID_0" OrderDate="OrderDate_1"
    Status="Status_2"
    xmlns:ns0="http://schemas.microsoft.biztalk.esb.test.com/test">

The Remove Namespace component simply removes this namespace and returns a document that does not have a root node namespace, as shown here:

Copy Code
<CanonicalOrder OrderID="OrderID_0" OrderDate="OrderDate_1" Status="Status_2">


Installing and Running the Transformation Service Sample

The Transformation Web service directly exposes maps deployed in Microsoft BizTalk through a Web service, thereby eliminating a trip by the message to the BizTalk Message Box database. The Transformation Web service allows external applications to submit a document to the Microsoft.Practices.ESB application and have it transformed using a map deployed within BizTalk.

This section contains the following topics:

  • Installing the Transformation Service Sample

  • Running the Transformation Service Sample


Installing the Transformation Service Sample

This section describes the process for installing the Transformation Service sample into the GlobalBank.ESB BizTalk application. You can install the Transformation Service sample from the solution project or use the Windows Installer file included with the ​Microsoft BizTalk ESB Toolkit. This section contains the following topics:

  • Install the Transformation Service Sample Using the Install Scripts

  • Assemblies and Artifacts Installed by the Transformation Service Sample


Install the Transformation Service Sample Using the Install Scripts

This section describes how you can install the Transformation Service sample from the install scripts provided with the ​Microsoft BizTalk ESB Toolkit.

To install the Transformation Service sample from the install scripts

  1. On the Start menu, click Run.

  2. In the Run dialog box, type cmd, and then press ENTER to open a command prompt.

  3. Execute the following command, replacing the <path> parameter with the full path to the .cmd file you want to install (the default path in this release is \Source\Samples\TransformServices\Install\Scripts\):

    Copy Code
    <path>\TransformServices_Install.cmd


Assemblies and Artifacts Installed by the Transformation Service Sample

The following table lists the assemblies and artifacts installed by the ​Microsoft BizTalk ESB Toolkit Transformation Service sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | (none)
BizTalk application GlobalBank.ESB | Send Ports | (none)
BizTalk application GlobalBank.ESB | Receive Ports | (none)
BizTalk application GlobalBank.ESB | Receive Locations | (none)
BizTalk application GlobalBank.ESB | Schemas | GlobalBank.ESB.TransformServices.Schemas.RetailOrder Version 2.0.0.0
 |  | GlobalBank.ESB.TransformServices.Schemas.OrderConfirmation Version 2.0.0.0
 |  | GlobalBank.ESB.TransformServices.Schemas.CanonicalOrder Version 2.0.0.0
BizTalk application GlobalBank.ESB | Pipelines | (none)
BizTalk application GlobalBank.ESB | Resources | GlobalBank.ESB.TransformServices.Maps Version 2.0.0.0
 |  | GlobalBank.ESB.TransformServices.Schemas Version 2.0.0.0
BizTalk application GlobalBank.ESB | Policies | (none)
BizTalk application GlobalBank.ESB | Maps | GlobalBank.ESB.TransformServices.Maps.CanonicalOrder_To_OrderConfirmation Version 2.0.0.0
 |  | GlobalBank.ESB.TransformServices.Maps.RetailOrder_To_CanonicalOrder Version 2.0.0.0
Global assembly cache | Assemblies | GlobalBank.ESB.TransformServices.Maps Version 2.0.0.0
 |  | GlobalBank.ESB.TransformServices.Schemas Version 2.0.0.0
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components | (none)


Running the Transformation Service Sample

You can execute the Transformation Service sample using any tool or utility that can execute Web service methods. For example, you can use Storm, available from CodePlex (http://go.microsoft.com/fwlink/?LinkId=187762), or you can create your own test client that invokes the Transformation Web service.

To use the .NET Web Service Studio to test for correct installation of the Transformation Service sample, enter the URL for the ASMX-based Transformation Web service into the WSDL EndPoint text box, and then click the Get button. This generates a client front-end interface that you can use to call the ESB Transformation Web Service, as shown in Figure 1.

Figure 1

Using the .NET Web Service Studio to test the Transformation Service sample

The Transformation Service sample contains two Microsoft BizTalk maps and two test XML message documents. You can execute the Transformation Web service with the XML messages named TEST_CanonicalOrder_to_OrderConfirmation.xml and TEST_RetailOrder_to_CanonicalOrder.xml (located in the \Source\Samples\TransformServices\Test\Data folder).

The service will automatically transform the messages using the schemas CanonicalOrder.xsd and RetailOrder.xsd and OrderConfirmation.xsd (located in the \Source\Samples\TransformServices\Source\ESB.TransformServices.Schemas folder), and .NET Web Service Studio will display the resulting transformed messages. The following procedure shows how you can test the CanonicalOrder_To_OrderConfirmation map.

To test the GlobalBank.ESB.TransformServices.Maps.CanonicalOrder_To_OrderConfirmation map

  1. If the GlobalBank.ESB application is not running, use the BizTalk Administration Console to start it.

  2. Enter the following string representation of the TEST_CanonicalOrder_to_OrderConfirmation.xml file as the value of the message parameter in the Input tree view of .NET Web Service Studio. This string conforms to the GlobalBank.ESB.TransformServices.Schemas.CanonicalOrder schema:

    Copy Code
    <ns0:CanonicalOrder OrderID="OrderID_0" OrderDate="OrderDate_1"
    Status="Status_2" xmlns:ns0=
    "http://schemas.globalbank.esb.transformservices.com">
    <OrderHeader><CustomerName>CustomerName_0</CustomerName>
    <CustomerID>CustomerID_0</CustomerID><ShipToLine1>
    ShipToLine1_0</ShipToLine1><ShipToLine2>ShipToLine2_0
    </ShipToLine2><BillToLine1>BillToLine1_0</BillToLine1>
    <BillToLine2>BillToLine2_0</BillToLine2><OrderTotal>OrderTotal_0
    </OrderTotal></OrderHeader><OrderDetails><LineItem Qty="Qty_0"
    PartNum="PartNum_1" Description="Description_2"
    UnitPrice="UnitPrice_3" Ext="Ext_4" /></OrderDetails>
    <B2BPartnerDetails CreditLimit="CreditLimit_0"
    AccountBalance="AccountBalance_1"
    LastOrderedData="LastOrderedData_2"
    DiscountLevel="DiscountLevel_3" /></ns0:CanonicalOrder>
  3. Enter the following string as the value of the mapName parameter in the Input tree view of .NET Web Service Studio. This is the fully typed name of the BizTalk map to execute against the message:

    Copy Code
    GlobalBank.ESB.TransformServices.Maps.CanonicalOrder_To_
    OrderConfirmation, GlobalBank.ESB.TransformServices.Maps,
    Version=1.0.0.0, Culture=neutral, PublicKeyToken=<insertYourPublicKeyTokenHere>
  4. Click the Invoke button to execute the Web service. The Output test box displays the results.


Installing and Running the Dynamic Resolution Sample

The Dynamic Resolution sample demonstrates typical usage scenarios for the ESB Dispatcher and ESB Dispatcher Disassembler pipeline components. It demonstrates how you can use the components to dynamically resolve endpoint location, set routing properties, and resolve and execute Microsoft BizTalk maps at the messaging level without using an orchestration. It also demonstrates both one-way and two-way messaging patterns.

Note
For optimum results when familiarizing yourself with the resolution mechanism within the ​Microsoft BizTalk ESB Toolkit, you should run the Installing and Running the Resolver Service Sample before you run the Dynamic Resolution sample.

The sample application contains two receive locations and two dynamic send ports, which the sample uses to demonstrate multiple use cases for the dynamic resolution components. Each use case shows how the resolvers and adapter providers in the Resolution and Adapter Provider Framework, when used in combination, can provide the basis for a variety of loosely coupled messaging solutions.

One-Way Messaging Scenarios

All one-way messaging scenarios (except the one that uses the XPATH Resolver) use the file NAOrderDoc.xml, located in the \Source\Samples\DynamicResolution\Test\Data folder, as input to the receive location named DynamicResolution_FILE. There are seven one-way messaging examples, all represented by a unique binding file that you must import before you execute each example.

Two-Way Messaging Scenarios

All two-way messaging scenarios use the sample ESB.NorthAmericanServices Web service located at http://localhost/ESB.NorthAmericanServices/CustomerOrder.asmx to publish the request message into BizTalk. You can execute this Web service using Microsoft InfoPath or through a utility such as the Storm available from CodePlex (http://go.microsoft.com/fwlink/?LinkID=187762&clcid=0x409).

Each example dynamically resolves the endpoint URL to submit the message to the sample ESB.CanadianServices Web service located at http://localhost/ESB.CanadianServices/SubmitPOService.asmx. The example will execute either the submitOrder action or the submitPurchase action, depending on the results of the resolution process. The receive location for two-way messaging scenarios is DynamicResolutionReqResp_SOAP. There are 10 two-way messaging examples, all represented by a unique binding file that you must import before you execute each example.

Binding Files

The binding files for this sample are located in the folder named \Source\Samples\DynamicResolution\Samples\Release.

The binding file names all start with GlobalBank.ESB.DynamicResolution_SubmitOrder_To, followed by an indication of the individual example to which they apply. For example, the binding file for the "File Inbound to File Outbound using the STATIC Resolver" example is GlobalBank.ESB.DynamicResolution_SubmitOrder_To_FILE_To_FILE_STATIC_Bindings.xml.

Every time you import one of the binding files into the GlobalBank.ESB BizTalk application, the underlying receive location within the sample application is reset. The associated dynamic send port filters on the receive port name. Therefore, to execute a test, you just import one of the binding files and either drop the appropriately named message into the input folder (for one-way messaging scenarios) or call the NorthAmerican Web service using InfoPath, the Storm utility, or any other suitable client.

Sample Dependencies

The Dynamic Resolution sample has dependencies on a number of assemblies that are part of the core ESB installation. These assemblies are the following:

  • Microsoft.Practices.ESB.PipelineComponents.dll. This contains the ESB Dispatcher Pipeline component.

  • Microsoft.Practices.ESB.Resolver.dll. This implements the Resolver Manager called by the pipeline.

  • Microsoft.Practices.ESB.Resolver.BRE.dll. This implements the Business Rules Engine Resolver.

  • Microsoft.Practices.ESB.Resolver.STATIC.dll. This implements the STATIC Resolver.

  • Microsoft.Practices.ESB.Resolver.UDDI.dll. This implements the UDDI Resolver.

  • Microsoft.Practices.ESB.Resolver.UDDI3.dll. This implements the UDDI3 Resolver.

  • Microsoft.Practices.ESB.Resolver.XPATH.dll. This implements the XPATH Resolver.

  • Microsoft.Practices.ESB.Resolver.Schemas.dll. This contains the resolver schemas.

  • Microsoft.Practices.ESB.Adapter.dll. This implements the adapter manager.

  • Microsoft.Practices.ESB.Adapter.FTP.dll. This implements the FTP adapter provider.

  • Microsoft.Practices.ESB.Adapter.FILE.dll. This implements the FILE adapter provider.

  • Microsoft.Practices.ESB.Adapter.MQSeries.dll. This implements the MQSeries adapter provider.

  • Microsoft.Practices.ESB.Adapter.WcfBasicHttp.dll. This implements the WCF-BasicHttp adapter provider.

  • Microsoft.Practices.ESB.Adapter.WcfWSHttp.dll. This implements the WCF-WSHttp adapter provider.

The Dynamic Resolution sample is also dependent on correct configuration of the preceding resolvers and adapters. Make sure that you complete the process for configuring these, as described in Installing the ​Microsoft BizTalk ESB Toolkit.

This section contains the following topics:

  • Installing the Dynamic Resolution Sample

  • Running the Dynamic Resolution Sample


Installing the Dynamic Resolution Sample

This section describes the process for installing the Dynamic Resolution sample into the GlobalBank.ESB BizTalk application. You can install the Dynamic Resolution sample from the solution project or use the Windows Installer file included with the ​Microsoft BizTalk ESB Toolkit. This section contains the following topics:

  • Install the Dynamic Resolution Sample Using the Install Scripts

  • Assemblies and Artifacts Installed by the Dynamic Resolution Sample


Install the Dynamic Resolution Sample Using the Install Scripts

This section describes how you can install the Dynamic Resolution sample from the install scripts provided with the ​Microsoft BizTalk ESB Toolkit.

To install the Dynamic Resolution sample from the install scripts

  1. If you want to execute one-way messaging examples that use FTP, create the following FTP site:

    • FTP Virtual Directory name: Out

    • Location: \Source\Samples\DynamicResolution\Test\FTP\Out

    • Permissions: Read and Write

    • Ensure the BizTalk Application Users group has full access permission for this location

  2. If you want to execute two-way messaging examples that use MQSeries, use WebSphere Explorer to create the following:

    • A queue manager with the name ESB.DEP.Sample.QueueManager

    • A queue named TEST.OUT within the ESB.DEP.Sample.QueueManager

  3. On the Start menu, click Run.

  4. In the Run dialog box, type cmd, and then press ENTER to open the command prompt.

  5. Run the following command, replacing the <path> parameter with the full path to the .cmd file you want to install (the default path in this release is \Source\Samples\DynamicResolution\Install\Scripts\):

    Copy Code
    <path>\Setup_bin.cmd


Assemblies and Artifacts Installed by the Dynamic Resolution Sample

The following table lists the assemblies and artifacts installed by the ​Microsoft BizTalk ESB Toolkit Dynamic Resolution sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | (none)
BizTalk application GlobalBank.ESB | Send Ports | DynamicResolutionSolicitResp
 |  | DynamicResolutionOneWay
BizTalk application GlobalBank.ESB | Receive Ports | DynamicResolutionReqResp
 |  | DynamicResolution
BizTalk application GlobalBank.ESB | Receive Locations | DynamicResolutionReqResp_SOAP DynamicResolution_FILE
BizTalk application GlobalBank.ESB | Schemas | GlobalBank.ESB.DynamicResolution.Schemas.CNPurchaseOrderResponse Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Schemas.NAOrderDoc Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Schemas.NAOrderResponse Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Schemas.CNOrderDoc Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Schemas.CNOrderResponse Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Schemas.CNPurchaseOrderDoc Version 2.0.0.0
BizTalk application GlobalBank.ESB | Pipelines | GlobalBank.ESB.DynamicResolution.Pipelines.ESBReceiveSendXMLXML Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Pipelines.ESBReceiveXML Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Pipelines.ESBPassThrough Version 2.0.0.0
BizTalk application GlobalBank.ESB | Resources | GlobalBank.ESB.DynamicResolution.Pipelines Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Schemas Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Transforms Version 2.0.0.0
BizTalk application GlobalBank.ESB | Policies | CanadaSubmitOrderMaps.xml
 |  | GetCanadaEndPoint.xml
 |  | GetCanadaPurchaseEndPoint.xml
 |  | ResolveMap.xml
 |  | ResolveEndPoint.xml
BizTalk application GlobalBank.ESB | Vocabularies | DynamicRunTimeDocSpecs.xml DynamicRunTimeEndPoints.xml DynamicRunTimeMapTypes.xml DynamicRunTimeServiceActions.xml
BizTalk application GlobalBank.ESB | Maps | GlobalBank.ESB.DynamicResolution.Transforms.SubmitPurchaseOrderResponseCN_To_SubmitOrderResponseNA Version=2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Transforms.SubmitOrderRequestNA_To_SubmitOrderRequestCN Version=2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Transforms.SubmitOrderRequestNA_To_SubmitPurchaseOrderRequestCN Version=2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Transforms.SubmitOrderResponseCN_To_SubmitOrderResponseNA Version=2.0.0.0
Global assembly cache | Assemblies | GlobalBank.ESB.DynamicResolution.Pipelines Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Schemas Version 2.0.0.0
 |  | GlobalBank.ESB.DynamicResolution.Transforms Version 2.0.0.0
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components | (none)


Running the Dynamic Resolution Sample

To execute one of the use case examples, you import the appropriate Microsoft BizTalk binding file into the GlobalBank.ESB BizTalk application and then either drop a suitable message into the sample input folder or call the sample Web service. The Dynamic Resolution sample supports two main scenarios:

  • One-Way Messaging Scenarios for the Dynamic Resolution Sample. The Dynamic Resolution sample supports this scenario using a file drop folder as the publication point into Microsoft BizTalk.

  • Two-Way Messaging Scenarios for the Dynamic Resolution Sample. The Dynamic Resolution sample supports this scenario using the NorthAmerican Web service located at http://localhost/ESB.NorthAmericanServices/CustomerOrder.asmx as the publication point into BizTalk.

To understand how the sample uses the ESB Dispatcher and ESB Dispatcher Disassembler pipeline components, see How the Dynamic Resolution Sample Works.


One-Way Messaging Scenarios for the Dynamic Resolution Sample

This topic shows how you can run the one-way messaging scenarios for the ​Microsoft BizTalk ESB Toolkit Dynamic Resolution sample.

To run the one-way messaging scenarios for the Dynamic Resolution sample

  1. Before you run this sample for the first time, make sure that the receive location URL points to the appropriate directory. Specify the source subfolder \Source\Samples\DynamicResolution\Test\Filedrop\In for the DynamicResolution_FILE receive location. Additionally, make sure that the dynamic send port named DynamicResolutionOneWay exists.

    Note
    The Dynamic Resolution sample uses the dynamic resolution mechanism to send messages to the output folder, FTP site, or MQSeries queue. This is why a static send port is not defined for this sample. The Dynamic Resolution component retrieves the output URL from the Resolution and Adapter Provider Framework when called by the ESBReceiveXml pipeline, which is configured within the DynamicResolution_FILE receive location.

  2. If the GlobalBank.ESB application is not already running, use the Microsoft BizTalk Administration Console to start it.

  3. Decide which example you want to execute. All one-way messaging examples (except the one that uses the XPATH Resolver) use the file NAOrderDoc.xml located in the \Source\Samples\DynamicResolution\Test\Data folder as input to the receive location named DynamicResolution_FILE. There are seven one-way messaging examples, each represented by a unique binding file. The following tables list these examples, with their associated binding files and descriptions.

    File Inbound to File Outbound Using the STATIC Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_FILE_To_FILE_STATIC_Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    File Inbound to File Outbound Using the UDDI Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_FILE_To_FILE_UDDI_Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    File Inbound to File Outbound Using UDDI Resolver via UDDI Service Key

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_FILE_To_FILE_UDDI_SERVICEKEY_ Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    Note
    For the preceding example, you must change the service key in the binding file to one that exists on the target UDDI server.

    File Inbound to FTP Outbound Using the STATIC Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_FILE_To_FTP_STATIC_Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    File Inbound to FTP Outbound Using the STATIC Resolver and ENDPOINTCONFIG Parameter

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_FILE_To_FTP_STATIC__ ENDPOINTCONFIG_Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    Passes additional name/values pairs for the adapter provider to set.

    File Inbound to MQS Outbound Using the STATIC Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_FILE_To_MQS_STATIC_Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    File Inbound to FILE Outbound Using the XPATH Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_FILE_XPATH_STATIC_Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    Uses information within the message to determine the appropriate endpoint. The test files you can use with this example are NAOrderDoc_XPATH_FILE.xml, NAOrderDoc_XPATH_FTP.xml, and NAOrderDoc_XPATH_MQS.xml.

  4. Import the binding file for the messaging example you want to execute into the GlobalBank.ESB application.

  5. In Windows Explorer, open the folder \Source\Samples\DynamicResolution\Test\Data and copy the appropriate input file into the folder \Source\Samples\DynamicResolution\Test\Filedrop\In. The file you use depends on the example you decided to execute:

    • For the XPATH example, use one of the following files: NAOrderDoc_XPATH_FILE.xml, NAOrderDoc_XPATH_FTP.xml, or NAOrderDoc_XPATH_MQS.xml.

    • For all other examples, use the file NAOrderDoc.xml.

  6. Look in the appropriate location for the delivered message. The location depends on the binding file you used. The following are examples:

    • The File Inbound to FTP Outbound example delivers the message to the FTP virtual directory named Out that you created when you installed the sample.

    • The File Inbound to FILE Outbound example delivers the message to the \DynamicResolution\Test\Filedrop\Out subfolder.

    • The File Inbound to MQS Outbound example delivers the message to the TEST.OUT queue that you created when you installed the sample.

    • The File Inbound to FILE Outbound using the XPATH Resolver example delivers the message to the location specified in the message. The sample documents contain the destination location and transport type (the transport type is appended to the message file name; for example, the NAOrderDoc_XPATH_FTP.xml message contains the FTP transport type specification).

To understand how the sample uses the ESB Dispatcher and ESB Dispatcher Disassembler pipeline components, see How the Dynamic Resolution Sample Works.


Two-Way Messaging Scenarios for the Dynamic Resolution Sample

This topic shows how you can run the two-way messaging scenarios for the ​Microsoft BizTalk ESB Toolkit Dynamic Resolution sample.

To run the two-way messaging scenarios for the Dynamic Resolution sample

  1. Before you run this sample for the first time, make sure that the receive location URL points to the appropriate Web service. Specify the Web service URL /ESB.NorthAmericanServices/CustomerOrder.asmx for the DynamicResolutionReqResp_SOAP receive location. Also, make sure that the dynamic send port named DynamicResolutionSolicitResp exists.

    Note
    The Dynamic Resolution sample uses dynamic resolution to send messages to, and receive responses from, the Canadian Web service (http://localhost/ESB.CanadianServices/SubmitPOService.asmx). This is why a static send port is not defined for this sample. The dynamic resolution component retrieves the outbound URL from the Resolution and Adapter Provider Framework called by the ESBReceiveXml pipeline, which is configured within the DynamicResolutionReqResp_SOAP receive location. In some of the two-way messaging examples, the ESBMapSend pipeline resolves and executes Microsoft BizTalk maps.

  2. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  3. Decide which example you want to execute. All two-way messaging scenarios use the ESB.NorthAmericanServices Web service located at http://localhost/ESB.NorthAmericanServices/CustomerOrder.asmx to publish the request message to BizTalk, which uses the receive location named DynamicResolutionReqResp_SOAP. There are 10 two-way messaging examples, each represented by a unique binding file. The following tables list these examples, with their associated binding files and descriptions.

    SOAP Inbound to SOAP Outbound (submitOrder Action) Using the BRE Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_SubmitOrder_BRE_Bindings.xml to set the receive location and send port properties.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    SOAP Inbound to SOAP Outbound (submitOrder Action) Using the BRE Resolver for Endpoint and Transformation Resolution

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_SubmitOrder_BRE_Routing_AND_ Transform_Bindings.xml to set the receive location and send port properties.

    Uses the ESB Dispatcher component on the outbound send port pipeline and the outbound receive location pipeline to dynamically resolve and execute the map.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    SOAP Inbound to SOAP Outbound (submitOrder Action) Using the STATIC Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_SubmitOrder_STATIC_Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    SOAP Inbound to SOAP Outbound (submitOrder Action) Using the UDDI Resolver Against the Microsoft UDDI Server

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_SubmitOrder_UDDI_MSFTREGISTRY_ Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    Note
    For the preceding example, you must change the service key in the binding file to one that exists on the target UDDI server.

    SOAP Inbound to SOAP Outbound (submitOrder Action) Using the UDDI Resolver Against the SOA Software UDDI Server

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_SubmitOrder_UDDI_SOAREGISTRY_ Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    SOAP Inbound to SOAP Outbound (submitOrder Action) Using the XPATH Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_SubmitOrder_XPATH_Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    The message contains the endpoint configuration ID=http://localhost/ESB.CanadianServices/SubmitPOService.asmx and customerName=http://globalbank.esb.dynamicresolution.com/canadianservices/.

    SOAP Inbound to SOAP Outbound (submitPurchase Action) Using the BRE Resolver Endpoint and Transformation Resolution

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_SubmitPurchaseOrder_BRE_Routing_ AND_Transform_Bindings.xml to set the receive location and send port properties.

    Uses the ESB Dispatcher component on the outbound send port pipeline and the outbound receive location pipeline to dynamically resolve and execute the map.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    The BRE Resolver changes the Action from submitOrder to submitPurchase.

    SOAP Inbound to SOAP Outbound (submitPurchase Action) Using the STATIC Resolver

    Uses the binding file named GlobalBank.ESB.DynamicResolution_SubmitOrder_To_SubmitPurchaseOrder_STATIC_ Bindings.xml to set the receive location and send port properties.

    Sets the maps statically at the receive port.

    Uses the ESB Dispatcher at the receive location for endpoint resolution.

    The STATIC Resolver changes the Action from submitOrder to submitPurchase.

  4. Import the binding file for the messaging example you want to execute into the GlobalBank.ESB application.

  5. Call the NorthAmerican Web service using Microsoft InfoPath, the .NET Web Service Studio, or any other appropriate mechanism. Make sure that you include all parameters required by the operation.

  6. Look for the returned message response. If you specified the submitOrder action, the text "Submit Order" will precede the value of the ID field in the returned message. If you specified the submitPurchase action, the text "Submit Purchase" will precede the value of the ID field in the returned message.

To understand how the sample uses the ESB Dispatcher and ESB Dispatcher Disassembler pipeline components, see How the Dynamic Resolution Sample Works.


How the Dynamic Resolution Sample Works

The Dynamic Resolution sample uses the ESB Dispatcher Disassembler pipeline component for all the messaging examples described in the previous section.

For one-way messaging scenarios, the example resolves the endpoint using the STATIC, BRE, or XPATH Resolver and brokers the protocol from FILE to FILE, FTP, or MQSeries.

For two-way messaging scenarios, the example resolves the endpoint using the STATIC, BRE, UDDI, or XPATH Resolver and brokers the protocol from SOAP to either SOAP or WCF-BasicHttp. In addition, the examples resolve and execute Microsoft BizTalk maps using the BRE Resolver, which uses facts contained in the message context properties and the message body to determine the resolution result.

The result of the resolution process is that all the two-way examples submit their message to the ESB.CanadianServices Web service located at http://localhost/ESB.CanadianServices/SubmitPOService.asmx. In addition, depending on the resolution result, the example executes either the submitOrder or the submitPurchase action. Additionally, the ESB Dispatcher Disassembler pipeline component dynamically executes a BizTalk map, depending on the specified or the resolved action.

Figure 1 shows the configured pipelines for the DynamicResolutionReqResp_SOAP receive location.

Dynamic Resolution Pipelines

Figure 1

The configured pipelines of the DynamicResolutionReqResp_SOAP receive location of the Dynamic Resolution sample application

Figure 2 shows the per-instance properties of the ESBReceiveXML component that uses the ESB Dispatcher Disassembler.

Dynamic Resolution Receive XML

Figure 2

The per-instance properties for the components in the ESBReceiveXML pipeline of the Dynamic Resolution sample application

The following properties are shown in Figure 2:

  • Enabled. This property determines whether the pipeline is active. If this is set to False, messages pass through without processing.

  • Endpoint. This property is the connection string used to determine which resolver to load, and it specifies the endpoint configuration.

  • MapName. This property is the connection string used to determine which resolver to load and which BizTalk map to execute. It can be the fully qualified name of a map instead of a resolver connection string.

  • Validate. When set to True (the default setting), the ESB Dispatcher Disassembler component instructs the ESB Transformation service to validate the source message against the source schema defined in the map that is will resolve and execute.

Figure 3 shows the per-instance properties of the ESBSendPassthrough component that uses the ESB Dispatcher.

Dynamic Resolution Send Passthrough

Figure 3

The per-instance properties for the components in the ESBSendPassthrough pipeline of the Dynamic Resolution sample application

The following properties are shown in Figure 3:

  • Enabled. This property determines whether the pipeline is active. If this is set to False, messages pass through without processing.

  • Endpoint. This property is the connection string used to determine which resolver to load and the end-point configuration.

  • MapName. This property is the connection string used to determine which resolver to load and which BizTalk map to execute. A fully qualified name of a map can be used in place of a resolver's connection string.

  • Validate. When set to True (the default setting), the ESB Dispatcher Disassembler component instructs the ESB Transformation service to validate the source message against the source schema defined in the map that is will resolve and execute.


Installing and Running the BizTalk Operations Sample

The Microsoft BizTalk Operations sample shows how you can query for operational data on BizTalk applications using the ESB BizTalk Operations Service. The ESB Management Portal uses this service to return or update information in the BizTalk management and tracking databases. The available information includes the following:

  • The status of deployed BizTalk applications and hosts

  • Active or suspended service instances

  • Messages and their properties

  • Deployed BizTalk applications

  • Receive port properties and receive locations

  • Send port properties

This section contains the following topics:

  • Installing the BizTalk Operations Sample

  • Running the BizTalk Operations Sample


Installing the BizTalk Operations Sample

The Microsoft BizTalk Operations sample requires the ESB BizTalk Operations service installed and configured. ESB BizTalk Operations service is one of the core Web services that can be installed and configured using the ESB Configuration Tool. For more information about using the ESB Configuration Tool, see http://msdn.microsoft.com/library/jj684558(v=bts.80).aspx. The default location of the BizTalk Operations Web service is http://localhost/ESB.BizTalkOperationsService/Operations.asmx; however, you can change this in the application configuration file if you deploy the service in a different location or a remote server.

You must install BizTalk Operations sample from the solution project.

To install the BizTalk Operations sample

  1. Open the solution named ESB.BizTalkOperations.Test.Client.csproj from the \Source\Samples\BizTalkOperations folder where you installed the ​Microsoft BizTalk ESB Toolkit samples into Visual Studio 2013.

  2. Use the commands on the Build menu to compile the solution.


Running the BizTalk Operations Sample

The Microsoft BizTalk Operations sample uses a Windows Forms test client application to execute methods of the BizTalk Operations Web service and display the results. You can open the test client project to run it and to examine the code to see how you can use the BizTalk Operations Web service in your own service-oriented architecture (SOA) and ESB applications.

In Windows Explorer, open the folder named \Samples\BizTalkOperations\bin\Debug, and then execute the application Microsoft.Practices.ESB.BizTalkOperations.Test.Client.exe.

Figure 1 shows the test client application for the BizTalk Operations Web service. You can execute all the functions of the BizTalk Operations Web service using this application. The application displays the results in a tree-view format and shows the message returned by the service.

Web Service Test

Figure 1

The BizTalk Operations Web Service Test Client

To execute a method of the BizTalk Operations Web service that does not require any parameters, simply click the appropriate button in the left side of the application window. For methods that do require input parameters, select the method in the drop-down list at the top of the window, enter the parameter values you require, and then click the Invoke Service button.

How the Sample Works

The sample application instantiates the ESB BizTalk Operations Web service and calls the appropriate method depending on the settings you select in the application. It passes the value(s) you enter in the application controls as parameters to the selected service method, and it collects the output from the service method to display in the application window.


Installing and Running the Resolver Service Sample

The Resolver Service sample uses a command-line application to execute the methods of the Resolver Web service and save the results to a disk file. You can open the test client project to run it and to examine the code to see how you can use the Resolver Web service in your own service-oriented architecture (SOA) and ESB applications.

This section contains the following topics:

  • Installing the Resolver Service Sample

  • Running the Resolver Service Sample

  • How the Resolver Service Sample Works


Installing the Resolver Service Sample

This section describes the process for installing the Resolver Service sample. The Resolver Service depends on the ​Microsoft BizTalk ESB Toolkit core solution. Installing the ​Microsoft BizTalk ESB Toolkit core automatically copies and installs the core assemblies required by this sample to the correct locations.

To install the Resolver Service sample from the solution project

  1. In Windows Explorer, open the \Source\Samples\ResolverService\Install\Scripts folder.

  2. Double-click the Setup_bin.cmd file.

  3. To confirm successful installation of the sample, or if you are encountering issues when you run applications, you can use the list provided in the following table to check for the presence of the required assemblies and other artifacts.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | (none)
BizTalk application GlobalBank.ESB | Send Ports | (none)
BizTalk application GlobalBank.ESB | Receive Ports | (none)
BizTalk application GlobalBank.ESB | Receive Locations | (none)
BizTalk application GlobalBank.ESB | Schemas | (none)
BizTalk application GlobalBank.ESB | Pipelines | (none)
BizTalk application GlobalBank.ESB | Resources | (none)
BizTalk application GlobalBank.ESB | Policies | ResolveEndpoint
 |  | ResolveMap
BizTalk application GlobalBank.ESB | Maps | (none)
Global assembly cache | Assemblies | (none)
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components | (none)


Running the Resolver Service Sample

The Resolver Service sample demonstrates the following scenarios:

  • Resolve a service endpoint URI from UDDI3 using a binding key

  • Resolve a service endpoint URI from UDDI3 using a categorization search

  • Resolve a transformation (BizTalk Map type) using a STATIC resolver

  • Resolve a service endpoint URI using a STATIC resolver

  • Resolve a service endpoint URI using an XPath expression

  • Resolve an itinerary using a static ITINERARY resolver

  • Resolve an itinerary using an ITINERARY-STATIC (Unity) resolver

  • Resolve an itinerary using BRE (BRI Resolver)

  • Resolve an Itinerary using BRE (BRI Resolver) with the Message

  • Resolve a service endpoint URI using BRE

  • Resolve a transformation using BRE

To run all the resolution scenarios using the ASMX implementation of the Resolver service

  1. If the GlobalBank.ESB application is not already running, use the Microsoft BizTalk Administration Console to start it.

  2. In Windows Explorer, open the \Source\Samples\ResolverService folder, and then double-click the file RunTestClient_ASMX.cmd.

  3. Open the \Source\Samples\ResolverService\Output folder, and then open the result files, which correspond to the resolution requests listed earlier.

To run all the resolution scenarios using the WCF implementation of the Resolver service

  1. If the GlobalBank.ESB application is not already running, use the BizTalk Administration Console to start it.

  2. In Windows Explorer, open the \Source\Samples\ResolverService folder, and then double-click the file RunTestClient_WCF.cmd.

  3. Open the \Source\Samples\ResolverService\Output folder, and then open the result files, which correspond to the resolution requests listed earlier.


How the Resolver Service Sample Works

The Resolver Service sample instantiates the Resolver service and passes the message you specify to it for processing. The Resolver Service sample client application uses the first parameter as the path to the ResolverList.xml file, which contains multiple resolver requests, and sends these requests to the Resolver service. For example, the following is the XPATH request used in the sample.

Copy Code
//XPATH
<Resolver>
  <name>XPATHWithFILE</name>
  <Content>![CDATA[XPATH:\\TransportLocation=/*[local-name()='OrderDoc'
    and namespace-uri()='http://globalbank.esb.dynamicresolution.com/
    northamericanservices/']/*[local-name()='ID' and namespace-
    uri()='http://globalbank.esb.dynamicresolution.com/
    northamericanservices/'];TargetNamespace=;
    MessageExchangePattern=;EndpointConfig=;JaxRpcResponse=;TransportType=;
    Action=;TransformType=]]
  </Content>
  <body>
    ![CDATA[
    <ns0:OrderDoc xmlns:ns0="http://globalbank.esb.dynamicresolution.com/northamericanservices/">
      <ns0:customerName>Microsoft</ns0:customerName>

<ns0:ID>FILE://C:\Projects\Microsoft.Practices.ESB\Source\Samples
    \DynamicResolution\Test\Filedrop\OUt\%MessageID%.xml</ns0:ID>
      <ns0:requestType>10</ns0:requestType>
    </ns0:OrderDoc>
    ]]
  </body>
</Resolver>
Note
The actual content of the <Content> element does not contain the white space characters used to wrap the lines in the preceding listing.

The preceding listing shows that the request contains the resolver configuration connection string within a <Content> element. The <body> element contains the message body.

The Resolver service uses the ResolverMgr class to instantiate a concrete instance of the appropriate resolver, defined by the resolver type in the connection string. In the case of the XPATH request, this is the XPATH resolver.

Next, the framework creates an instance of the ResolveProvider class named ESB.Resolver.XPath to process the request. The client application writes the response message from the Resolver service into the folder named \Source\Samples\ResolverService\Output. The following listing shows the contents of the response.

Copy Code
//XPATH
Resolver.Action =
Resolver.ActionField =
Resolver.DocumentSpecName =
Resolver.DocumentSpecStrongName =
Resolver.EndpointConfig =
Resolver.EpmRRCorrelationToken =
Resolver.FixJaxRpc = False
Resolver.InboundTransportLocation =
Resolver.InboundTransportType =
Resolver.InterchangeId =
Resolver.IsRequestResponse =
Resolver.MessageExchangePattern =
Resolver.MessageType =
Resolver.MethodName =
Resolver.OutboundTransportCLSID =
Resolver.ReceiveLocationName =
Resolver.ReceivePortName =
Resolver.Success = False
Resolver.TargetNamespace =
Resolver.TransformType =
Resolver.TransportLocation = FILE://C:\Projects\Microsoft.
    Practices.ESB\Source\Samples
\DynamicResolution\Test\Filedrop\OUt\%MessageID%.xml
Resolver.TransportNamespace =
Resolver.TransportType = FILE
Resolver.WindowUserField =


Installing and Running the Scatter-Gather Sample

The Scatter-Gather sample shows how you can develop an orchestration as a custom itinerary step to apply the Scatter-Gather design pattern by resolving and sending asynchronous requests to multiple services and aggregating their asynchronous responses into a single response message to forward to another endpoint location. The sample uses the test client application provided with the Itinerary On-Ramp sample and artifacts provided with the Dynamic Resolution sample.

This section contains the following topics:

  • Installing the Scatter-Gather Sample

  • Assemblies and Artifacts Installed by the Scatter-Gather Sample

  • Running the Scatter-Gather Sample

  • How the Scatter-Gather Sample Works


Installing the Scatter-Gather Sample

This section describes the process for installing the Scatter-Gather sample. You must install the samples in Installing and Running the Itinerary On-Ramp Sample and Installing and Running the Dynamic Resolution Sample before you install and use this sample.

To install the Scatter-Gather sample

  1. In Windows Explorer, open the \Source\Samples\ScatterGather\Install\Scripts folder.

  2. Double-click the script file named Setup_bin.cmd.


Assemblies and Artifacts Installed by the Scatter-Gather Sample

The following table lists the assemblies and other artifacts installed for the ESB Scatter-Gather sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | GlobalBank.ESB.ScatterGather.Processes.Broker
 |  | GlobalBank.ESB.ScatterGather.Processes.ServiceDispatcher
BizTalk application GlobalBank.ESB | Send Ports | GlobalBank.ESB.ScatterGather.Processes_2.0.0.0_ GlobalBank.ESB.ScatterGather.Processes.ServiceDispatcher_ServiceRequestPort_d98186f1038d4721
BizTalk application GlobalBank.ESB | Receive Ports |
BizTalk application GlobalBank.ESB | Receive Locations |
BizTalk application GlobalBank.ESB | Schemas | GlobalBank.ESB.ScatterGather.Schemas.RequestMetaData Version 2.0.0.0
 |  | GlobalBank.ESB.ScatterGather.Schemas.AggregatedResponse Version 2.0.0.0
 |  | GlobalBank.ESB.ScatterGather.Schemas.ServiceResponse Version 2.0.0.0
 |  | GlobalBank.ESB.ScatterGather.Schemas.ServicePayload Version 2.0.0.0
BizTalk application GlobalBank.ESB | Pipelines | GlobalBank.ESB.ScatterGather.Processes.AggregatingPipeline Version 2.0.0.0
BizTalk application GlobalBank.ESB | Resources | GlobalBank.ESB.ScatterGather.Processes Version 2.0.0.0
 |  | GlobalBank.ESB.ScatterGather.Schemas Version 2.0.0.0
BizTalk application GlobalBank.ESB | Policies | ResolveEndPointScatterGather ResolveMapScatterGather
BizTalk application GlobalBank.ESB | Maps |
Global assembly cache | Assemblies | GlobalBank.ESB.ScatterGather.Processes Version 2.0.0.0
 |  | GlobalBank.ESB.ScatterGather.Schemas Version 2.0.0.0
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components |


Running the Scatter-Gather Sample

The Scatter-Gather sample uses a the Windows Forms test client application provided with the Itinerary On-Ramp sample to demonstrate how this pattern applies the features of the Itinerary service.

To run the Scatter-Gather sample

  1. If the GlobalBank.ESB application is not already running, use the Microsoft BizTalk Administration Console to start it.

  2. In Windows Explorer, open the folder \Source\Samples\Itinerary\Source\ESB.Itinerary.Test where you installed the ​Microsoft BizTalk ESB Toolkit samples, and then start the application named Esb.Itinerary.Test.exe.

  3. Click the LoadItinerary button, and then select the sample itinerary named ScatterGatherItinerary.xml from the \Source\Samples\ScatterGather\Itineraries folder.

  4. Clear the Is Request Response check box so the application will perform a one-way itinerary services operation.

  5. (Optional) Set the Use WCF Service check box if you want the application to use the OnRamp.Itinerary.Response.WCF receive location instead of the default OnRamp.Itinerary.Response.SOAP receive location.

  6. Click the LoadMessage button, and then select the NAOrderDoc.xml sample message from the \Source\Samples\Itinerary\Test\Data folder.

  7. Click the SubmitRequest button to send the request to the Itinerary On-Ramp service. Open the folder \Source\Samples\DynamicResolution\Test\FileDrop\Out to see the response message.

For information about how the Scatter Gather sample uses the ESB Itinerary service, see How the Scatter-Gather Sample Works.


How the Scatter-Gather Sample Works

The sample application builds a set of SOAP headers containing the itinerary loaded from the Scatter-Gather itinerary file, loads the specified message file from disk, appends the itinerary headers to the message, and submits it to the ESB through an on-ramp for processing. If the itinerary generates a response, the application collects this and displays it in the application window.

To help you understand how the Itinerary service uses the itinerary information in a message, the following listing shows the sample itinerary configuration file named ScatterGatherItinerary.xml. The first section of this itinerary specifies two service invocation steps.

Xml Copy Code
<Itinerary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" uuid="" beginTime=""
    completeTime="" state="Pending" isRequestResponse="false"
    xmlns="http://schemas.microsoft.biztalk.practices.esb.com/itinerary">
  <ServiceInstance uuid="" name="ScatterGather" type="Orchestration"
                   state="Pending" position="0"
                   isRequestResponse="false" xmlns="" />
  <Services xmlns="">
    <Service uuid="" beginTime="" completeTime="" name="ScatterGather"
             type="Orchestration" state="Pending" isRequestResponse="false"
             position="0" serviceInstanceId="" />
  </Services>
  <Services xmlns="">
    <Service uuid="" beginTime="" completeTime="" name="DynamicTest"
             type="Messaging" state="Pending" isRequestResponse="false"
             position="1" serviceInstanceId="" />
  </Services>
</Itinerary>
...

Following the list of service invocation steps in the itinerary is the section containing details of the resolvers and connection strings that allow the Itinerary service to locate each service defined in the itinerary, as shown in the following XML.

Xml Copy Code
<ResolverGroups xmlns="">
 <Resolvers serviceId="ScatterGather0">&lt;![CDATA[BRE:\\policy=ResolveEndPointScatterGather;version=;useMsg=;]]&gt;&lt;![CDATA[UDDI3:\\serverUrl=http://localhost/uddi;bindingKey=uddi:esb:purchaseordersubmitorderservicebinding;credentialType=Ntlm]]&gt;</Resolvers>
<Resolvers serviceId="DynamicTest1">&lt;![CDATA[UDDI3:\\serverUrl=http://localhost/uddi;bindingKey=uddi:esb:orderfileservicebinding;credentialType=Ntlm]]&gt;
</Resolvers>
  </ResolverGroups>

In this example, the application executes the SubmitPOService Web service twice because both resolver connection strings resolve to the location of this service (http://localhost/ESB.CanadianServices/SubmitPOService.asmx). The message context specifies the Broker orchestration as the first itinerary service to activate, defined in the sample as the following.

C# Copy Code
(Microsoft.Practices.ESB.Itinerary.Schemas.ServiceName == "ScatterGather")
     && (Microsoft.Practices.ESB.Itinerary.Schemas.ServiceState ==
    "Pending") && (Microsoft.Practices.ESB.Itinerary.Schemas.ServiceType
    == "Orchestration")

The Broker orchestration analyzes the settings for its itinerary step and retrieves a collection of resolvers associated with the itinerary step. For each of these resolvers, the orchestration uses the ​Microsoft BizTalk ESB Toolkit Resolver and Adapter Framework to resolve the service endpoint. The Broker orchestration then activates n number of ServiceDispatcher orchestrations asynchronously (where n is the number of resolvers associated with the ScatterGather service in the itinerary) to dispatch the request message with following parameters:

  • TransportLocation. The resolver populates this parameter.

  • TransportType. The resolver populates this parameter.

  • ResolverDictionary. This parameter contains a collection of resolver facts populated by the concrete resolver instance.

  • InboundMessage. This parameter contains the original message that contains the itinerary.

  • ServiceResponsePort. This parameter is the name of the self-correlating response port that will receive responses from the instances of the ServiceDispatcher orchestration.

Each instance of the ServiceDispatcher orchestration uses the ResolveMapScatterGather policy to resolve the Microsoft BizTalk map types for the request and response message, based on TransportType and TransportLocation properties. The orchestration instances use the resolved maps to transform the inbound message into the request message for the Web service call.

The ESB Adapter Manager sets the outbound transport context properties on the request message, which BizTalk then forwards to the solicit-response port named ServiceRequestPort.

When it receives a response message from a service, the ServiceDispatcher orchestration uses the resolved map information to transform the inbound response message to a canonical format. It then wraps the modified response within the ServiceResponse envelope and forwards it to the Broker orchestration through the self-correlating port. The Broker orchestration aggregates all incoming responses and prepares the final response message using GlobalBank.ESB.ScatterGather.Processes.AggregatingPipeline, as shown in the following code.

C# Copy Code
AggregatedResponse.Body = null;
AggregatedResponse(*) = InboundMessage(*);
Microsoft.XLANGs.Pipeline.XLANGPipelineManager.ExecuteSendPipeline(
    typeof(GlobalBank.ESB.ScatterGather.Processes.AggregatingPipeline),
    messageAggregator,AggregatedResponse);

This code wraps the entire batch of responses within a predefined envelope. The Broker orchestration then advances the itinerary to the DynamicTest itinerary step, as shown in the following code.

C# Copy Code
// Copy the context and advance the itinerary.
OutboundMessage = AggregatedResponse.Body;
OutboundMessage(*) = AggregatedResponse(*);
// Advance the Itinerary to the next step.
itinerary.Itinerary.Advance(OutboundMessage, itineraryStep);

Because the service type attribute named DynamicTest is set to Messaging, the ItineraryHelper class promotes the resolver properties into the context of the message named OutboundMessage. The Broker orchestration sends this message to a BizTalk direct-bound port. BizTalk then forwards the message to the dynamic send port represented by the ServiceName subscription, which is DynamicTest. This send port serializes the final aggregated response to the \Source\Samples\DynamicResolution\Test\Filedrop\Out folder.


Installing and Running the SQL Adapter Sample

The SQL Adapter sample shows how you can use the dynamic resolution framework to execute a SQL stored procedure through the use of a WCF-Custom adapter provider. The sample uses the test client application provided with the Itinerary On-Ramp sample.

This section contains the following topics:

  • Installing the SQL Adapter Sample

  • Assemblies and Artifacts Installed by the SQL Adapter Sample

  • Running the SQL Adapter Sample

  • How the SQL Adapter Sample Works


Installing the SQL Adapter Sample

This section describes the process for installing the SQL Adapter sample. You must install the samples in Installing and Running the Itinerary On-Ramp Sample and Installing and Running the Dynamic Resolution Sample before you install and use this sample.

To install the SQL Adapter sample

  1. In Windows Explorer, open the folder \Source\Samples\SqlAdapter\Install\Scripts.

  2. Double-click the script file named Setup_bin.cmd.


Assemblies and Artifacts Installed by the SQL Adapter Sample

The following table lists the assemblies and other artifacts installed for the SQL Adapter sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations |
BizTalk application GlobalBank.ESB | Send ports |
BizTalk application GlobalBank.ESB | Receive ports |
BizTalk application GlobalBank.ESB | Receive locations |
BizTalk application GlobalBank.ESB | Schemas | ESB.SqlAdapter.BTSArtifacts.Product Version 1.0.0.0
 |  | ESB.SqlAdapter.BTSArtifacts.DataSetSchema Version 1.0.0.0
 |  | ESB.SqlAdapter.BTSArtifacts.Procedure_dbo Version 1.0.0.0
BizTalk application GlobalBank.ESB | Pipelines |
BizTalk application GlobalBank.ESB | Resources | ESB.SqlAdapter.BTSArtifacts Version 1.0.0.0
BizTalk application GlobalBank.ESB | Policies |
BizTalk application GlobalBank.ESB | Maps | ESB.SqlAdapter.BTSArtifacts.ProductToInsertProductMap 1.0.0.0
Global assembly cache | Assemblies | ESB.SqlAdapter.BTSArtifacts Version 1.0.0.0
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components |


Running the SQL Adapter Sample

The SQL Adapter sample uses a Windows Forms test client application provided with the Itinerary On-Ramp sample.

To run the SQL Adapter sample

  1. If the GlobalBank.ESB application is not already running, use the Microsoft BizTalk Administration Console to start it.

  2. In Windows Explorer, open the folder \Source\Samples\Itinerary\Source\ESB.Itinerary.Test where you installed the ​Microsoft BizTalk ESB Toolkit samples, and then start the application named Esb.Itinerary.Test.exe.

  3. Clear the Use WCF Service check box so that a client-side itinerary can be used.

  4. Select the Two Way Service option

  5. Click the Load Itinerary button, and then select one of the sample itineraries located in the folder \Source\Samples\SqlAdapter \Itineraries.

  6. Click the LoadMessage button, and then select the OrderDoc.xml sample message in the folder \Source\Samples\SqlAdapter \Test.

  7. Click the SubmitRequest button to send the request to the Itinerary On-Ramp service.

  8. Make sure one row is inserted in the Product table of the GlobalBankESB database.

For information about how the SQL Adapter sample works, see How the SQL Adapter Sample Works.


How the SQL Adapter Sample Works

The SQL Adapter sample provides a sample two-way itinerary configured with the routing service and a transform messaging service.

The routing service is configured with a STATIC resolver, which specifies that the message should be routed to execute a SQL stored procedure within the GlobalBankESB database named InsertProduct using the WCF-Custom adapter provider.

The transform service specifies a map that converts the incoming message to the format accepted by the InsertProduct stored procedure.


Installing and Running the Message Enrichment Sample

The Message Enrichment sample shows how you can develop an orchestration as a custom itinerary service to apply the Message Enrichment design pattern by querying a database and incorporating the response into your message. The sample uses the test client application provided with the Itinerary On-Ramp sample.

This section contains the following topics:

  • Installing the Message Enrichment Sample

  • Assemblies and Artifacts Installed by the Message Enrichment Sample

  • Running the Message Enrichment Sample

  • How the Message Enrichment Sample Works


Installing the Message Enrichment Sample

This section describes the process for installing the Message Enrichment sample. You must install the samples in Installing and Running the Itinerary On-Ramp Sample and Installing and Running the Dynamic Resolution Sample before you install and use this sample.

To install the Message Enrichment sample

  1. In Windows Explorer, open the \Source\Samples\MessageEnrichment\Install\Scripts folder.

  2. Double-click the script file named Setup_bin.cmd.


Assemblies and Artifacts Installed by the Message Enrichment Sample

The following table lists the assemblies and other artifacts installed for the Message Enrichment sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | MessageEnrichment.Orchestrations.MessageEnricher
BizTalk application GlobalBank.ESB | Send Ports | MessageEnrichment.Orchestrations_1.0.0.0_ MessageEnrichment.Orchestrations.MessageEnricher_RoutingPort_d98186f1038d4721
BizTalk application GlobalBank.ESB | Receive Ports |
BizTalk application GlobalBank.ESB | Receive Locations |
BizTalk application GlobalBank.ESB | Schemas | MessageEnrichment.Schema.ProcedureResultSet_dbo_GetOrderDetails Version 1.0.0.0
 |  | MessageEnrichment.Schema.OrderDoc Version 1.0.0.0
 |  | MessageEnrichment.Schema.InventoryOrder Version 1.0.0.0
 |  | MessageEnrichment.Schema.TypedProcedure_dbo Version 1.0.0.0
BizTalk application GlobalBank.ESB | Pipelines |
BizTalk application GlobalBank.ESB | Resources | MessageEnrichment.Transforms Version 1.0.0.0
 |  | MessageEnrichment.Orchestrations Version 1.0.0.0
 |  | MessageEnrichment.Schema Version 1.0.0.0
BizTalk application GlobalBank.ESB | Policies |
BizTalk application GlobalBank.ESB | Maps | MessageEnrichment.Transforms.NAOrderDocToGetOrderDetailsRequestMap Version 1.0.0.0
Global assembly cache | Assemblies | MessageEnrichment.Transforms Version 1.0.0.0
 |  | MessageEnrichment.Orchestrations Version 1.0.0.0
 |  | MessageEnrichment.Schema Version 1.0.0.0
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components |


Running the Message Enrichment Sample

The Message Enrichment sample uses a Windows Forms test client application provided with the Itinerary On-Ramp sample.

To run Message Enrichment sample

  1. If the GlobalBank.ESB application is not already running, use the Microsoft BizTalk Administration Console to start it.

  2. In Windows Explorer, open the folder \Source\Samples\Itinerary\Source\ESB.Itinerary.Test where you installed the ​Microsoft BizTalk ESB Toolkit samples, and then start the application named Esb.Itinerary.Test.exe.

  3. Clear the Use WCF Service check box so that a client-side itinerary can be utilized.

  4. Click the Load Itinerary button, and then select one of the sample itineraries located in the \Source\Samples\MessageEnrichment\Itineraries folder.

  5. Click the LoadMessage button, and then select the OrderDoc.xml sample message from the \Source\Samples\MessageEnrichment\Test\ folder.

  6. Click the SubmitRequest button to send the request to the Itinerary On-Ramp service.

  7. Browse to C:\Projects\Microsoft.Practices.ESB\Source\Samples\DynamicResolution\Test\Filedrop\Out\%MessageID%.xml to see the output message.

For information about how the Message Enrichment sample works, see How the Message Enrichment Sample Works.


How the Message Enrichment Sample Works

The Message Enrichment sample provides an orchestration-based itinerary service that can use up to two resolvers to configure enrichment of a message using information from an external source.

The first resolver must return routing information; it can also return transform information alongside it. If specified, the transform is applied to the incoming message before being routed to the location specified by the resolver. In the provided sample itinerary, the WCF-Custom adapter provider is used to execute a SQL stored procedure within the GlobalBankESB database named GetOrderDetails and return the result.

Optionally, a second resolver can be included. If provided, the second resolver must include transformation information. This transform will be given the original message and the result, returned by whichever data source was contacted, as input. In the sample itinerary, a map is referenced that uses a table looping functoid to pull information out of the original message and the result of the stored procedure and include it inside the resulting InventoryOrder message.


Installing and Running the Multiple Web Services Sample

The Multiple Web Services sample shows how you can develop an itinerary that can submit a message to multiple Web services, one after another, by using the Forwarder pipeline component. This sample requires that you have already installed the Itinerary On-Ramp sample.

This section contains the following topics:

  • Installing the Multiple Web Services Sample

  • Assemblies and Artifacts Installed by the Multiple Web Services Sample

  • Running the Multiple Web Services Sample

  • How the Multiple Web Services Sample Works

  • The Sample Multiple Web Services Itineraries


Installing the Multiple Web Services Sample

This section describes the process for installing the Multiple Web Services sample. You must install the samples in Installing and Running the Itinerary On-Ramp Sample and Installing and Running the Dynamic Resolution Sample before you install and use this sample.

To install the Multiple Web Services sample

  1. In Windows Explorer, open the \Source\Samples\MultipleWebServices\Install\Scripts folder.

  2. Double-click the script file named Setup_bin.cmd.


Assemblies and Artifacts Installed by the Multiple Web Services Sample

The following table lists the assemblies and other artifacts installed for the Multiple Web Services sample.

Location | Category | Name and version of the component
BizTalk application GlobalBank.ESB | Orchestrations | ESB.MultipleWebServices.Orchestrations.TwoWayRouting
BizTalk application GlobalBank.ESB | Send Ports | ESB.MultipleWebServices.Orchestrations_2.0.0.0_ ESB.MultipleWebServices.Orchestrations.TwoWayRouting_RoutingPort_d98186f1038d4721
BizTalk application GlobalBank.ESB | Receive Ports |
BizTalk application GlobalBank.ESB | Receive Locations |
BizTalk application GlobalBank.ESB | Schemas |
BizTalk application GlobalBank.ESB | Pipelines |
BizTalk application GlobalBank.ESB | Resources | ESB.MultipleWebServices.Maps Version 2.0.0.0
 |  | ESB.MultipleWebServices.Orchestrations Version 2.0.0.0
BizTalk application GlobalBank.ESB | Policies |
BizTalk application GlobalBank.ESB | Maps | ESB.MultipleWebServices.Maps.SubmitOrderResponseCN_To_SubmitOrderRequestCN Version 2.0.0.0
 |  | MessageEnrichment.Transforms.OrderDocAndGetOrderDetailsToInventoryOrder Version 1.0.0.0
Global assembly cache | Assemblies | ESB.MultipleWebServices.Maps Version 2.0.0.0
 |  | ESB.MultipleWebServices.Orchestrations Version 2.0.0.0
%Program Files%\BizTalk Server 2013 R2\Pipeline Components | Pipeline components |


Running the Multiple Web Services Sample

The Multiple Web Services sample uses the Windows Forms test client application provided with the Itinerary On-Ramp sample.

To run the Multiple Web Services sample

  1. If the GlobalBank.ESB application is not already running, use the Microsoft BizTalk Administration Console to start it.

  2. In Windows Explorer, open the folder \Source\Samples\Itinerary\Source\ESB.Itinerary.Test where you installed the ​Microsoft BizTalk ESB Toolkit samples, and then start the application named Esb.Itinerary.Test.exe.

  3. Clear the Use WCF Service check box, so that a client-side itinerary can be utilized.

  4. Click the Load Itinerary button, and then select one of the sample itineraries located in the \Source\Samples\MultipleWebServices\Itineraries folder.

  5. Select the Two Way Service check box so the application will perform a two-way itinerary services operation.

  6. Click the LoadMessage button, and then select the NAOrderDoc.xml sample message from the \Source\Samples\Itinerary\Test\Data folder.

  7. Click the SubmitRequest button to send the request to the Itinerary On-Ramp service. Wait for a response message to appear in the Result box.

For information about how the Multiple Web Services sample uses the ESB Itinerary service, see How the Multiple Web Services Sample Works.


How the Multiple Web Services Sample Works

The Multiple Web Services sample uses two separate techniques to call multiple Web services in serial while still being able to return a proper result to the original caller. One method uses a custom pipeline component in the response pipeline, and the other method uses a custom two-way routing orchestration-based itinerary service that bypasses the requirement of an off-ramp invocation to complete a request/response call to a Web service.

The custom pipeline component method uses the Forwarder Pipeline component. This component conditionally promotes properties to keep Microsoft BizTalk from routing the message back to the send pipeline of the on-ramp until all the itinerary services are processed.

The custom orchestration-based service method uses the TwoWayRouting orchestration contained in the ESB.MultipleWebServices.Orchestrations project in the \Source\Samples\MultipleWebSerivces\Source\ESB.MultipleWebServices.Orchestrations folder. This service processes an associated resolver to determine the endpoint address of a two-way Web service. It then configures a Dynamic Solict-Response Send Port named RoutingPort to send the message to the Web service and return the result to the orchestration. The orchestration then advances the itinerary and returns the resulting message to the MessageBox.

The itineraries included with the sample use one or both of these methods to ensure message flow following the itinerary is maintained. For more information, see The Sample Multiple Web Services Itineraries.


The Sample Multiple Web Services Itineraries

The following table lists all the predefined itinerary files included with the Multiple Web Services sample. These are located in the \Source\Samples\MultipleWebServices\Itineraries folder.

File name | Description
OneWayMessagingMultipleServices.xml | This one-way itinerary transforms an NAOrderDoc message to a CNOrderDoc message and then routes it to the Candian Order Service using the off-ramp DynamicResolutionSolicitResp. The response is then transformed to the CNOrderDoc message using the messaging-based transform service and then it is routed again to the Canadian Order Service using the off-ramp DynamicResolutionSolicitResp. The response returned is routed to the Source\Samples\DynamicResolution\Test\Filedrop\Out folder using the routing service.
TwoWayMessagingMultipleServices.xml | This two-way itinerary transforms an NAOrderDoc message to a CNOrderDoc message and then routes it to the Canadian Order Service. It then takes the response from the Canadian Order Service, transforms it to a CNOrderDoc message, and then routes it again to the Canadian Order Service. The result is then returned to the caller. All transformation and routing takes place through messaging services. Both off-ramps use the DynamicResolutionSolicitRespForwarder send port.
TwoWayMessagingOrchestrationMultipleServices.xml | This two-way itinerary uses messaging services to transform an NAOrderDoc message to a CNOrderDoc message, and then it routes that message to the Canadian Order Service using the DynamicResolutionSolicitRespForwarder send port. The response is transformed using the orchestration-based implementation of the transform service, and then it is passed to the custom Microsoft.Practices.ESB.Routing.TwoWay orchestration-based itinerary service provided as part of the sample. This service sends a message to the Web service specified by the associated resolver (in this case, the Canadian Order Service), and then it receives and returns the response from the service. This response is then sent back to the caller.
TwoWayOrchestrationsMultipleServices.xml | This two-way itinerary uses a messaging service to transform an NAOrderDoc message to a CNOrderDoc message, and then it uses the Microsoft.Practices.ESB.Routing.TwoWay orchestration to route that message to the Canadian Order Service and return the result. The message is then transformed back to a CNOrderDoc message using the orchestration-based transform service; after that, it is sent back to the Canadian Order Service using the Microsoft.Practices.ESB.Routing.TwoWay orchestration-based itinerary service. The result is then returned to the caller.
TwoWay-Partial-Selector-Required.xml | This two way itinerary uses a messaging service to route an NAOrderDoc message to the Canadian Order Service through the DynamicResolutionSolicitResp off-ramp. The NAOrderDoc is transformed to CNOrderDoc using the messaging-based transform service and Canadian service called. The response is then returned back to caller.


Installing and Running the Designer Extensibility Sample

The Designer Extensibility sample shows how designer extensions can be developed to provide design-time support for configuration of custom resolvers and configuration of itinerary services.

This section contains the following topics:

  • Installing the Designer Extensibility Sample

  • Running the Designer Extensibility Sample

  • How the Designer Extensibility Sample Works


Installing the Designer Extensibility Sample

This section describes the process for installing the Designer Extensibility sample. You must install the samples in Installing and Running the Itinerary On-Ramp Sample and Installing and Running the Dynamic Resolution Sample before you install and use this sample.

To install the Designer Extensibility sample

  1. In Windows Explorer, open the folder \Source\Samples\Designer Extensibility Samples\Extenders.Itinerary.OrchestrationSample, where you installed the ​Microsoft BizTalk ESB Toolkit samples, and then open the Microsoft Visual Studio solution file named Extenders.Itinerary.OrchestrationSample.sln.

  2. In Visual Studio 2013, click Build Solution on the Build menu.

  3. Close Visual Studio.

  4. In Windows Explorer, open the folder \Source\Samples\Designer Extensibility Samples\Extenders.Resolvers.ResolverSample, where you installed the ​Microsoft BizTalk ESB Toolkit samples, and then open the Visual Studio solution file named Extenders.Resolvers.ResolverSample.sln.

  5. In Visual Studio 2013, click Build Solution on the Build menu.

  6. Close Visual Studio.

  7. In Windows Explorer, open the \Lib folder under the Itinerary Designer install path.

  8. From the \bin\Debug folders of the Visual Studio solutions built in the preceding steps, copy the files Extenders.Resolvers.ResolverSample.dll and Extenders.Itinerary.OrchestrationSample.dll to the \Lib directory.


Running the Designer Extensibility Sample

The Designer Extensibility sample uses two sample extenders to demonstrate how you can provide design-time configuration options for custom resolvers and for itinerary services.

To run the Designer Extensibility sample

  1. Start Visual Studio 2013.

  2. In Visual Studio, point to New on the File menu, and then click Project.

  3. Select the C# Class Library template, type ItineraryLibrary in the Name box, and then click OK.

  4. In Solution Explorer, right-click the ItineraryLibrary project, point to Add, and then click New Itinerary.

  5. In the Name box, type TestItinerary, and then press ENTER.

  6. In the Toolbox, click an On-Ramp model element, and then drag it to the design surface.

  7. In the Toolbox, click an Itinerary Service model element, and then drag it to the design surface.

  8. In the Toolbox, click another Itinerary Service model element, and then drag it to the design surface.

  9. In the Toolbox, click an Off-Ramp model element, and then drag it to the design surface.

  10. In the Toolbox, click the Connector tool, and then drag a connection between the OnRamp1 model element and the ItineraryService1 model element.

  11. In the Toolbox, click the Connector tool, and then drag a connection between the ItineraryService1 model element and the ItineraryService2 model element.

  12. In the Toolbox, click the Connector tool, and then drag a connection between the ItineraryService2 model element and the OffRamp1 model element.

  13. Click the OnRamp1 model element, and then in the Properties window, set the Extender property to On-Ramp ESB Service Extension.

  14. Set the BizTalk Application property to Microsoft.Practices.ESB.

  15. Set the Receive Port property to OnRamp.Itinerary.

  16. Click the ItinearyService1 model element, and then in the Properties window, set the Extender property to Sample Orchestration Itinerary Service Extension.

    Note
    This is the custom extension installed as part of the Designer Extensibility sample. It allows you to add properties to the property bag passed to an orchestration-based itinerary service.

  17. Set the OtherValue property to 1.

  18. Set the ServiceName property to Microsoft.Practices.ESB.Services.Routing.

  19. Set the SomeValue property to 2.

  20. Right-click the Resolver collection of ItineraryService1, and then click Add new Resolver.

  21. Click Resolver1, and then in the Properties window, set the Resolver Implementation property to Sample Resolver Extension.

  22. Set the SomeResolverValue property to test, and then set the version property to 1.0.

  23. Click the ItineraryService2 model element, and then in the Properties window, set the Itinerary Service Extender property to Off-Ramp Itinerary Service Extension.

  24. Set the Off-Ramp property to OffRamp1 > Send Handlers.

  25. Click the OffRamp1 model element, and then in the Properties window, set the Extender property to Off-Ramp ESB Service Extension.

  26. Set the BizTalk Application property to GlobalBank.ESB.

  27. Set the Send Port property to DynamicResolutionOneWay.

  28. Right-click the design surface, and then click Export Model.

  29. Examine the generated XML.

    Note
    Notice the PropertyBag element and the properties it contains. Also notice the Sample resolver connection string and how it was configured based on the properties entered.


How the Designer Extensibility Sample Works

Each project in the Designer Extensibility sample contains two classes: an Extender class and an Extension Provider class. These classes are designed to extend the capabilities and define the properties of the ItineraryDsl model elements.

The Extension Provider classes derive from the ExtensionProviderBase class and have the ExtensionProviderAttribute applied to them with properties that identify the extension and its purpose. These values will be displayed to the user in the designer when the user is setting the Extender property on a model element. When the Extension Provider classes initialize, they call to the constructor for the ExtensionProviderBase and pass to it the type of the extender class.

The Extender classes have an ObjectExtender attribute applied to them; to the ObjectExtender attribute, they pass the type of the object in the ItineraryDsl that they extend. The base class for these classes varies, depending on the type of extender. For Resolver extenders, the base class is ObjectExtender<Resolver>. For Itinerary Service extenders, the base class is ItineraryServiceExtenderBase. In the Extender classes, the following attributes are applied to the properties: attributes necessary for proper display in a property grid, attributes included in the Microsoft Enterprise Library for validation purposes, attributes necessary for proper serialization, and/or attributes that determine how properties are persisted.

When these assemblies are compiled and placed in the Lib folder, they are loaded and cached by the designer at run time. As extenders are needed, the ItineraryDsl uses reflection to load the applicable assemblies from the cache by examining the types exported and the attributes on those types.


Running the Exception Handling Service Sample

The Exception Handling Service sample demonstrates how to consume the Exception Handling Web Service in order to submit a fault into the ESB Exception Handling Framework from an external application. The following procedure for running this sample requires Installing the Exception Management Samples.

To run the Exception Handling Service sample

  1. In Windows Explorer, open the folder \Source\Samples\ExceptionHandlingService, where you installed the ​Microsoft BizTalk ESB Toolkit samples, and then open the Visual Studio solution file named ExceptionHandlingService.sln.

  2. In Visual Studio 2013, click Start Debugging on the Toolbar.

  3. On the form that loads, click the Generate Exception button.

  4. In Windows Explorer, open the folder \Samples\Exception Handling\Test\Filedrop\All_Exceptions, and then open the most recent Exceptions_{GUID}.xml file.

  5. Examine the contents of the generated exception.

For more information about how the Exception Handling Service sample uses the Exception Management service, see How the Exception Handling Service Sample Works.


How the Exception Handling Service Sample Works

The Exception Handling Service sample is a standard .NET Windows Forms application that contains a generated service proxy for the exception handling service. The application consists of a single form with a single button, Generate Exception. When you click this button, an instance of the FaultMessage class is generated. The FaultMessage class is a class that was generated by Microsoft Visual Studio based on the Web Services Description Language (WSDL) provided by the Exception Handling Web service. The properties of this instance are populated with default values that simulate a fault occurring in an external application before the properties are passed as parameters to the SubmitFault method of the Exception Handling Web service.

For more information about how the Exception Handling Web service works, see The Exception Handling Web Service.


Modifying and Extending the BizTalk ESB Toolkit

You can modify and/or extend ​Microsoft BizTalk ESB Toolkit services and components to suit your specific requirements. For example, you may want to change the behavior of an existing component, create a custom messaging service to use in a pipeline, add providers and adapters, or add other custom features to the ​Microsoft BizTalk ESB Toolkit.

This section includes the following topics:

  • Extending the Resolver and Adapter Provider Framework

  • Creating a Custom Itinerary Service

  • Extending the Itinerary Designer


Extending the Resolver and Adapter Provider Framework

The Resolver and Adapter Provider Framework provides support for endpoint and transformation resolution and routing, and it can also provide custom metadata for services. The framework can dynamically resolve endpoints and set outbound adapter properties. After a resolver component resolves an endpoint (for example, using Universal Description, Discovery, and Integration [UDDI] to look up an outbound URL), an adapter provider component sets specific properties of registered Microsoft BizTalk Server adapters.

There are three main areas where you can extend the Resolver and Adapter Provider Framework:

  • Creating a Custom Resolver

  • Creating a Custom Resolver with a Unity Container

  • Creating a Custom Adapter Provider


Creating a Custom Resolver

The Resolver and Adapter Provider Framework implementation in ​Microsoft BizTalk ESB Toolkit uses a pipeline component named Dispatcher and pipelines named ItineraryReceive and ItinerarySend.

The Dispatcher pipeline component has four properties: Validate, Enabled, EndPoint, and MapName. The EndPoint property can contain resolver connection strings with values such as the following, where UDDI:\\ represents the resolution type to use (the root moniker).

Copy Code
UDDI:\\serverUrl=http://localhost/uddi;serviceName=OrderPurchaseToOrderPost;serviceProvider=Microsoft.Practices.ESB

Other supported monikers include XPATH:\\, STATIC:\\, and BRE:\\. Each moniker type uses a specific class that implements the IResolveProvider interface. You can create your own custom resolvers for other moniker types and register them for use by the dynamic resolution system.

The moniker equates to a resolver connection string. Individual schemas define the parameters and their root moniker. A resolver takes the resolver connection string, validates it, and uses the result to query and populate a Dictionary object that can be used for routing, transformation, itinerary selection, or some other purpose specific to your service.

Resolver Configuration

You must register all resolvers in the Esb.config configuration file. The following XML shows an example of the configuration file content.

Xml Copy Code
<?xml version="1.0" encoding="utf-8"?>
<configuration>
     <configSections>
          <section name="esb" type="Microsoft.Practices.ESB.Configuration.ESBConfigurationSection, Microsoft.Practices.ESB.Configuration, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
          <!-- Other Section Definitions Here -->
     </configSections>

     <esb>
          <resolvers cacheManager= "Resolver Providers Cache Manager"  absoluteExpiration="3600">
               <resolver name="UDDI" type="Microsoft.Practices.ESB.Resolver.UDDI.ResolveProvider, Microsoft.Practices.ESB.Resolver.UDDI, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22">
                    <resolverConfig>
                         <add name="cacheTimeoutValue" value="120" />
                         <add name="cacheName" value="UDDI Cache Manager" />
                    </resolverConfig>
               </resolver>
               <resolver name="XPATH" type="Microsoft.Practices.ESB.Resolver.XPATH.ResolveProvider, Microsoft.Practices.ESB.Resolver.XPATH, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <!-- Other Resolver Definitions Here -->
          </resolvers>
          <!-- Other ESB Configuration Settings Here -->
     </esb>
     <!-- Other Configuration Sections Here -->
</configuration>

The resolverConfig section under each resolver node allows you to configure additional properties that your resolver may require to operate in a specific environment. To have access to the configuration, your resolver must expose a constructor that takes in a parameter of type Microsoft.Practices.ESB.Configuration.Resolver. In your resolver implementation, configuration properties can then be accessed using the ReadResolverConfigByKey method of the ResolverConfigHelper class; to do this, pass in the parameter originally passed to the constructor, and then pass in the name of the value in question. If no name-value pairs are specified in the resolverConfig node, the default parameterless constructor will be used to instantiate your resolver.

Two Universal Description, Discovery, and Integration (UDDI) 3 resolvers have been defined in the configuration: UDDI 3 and UDDI 3-SOASOFTWARE. Both of these resolvers use the same underlying assembly, but they provide different configurations for supporting different UDDI 3.0–compliant registries with different Uniform Resource Identifier (URI) formats and security requirements. If you need to configure an additional moniker for a UDDI 3.0–compliant registry besides those already supported, the following configuration properties can be used:

  • cacheTimeoutValue

  • cacheName

  • publisherKey

  • useUddiAuth

  • baseUri

  • inquireUriSuffix

  • securityUriSuffix

  • securityMode. For valid values, see the enumeration System.ServiceModel.BasicHttpSecurityMode (http://go.microsoft.com/fwlink/?LinkID=188284&clcid=0x409). The default value is TransportCredentialOnly.

  • credentialType. For valid values, see the enumeration System.ServiceModel.HttpClientCredentialType (http://go.microsoft.com/fwlink/?LinkId=188285). The default value is Windows.

  • username

  • password

If you want to create a resolver that relies on the dependency injection capabilities of the Unity Application Block, additional configuration is required. For more information, see Creating a Custom Resolver with a Unity Container.

The IResolveProvider Interface

All resolvers must implement the IResolveProvider interface. The IResolveProvider interface, located in the Microsoft.Practices.ESB.Resolver project, consists of three overloads of the Resolve method that return an instance of the Dictionary class, which contains resolution facts provided by the instance of concrete resolver class. The following code example shows the signature of these method overloads.

C# Copy Code
// <summary>
// This is the main interface that is called from the
// ResolverMgr class.
// This interface supports being called from a Microsoft BizTalk
// Server pipeline component.
// </summary>
// <param name="config">Configuration string entered into
// pipeline component as argument</param>
// <param name="resolver">Moniker representing the resolver
// to load</param>.
// <param name="message">IBaseMessage passed from pipeline</param>.
// <param name="pipelineContext">IPipelineContext passed from
// pipeline</param>.
// <returns>Dictionary object fully populated</returns>.
        Dictionary<string, string> Resolve(string config, string resolver,
              IBaseMessage message, IPipelineContext pipelineContext);

// <summary>
// This is the main interface that is called from the ResolverMgr
// class.
// This interface supports being called from a Web service interface.
// </summary>
// <param name="config">Configuration string entered into Web
// service as argument</param>.
// <param name="resolver">Moniker representing the resolver
// to load</param>.
// <param name="message">XML document passed from Web
// service</param>.
// <returns>Dictionary object fully populated</returns>.
        Dictionary<string,string> Resolve(string config, string resolver, System.Xml.XmlDocument message);

// <summary>
// This is the main interface that is called from the
// ResolverMgr class.
// This interface supports being called from an orchestration.
// </summary>
// <param name="resolverInfo">Configuration string containing
// configuration and resolver</param>.
// <param name="message">XLANGMessage passed from
// orchestration</param>.
// <returns>Dictionary object fully populated</returns>.
        Dictionary<string, string> Resolve(ResolverInfo resolverInfo, XLANGs.BaseTypes.XLANGMessage message);

The Resolution structure, located in Microsoft.Practices.ESB.Resolver project, also defines the name/value pairs stored in the Dictionary instance. The Resolution structure exposes several properties; the following table lists the most relevant of these. The CreateResolverDictionary method of the ResolutionHelper class can be used to generate a resolver dictionary that contains the most used keys, with empty string values. The Dictionary instance supports the addition of custom resolver name/value pairs through a concrete implementation of the Resolver class.

Property | Data type | Data type | Data type
TransformType | String | ActionField | String
Success | Boolean | EpmRRCorrelationTokenField | String
TransportNamespace | String | InboundTransportLocationField | String
TransportType | String | InterchangeIDField | String
TransportLocation | String | ReceiveLocationNameField | String
Action | String | ReceivePortNameField | String
MessageExchangePattern | String | InboundTransportTypeField | String
EndpointConfig | String | IsRequestResponseField | String
TargetNamespace | String | DocumentSpecStrongNameField | String
FixJaxRPC | Boolean | DocumentSpecNameField | String
WindowUserField | String | MessageType | String
CacheTimeout | String | OutboundTransportCLSID | String
MethodNameField | String |  |

Creating a Custom Resolver

At run time, a pipeline retrieves the resolver connection string and calls the resolver manager (an instance of the ResolverMgr class). The resolver manager parses, populates, and validates the resolver connection string. It does this by doing the following:

  • It parses the connection string to determine which Resolver type to load.

  • It matches this type to a moniker defined in the configuration file (the key is the root moniker, such as UDDI).

  • It reads the assembly name of the resolver for this moniker.

  • It loads the specified assembly.

The dynamic resolution mechanism caches all loaded implementations of the IResolveProvider interface to avoid repeated reading of configuration information and assembly loading when several incoming messages use the same resolver.

Finally, the resolver manager executes the Resolve method of the concrete IResolveProvider implementation and returns the populated Dictionary instance.

To create a custom resolver

  1. Create an assembly with a class that implements the IResolveProvider interface and contains a Resolve method that returns resolver facts as an instance of the Dictionary class.

  2. Register the resolver by adding it to the Esb.config configuration file using a <resolver> element that contains the root moniker as the name attribute and the fully qualified assembly name as the type attribute.

  3. (Optional) Create a schema that defines the root moniker and the query parameters, and then save it in the ESB.Schemas.Resolvers folder. The name should follow existing ESB naming conventions; this means it should use the name of the root moniker appended with "_Resolution.xsd".

  4. (Optional) Generate a class from the new schema and save it in the custom resolver assembly. This exposes typed parameters in the custom resolver.

  5. Register the new assembly in the global assembly cache.


Creating a Custom Resolver with a Unity Container

You can create a custom resolver using the Unity Application Block (Unity) (http://go.microsoft.com/fwlink/?LinkId=188286) for run-time dependency injection of resolution logic and metadata sources. These resolvers can be composed of three separate types of components:

  • Fact Providers

  • Fact Translators

  • Resolve Containers

For more information about configuring and creating custom Unity resolvers, see the following:

  • Configuring a Custom Unity Resolver

  • Creating a Custom Unity Resolver

Fact Providers

Fact providers are instances of classes that implement the IFactProvider interface. This interface exposes three different overloads of a method named RegisterFact. This method takes in the message, the resolver configuration, and, in some cases, the pipeline context, and returns an object. This object may be information extracted from the inputs in some way, it may be a calculation of some form, or it may be looked up from some external source. Each object returned by a fact provider can be referred to as a fact and is typically added to a list by the resolve container for later use by a fact translator.

A Unity resolver may have zero or more fact providers that can be added or removed at any time with a single configuration change.

The following code is an example of the logic contained in a fact provider. This code can also be found in the ItineraryStaticFactProvider.cs file of the ESB.Resolver.Itinerary.Facts project. It is a component in the ITINERARY-STATIC resolver that gathers the name and version of an itinerary from the resolver connection string.

C# Copy Code
        public object RegisterFact(IBaseMessage message, IPipelineContext pipelineContext, Dictionary<string, string> resolverContents)
        {
            return GetItineraryFactFromResolver(resolverContents);
        }

        private static object GetItineraryFactFromResolver(Dictionary<string, string> resolverContents)
        {
            if (resolverContents == null)
                throw new ArgumentNullException("resolverContents");

            ItineraryFact itineraryFact = new ItineraryFact();
            itineraryFact.Name = ResolverMgr.GetConfigValue(resolverContents, true, "name");
            string version = ResolverMgr.GetConfigValue(resolverContents, false, "version");
            if (!string.IsNullOrEmpty(version))
            {
                EventLogger.Write(string.Format("Version set with value {0}.", version));
                itineraryFact.SetVersion(version);
            }
            return itineraryFact;
        }

Fact Translators

Fact translators are instances of classes that implement the IFactTranslator interface. This interface exposes a single method named TranslateFact. This method takes in an object array that contains a list of facts and the resolver dictionary that will later be returned by the resolver using the fact translator. A fact translator is responsible for processing the facts provided by the fact providers in a meaningful way and then populating the resolver dictionary.

A Unity resolver may have zero or more fact translators that can be added or removed at any time with a single configuration change.

The following code is an example of the logic contained in a fact translator. This code can also be found in the ItineraryStaticFactTranslator.cs file of the ESB.Resolver.Itinerary.Facts project. It is a component in the ITINERARY-STATIC resolver that performs a database query to gather the itinerary XML for an itinerary by name and, optionally, by version.

C# Copy Code
        public void TranslateFact(object[] facts, Dictionary<string, string> factDictionary)
        {
            #region Argument Check
            if (null == facts) throw new ArgumentNullException("fact");
            if (null == factDictionary) throw new ArgumentNullException("factDictionary");
            #endregion

            #region Local Variables
            Version version = new Version(1, 0);
            #endregion
            try
            {
                foreach (object fact in facts)
                {
                    if (fact is ItineraryFact)
                    {
                        ItineraryFact targetFact = (ItineraryFact)fact;
                        factDictionary.Add(_FactKeyItineraryName, targetFact.Name ?? string.Empty);
                        if (null != targetFact.Version)
                        {
                            factDictionary.Add(_FactKeyItineraryVersion, targetFact.Version.ToString(2) ?? string.Empty);
                            version = targetFact.Version;
                        }

                        string xml = null;

                        if (targetFact.Version != null)
                        {
                            xml = _repositoryProvider.GetItinerary(targetFact.Name, version.Major, version.Minor);
                        }
                        else
                        {
                            xml = _repositoryProvider.GetItinerary(targetFact.Name);
                        }
                        if (!string.IsNullOrEmpty(xml))
                        {
                            factDictionary.Add(_FactKeyItinerary, xml);
                        }

                        break;
                    }
                }
            }
            #region Exception Handling
            catch (System.Exception)
            {
                throw;
            }
            #endregion
        }
        #endregion

Resolve Containers

A resolve container is a class that implements the IResolveContainer interface. Typically, it also implements the IResolveProvider interface. The IResolveContainer interface exposes a single method named Initialize that takes in an IUnityContainer. The container passed to this method will contain all of the dependencies (that is, instances of the classes IFactProvider and IFactTranslator, and any other types required) necessary for the resolver to complete its processing.

The following code is an example of an implementation of the IResolveContainer interface. This code can also be found in the StaticItineraryResolveContainer.cs file of the ESB.Resolver.Itinerary project.

C# Copy Code
#region IResolveContainer Members

private static IUnityContainer Container;

// <summary>
// This is used by the Unity resolver to initialize the current
// object with the Unity container.
// </summary>
// <param name="container">Unity container used for dependency
// injection.</param>
// <remarks>
// The container used is the ITINERARY container, although this is
// configurable in Esb.config.
// </remarks>

public void Initialize(IUnityContainer container)
{
  if (container == null)
    throw new ArgumentNullException("container");

  Container = container;
}
#endregion

In a resolve container, in the implementations of the Resolve methods from the IResolveProvider interface, it is necessary to iterate through all the fact providers and fact translators in the Unity container to allow each of them to perform their processing.

The following code is an example of the logic contained in a Resolve container. This code can also be found in the StaticItineraryResolveContainer.cs file of the ESB.Resolver.Itinerary project.

C# Copy Code
        public Dictionary<string, string> Resolve(ResolverInfo resolverInfo,
            XLANGMessage message)
        {
            #region Argument Check
            if (String.IsNullOrEmpty(resolverInfo.Config))
                throw new ArgumentNullException("resolverInfo.Config");
            if (String.IsNullOrEmpty(resolverInfo.Resolver))
                throw new ArgumentNullException("resolverInfo.Resolver");
            if (null == message)
                throw new ArgumentNullException("message");
            #endregion Argument Check

            return ResolveStatic(resolverInfo.Config, resolverInfo.Resolver,
                (factProvider, resolverContent) =>
                    factProvider.RegisterFact(message, resolverContent)
             );
        }

        private Dictionary<string, string> ResolveStatic(string config, string resolver,
            Func<IFactProvider, Dictionary<string, string>, object> RegisterFact)
        {
            try
            {
                EventLogger.Write(string.Format("Received {0} value in ITINERARY STATIC resolver.", config));

                Dictionary<string, string> queryParams =
                        ResolverMgr.GetFacts(config, resolver);

                List<object> facts = new List<object>();

                foreach (IFactProvider factProvider in Container.ResolveAll<IFactProvider>())
                {
                    facts.Add(RegisterFact(factProvider, queryParams));
                }

                Dictionary<string, string> resolverDictionary = new Dictionary<string, string>();

                object[] convertedFacts = facts.ToArray();

                foreach (IFactTranslator translator in Container.ResolveAll<IFactTranslator>())
                {
                    translator.TranslateFact(convertedFacts, resolverDictionary);
                }

                return resolverDictionary;
            }
            catch (System.Exception ex)
            {
                EventLogger.Write(MethodInfo.GetCurrentMethod(), ex);
                throw;
            }
        }

Configuring a Custom Unity Resolver

To configure a custom Unity resolver, the same configuration steps apply as when creating a custom resolver; however, there is some additional configuration that must be included to properly register the components that make up the resolver.

First, in the Esb.config file, under the resolver declaration, a resolverConfig node must be added with the following two properties:

  • unitySectionName. This property contains the name of the configuration section in the configuration file that contains the configuration for the Unity Application Block; by default, the value for this property is esb.resolver.

  • unityContainerName. This property contains the name of the Unity container defined in the Unity configuration specific to your custom resolver.

The following XML is an example of the configuration necessary in the resolvers node.

Xml Copy Code
               <resolver name="ITINERARY-STATIC" type="Microsoft.Practices.ESB.Resolver.Unity.ResolveProvider, Microsoft.Practices.ESB.Resolver.Unity, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22">
                    <resolverConfig>
                         <add name="unitySectionName" value="esb.resolver" />
                         <add name="unityContainerName" value="ITINERARY" />
                    </resolverConfig>
               </resolver>

The following XML is an example of the configuration necessary under the esb.resolver node.

Xml Copy Code
          <typeAliases>
               <!-- Lifetime manager types -->
               <typeAlias alias="singleton" type="Microsoft.Practices.Unity.ContainerControlledLifetimeManager, Microsoft.Practices.Unity, Version=1.2.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
               <!-- std type providers -->
               <typeAlias alias="string" type="System.String, mscorlib"/>
               <typeAlias alias="int" type="System.Int32, mscorlib"/>
               <!-- repository providers -->
               <typeAlias alias="IRepositoryProvider" type="Microsoft.Practices.ESB.Resolver.Itinerary.Facts.Repository.IRepositoryProvider, Microsoft.Practices.ESB.Resolver.Itinerary.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="SqlRepositoryProvider" type="Microsoft.Practices.ESB.Resolver.Itinerary.DataAccess.SqlRepositoryProvider, Microsoft.Practices.ESB.Resolver.Itinerary.DataAccess, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <!-- fact providers -->
               <typeAlias alias="IFactProvider" type="Microsoft.Practices.ESB.Resolver.Facts.IFactProvider, Microsoft.Practices.ESB.Resolver.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="IFactTranslator" type="Microsoft.Practices.ESB.Resolver.Facts.IFactTranslator, Microsoft.Practices.ESB.Resolver.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="ItineraryFactProvider" type="Microsoft.Practices.ESB.Resolver.Itinerary.Facts.ItineraryFactProvider, Microsoft.Practices.ESB.Resolver.Itinerary.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="ItineraryStaticFactProvider" type="Microsoft.Practices.ESB.Resolver.Itinerary.Facts.ItineraryStaticFactProvider, Microsoft.Practices.ESB.Resolver.Itinerary.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="ItineraryHeaderFactProvider" type="Microsoft.Practices.ESB.Resolver.Itinerary.Facts.ItineraryHeaderFactProvider, Microsoft.Practices.ESB.Resolver.Itinerary.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="ResolutionFactProvider" type="Microsoft.Practices.ESB.Resolver.Itinerary.Facts.ResolutionFactProvider, Microsoft.Practices.ESB.Resolver.Itinerary.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="DefaultFactTranslator" type="Microsoft.Practices.ESB.Resolver.Facts.DefaultFactTranslator, Microsoft.Practices.ESB.Resolver.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="ItineraryFactTranslator" type="Microsoft.Practices.ESB.Resolver.Itinerary.Facts.ItineraryFactTranslator, Microsoft.Practices.ESB.Resolver.Itinerary.Facts, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <!-- resolve providers -->
               <typeAlias alias="IResolveProvider" type="Microsoft.Practices.ESB.Resolver.IResolveProvider, Microsoft.Practices.ESB.Resolver, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22"/>
               <typeAlias alias="ItineraryResolveProvider" type="Microsoft.Practices.ESB.Resolver.Itinerary.BREItineraryResolverContainer,Microsoft.Practices.ESB.Resolver.Itinerary, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22 "/>
               <typeAlias alias="StaticItineraryResolveProvider" type="Microsoft.Practices.ESB.Resolver.Itinerary.StaticItineraryResolveContainer,Microsoft.Practices.ESB.Resolver.Itinerary, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22 "/>
          </typeAliases>
          <containers>
               <container name="ITINERARY">
                    <types>
                         <type type="IResolveProvider" mapTo="StaticItineraryResolveProvider" />
                         <type type="IRepositoryProvider" mapTo="SqlRepositoryProvider" name="CurrentRepositoryProvider">
                              <lifetime type="singleton" />
                              <typeConfig extensionType="Microsoft.Practices.Unity.Configuration.TypeInjectionElement,Microsoft.Practices.Unity.Configuration, Version=1.2.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
                                   <constructor>
                                        <param name="connectionStringName" parameterType="string">
                                             <value value="ItineraryDb"/>
                                        </param>
                                        <param name="cacheManagerName" parameterType="string">
                                             <value value="Itinerary Cache Manager"/>
                                        </param>
                                        <param name="cacheTimeout" parameterType="string">
                                             <value value="120" />
                                        </param>
                                   </constructor>
                              </typeConfig>
                         </type>
                         <type type="IFactProvider" mapTo="ResolutionFactProvider" name="ResolutionFactProvider"  />
                         <type type="IFactProvider" mapTo="ItineraryHeaderFactProvider" name="HeaderFactProvider"  />
                         <type type="IFactProvider" mapTo="ItineraryStaticFactProvider" name="StaticFactProvider"  />
                         <type type="IFactTranslator" mapTo="DefaultFactTranslator" name="DefaultFactTranslator">
                              <lifetime type="singleton" />
                         </type>
                         <type type="IFactTranslator" mapTo="ItineraryFactTranslator" name="ItineraryFactTranslator">
                              <lifetime type="singleton" />
                              <typeConfig extensionType="Microsoft.Practices.Unity.Configuration.TypeInjectionElement,Microsoft.Practices.Unity.Configuration, Version=1.2.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35">
                                   <constructor>
                                        <param name="repositoryProvider" parameterType="IRepositoryProvider">
                                             <dependency name="CurrentRepositoryProvider"/>
                                        </param>
                                   </constructor>
                              </typeConfig>
                         </type>
                    </types>
               </container>
          </containers>

For detailed information about the configuration that is necessary in the esb.resolvers node, see Source Schema for the Unity Application Block (http://go.microsoft.com/fwlink/?LinkId=188288) on MSDN.

Creating a Custom Unity Resolver

To create a custom Unity resolver

  1. (Optional) Create an assembly or assemblies with a class that implements the IFactProvider interface and contains a RegisterFact method that provides information necessary for resolution to occur.

  2. (Optional) Create an assembly or assemblies with a class that implements the IFactTranslator interface and contains a TranslateFact method that translates the provided facts to key/value pairs within the resolver dictionary.

  3. Create an assembly with a class that implements the IResolveContainer and IResolveProvider interface and that contains a Resolve method that validates the resolver configuration, gathers all the facts from the fact providers, performs any specialized processing, translates them using the fact translators, and returns the translated facts as an instance of the Dictionary class.

  4. Register the resolver by adding it to the Esb.config configuration file using a <resolver> element that contains the root moniker as the name attribute and the fully qualified assembly name as the type attribute.

  5. Add the Unity-specific configuration to the Esb.config file for this resolver.

  6. (Optional) Create a schema that defines the root moniker and the query parameters, and then save it in the ESB.Schemas.Resolvers folder. The name should follow existing ESB naming conventions; this means it should use the name of the root moniker appended with "_Resolution.xsd".

  7. (Optional) Generate a class from the new schema and save it in the custom resolver assembly. This will expose typed parameters in the custom resolver.

  8. Register all the assemblies in the global assembly cache.


Creating a Custom Adapter Provider

After a resolver executes, as described in the previous sections, the dynamic resolution service checks whether the result is an endpoint (not a transformation). If it is an endpoint, the service instantiates the adapter manager, which is an instance of the AdapterMgr class.

The adapter manager validates and fixes the transport type and the outbound transport location. If the transport type is still not resolved, and if the URL begins with either "http" or "https", the adapter manager sets the transport type to "WCF-WSHttp".

Next, the adapter manager verifies that the transport type equates to a valid Microsoft BizTalk Server adapter, and then it returns its property namespace. This process runs only once for all adapters and stores the results in a cache to avoid repeated queries for other incoming messages that use the same adapter.

The adapter manager uses the transport type (without the "://" suffix) to determine the appropriate adapter provider. An adapter provider is a custom assembly that must implement the IAdapterProvider interface. The adapter provider uses the properties of the Resolution structure in the Dictionary instance generated by the resolver to set all the protocol-specific properties of the message that enables the Microsoft BizTalk Server run-time engine to perform dynamic resolution.

Like with the resolver (described in the previous section), the dynamic resolution mechanism uses entries in the Esb.config configuration file to locate adapter providers. The following XML shows the section of the configuration file.

Xml Copy Code
          <adapterProviders cacheManager= "Adapter Providers Cache Manager"  absoluteExpiration="3600">
               <adapterProvider name="WCF-WSHttp" type="Microsoft.Practices.ESB.Adapter.WcfWSHttp.AdapterProvider, Microsoft.Practices.ESB.Adapter.WcfWSHttp, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22" moniker="Http,Https" />
               <adapterProvider name="WCF-BasicHttp" type="Microsoft.Practices.ESB.Adapter.WcfBasicHttp.AdapterProvider, Microsoft.Practices.ESB.Adapter.WcfBasicHttp, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22" moniker="Http,Https" />
               <adapterProvider name="WCF-Custom" type="Microsoft.Practices.ESB.Adapter.WcfCustom.AdapterProvider, Microsoft.Practices.ESB.Adapter.WcfCustom, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22" moniker="mssql" />
               <adapterProvider name="SMTP" type="Microsoft.Practices.ESB.Adapter.SMTP.AdapterProvider, Microsoft.Practices.ESB.Adapter.SMTP, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22" moniker="smtp" />
               <adapterProvider name="FTP" type="Microsoft.Practices.ESB.Adapter.FTP.AdapterProvider, Microsoft.Practices.ESB.Adapter.FTP, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22">
                    <adapterConfig>
                         <add name="DefaultUsername" value="anonymous" />
                         <add name="DefaultPassword" value="" />
                    </adapterConfig>
               </adapterProvider>
               <adapterProvider name="MQSeries" type="Microsoft.Practices.ESB.Adapter.MQSeries.AdapterProvider, Microsoft.Practices.ESB.Adapter.MQSeries, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22" moniker="MQS" adapterAssembly="MQSeries, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
               <adapterProvider name="FILE" type="Microsoft.Practices.ESB.Adapter.FILE.AdapterProvider, Microsoft.Practices.ESB.Adapter.FILE, Version=2.0.0.0, Culture=neutral, PublicKeyToken=c62dd63c784d6e22" moniker="File" />
          </adapterProviders>

Creating a Custom Adapter Provider

The adapter manager (an instance of the AdapterMgr class) looks up the adapter provider in the configuration files and loads the appropriate assembly. The dynamic resolution mechanism caches all loaded concrete implementations of the IAdapterProvider interface to avoid repeated reading of configuration information and assembly loading when several incoming messages use the same adapter provider.

Finally, the adapter manager executes the SetEndPoint method of the concrete implementation of the IAdapterProvider interface, and the pipeline component returns the message to the BizTalk Message Box database.

To create a custom adapter provider

  1. Create an assembly that derives from the BaseAdapterProvider base class and contains a SetEndPoint method that sets the endpoint context properties of the message.

  2. Register the adapter provider by adding it to Esb.config configuration files using an <adapterProvider> element with a name for the adapter as the name attribute, the fully qualified name of the class as the type attribute, the moniker as the moniker attribute (multiple values should be separated by a comma), and optionally the assembly of the actual adapter as the adapterAssembly attribute.

  3. Register the new assembly in the global assembly cache.


Creating a Custom Itinerary Service

You can modify and/or extend the ​Microsoft BizTalk ESB Toolkit itinerary services and components to suit your specific requirements. There are two ways in which you can create a custom itinerary service:

  • Creating a Custom Itinerary Service Using a BizTalk Orchestration

  • Creating a Custom Itinerary Messaging Service


Creating a Custom Itinerary Service Using a BizTalk Orchestration

The itinerary framework that is part of the ​Microsoft BizTalk ESB Toolkit supports execution of itinerary steps using orchestrations. You can implement a custom itinerary service as a Microsoft BizTalk Server orchestration based on your functional requirements, which may include the following:

  • Multiple service invocations (as demonstrated by the Installing and Running the Scatter-Gather Sample)

  • Protocol mediation and message correlation (for example, HTTP-MQSeries)

  • Complex routing decisions based on message enrichment from external data sources

  • Business processing logic

Every itinerary service implemented using a BizTalk Server orchestration is responsible for the following:

  • Exception and error handling using the ESB Exception Handling Framework or optional custom exception handlers that support resubmission (one-way itineraries)

  • Advancing the itinerary and publishing outbound messages through BizTalk Server so that the next itinerary service step can execute

To create a custom itinerary service using a BizTalk Server orchestration

  1. Create new BizTalk Server project containing a new orchestration; for example, MyCustomeItineraryService.odx.

  2. Add references to the following assemblies:

    • Microsoft.Practices.ESB.Itinerary

    • Microsoft.Practices.ESB.Itinerary.Schemas

    • Microsoft.Practices.ESB.ExceptionHandling

    • Microsoft.Practices.ESB.ExceptionHandling.Faults

  3. Define a logical direct-bound receive port and an activated receive shape in the orchestration.

  4. Define a subscription filter to activate the orchestration from the message itinerary context so that the orchestration executes the MyCustomItineraryService step. The following code shows an example of a suitable filter.

    C# Copy Code
    (Microsoft.Practices.ESB.Itinerary.Schemas.ServiceName
    == "MyCustomItineraryService")
&& (Microsoft.Practices.ESB.Itinerary.Schemas.ServiceState == "Pending")
&& (Microsoft.Practices.ESB.Itinerary.Schemas.ServiceType
    == "Orchestration")

  5. Define an orchestration of type Microsoft.Practices.ESB.Itinerary.ItineraryStep. Add an expression activity to the orchestration that populates this variable, as shown in the following code.

    C# Copy Code
    // Retrieve the current itinerary step.
itinerary = new Microsoft.Practices.ESB.Itinerary.SerializableItineraryWrapper();
step = new Microsoft.Practices.ESB.Itinerary.SerializableItineraryStepWrapper();

itinerary.Itinerary = Microsoft.Practices.ESB.Itinerary.ItineraryOMFactory.Create(InboundMessage);
step.ItineraryStep = itinerary.Itinerary.GetItineraryStep(InboundMessage);

  6. Add your custom implementation to the itinerary that creates the outbound message for the next itinerary steps; for example, OutboundMsg.

  7. Advance the itinerary using the following expression activity that uses the message context from inbound message.

    C# Copy Code
    OutboundMessage(*) = InboundMessage(*);
itinerary.Itinerary.Advance(OutboundMessage, itineraryStep.ItineraryStep);

  8. Send the outbound message with the updated itinerary through a direct-bound send port to activate the next itinerary service.

For more information about implementing a custom itinerary service using BizTalk Server orchestrations, see Installing and Running the Itinerary On-Ramp Sample and Installing and Running the Scatter-Gather Sample.


Creating a Custom Itinerary Messaging Service

The itinerary framework that is part of the ​Microsoft BizTalk ESB Toolkit supports execution of itinerary steps using classes implementing the IMessagingService interface that execute itinerary messaging services. You can implement a custom messaging service when you want the service to be responsible for the following:

  • Custom message validation configured in the itinerary

  • Custom message transformation configured in the itinerary

  • Custom processing of the message

In all these cases, a custom itinerary service that you implement acts as an interceptor and is called by the Dispatcher pipeline component.

Custom messaging-based itinerary services, or messaging services, all implement the IMessagingService interface. This interface exposes the Name and SupportsDisassemble properties and the Execute and ShouldAdvanceStep methods.

The Name property is the name of the service as it will appear in an itinerary. It must match the configured name in the itinerary services configuration in the Esb.config file.

The SupportsDisassemble property indicates whether the custom messaging service you are creating supports disassemble and the execution of multiple resolvers.

The ShouldAdvanceStep method takes in the current itinerary step, and the current message, and returns a Boolean value that indicates whether the dispatcher should advance the itinerary after the service executes. In almost all cases, this method should return true.

The Execute method is of greatest importance for a messaging service and contains the logic that will be executed at run time. It takes in the pipeline context, the message, the resolver string, and the current itinerary step; and it returns the updated message.

A reference implementation of the Execute method can be found in the RoutingService.cs file of the ESB.Itinerary.Services project, as shown in the following code.

C# Copy Code
public IBaseMessage ExecuteRoute(IPipelineContext context, IBaseMessage msg, string resolverString)
        {
            if (context == null)
                throw new ArgumentNullException("context");
            if (msg == null)
                throw new ArgumentNullException("msg");
            if (string.IsNullOrEmpty(resolverString))
                throw new ArgumentException(Properties.Resources.ArgumentStringRequired, "resolverString");
            try
            {
                ResolverInfo info = ResolverMgr.GetResolverInfo(ResolutionType.Endpoint, resolverString);
                if (!info.Success)
                    throw new RoutingException(Properties.Resources.ResolverStringInvalid, resolverString);

                // Resolve configuration for routing.
                Dictionary<string, string> resolverDictionary = ResolverMgr.Resolve(info, msg, context);

                if (string.IsNullOrEmpty(resolverDictionary["Resolver.TransportLocation"]))
                    throw new RoutingException(Properties.Resources.TransportLocationNotResolved, resolverString);

                AdapterMgr.SetEndpoint(resolverDictionary, msg.Context);

                return msg;
            }
            catch (System.Exception ex)
            {
                EventLogger.Write(MethodInfo.GetCurrentMethod(), ex);
                throw;
            }
        }

To implement a custom itinerary service for messaging

  1. Create an assembly with a class that derives from IMessagingService; in the Execute method, include all logic necessary to make modifications to the message or the message context (if any).

  2. Add an entry in the itineraryServices section of the Esb.config file for your service by adding an <itineraryService> element with a GUID as the id attribute, the name of the service as the name attribute, the fully qualified name of the class as the type attribute, Messaging as the scope attribute, and the allowed stage (for example, OnRampReceive, OnRampSend, OffRampSend, OffRampReceive, AllSend, AllReceive, or All) as the stage attribute.

  3. Register the new assembly in the global assembly cache.


Extending the Itinerary Designer

The Itinerary Designer is a visual domain-specific language (DSL) for Microsoft Visual Studio that enables the graphical modeling of itineraries for use with the ​Microsoft BizTalk ESB Toolkit. The designer exposes various extension points for which developers can write custom extensions to enable new functionality and/or new configuration options.

The Itinerary Designer can be extended in the following ways:

  • Creating a Custom Itinerary Exporter

  • Creating a Custom Extender Messaging Service

  • Creating a Custom Extender for Orchestration-Based Itinerary Service

  • Creating a Custom Resolver Extender

  • Creating a Manifest File for Custom Adapter Properties

  • Creating a Custom Filter Extender

  • Creating Custom Validation Rules

Creating a Custom Itinerary Exporter

The architecture of the Itinerary Designer allows for the creation of custom model exporters that serialize and persist the data in an Itinerary model.

Creating a Custom Extender for a Messaging Service

The architecture of the Itinerary Designer allows you to create custom extenders for Itinerary Service model elements that can be used to add properties to the property bag for use by Messaging Services.

For a sample of how to create such an extender, see Installing and Running the Designer Extensibility Sample.

Creating a Custom Extender for an Orchestration-Based Itinerary Service

The architecture of the Itinerary Designer allows you to create custom extenders for Itinerary Service model elements that can be used to add properties to the property bag for use by orchestration-based itinerary services.

For a sample of how to create such an extender, see Installing and Running the Designer Extensibility Sample.

Creating a Custom Resolver Extender

The architecture of the Itinerary Designer allows you to create custom extenders for the configuration of custom resolvers. These extenders provide a graphical interface for configuring the name-value pairs in the resolver connection string, which map to properties in the specific resolver extender class.

For a sample of how to create such an extender, see Installing and Running the Designer Extensibility Sample.

Creating a Manifest File for Custom Adapter Properties

When creating a custom adapter provider, you must also provide designer support for the adapter provider to those resolver extenders that display an endpoint configuration property. To enable designer support, it is necessary to create an adapter provider manifest file.

The adapter provider manifest file defines the properties associated with a specific adapter provider, their types, descriptions, and the assembly in which they can be found. These manifest files should be placed in the same folder as the Itinerary Designer binaries (for example, Microsoft.Practices.Itineary.DslPackage.dll) with a unique name (for example, FTPPropertyManifest.xml).

The following is a reference instance of an adapter provider manifest file; custom manifest files should be structured likewise.

Xml Copy Code
<?xml version="1.0" encoding="utf-8" ?>
<adapterPropertyManifest adapterName="FTP">
     <aliases>
          <alias name="globalPropertySchemas" value="Microsoft.BizTalk.GlobalPropertySchemas, Version=3.0.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
     </aliases>
     <properties>
          <property name="UserName" type="FTP.UserName" description="The user name for the connection." encrypted="true" assembly="globalPropertySchemas" />
          <property name="Password" type="FTP.Password" description="The password for the conection." encrypted="true" assembly="globalPropertySchemas" />
          <property name="MaxConnections" type="FTP.MaxConnections" description="The maximun number of connections." assembly="globalPropertySchemas" />
          <property name="EventArgs" type="System.EventArgs" assembly="mscorlib, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
     </properties>
</adapterPropertyManifest>

Creating a Custom Filter Extender

The architecture of the Itinerary Designer allows you to create custom extenders for the configuration of custom filters. These extenders provide a graphical interface for configuring the name-value pairs in the filter connection string, which map to properties in the specific filter extender class.

  • /Samples/Designer Extensibility Samples/Extenders.Itinerary.OrchestrationSample/Extenders.Itinerary.OrchestrationSample/Extenders.Itinerary.OrchestrationSample

  • /Samples/Designer Extensibility Samples/Extenders.Resolvers.ResolverSample/Extenders.Resolvers.ResolverSample

Creating Custom Validation Rules

The last significant extension introduced by the Itinerary Designer is a validation mechanism that allows you to externally, with respect to a domain-specific language (DSL), specify and implement the model validation rules. The mechanism "hooks into" the DSL validation framework and is activated when the user clicks Validate or Validate all on the shortcut menu of a model. This invokes the DSL framework's DslCommandSet object that, in turn, calls the validation engine in the Itinerary Designer.

The ValidationEngine class performs the model element validation using the Enterprise Library Validation Application Block and logs the validation errors to the Error List window in Microsoft Visual Studio IDE. The validation that should be performed for each type of element in a model is defined in the Enterprise Library configuration file. The file is named Ruleset.config and is located in the binary folder where all the Itinerary Designer binaries are located. The following example is a fragment of the configuration file and includes two validation rules (named validators) for the UddiResolver extender, one for the ServerUrl property and one for the ServiceKey property.

Copy Code
<!--
UddiResolver
-->
<type assemblyName="Microsoft.Practices.Services.Extenders.Resolvers.UDDI"
 name="Microsoft.Practices.Services.Extenders.Resolvers.UDDI.UddiResolver">
<ruleset name="Menu">
<properties>
<property name="ServerUrl">
<validator type="Microsoft.Practices.Modeling.Validation.NotEmptyStringValidator, Microsoft.Practices.Modeling.Validation"
          messageTemplate="The '{1}' property value should not be empty or null."
          name="UddiResolver.ServerUrl not null validator"/>
</property>
<property name="ServiceKey">
<validator type="Microsoft.Practices.Modeling.Validation.NotEmptyStringValidator, Microsoft.Practices.Modeling.Validation"
          messageTemplate="The '{1}' property value should not be empty or null."
          name="UddiResolver.ServiceKey not null validator"/>
</property>
</properties>
</ruleset>
</type>

Each rule identifies the validator that implements the rule. The Itinerary Designer comes with a large set of validator classes. They are all in the Microsoft.Practices.Modeling.Validation project in the Designer binary folder.

The final result of using this validation mechanism is that Itinerary Designer users can modify how the models are validated by changing the provided rules and validators or by adding their own rules and validators. This can be done without opening, modifying, rebuilding, and re-deploying the DSLs by performing the following two steps:

  1. Create a validator class and put it in a library inside the binary folder where the Microsoft.Practices.Modeling.Validation.dll library is located.

  2. Add entries to the Rules.config file to define what property of what model element class the validator should be applied.


Administration with the BizTalk ESB Toolkit

This section discusses an important area of administrative activity related to applications based on the ​Microsoft BizTalk ESB Toolkit and Microsoft BizTalk Server; specifically, it discusses the ESB Management Portal. The ESB Management Portal is a Web-based utility for monitoring BizTalk Server applications that generates alerts when exceptions arise and manages certain features of the BizTalk ESB Toolkit, such as the registration of Universal Description, Discovery, and Integration (UDDI) entries.

This section includes the following topics:

  • Administration Using the ESB Management Portal

  • ESB Management Portal Feature Reference


Administration Using the ESB Management Portal

The ESB Management Portal, included as part of the ​Microsoft BizTalk ESB Toolkit, is a sample site that demonstrates the use of metrics and the possibilities that exist for extending the BizTalk ESB Toolkit. The portal provides a starting point from which you can build your own customized portal.

The ESB Management Portal is also a highly capable and useful tool that can help to maximize the use and efficiency of the ESB exception management system. In addition, the portal provides a user interface for an underlying Universal Description, Discovery, and Integration (UDDI) registry server and graphical configuration capabilities for features such as auditing, viewing history information, configuring alerts and notifications, and allowing users to subscribe to alerts that indicate faults occurring in ESB applications.

This section describes the common tasks you can accomplish using the ESB Management Portal, including the following:

  • Working with Exceptions and Fault Messages

  • Configuring Alerts, Notifications, and Subscriptions

  • Viewing and Managing Auditing and History

  • Analyzing Fault Trends Using Charts and Reports

  • Viewing and Publishing UDDI Registrations

Note
For a detailed description of the individual features of the ESB Management Portal, see ESB Management Portal Feature Reference.

ESB Portal Technologies

The ESB Management Portal takes advantage of the following technologies:

  • SQL Server 2014 or SQL Server 2012 SP1

  • ASP.NET 4

  • Enterprise Library 4.1(http://go.microsoft.com/fwlink/?LinkId=188292). The ESB Management Portal uses the following Enterprise Library assemblies:

    • Microsoft.Practices.EnterpriseLibrary.Caching

    • Microsoft.Practices.EnterpriseLibrary.Common

    • Microsoft.Practices.EnterpriseLibrary.Data

    • Microsoft.Practices.EnterpriseLibrary.ExceptionHandling

    • Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.Logging

    • Microsoft.Practices.EnterpriseLibrary.Logging

    • Microsoft.Practices.EnterpriseLibrary.ObjectBuilder2

    • Microsoft.Practices.EnterpriseLibrary.Validation

    • Microsoft.Practices.Unity

  • Microsoft Chart Controls (http://go.microsoft.com/fwlink/?LinkId=188293) for Microsoft .NET Framework 4

In this release of the ​Microsoft BizTalk ESB Toolkit, metric tracking extends only to fault tracking for the exception management system.


Working with Exceptions and Fault Messages

This section describes the methods by which the ESB Management Portal can be used to monitor the behavior of applications by viewing fault messages generated when errors occur, according to the following common tasks:

  • Listing, Searching, and Sorting Fault Messages

  • Viewing and Downloading the Original Messages

  • Repairing and Resubmitting Messages


Listing, Searching, and Sorting Fault Messages

You can use the Home page of the ESB Management Portal to obtain an overall view of the status of the applications executing within Microsoft BizTalk Server. The Faults page can be used to query for fault messages, based on a range of criteria.

To see an overview of the status of current BizTalk Server applications

  1. Open the Portal Home Page. This page displays the overall application state, a summary of faults, recent requests for Universal Description, Discovery, and Integration (UDDI) registration, and charts that show a breakdown of faults by type and by application.

  2. To select the applications for which you want to view information, click the Select Applications link above the first chart, and then select or clear the check boxes in the list of installed BizTalk Server applications that appears.

  3. To change the period for which the portal displays information, select Hour, Day, Week, Month, Quarter, Year, or ALL in the drop-down list above the first chart.

  4. To change the default settings used on the Home page for the list of applications and the display period, edit the settings on the Portal My Settings Page.

To list, search for, and sort fault messages in the ESB Management Portal

  1. Open the Fault Settings Page. This page displays a truncated list of properties for each fault and supports analysis of faults by a range of criteria.

  2. To filter the list of faults displayed on the page, use the drop-down lists and text boxes above the list of faults. You can filter the rows displayed by application, period, fault code number, fault category name, error type text, and minimum/maximum fault severity. Leave any of the controls empty to retrieve all messages irrespective of their value for this criterion.

  3. Click Apply Filters to see the list of matching faults. Note that filtering on very large fault databases may take a few seconds to display results.

  4. To display more or fewer rows in the page, select the appropriate value in the Records Per Page drop-down list.

  5. To sort the list of fault messages, click a column heading. To sort the rows in reverse order, click the same column heading again.

  6. Click Export To Excel to download the complete list of fault messages in a format that you can view in Microsoft Excel.


Viewing and Downloading the Original Messages

To view a fault message in greater detail, use the Fault Viewer pages of the ESB Management Portal.

To view the properties and status of a fault message

  1. Locate the fault message on the Portal Faults Page of the ESB Management Portal.

  2. Click anywhere in the row to open the ESB Fault Message Viewer in Fault Details View.

  3. Scroll to the list of messages at the bottom of the page, and then click the message identifier of the chosen fault message to open it in Message Details View.

To view and download individual messages from a fault message

  1. Locate the fault message on the Portal Faults Page of the ESB Management Portal.

  2. Click anywhere in the row to open the ESB Fault Message Viewer in Fault Details View view.

  3. Scroll to the list of messages at the bottom of the page.

  4. Click the message identifier of the chosen fault message to open it in Message Details View view or click Download to download the message body.

  5. To download the message from the Message Details view, click the Download link under the message content text box.


Repairing and Resubmitting Messages

Fault messages displayed in the ESB Management Portal may be the result of an error in the values of the original message when submitted for processing. The ​Microsoft BizTalk ESB Toolkit supports "repair and resubmit" functionality that allows administrators or users to edit failed messages and resubmit them to the ESB for processing.

This section contains the following topics:

  • Repairing and Resubmitting a Message

  • Resubmission Notes and Restrictions

  • Troubleshooting Resubmission Issues


Repairing and Resubmitting a Message

To repair and resubmit a failed message, use the Faults page of the ESB Management Portal.

To repair and resubmit a message for processing

  1. Locate the desired fault message on the Portal Faults Page page of the ESB Management Portal. Use the filtering capabilities on the Faults page to search for a specific message. Leave any of the controls empty to retrieve all messages. Note that filtering on a very large fault database may take several seconds to display the appropriate results. Figure 1 illustrates the Faults page.

    Figure 1

    The Faults page of the ESB Management Portal

  2. Click anywhere in the row of the desired fault message to open the Portal Fault Message Viewer page in Fault Details View.

  3. Scroll to the bottom of the Fault Details view to the list of messages contained within the fault message. Figure 2 illustrates the section of the Fault Viewer page.

    Figure 2

    The Messages section of the Fault Viewer page of the ESB Management Portal

  4. Click the message identifier of the message you want to resubmit. This opens the message in Message Details View, which shows details of the individual message and the message content, as illustrated in Figure 3.

    Figure 3

    The Message Viewer page of the ESB Management Portal

  5. Click the Edit link under the text box that contains the message content to switch to edit mode, and then edit the message contents as required. For example, you may need to change the parameters for service method invocations contained within the message. Note that you must adhere to the native document style (such as XML or flat file format) to prevent rejection of the message when resubmitted. Figure 4 illustrates the Message Details section of the Message Editor page.

    Figure 4

    The Message Details section of the Message Viewer page of the ESB Management Portal

  6. After editing the message, select a resubmission location in the drop-down list under the message text box. This list shows the dynamically retrieved list of available endpoints. You must select an endpoint configured as a resubmission endpoint. The following endpoints are suitable for resubmission:

    • WCF On-Ramp. This endpoint is the ESB Itinerary Services WCF on-ramp and is available only for XML files. The portal Web.config file defines the URL for this on-ramp.

    • SOAP On-Ramp. This endpoint is the ESB Itinerary Services ASMX on-ramp and is available only for XML files. The portal Web.config file defines the URL for this on-ramp.

    • Any receive location using the BizTalk HTTP adapter. This option is available for XML files and flat files.

  7. Click the Resubmit link to resubmit the message. A message indicating the Resubmission Status appears under the message content text box.

  8. If required, open the Audit Log Page from the Admin tab to confirm message resubmission, as illustrated in Figure 5.

    AuditLog Page Small View

    Figure 5

    The Audit Log page of the ESB Management Portal


Resubmission Notes and Restrictions

The following notes and restrictions apply to the resubmission process:

  • You can resubmit XML messages to the ESB WCF on-ramp, SOAP (ASMX) on-ramp, or any HTTP receive location.

  • The default URL for the WCF on-ramp is http://localhost/ESB.ItineraryServices.WCF/ProcessItinerary.svc.

  • The portal Web.config file defines the endpoint details for the WCF on-ramp in the <Client> node of the <System.ServiceModel> section. The following is the default value.

    Copy Code
    <endpoint
  address="http://localhost/ESB.ItineraryServices.WCF/ProcessItinerary.svc"
  binding="wsHttpBinding"
  bindingConfiguration="WSHttpBinding_ITwoWayAsyncVoid"
  contract="ProcessRequest"
  name="WSHttpBinding_ITwoWayAsyncVoid">
</endpoint>
  • If the WCF on-ramp resides on a remote server, you must update the address to point to the correct server.

  • The default URL for the SOAP (ASMX) on-ramp is http://localhost/ESB.ItineraryServices/ProcessItinerary.asmx.

  • The portal Web.config file defines the configuration for the SOAP (ASMX) on-ramp in the <applicationSettings> section. The following is the default value.

    Copy Code
    <setting
  name="Microsoft_Practices_ESB_Portal_ProcessItinerary_Process"
  serializeAs="String">
  <value>
    http://localhost/ESB.ItineraryServices/ProcessItinerary.asmx
  </value>
</setting>
  • If the ASMX on-ramp resides on a remote server, you need to update the URL with the correct server address.

  • You can resubmit flat file formatted messages only to an HTTP receive location. You cannot submit them to a WCF or SOAP on-ramp. You must ensure that the HTTP receive location has the appropriate pipeline that can consume and/or parse the flat file.

  • The resubmitted message does not contain any of the context properties of the original message.

  • Resubmission applies to only the message body; it does not apply to the entire message.

  • The resubmission process supports only single-part messages. You cannot use the resubmission process with multi-part messages.

  • You cannot resubmit binary-formatted messages.


Troubleshooting Resubmission Issues

If you have problems resubmitting messages, check the following:

  • Can you access the receive location through your browser? If you are trying to resubmit to the WCF on-ramp or the SOAP on-ramp, the URL should be of the form http://localhost/ESB.OnRampServices.WCF/ProcessItinerary.svc or http://localhost/ESB.OnRampServices/ProcessItinerary.asmx. If you are trying to resubmit to an HTTP receive location, you can use your Internet browser to determine whether the receive location is functioning properly by appending a sample message to the query string, as shown in the following example.

    Copy Code
    http://localhost/HTTPOnRamp/BTSHttpReceive.dll?<SampleMessage>Sample Message Content</SampleMessage>
  • Verify that the BizTalk HTTP receive adapter is properly configured.


Configuring Alerts, Notifications, and Subscriptions

This section examines the ways that you can configure the ESB Management Portal to generate alerts when fault messages arrive at the portal and how to create subscriptions and notifications that can alert users automatically when errors occur. The common tasks are the following:

  • Creating, Viewing, and Deleting Fault Message Alerts

  • Subscribing to Alerts

  • Configuring Alert Queue Options and Notifications


Creating, Viewing, and Deleting Fault Message Alerts

The ESB Management Portal can generate alerts when fault messages arrive at the portal, based on a comparison of values in the message with criteria specified for the alert. The portal can also maintain a list of notifications linked to individual alerts and users, and it will notify these users when it proactively raises alerts.

To create and configure a new alert

  1. Open the Portal Alerts Page to see a list of existing alerts and your current subscriptions to these alerts.

  2. Click the Create Alert link to open the Add Alert Page.

  3. In the Enter Alert Name text box, type a name for the new alert.

  4. In the Conditions section of the Add Alert page, select a field (such as Application, Error Type, or Fault Severity) in the Criteria drop-down list; select a comparison type (such as +, =, !=, >=, <=, or like) in the Operator drop-down list; and type or select a value from the third list or text box (named Value). As you select a Criteria value, the page changes to display either a text box or a drop-down list for the matching value. All conditions are combined using the AND operator.

  5. Click the Add link to add this condition to the list, and then repeat the previous step to add more conditions if required.

  6. Click the Save button to create a new alert with the specified name and conditions.

To view details of an existing alert or delete an existing alert

  1. Open the Portal Alerts Page.

  2. To delete an alert, click the Delete Alert icon in the Action column of an existing alert.

    Note
    Non-administrative users can delete only alerts for which they are an owner, and for which there are currently no subscribers. You must log on to the portal as an administrator to delete other alerts.

  3. To view details of an alert, click the View icon in the Action column of an existing alert. This opens the Alert Viewer page.

  4. Click Export To Excel to download the complete list of alerts in a format that you can view in Microsoft Excel.


Subscribing to Alerts

To subscribe to an alert

  1. Open the Portal Alerts Page to see a list of existing alerts and your current subscriptions to these alerts.

  2. In the Action column, click the AddSubscriber icon for an existing alert. This opens the Add Alert Subscription and Edit Subscription Pages.

  3. The portal sends alert notifications to the e-mail address associated with the account you use to access the portal. If you want to use a different e-mail address, select the check box next to the Custom Email text box, and then type the preferred e-mail address in the text box.

  4. Select the check box in the Schedule section if you want to specify a period when the portal should send alerts to you, and then specify the start and end times for the period in the Start Time and EndTime drop-down lists.

  5. If there is a period when you will be unable to receive and act upon alerts, type the start and end dates in the Black-out Period boxes.

  6. Select an Interval in Minutes during which the portal will compare alerts raised and send only one when multiple instances of the same alert occur. This prevents a rapidly occurring fault from creating a large number of identical alert messages.

  7. Click the Save button to create the new subscription.

To edit an existing alert subscription

  1. Open the Portal Alerts Page to see a list of existing alerts and your current subscriptions to these alerts.

  2. Click the Edit link next to the subscription you want to modify in the list in the My Subscriptions section of the page to open the Add Alert Subscription and Edit Subscription Pages.

  3. The portal sends alert notifications to the e-mail address associated with the account you use to access the portal. If you want to use a different e-mail address, select the check box next to the Custom Email text box, and then type the preferred e-mail address in the text box.

  4. Select the check box in the Schedule section if you want to specify a period when the portal should send alerts to you, and then specify the start and end times for the period in the Start Time and EndTime drop-down lists.

  5. Type the start and end dates for a Black-out Period if there is a period when you will be unable to receive and act upon alerts.

  6. Select an Interval in Minutes during which the portal will compare alerts raised and will send only one when multiple instances of the same alert occur. This prevents a rapidly occurring fault from creating a large number of identical alert messages.

  7. Click the Save button to update the subscription.

To delete an existing alert subscription

  1. Open the Portal Alerts Page to see a list of existing alerts and your current subscriptions to these alerts.

  2. Click the Delete link next to the subscription you want to delete in the list in the My Subscriptions section of the page.


Configuring Alert Queue Options and Notifications

The ESB Management Portal uses the ESB Alert Service to generate alerts as fault messages arrive at the portal, and it uses the ESB Notification Service to queue and send alert notifications to users that subscribe to alerts. You can edit the settings used by these services in the ESB Management Portal.

To configure the settings for the ESB Alert Service

  1. Ensure that you log on to the portal using an account that is a member of the Microsoft BizTalk Server Administrators account group (of which portal administrators are automatically a member).

  2. Point to the Admin tab on the portal main menu, and then click Fault Settings to open the portal Fault Settings Page.

  3. In the Alert Queue Options section, select or clear the Enable Alert Queue Service check box to enable or disable the service.

  4. If you enable the service, edit the values in the remaining controls to suit our requirements. The service interacts with Microsoft Active Directory, so you must specify the appropriate LDAP (Lightweight Directory Access Protocol) connection string. You can also specify the queue batch size and polling interval.

  5. Click Save to save the new settings.

To configure the settings for the ESB Alert Email Notification service

  1. Ensure that you log on to the portal using an account that is a member of the BizTalk Server Administrators account group (of which portal administrators are automatically a member).

  2. Point to the Admin tab on the portal main menu, and then click Fault Settings to open the portal Fault Settings Page.

  3. In the Alert Email Options section, select or clear the Enable Alert Email Service check box to enable or disable the service.

  4. If you enable the service, edit the values in the remaining controls to suit our requirements. Specify the e-mail server name and the "from" address, change the polling interval and batch size as required, and specify the path to Extensible Stylesheet Language Transformations (XSLT) files that the service uses.

  5. Click Save to save the new settings.


Viewing and Managing Auditing and History

The ESB Management Portal automatically maintains a history log of events occurring in the portal, such as fault messages and Universal Description, Discovery, and Integration (UDDI) publications. It also generates an audit log, for which you can configure the level of auditing you require. This section describes the following common tasks:

  • Configuring and Viewing Audit Logs

  • Viewing History Information


Configuring and Viewing Audit Logs

The ESB Management Portal maintains an audit log of actions that help you to monitor usage and track problems. Administrators can specify which events the portal will write to the audit log.

To view the audit logs for the portal

  1. Point to the Admin tab on the portal main menu, and then click Manage Audit Log to open the Audit Log Page.

  2. To see the resubmission details and the original message for resubmitted messages, click the identifier of a message in the list to open the Audit Log – Message Viewer page.

To configure the auditing settings for the portal

  1. Ensure that you log on to the portal using an account that is a member of the BizTalk Server Administrators account group (of which portal administrators are automatically a member).

  2. Point to the Admin tab on the portal main menu, and then click Fault Settings to open the portal Fault Settings Page.

  3. To change the auditing options, select the check boxes in the AuditOptions section for each event you want to audit. The available events are the saving of modified settings, successful resubmission of a fault after editing, and failure when resubmitting a fault.


Viewing History Information

The ESB Management Portal maintains a history of all requests for Universal Description, Discovery, and Integration (UDDI) registration. Administrators can view this list within the portal.

To view UDDI request history

  1. Ensure that you log on to the portal using an account that is a member of the Microsoft BizTalk Server Administrators account group (of which portal administrators are automatically a member).

  2. Point to the Registry tab on the portal main menu, and then click Manage Pending Requests to open the portal Manage Pending Requests Page.

  3. Click the View Request History link.


Analyzing Fault Trends Using Charts and Reports

This section describes the charts and reports that the ESB Management Portal generates. These charts and reports provide valuable detail and trend information for faults, alerts, and message resubmission. You can view the following:

  • Faults by Application or Service

  • Alerts by Application or Service

  • Fault Error Types by Application or Service

  • Faults over Time by Application or Service

  • Resubmissions over Time by Application or Service

  • Subscriptions over Time by Application or Service

For more information about the reporting features of the ESB Management Portal, see the Portal Reports Page. Figure 1 shows the default view of the Reports page.

Portal Reports Page

Figure 1

The Reports page of the ESB Management Portal


Faults by Application or Service

This option displays an aggregate view of all the faults generated for a specified set of applications over a specified time. Selecting a specific service displays a report that lists the faults for that specific service. You can export the list of faults as a Microsoft Excel spreadsheet.

To view charts and lists of faults by application or service

  1. Open the Portal Reports Page.

  2. Click the Select Applications link above the first chart, and then select or clear the check boxes in the list of installed Microsoft BizTalk Server applications that appears. You can also use the links that appear to select all or none of the applications. Then click Save to show the information for the selected applications, or click Cancel to abandon your changes.

  3. To change the period for which the charts display information, select Hour, Day, Week, Month, Quarter, Year, or ALL in the drop-down list above the first chart.

  4. Select an application; the chart changes to show faults for each of the services within that application.

  5. Click Export To Excel to download the list of faults in a format that you can view in Microsoft Excel.


Alerts by Application or Service

This option displays an aggregate view of all the alerts generated for a specified set of applications over a specified time. Selecting a specific service displays a report that lists the alerts for that specific service. You can export the list of alerts as a Microsoft Excel spreadsheet.

To view charts and lists of alerts by application or service

  1. Open the Portal Reports Page.

  2. Click the Select Applications link above the first chart, and then select or clear the check boxes in the list of installed Microsoft BizTalk Server applications that appears. You can also use the links that appear to select all or none of the applications. Click Save to show the information for the selected applications, or click Cancel to abandon your changes.

  3. To change the period for which the charts display information, select Hour, Day, Week, Month, Quarter, Year, or ALL in the drop-down list above the first chart.

  4. Select an application; the chart changes to show alerts for each of the services within that application.

  5. Select a service in the chart; the page displays a table that lists the alerts for that service.

  6. Click Export To Excel to download the list of alerts in a format that you can view in Microsoft Excel.


Fault Error Types by Application or Service

This option displays an aggregate view of all faults by specified error type generated for a specified set of applications over a specified time. You can select the specific error type and application to display a report that lists the matching error type faults for that application. You can also export the list of faults as a Microsoft Excel spreadsheet.

To view charts and lists of faults by error type, application, and service

  1. Open the Portal Reports Page.

  2. Click the Select Applications link above the first chart, and then select or clear the check boxes in the list of installed Microsoft BizTalk Server applications that appears. You can also use the links that appear to select all or none of the applications. Click Save to show the information for the selected applications, or click Cancel to abandon your changes.

  3. To change the period for which the charts display information, select Hour, Day, Week, Month, Quarter, Year, or ALL in the drop-down list above the first chart.

  4. Each segment in the pie chart relates to a specific error type. Click one of the segments in the chart to display another pie chart showing a breakdown of that error type by application.

  5. Click Export To Excel to download the list of faults in a format that you can view in Microsoft Excel.


Faults over Time by Application or Service

This option displays a count of faults over a specified period for a specified set of applications. You can select an application to display a trend chart that shows the number of faults over time for specific services within the application. Selecting a specific service displays a report that lists the faults for that service. You can also export the list of faults as a Microsoft Excel spreadsheet.

To view charts and lists of faults over time by application or service

  1. Open the Portal Reports Page.

  2. Click the Select Applications link above the first chart, and then select or clear the check boxes in the list of installed Microsoft BizTalk Server applications that appears. You can also use the links that appear to select all or none of the applications. Click Save to show the information for the selected applications, or click Cancel to abandon your changes.

  3. To change the period for which the charts display information, select Hour, Day, Week, Month, Quarter, Year, or ALL in the drop-down list above the first chart.

  4. Click the name of an application in the chart keys section to display a trend chart for faults for each of the services within that application.

  5. Click the name of a service in this chart to display a table listing all the faults for the selected service.

  6. Click Export To Excel to download the list of faults in a format that you can view in Microsoft Excel.


Resubmissions over Time by Application or Service

This option displays a count of failed message resubmissions over a specified period for a specified set of applications. You can select an application to display a trend chart showing the number of resubmissions over time for specific services within the application. Selecting a specific service displays a report that lists the resubmissions for that service. You can also export the list of resubmissions as a Microsoft Excel spreadsheet.

To view charts and lists of resubmissions over time by application or service

  1. Open the Portal Reports Page.

  2. Click the Select Applications link above the first chart, and then select or clear the check boxes in the list of installed Microsoft BizTalk Server applications that appears. You can also use the links that appear to select all or none of the applications. Click Save to show the information for the selected applications, or click Cancel to abandon your changes.

  3. To change the period for which the charts display information, select Hour, Day, Week, Month, Quarter, Year, or ALL in the drop-down list above the first chart.

  4. Click the name of an application in the chart keys section to display a trend chart for resubmissions for each of the services within that application.

  5. Click the name of a service in this chart to display a table listing all the resubmissions for the selected service.

  6. Click Export To Excel to download the list of resubmissions in a format that you can view in Microsoft Excel.


Subscriptions over Time by Application or Service

This option displays a count of alert subscriptions over a specified period for a specified set of applications. You can select an application to display a trend chart showing the number of subscriptions over time for specific services within the application. Selecting a specific service displays a report that lists the subscriptions for that service. You can also export the list of subscriptions as a Microsoft Excel spreadsheet.

To view charts and lists of subscriptions over time by application or service

  1. Open the Portal Reports Page.

  2. Click the Select Applications link above the first chart, and then select or clear the check boxes in the list of installed Microsoft BizTalk Server applications that appears. You can also use the links that appear to select all or none of the applications. Click Save to show the information for the selected applications, or click Cancel to abandon your changes.

  3. To change the period for which the charts display information, select Hour, Day, Week, Month, Quarter, Year, or ALL in the drop-down list above the first chart.

  4. Click the name of an application in the chart keys section to display a trend chart for subscriptions for each of the services within that application.

  5. Click the name of a service in this chart to display a table listing all the subscriptions for the selected service.

  6. Click Export To Excel to download the list of subscriptions in a format that you can view in Microsoft Excel.


Viewing and Publishing UDDI Registrations

The ESB Management Portal integrates with a Universal Description, Discovery, and Integration (UDDI) registry and can publish entries into the server in addition to displaying existing registration entries. The portal supports both an auto-publish capability and an approval process that allows administrators to control the publication of entries to the UDDI server. This section describes the following common tasks:

  • Publishing BizTalk Endpoints

  • The Auto-Enlist and Approval Process

  • Publishing from the BizTalk Server Administration Console


Publishing BizTalk Endpoints

You can use the ESB Management Portal to create and publish entries into the currently configured Universal Description, Discovery, and Integration (UDDI) server.

To publish a Microsoft BizTalk Server endpoint into the current UDDI server

  1. Point to the Registry tab on the portal main menu, and then click New Registry Entry to open the New Registry Entry Page.

  2. Use the drop-down lists on the page to filter on the endpoint type, the status, and the application where the endpoint resides.

  3. Click the arrow icon next to the endpoint you want to publish to create a UDDI registration request.

  4. If an administrator has enabled auto-publishing of endpoints, the portal automatically publishes the new entry into the UDDI server.

  5. If an administrator has not enabled auto-publishing of endpoints, the requests remains in the queue until an administrator approves or declines the request.


The Auto-Enlist and Approval Process

You can configure the ESB Management Portal to publish Microsoft BizTalk Server endpoints in two ways:

  • It can be configured through the approval process, where an administrator must confirm and approve the registration request.

  • It can be configured by using auto-publish, where the portal automatically publishes the request into the Universal Description, Discovery, and Integration (UDDI) registry without requiring administrator intervention.

You can also specify several other settings of the UDDI Integration features of the portal, as described in the following two procedures.

To configure auto-approval and publishing in the ESB Management Portal

  1. Make sure that you log on to the portal using an account that is a member of the BizTalk Server Administrators group.

  2. Point to the Admin tab on the portal main menu, and then click Registry Settings to open the portal Registry Settings Page.

  3. To enable auto-approval and publishing, type the URL of your UDDI server in the text box at the top of the UDDI Details section of the page, and then select the AutoPublish check box.

  4. To disable auto-approval and publishing, clear the Auto Publish check box.

To configure e-mail and registry settings for the UDDI Integration features

  1. Make sure that you log on to the portal using an account that is a member of the BizTalk Server Administrators account group.

  2. Point to the Admin tab on the portal main menu, and then click Registry Settings to open the portal Registry Settings Page.

  3. Edit the URL of your UDDI server in the text box at the top of the UDDI Details section of the page. The default UDDI service is the local Microsoft UDDI service.

  4. Select the Anonymous check box if you want the portal to use anonymous authentication when accessing the UDDI server.

  5. If you want the portal to notify you by e-mail when a UDDI publishing request is awaiting approval, select the Notification Enabled check box in the Email Notification section of the page. Then enter the details of your e-mail server, the address for delivery of e-mail messages, an appropriate "from" e-mail address, the message subject, and the message body.

  6. Enter the administrator contact name and e-mail address for the receipt of UDDI request e-mail messages in the Default Settings section of the page.

To approve or decline a registration request as an administrator

  1. Make sure that you log into the portal using an account that is a member of the BizTalk Server Administrators group.

  2. Point to the Registry tab on the portal main menu, and then click Manage Pending Requests to open the portal Manage Pending Requests Page.

  3. To approve a pending request, click the Approve icon (the check mark) next to that request in the list.

  4. To reject a pending request, click the Reject icon (the cross mark) next to that request in the list.

  5. To view details of a pending request, click the View Details icon (the magnifying glass) to open the Registry Details Page. You can publish, delete, or update the request in this page.

  6. To review the requests status and see a list of previous requests, click the View Request History link.


Publishing from the BizTalk Server Administration Console

If you want to manage endpoint publishing through the BizTalk Server 2013 R2 Administration Console instead of the ESB Management Portal, you can do so by entering a Universal Description, Discovery, and Integration (UDDI) moniker in the description field of the endpoints to publish to UDDI. The following is an example moniker.

Copy Code
uddi://TransportType=other;Status=Published.

You can set the following UDDI properties using the Description field in the BizTalk Server 2013 R2 Administration Console:

  • ModifiedBy. This optional property contains the account name of the user that modified the endpoint; for example, MyDomainName\MyUserName.

  • UDDIContact. This optional property is the contact name of the user defined for the UDDI Business Provider.

  • UDDIUserType. This optional property is the user type of the user defined for the UDDI Business Provider.

  • UDDIEmail. This optional property is the e-mail address of the user defined for the UDDI Business Provider.

  • TransportType. This optional property is the endpoint adapter type, such as FILE, MQS, WCF-WsHttp, SOAP, HTTP, or FTP.

  • Status. This optional property is the status of the endpoint, such as Published or Pending. The UDDI Publishing Service uses this attribute to discover the status of the endpoint.

  • BindingType. This optional property is the specific protocol (URL Type) that the UDDI binding supports, such as mailto, http, https, ftp, fax, phone, or other. The UDDI Publishing Service uses this attribute to create the endpoint binding.


ESB Management Portal Feature Reference

The ESB Management Portal provides views of fault information that make it easy to monitor, manage, and debug ESB applications. It also provides features that you can use to manage alerts, publish UDDI information, and administer the portal. To open the portal, go to http://localhost/ESB.Portal/.

The following views are available in the portal:

  • Portal Home Page. This page displays the overall application state, a summary of faults, recent requests for UDDI registration, and charts that show a breakdown of faults by type and by application.

  • Portal Faults Page. This page displays a truncated list of properties for each fault; it supports analysis of faults by a range of criteria.

  • Portal Fault Message Viewer. This page is accessible only though the Portal Faults page. It displays details of individual fault messages and allows you to repair and resubmit messages.

  • Portal Alerts Page. This page allows users to create and modify alerts and to configure alert email settings. The portal can send an alert email message when a specific type of fault, or any fault, occurs.

  • Portal Reports Page. This page displays charts indicating the fault, alert, and message resubmission activity from an application perspective and supports analysis of the health of the individual services within applications.

  • Portal Registry Pages. This page allows users to publish service endpoints (such as Microsoft BizTalk Server receive locations) to the UDDI service. The UDDI service acts as a central registry of service endpoints within an organization.

  • Portal Admin Pages. This page allows administrators to configure portal settings, view an audit log of edited and resubmitted messages, and manage alerts for users and groups.

  • Portal My Settings Page. This page allows users to select the default application and time-period filters for the portal.


Portal Home Page

Figure 1 shows the Home page, which contains four sections:

  • The Charts section contains a breakdown of faults by application, by type, and an analysis over time, indicating the overall health of the entire enterprise from an application perspective.

  • The Registry section contains a list of recent requests for service-endpoint publication sent to the Universal Description, Discovery, and Integration (UDDI) service.

  • The Alert History section displays a list of alerts received by the Alerts service.

  • The Faults section displays an abbreviated list of the most recent faults generated by the ESB Failed Orchestration Exception Routing mechanism and the BizTalk Failed Message Routing mechanism. The list shows faults grouped by application and displays the severity, service name, error type, and the date and time for each fault in the list.

Portal Home Page

Figure 1

The Home page of the ESB Management Portal

The following list explains how you can use the features of the ESB Management Portal Home page.

  • When you first load the Home page, you may not see any applications in the first chart. To select the applications for which you want to view information, click the Select Applications link above the first chart, and then select or clear the check boxes in the list of installed BizTalk applications that appears. You can also use the links that appear to select all or none of the applications. Click Save to show the information for the selected applications, or click Cancel to abandon your changes. You can change the default list of applications on the Portal My Settings Page.

  • To change the period for which the portal displays information, change the setting in the drop-down list above the first chart. You can chose to display information for the previous Hour, Day, Week, or Month. You can change the default period on the Portal My Settings Page.

  • To turn on or turn off auto-publishing of UDDI entries, click the Change link at the top of the Registry section of the page. This opens the Registry Settings Page, where you specify the following:

    • Details of the UDDI server the portal will use, including the URI of the server, whether auto-publishing is enabled, and whether anonymous access is enabled

    • Whether or not e-mail notification of UDDI publications are enabled, and the settings to use for the e-mail server, e-mail addresses, message subject, and message body.

    • Your contact name and e-mail address for published entries.

  • To view a list of pending UDDI registry requests, click the link at the top of the Registry section of the page that shows the number of pending requests. This opens the Manage Pending Requests Page, which contains the following:

    • A list of pending registration requests. For each one, you can click the icons to the right of that request to view the details, approve the request, or reject the request. When viewing the request, you see the details of the registry, the details of the registry service (which you can edit), and contact details.

    • A link to display a history of requests as a list. This list shows a range of values from each registration request.

  • To change the sort order of the faults listed in the Faults section of the page, click either the Date or the Severity option button located above the list of faults.

  • The portal displays faults in the Faults section of the page grouped by BizTalk application. To see the faults for only a specific application, click the link that is the name of the application above the relevant group of faults.

  • To view details of a specific fault, click anywhere in the row containing that fault in the Faults section of the page. This opens the Portal Fault Message Viewer for the selected fault.


Portal Faults Page

Figure 1 shows the Faults page. This page displays the main properties of each fault, and it provides sorting and filtering capabilities that support detailed analysis of faults over a range of criteria, such as error type and time. A link for each fault allows you to view more details in the Fault Message Viewer.

Figure 1

The Faults page of the ESB Management Portal

The following list explains how you can use the features of the ESB Management Portal Faults page:

  • To filter the list of faults displayed in the page, use the drop-down lists and text boxes above the list of faults. You can filter the rows displayed in the following ways:

    • Select any one of the installed BizTalk applications in the Application drop-down list.

    • Specify the period within which the fault occurred by selecting hour, day, week, month, quarter, year, or all in the Retrieve records within last drop-down list.

    • Specify how many rows you want to display on the page in the Records Per Page drop-down list.

    • Type a fault code number in the Fault Code text box.

    • Type all or part of the fault category name in the Fault Category text box.

    • Type all or part of the error type text in the Error Type text box.

    • Type a value for the minimum and/or maximum fault severity (such as Warning, Error, Severe, or Critical) in the Min Fault Severity and Max Fault Severity text boxes.

  • After you specify the values for one or more of these controls, click the Apply Filters button to apply all the specified criteria.

  • Click a column heading to display the fault message rows in the order of that column contents, and then click again to display the list in reverse order.

  • To display more details of a fault shown in the list, or to edit and resubmit the message it contains, click anywhere in the row for that fault to open it in the Portal Fault Message Viewer.


Portal Fault Message Viewer

The ESB Fault Message Viewer renders all messages produced by the Custom Exception Encoder Pipeline component within the ESB Management Portal. The following views are available:

  • Fault Details View

  • Message Details View


Fault Details View

Figure 1 shows Fault Details view, which displays the ambient properties of the fault and the underlying exception. At the bottom of this page is a list of messages associated with this fault. Click the identifier of one of these messages to open it in Message Details View, or click the Download icon at the end of the row to download the message as an XML document.

Fault Details View

Figure 1

The ESB Fault Message Viewer showing the Fault Details view


Message Details View

Figure 1 shows the Message Details view, which displays the ambient properties of the message you selected in the Fault Details view, the message content, and the values of the context properties of the persisted message. Click the Download icon above the message data to download it as an XML document. Click the Edit icon below the message data to edit and resubmit the message.

Message Details View

Figure 1

The ESB Fault Message Viewer showing the Message Details view


Portal Alerts Page

Figure 1 shows the Alerts page, which contains two sections:

  • The main section displays a link to create a new alert and a list of existing alerts. Each alert has a corresponding link that allows you to subscribe to the alert. You can also click the icons in the Action column to view details of the alert, create a new subscription for the alert, and delete the alert.

  • The My Subscriptions section displays a list of subscriptions you have defined within the portal. You can edit and unsubscribe your existing subscriptions using the links in this list.

Portal Alerts Page

Figure 1

The ESB Management Portal Alerts page

The ESB Alert Service generates alerts based on criteria you specify that match the values in exceptions as they arrive at the ESB Management Portal. You can match and compare a range of fields in an exception to control accurately which alerts will match each possible type of exception. The portal also allows you to create subscriptions that map to the different types of alerts you define. These subscriptions can notify users when the matching alert occurs.

The following list explains how you can use the features of the ESB Management Portal Alerts page:

  • To create a new alert, click the Create Alert link at the top of the page to open the Add Alert page.

  • To view or edit an existing alert, click the magnifying glass icon in the Action column for the alert in the main section of the page. This opens the Alert Viewer Page.

  • To subscribe to an existing alert, click the new subscription icon the Action column next to the alert to open the Add Alert Subscription and Edit Subscription Pages.

  • If you opened this page as an administrator using the options on the Admin tab menu (instead of from the Alerts tab), you can click the cross mark icon the Action column next to any of the alerts in the list to delete the alert and any linked subscriptions.

  • To edit an existing subscription, click the Edit link next to that subscription in the list in the My Subscriptions section of the page to open the Add Alert Subscription and Edit Subscription Pages.

  • To remove an existing subscription, click the Unsubscribe link next to that subscription in the list in the My Subscriptions section of the page.

  • To export the entire list of alerts to Microsoft Excel, click Export to Excel.


Add Alert Page

Figure 1 shows the Add Alert page, where you can create a new alert that the portal will raise when a fault message matching the criteria (conditions) specified in the alert arrives at the portal.

Add Alert Page

Figure 1

The ESB Management Portal Add Alert page

On the Add Alert page, you can do the following:

  • Type a name for the new alert in the Enter Alert Name text box.

  • Specify how the alert will match to values of the fields in incoming exceptions in the Add conditions for this alert section of this page. Select a field from the exception schema (such as Application, Error Type, or Fault Severity) in the Criteria drop-down list; select a comparison type for the (such as =, !=, >=, <=, or like) in the Operator drop-down list; and type or select a value from the third list. When you select an exception field, the Value control changes to either a text box or a drop-down list for you to enter or select a matching value.

  • After selecting or entering the criteria values, click the Add link to add this condition to the list in the Conditions section of the page, and repeat to add any more conditions you require for this alert.

  • Click the Save button to create the new alert with the name and conditions you specified.


Alert Viewer Page

The Alert Viewer page, shown in Figure 1, displays all the details of a selected alert, including the conditions that match it to incoming exceptions, and a list of subscriptions defined for this alert.

Alert Viewer Page

Figure 1

The ESB Management Portal Alert Viewer page

On the Alert Viewer page, you can do the following:

  • Use the Edit link next to a subscription to edit or delete that subscription. Clicking the Edit link opens the Add Alert Subscription and Edit Subscription Pages (described next).

  • Click the Add Subscriptions link under the list of existing subscriptions to create a new subscription for this alert. This opens the Add Alert Subscription and Edit Subscription Pages (described next).

  • Click the link at the bottom of the page to return to the list of alerts and subscriptions.


Add Alert Subscription and Edit Subscription Pages

The Add Alert Subscription and Edit Subscription pages are similar. They differ in that the Edit Subscription page shows the subscriber ID (the Microsoft Windows account of the current portal user), and has a different set of buttons. Figure 1 shows the Add Alert Subscription and Edit Subscription pages.

Add Alert Edit Subscription

Figure 1

The ESB Management Portal Add Alert Subscription and Edit Subscription pages

The Add Alert Subscription and Edit Subscription pages allow you to specify and modify the following:

  • A custom e-mail address to use for the subscription (instead of your Microsoft Windows account e-mail address)

  • The time period when you will accept alert notifications

  • A "black-out" period for events such as vacations

  • The interval over which the portal will not send duplicate alerts

You can do the following on the Add Alert Subscription and Edit Subscription pages:

  • Select the check box next to the Custom Email text box if you want to use an e-mail address for the subscription that is different to your standard Windows account e-mail address, and then type the preferred e-mail address in the text box.

  • Select the check box at the top of the Schedule section if you want to specify a period when the portal should send alerts to you, and then specify the start and end times for the period in the Start Time and End Time drop-down lists. Alerts occurring outside this period are queued and delivered during the specified period.

  • Type the start date and end date for a Black-out Period if there is a period when you will be unable to receive and act on alerts. Use the format mm/dd/yyyy for the two dates.

  • Select an Interval in Minutes during which the portal will compare alerts raised and send only one when multiple instances of the same alert occur. This prevents a rapidly occurring fault from creating a large number of identical alert messages.

  • Click the Save button to create or update the subscription.

  • Click the Delete button (available only on the Edit Subscription page) to delete the selected subscription.

  • Click the Cancel button to go back to the Alert Viewer Page without creating or modifying the subscription.


Portal Reports Page

The Portal Reports page, shown in Figure 1, displays the following charts:

  • Fault Count By Application. This option displays an aggregate view of all the faults generated for a specified set of applications over a specified time.

  • Fault Count By Error Type. This option displays an aggregate view of all faults by specified error type generated for a specified set of applications over a specified time.

  • Fault Count Over Time. This option displays a count of faults over a specified period for a specified set of applications. You can select an application to display a trend chart showing the number of faults over time for specific services within the application.

  • Alert Count By Application. This option displays an aggregate view of all the alerts generated for a specified set of applications over a specified time.

  • Resubmissions Over Time. This option displays a count of failed message resubmissions over a specified period for a specified set of applications.

  • Alert Subscriptions Over Time. This option displays a count of alert subscriptions over a specified period for a specified set of applications.

Portal Reports Page

Figure 1

The ESB Management Portal Reports page

The following list explains how you can use the features of the ESB Management Portal New Registry Entry page:

  • Click the SelectApplications link above the first chart, and then select or clear the check boxes in the list of installed Microsoft BizTalk Server applications that appears. You can also use the links that appear to select all or none of the applications. Click Save to show the information for the selected applications, or click Cancel to abandon your changes.

  • Use the drop-down list above the first chart to select the interval over which you want the charts to show data. You can choose to include data for the previous Hour, Day, Week, Month, Quarter, Year, or ALL.

  • Click one of the charts in the page to show a breakdown of the data by service within the application. Depending on the chart you select, this shows a count or trend line for the individual faults, alerts, error types, resubmissions, or alert subscriptions for each service.

  • Click the name of a service in this chart to display a table listing all the faults, alerts, error types, resubmissions, or alert subscriptions for the selected service.

  • Click Export To Excel to download the list of subscriptions in a format that you can view in Microsoft Excel.


Portal Registry Pages

When you move the mouse over the Registry tab, a pop-up menu provides a list of the following portal registry tasks:

  • New Registry Entry Page. This menu item opens a page where you can view a list of the existing endpoints in a specified Microsoft BizTalk Server ESB application. A link in the row for each available endpoint opens the Registry Details Page where you can edit registry details or create a new Universal Description, Discovery, and Integration (UDDI) publishing request for the currently configured UDDI server.

  • Manage Pending Requests Page. This menu item opens a page that lists all pending UDDI registry registration requests and allows you to manage these requests. You can also view a history of previous requests and their status.


New Registry Entry Page

Figure 1 shows the ESB Management Portal New Registry Entry page where you can view a list of the existing endpoints in a specified Microsoft BizTalk Server ESB application.

New Registry Entry Page

Figure 1

The ESB Management Portal New Registry Entry page

The following list explains how you can use the features of the ESB Management Portal New Registry Entry page:

  • Use the three drop-down lists near the top of the page to specify the type, status, and BizTalk application that contains the endpoints you want to view:

    • In the first (endpoint type) drop-down list, you can select Receive Locations, Send Ports, or All Endpoints.

    • In the second (status) drop-down list, you can select Registered, NotRegistered, Pending, or All.

    • In the third (BizTalk application) drop-down list, you can select one of the currently installed BizTalk applications.

  • After specifying the application and endpoint criteria, click the arrow icon next to the BizTalk application drop-down list to display a list of matching endpoints.

  • The list of endpoints contains details of matching endpoints. For each one that is not a dynamic endpoint, the list contains a link that allows you to view and edit the details of a pending request to publish this endpoint.

  • Click the View Detail link in any row of the list to open the Registry Details Page where you can modify the request and publish the endpoint.


Manage Pending Requests Page

Figure 1 shows the Manage Pending Requests page, which shows a list of pending registration requests and provides a link to view the request history.

Manage Pending Requests Page

Figure 1

The ESB Management Portal Manage Pending Requests page

The following list explains how you can use the features of the ESB Management Portal Manage Pending Requests page:

  • Click the ViewDetails icon (the magnifying glass) to open the Registry Details Page, where you can view details of the pending request, publish it, update it, or delete it.

  • Click the Approve icon (the check mark) to approve the pending request.

  • Click the Reject icon (the cross mark) to reject the pending request.

  • Click the View Request History link to open a page that displays a range of information for previous Universal Description, Discovery, and Integration (UDDI) registration requests.


Registry Details Page

Figure 1 shows the Registry Details page, where you can publish an existing Universal Description, Discovery, and Integration (UDDI) registry request, create a new request, or edit an existing request.

Registry Details Page

Figure 1

The ESB Management Portal Registry Details page

The following list explains how you can use the features of the ESB Management Portal Registry Details page:

  • The Registry Details section at the top of the page shows registry information. To change this information, you can use the Registry Settings Page available on the main Registry tab.

  • The Registry Service section of the page contains drop-down lists and text boxes where you enter details of the service you want to register. These details include the business provider; the service name and description; and information about the category and the endpoint.

  • The Registry Contact section of the page contains text boxes where you enter the request contact details; including the name, e-mail address, and the type of user.

  • If you opened the Registry Details page from the Manage Pending Requests Page, the Registry Details page contains buttons that allow you to publish the pending registration, delete the pending registration, or update it and go back to the previous page.

  • If you opened the Registry Details page from the New Registry Entry Page, the Registry Details page contains buttons that allow you to publish the pending registration or update it and go back to the previous page.


Portal Admin Pages

When you move the mouse over the Admin tab, a pop-up menu provides a list of portal administration tasks. The Admin tab is only visible to users who have administrative permission (members of the Microsoft BizTalk Server Administrators account group). The following options are on the pop-up menu:

  • Manage Audit Log. This menu item opens the Audit Log Page that contains a list of audit events. From this page, you can view the message details associated with the audit event.

  • Fault Settings. This menu item opens the Fault Settings Page where you can specify a range of administrative settings for auditing, the Alert Service queue, and the Alert Email service.

  • Manage Alerts (Administration view). This menu item opens the Portal Alerts Page in Administration view. Administrators can use this page to view and edit all alerts and subscriptions within the system. They can also view and edit subscriptions associated with specific alerts.

  • Registry Settings. This menu item opens the Registry Settings Page where you can specify a range of administrative settings for registry integration, e-mail notifications, and templates.


Audit Log Page

Figure 1 shows the Audit Log page. This page displays a list of audited events.

AuditLog Page View

Figure 1

The Audit Log page of the ESB Management Portal

The following list explains how you can use the features of the ESB Management Portal Audit Log page:

  • Click the message identifier link to view the resubmitted message body. This opens the Audit Log - Message Viewer page (see Figure 2), which displays the user, date, and URL for the resubmitted message, and the resubmitted message contents.

AuditLog Message Viewe rPage

Figure 2

The Audit Log – Message Viewer page of the ESB Management Portal


Fault Settings Page

Figure 1 shows the Fault Settings page. This page displays a range of administrative settings that you can modify.

Fault Settings Page

Figure 1

The ESB Management Portal Fault Settings page

The following list explains how you can use the features of the ESB Management Portal Fault Settings page:

  • To change the audit options, select the check boxes for each event you want to audit. The available events are the saving of modified settings, successful resubmission of a fault after editing, and failure when resubmitting a fault.

  • The portal maintains a queue of the alerts generated by the Portal Alert service. You can modify the settings for this service in the Alert Queue Options section of the page. You can enable or disable the service, specify its interaction with Microsoft Active Directory directory service, and control the queue batch size and polling interval.

  • To change the settings for the Alert Email service, use the controls in the Alert Email Options section of the page. You can enable or disable the service; specify the e-mail server and the "from" address; change the polling interval and batch size; and specify the path to XSLT files that the service uses.

Note
You must enter the values in this page when you install and configure the ESB Portal and the Portal Alert service. For more information, see Installing the ESB Management Portal.


Manage Alerts (Administration View)

Figure 1 shows the Alerts page in administration view, which administrators can use to view a list of all alerts and a summary of their activity. A table displays a row for each alert. Each row shows the alert name, the name of the creator, general statistics for the alert (such as number of alert activations within the last hour, day, or month), a count of subscribers for the alerts with a link to view a list, and an Actions column containing a set of clickable icons to perform actions on the alert.

Manage Alerts Page

Figure 1

The ESB Management Portal Manage Alerts (Administration view) page

The following list explains how you can use the features of the ESB Management Portal Manage Alerts page:

  • Click the Create Alert link at the top of the page to create a new alert.

  • Click the Export To Excel link to export the list of alerts as a Microsoft Excel spreadsheet.

  • Click the + View Subscribers link in a row to show a list of subscribers for the alert. The list expands within the row, and a delete icon appears in the Actions column for each one that allows administrators to remove a subscriber from the alert. At the same time, the link changes to - Hide Subscribers, allowing you to collapse the list of subscribers.

  • Click an icon in the Actions column to perform a task for the alerts in that row. The icons (in the order they appear) and the tasks are the following:

    • View alert details. This icon displays details of the selected alert.

    • View history. This icon displays a table containing all the activations for the selected alert.

    • Add subscriber. This icon allows administrators to add a subscriber to the selected alert.

    • Edit alert. This link allows administrators to edit the alert details.

    • Delete alert. This link deletes the alert and all associated subscriptions.


Registry Settings Page

Figure 1 shows the Registry Settings page, where you can modify the settings the portal uses when it interacts with the Universal Description, Discovery, and Integration (UDDI) service.

Registry Settings Page

Figure 1

The ESB Management Portal Registry Settings page

The following list explains how you can use the features of the ESB Management Portal Registry Settings page:

  • The UDDI Details section at the top of the page contains a text box for the URI or URL of the UDDI server, the default is the local Microsoft UDDI Service. There are two check boxes under this section that allow you to turn on auto-publication of requests for UDDI registrations and specify if access to the UDDI server will be through an anonymous account instead of the current user's Microsoft Windows account.

  • The Email Notification section of the page contains a check box that you select if you want the portal to send you e-mail notifications of registration requests automatically. Under this check box, there is a series of text boxes where you provide details of the e-mail server to use, the "to" and "from" e-mail addresses, the message subject, and the message body.

  • The Default Settings section of the page contains text boxes where you enter the default contact and e-mail address for use in the portal registration process.

  • To update the registry settings after editing the values in the page, click the Update button.

  • To return to the previous page without changing the registry settings, click the Cancel button.


Portal My Settings Page

The ESB Management Portal retains settings for each user. These settings include the list of applications to show in the charts on the Portal Home Page, and the default period for the charts. Figure 1 shows the My Settings page, where you can edit these settings.

Portal MySettings Page

Figure 1

The ESB Management Portal My Settings page

The following list explains how you can use the features of the ESB Management Portal My Settings page:

  • Select the check boxes for each of the currently installed Microsoft BizTalk Server applications for which you want to include fault data in the charts in the portal Home page. The portal uses this list as the default when you open the Home page, but you can change it using a link in the Home page on a per-session basis.

  • Select the default interval over which you want to show data in the charts on the Home page. You can choose to include data for the previous Hour, Day, Week, Month, Quarter, Year, or ALL. The portal uses this value as the default when you open the Home page, but you can change it using a drop-down list in the Home page on a per-session basis.

  • Click the Save button to update your default settings.

  • Click the Cancel button to return to the previous page without updating your settings.


SOA Governance Integration

Enterprise-level applications must support robust and reliable management features to be able to comply with business requirements, government legislation, service level agreements (SLAs), and customer and trading partner expectations. Run-time governance focuses specifically on the challenges of, and requirements for, successfully running service-oriented architecture (SOA)–based systems that meet these requirements. The quality of service delivered by a business system is the predominant factor that defines its success or failure.

Businesses deploying SOA-based systems into production face a number of challenges, including the following:

  • Minimizing the cost of maintenance and upgrades, and allowing incremental updates

  • Allowing rapid change through business process management and composition tools

  • End-to-end security; this includes trust and protection of the privacy of message senders, receivers, and content

  • Identifying, managing, and repairing exceptions as they occur

  • Decoupling of services and consumers

  • Measuring and proving the business value of SOA applications to offset cost concerns

  • Control (governance) of the proliferation of duplicate or otherwise unnecessary services

  • Facilitating the identification of the appropriate services required by potential users to reduce initial development cost

  • Managing the life cycle of services to minimize the cost and risk of ongoing maintenance and change

  • Simplifying the actual usage of appropriate services (decoupling location, transport, policies, standards, and messaging styles)

  • Reporting facilities used to identify who is using which service, where, and why

The ​Microsoft BizTalk ESB Toolkit supports integration with two third-party run-time governance systems:

  • SOA BizTalk Management Point from SOA Software, Inc.

  • AmberPoint BizTalk Nano Agent from AmberPoint, Inc.


SOA BizTalk Management Point

The BizTalk Management Point for BizTalk Server 2013 R2 is a conceptual extension to SOA Software's Web Services Management Point, applied specifically to the BizTalk Server 2013 R2 environment and providing run-time governance for Web service applications.

This section contains the following topics:

  • Overview of the SOA BizTalk Management Point

  • BizTalk Server Integration

  • Monitoring Policies and Usage Information


Overview of the SOA BizTalk Management Point

The BizTalk Management Point natively integrates with SOA Service Manager and Workbench products. Unlike the typical Web Services Management Point, this implementation is associated with services provided by the Microsoft BizTalk Server environment, expressed in terms of BizTalk Server receive locations and send ports. Because of the arbitrary nature of receive locations and send ports (configured against a variety of BizTalk Server adapters), these services are not necessarily associated with Web services, but they can be treated as Web services in terms of the SOA Service Manager and SOA Workbench.

Figure 1 shows the SOA Service Manager Web application displaying the Workbench page for an example application. The left-side tree view allows users to navigate through the applications and services installed within BizTalk Server, and the right-side pane allows users to view application details, operations, access ports, categories, rules, and monitoring information.

Figure 1

The SOA Service Manager showing the monitoring features available on the Workbench page

You can monitor all the operations within an application (all send ports and receive locations), or specific operations; the Workbench shows a list of the messages passing through the selected send ports and receive locations. When you double-click a message in the list, the Workbench displays details of the message, and its context properties (if recording is enabled). Alternatively, you can select a specific service and monitor in real-time messages passing through that service.


BizTalk Server Integration

The SOA Service Manager provides wizards that help you set up the SOA Service Manager for use with Microsoft BizTalk Server. For example, Figure 1 shows the wizard that helps you install and configure the BizTalk Integration Point that links BizTalk Server send ports and receive locations to the SOA Service Manager.

SOA BizTalk Integration Point

Figure 1

The SOA BizTalk Integration Point installation and configuration wizard

After installation, the SOA Service Manager can display details of the send ports and receive locations configured by the wizard. Figure 2 shows the Operations page displaying the name, interface, policy, and the number of virtual operations for three receive locations and a send port.

Figure 2

A list of BizTalk Server send ports and receive locations displayed by the SOA Service Manager


Monitoring Policies and Usage Information

The SOA Service Manager provides a mechanism that allows you to create and edit monitoring policies. For example, Figure 1 shows the screen for applying a policy template and activating monitoring for an application.

Figure 1

The SOA Service Manager showing the monitoring features available on the Workbench page

The SOA Service Manager also provides usage information for applications, services, and individual send ports and receive locations. This information includes charts that display the relative usage of each operation and usage over time, service usage, and response time information. Figure 2 shows some examples.

Figure 2

A selection of the charts that the SOA Service Manager can generate to assist in monitoring server and application behavior and performance

In addition, SOA Service Manager includes features that allow you to view details of individual messages, including the size, response time, operation name, and the associated SOAP messages, as shown in Figure 3.

Soap Message Details

Figure 3

The SOA Service Manager showing details of an individual message

Note
SOA Service Manager and Workbench products are products from SOA Software, Inc. that integrate with BizTalk Server 2013 R2. For more information about SOA Software and their products, and to download the latest installation and operational instructions, see the SOA Software Web site.


AmberPoint BizTalk Nano Agent

AmberPoint SOA Management System (SMS) delivers a comprehensive suite of visualization and analytical tools to address the challenges of run-time governance. The ​Microsoft BizTalk ESB Toolkit and Microsoft BizTalk Server make integrating SOA business applications and services easier, but analysis of the resulting composite applications and orchestrations is more challenging. AmberPoint's BizTalk Server integration through their BizTalk Nano Agent extends existing run-time governance capabilities to include BizTalk Server receive locations and send ports, regardless of their underlying adapter binding.

This section contains the following topics:

  • Service Network Management

  • Service Level Management

  • End-to-End Transaction Tracking

  • BizTalk Server Integration


Service Network Management

Effective run-time governance requires knowledge of the services deployed into the run-time environment. AmberPoint SMS can discover the actual receive locations and send ports deployed within a BizTalk Management Group, as shown in Figure 1.

AmberPoint Container Discovery

Figure 1

The AmberPoint SMS Container Discovery screens

Using information on the deployed services, AmberPoint SMS presents various perspectives of the services that help users to understand the run-time configuration and appreciate their dependencies on other services within the running service network. Figure 2 shows the service profile and dependencies screens.

AmberPoint Service Profile

Figure 2

The AmberPoint SMS service profile and dependencies screens

AmberPoint SMS can publish and forward service discoveries and run-time metadata to existing Universal Description, Discovery, and Integration (UDDI) registries, custom configuration management repositories, and master system management consoles, such as Microsoft Operations Manager 2004 (MOM) and System Center Operations Manager 2007 (SCOM).


Service Level Management

The AmberPoint SMS Service Level Manager provides visibility into specific performance and availability issues within enterprise-level SOA-based systems. It instruments and tracks the metrics for each Microsoft BizTalk Server receive location and send port. This provides real-time health and status indication, in addition to ongoing performance characterization of these components. Figure 1 shows the display of the metrics associated with a receive location.

AmberPoint Receive Location

Figure 1

The metrics associated with a receive location

AmberPoint run-time analytics allow users to set thresholds and send alerts when a system crosses a critical event threshold, including compliance warnings events, compliance violations events, and a subsequent return to compliance. Figure 2 shows the display where users configure service level agreements and view alerts generated for this service level agreement.

Figure 2

The screens to configure a service level agreement and view alerts

You can establish performance targets within the Service Level Manager. The software then tracks individual messages, messages from a specific user, or messages from groups of users, to measure performance against these targets.

You can also configure logging policies that instruct AmberPoint SMS to dynamically collect and inspect message context and data passing through BizTalk Server, as shown in Figure 3. You can then use these logs for "on-the-fly" troubleshooting, for technical analysis of problems, and for archiving to comply with industry-specific regulations.

BizTalk Service Messages

Figure 3

The log file for BizTalk Server service messages


End-to-End Transaction Tracking

Business visibility relates to the ability of operators and users to monitor the flow of traffic through the run-time environment. Enterprises must be able to track the processes and transactions flowing through their systems at each step to ensure that they play their part in contributing to revenue generation. AmberPoint SMS simplifies the measurement and tracking of these messages in Microsoft BizTalk Server. The system allows users to define new units of management that align with end-to-end business process flows, instead of being required to conform to the way developers chose to package and deploy individual service components. Figure 1 shows the screen for defining management units.

BizTalk Defining Transaction

Figure 1

Defining a transaction as a new unit of management

After defining transactions, users can instrument and track messages associated with each transaction using the same tools that provide visibility into a single service. These tools can expose performance metrics, monitor performance against service level agreements, and generate message logs, as shown in Figure 2.

Figure 2

Monitoring the end-to-end performance of a pipeline

A major requirement for successful run-time governance and system monitoring is the detection of important business events, such as exceptions and application errors that may disrupt the logical processing of business transaction flows. AmberPoint SMS allows operators and users to gain insight into operational and business events and to monitor the impact these events have on all components that depend on the service that generated the problem. In addition, operators and users can quickly troubleshoot the entire system to identify the root-cause of a problem.


BizTalk Server Integration

AmberPoint packages its Microsoft BizTalk Server integration product as a custom BizTalk pipeline component. You can add this component to your existing custom pipelines using Visual Studio 2013, as shown in Figure 1.

Figure 1

Installing the AmberPoint component into a send pipeline

In addition, AmberPoint ships four predefined pipelines that you can bind directly to existing receive locations and send ports using the BizTalk Administration Console. Figure 2 shows the binding of a receive pipeline to an adapter.

Figure 2

Binding an AmberPoint receive pipeline to an adapter

Note
The AmberPoint SOA Management System (SMS) product is a product from AmberPoint, Inc. that integrates with BizTalk Server 2013 R2. For more information about AmberPoint and their SOA governance products, see the AmberPoint Web site.


Appendices

This section contains the following appendices:

  • Appendix 1 - Additional Resources

  • Appendix 2 - Troubleshooting


Appendix 1 - Additional Resources

You may find the following resources useful when working with the ​Microsoft BizTalk ESB Toolkit:

  • Enterprise Service Bus Guidance in the BizTalk Server Developer Center on MSDN: http://www.microsoft.com/biztalk/en/us/esb-guidance.aspx

  • Getting Started in the BizTalk Server Developer Center on MSDN: http://msdn.microsoft.com/en-us/library/aa560946.aspx

  • Service Oriented Solution in the BizTalk Server Developer Center on MSDN: http://msdn.microsoft.com/en-us/library/aa578486.aspx

  • Using Web Services in the BizTalk Server Developer Center on MSDN: http://msdn.microsoft.com/en-us/library/aa577881.aspx

  • Web Services and Other Distributed Technologies on MSDN: http://msdn.microsoft.com/en-us/webservices/

  • BizTalk Server Developer Center on MSDN: http://msdn.microsoft.com/biztalk/


Appendix 2 - Troubleshooting

This section contains the following troubleshooting tables:

  • Installation

  • General Issues

Installation

Issue Resolution

You receive an "Error assigning permissions" exception during installation.

The ​Microsoft BizTalk ESB Toolkit uses the standard BizTalk account groups, which must exist during the installation process or the installation will fail. In addition, the toolkit assumes either a standalone installation where the computer is a member of a workgroup or an enterprise installation where the computer is a member of a domain.

Application import fails with an error message that warns of trust level mismatch.

The Microsoft.BizTalk.ESB binding files are configured to work with the default BizTalkServerApplication and BizTalkServerIsolatedHost, which are in turn configured to execute in untrusted mode. If you have changed your host to run in trusted mode, the binding file will not import. To correct this, you must either change the trust level to untrusted or edit the binding file to suit your environment in the BizTalk Toolkit \Bindings directory.

Kerberos authentication is not configured in Internet Information Services (IIS).

To enable Kerberos authentication for IIS, see the following articles in the Microsoft Knowledge Base:

  • How to configure IIS to support both the Kerberos protocol and the NTLM protocol for network authentication

  • How to enable IIS to use Kerberos authentication on a computer that is not a domain controller

  • You cannot configure the Negotiate or NTLM protocols for Windows Integrated Authentication in the IIS Manager for Internet Information Services (IIS) 7.0

General Issues

Issue | Resolution
You receive an "Internal SOAP Processing" exception when sending a message to the generic ESB Itinerary On-Ramp Web service. | Use the BizTalk Server Administration Console to ensure that the Microsoft.Practices.ESB application is running; if it is not running, start it.
Exception messages are not appearing in the ESB Management Portal site. | Check the BizTalk Administrator Group Overview page and the Windows Application Event Log for entries that indicate failures to send messages. You may need to reconfigure the exception Send Adapter (part of the Microsoft.Practices.ESB application) to match your environment. In addition, be aware that both the BizTalk Failed Message Routing feature and the BizTalk ESB Toolkit Exception Management Framework generate exceptions messages. Therefore, ensure that you enable the Route on Failed Messages option for send and receive ports.
When consuming a WCF service with a static resolver, you receive an invalid SOAP action exception. | If the WCF service SOAP action does not include the target namespace, set the value of the SOAP action in the following format in the resolver setting: {action} to indicate that the target namespace will not be concatenated by the ESB Toolkit core engine at runtime.


Copyright

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2014 Microsoft Corporation. All rights reserved.

Microsoft, Active Directory, BizTalk, IntelliSense, JScript, MSDN, Visual Basic, Visual C#, Visual C++, Visual Studio, Win32, Windows, Windows Server, Windows Server System, and Windows Vista are trademarks of the Microsoft group of companies.

All other trademarks are property of their respective owners.