Export (0) Print
Expand All

Extending Mapper (BizTalk Server Sample)

The Extending Mapper sample demonstrates how to use and extend BizTalk Mapper. The sample includes several BizTalk Server map files (.btm), each of which illustrates different features of BizTalk Mapper.

The Extending Mapper sample uses content-based routing (CBR) and does not use an orchestration. By specifying a filter on the sample send port, it is connected directly to the sample receive port. A map is specified on the send port to be applied to the processed document.

To download the updated BizTalk Server 2004 SDK, go to http://go.microsoft.com/fwlink/?LinkId=24723.

Location in SDK

<Samples Path>\XmlTools\ExtendingMapper

File Inventory

The following table shows the files in this sample and describes their purpose.

File(s)Description
MapperClassLibrary\AssemblyInfo.cs, MapperClassLibrary\MapperClassLibrary.csproj, MapperClassLibrary\MapperHelper.csMicrosoft® Visual Studio® project file and Visual C#® source files.
Cleanup.batUsed to undeploy assemblies and remove them from the global assembly cache (GAC).
Destination.xsdSchema file.
ExtendingMapper.btproj, ExtendingMapper.slnBizTalk project and solution files for this sample.
ExtendingMapper.xmlSource XML.
ExtendingMapperBinding.xmlBinding XML.
ExternalAssembly.xmlExternal assembly XML.
OverridingMapXslt.btmMap file.
OverridingMapXslt.xmlOverriding Map XML.
OverridingMapXslt.xsltOverriding Map style sheet.
Scriptor_CallExternalAssembly.btmSample map file.
Scriptor_GlobalVariableInInlineScript.btmSample map file.
Scriptor_InlineScripts.btmSample map file.
Scriptor_InlineXslt.btmSample map file.
Scriptor_InlineXsltCallingExternalAssembly.btmSample map file.
Scriptor_XsltCalltemplate.btmSample map file.
Setup.batUsed to build and initialize the sample.
Source.xsdSchema file.

To Build and Initialize This Sample

Use the following procedure to build and initialize the Extending Mapper sample.

  1. In a command window, change directory (cd) to the following folder:

    <Samples Path>\XmlTools\ExtendingMapper

  2. Run the file Setup.bat, which performs the following actions:
    • Creates the input (\In) and output (\Out) folders for this sample.
    • Compiles and deploys the Microsoft Visual Studio .NET project for this sample.
    • Creates and binds the BizTalk Server receive location, and the send and receive ports.

    If you want to use the Scriptor_CallExternalAssembly.btm map, open ExtendingMapper.sln in Visual Studio and make the following modifications (otherwise go to step 3):

    1. In Solution Explorer, open Scriptor_CallExternalAssembly.btm.
    2. On the mapper grid, select the Scripting functoid.
    3. In the property grid, select the Script property, and click the ellipsis (...) button to configure the functoid script.
    4. In the Configure Functoid Script dialog box, specify the following:
      Set thisTo this
      Script TypeExternal assembly
      Script AssemblyMicrosoft.Samples.BizTalk.ExtendingMapper.MapperClassLibrary
      Script ClassMicrosoft.Samples.BizTalk.ExtendingMapper.MapperHelper
      Script MethodMyConcat
    5. From the Visual Studio File menu, choose Save to save changes to the map file, and close the solution.
  3. Press any key to continue with Setup.bat.

    Important  If you want to use Scriptor_InlineXsltCallingExternalAssembly.btm, you must edit the ExternalAssembly.xml file. ExternalAssembly.xml is used by the BizTalk run time to map a mapper extension object registered namespace to a .NET assembly. Because the dependent assembly is referenced by its fully qualified name (including its public key token, which is automatically generated), you must update this value. If you do not want to use Scriptor_InlineXsltCallingExternalAssembly.btm, you do not need to complete steps a-f.

    1. In Windows Explorer, navigate to <Windows folder>\assembly\.
    2. Right-click Microsoft.Samples.BizTalk.ExtendingMapper.MapperClassLibrary and select Properties.
    3. Copy the public key token value.
    4. In a text editor, open <Samples Path>\XML Tools\ExtendingMapper\ExternalAssembly.xml.
    5. Select the AssemblyName="SampleClassLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=68496d20c737d84b" attribute, and replace the PublicKeyToken value with the public key token value you copied in step c.
    6. Save and close ExternalAssembly.xml.

    Note  You should confirm that no errors were reported during the build and initialization process before attempting to run this sample.

To configure, enlist, and start the send port

  1. In Visual Studio .NET 2003, in the View menu, click BizTalk Explorer.
  2. Expand the BizTalk Configuration databases collection.
  3. Expand the BizTalkMgmtDb collection.
  4. In BizTalk Explorer, expand the Send Ports collection, right-click ExtendingMapperSP, and then click Edit.
  5. In the Static One-Way Send Port Properties dialog box, expand the Filters & Mapping collection in the left pane, left-click the Outbound Maps node, left-click Map to apply to select one of the maps described in the following table, and then click OK.
    Map to apply PropertyDescription
    Microsoft.Samples.BizTalk.ExtendingMapper. Scriptor_CallExternalAssemblyDemonstrates how to call into a function in an external .NET assembly from a Scripting functoid in a map, based on the input parameters to this functoid. This helps cleanly separate any processing logic from the map file. This map file uses the assembly MapperClassLibrary.dll that ships with this sample.
    Microsoft.Samples.BizTalk.ExtendingMapper. Scriptor_InlineScriptsDemonstrates how to write simple inline scripts inside Scripting functoids in a map file using .NET languages such as C#, Visual Basic.NET, and JScript.NET.
    Microsoft.Samples.BizTalk.ExtendingMapper. Scriptor_GlobalVariableInInlineScriptDemonstrates how to use global variables in the inline scripts of Scripting functoids. Global variables are usually used to maintain state information in a map file across different Scripting functoids.
    Microsoft.Samples.BizTalk.ExtendingMapper. Scriptor_InlineXsltDemonstrates how to construct structure in the destination document using raw inline XSLT inside a Scripting functoid in the map. You can construct some parts of the destination document using Scripting functoids with inline XSLT whenever it is not possible to do that in BizTalk Mapper using other functoids.
    Microsoft.Samples.BizTalk.ExtendingMapper. Scriptor_XsltCalltemplateDemonstrates how to create structure in the destination document using an XSLT Call template inside a Scripting functoid in the map. The advantage of an XSLT Call template over inline XSLT is that the call template can accept parameters, so you can create the structure based on input parameters to the Scripting functoid. You can construct some parts of the destination document using Scripting functoids with inline XSLT whenever it is not possible to do that in BizTalk Mapper using other functoids.
    Microsoft.Samples.BizTalk.ExtendingMapper. Scriptor_InlineXsltCallingExternalAssemblyDemonstrates how to call into an external .NET assembly from inside The inline XSLT of a Scripting functoid in a map. Explains how you can override the Custom Extension XML property of the BizTalk Mapper grid with the custom extension file ExternalAssembly_extxml.xml that contains the details of the external .NET assembly to invoke. You can construct some parts of the destination document using Scripting functoids with inline XSLT whenever it is not possible to do that in the Mapper UI using other functoids.
    Microsoft.Samples.BizTalk.ExtendingMapper. OverridingMapXsltDemonstrates how to completely override the compiled XSLT of the BizTalk Mapper file with a custom XSLT file. You can do this by overriding the Custom XSLT Path property and optionally the Custom Extension XML property of the BizTalk Mapper grid. The custom XSLT file that you provide is included in the compiled BizTalk Server assembly of the project you want to use at run time. In this case, the contents of the map file (.btm) are ignored. This map file uses OverridingMapXslt.xslt and OverridingMapXslt.xml for the Custom XSLT Path and Custom Extension XML properties, respectively.

    You can validate a map file in Solution Explorer. You can then use it as a template file that you can edit and use for the Custom XSLT Path property of the BizTalk Mapper grid. You can resort to this option whenever it is not possible to produce this XSLT using BizTalk Mapper.

To Run This Sample

Use the following procedure to run the Extending Mapper sample.

  1. Copy the input file ExtendingMapper.xml into the input folder at <Samples Path>\XmlTools\ExtendingMapper\In.
  2. Notice how the file is transformed and routed to the <Samples Path>\XmlTools\ExtendingMapper\Out folder. The transformation that occurs is based on the map you applied.

See Also

XML Tools (BizTalk Server Samples Folder)

To download updated BizTalk Server 2004 Help from www.microsoft.com, go to http://go.microsoft.com/fwlink/?linkid=20616.

Copyright © 2004 Microsoft Corporation.
All rights reserved.
Show:
© 2014 Microsoft