Troubleshooting Maps

This topic provides troubleshooting strategies and problem detail and resolution information for maps.

Troubleshooting Strategies

Validate your map

This may sound obvious, but you should always validate your map at different points throughout its development. This will help identify design, logic, and schema problems early in the development cycle when it is easier to fix them or find an alternative solution.

To validate a BizTalk map
  1. In Solution Explorer, open the map that you want to validate.

  2. In Solution Explorer, right-click the map, and then click Validate Map.

  3. In the Output window, verify the results.


When you validate a map, your test instance data is not checked to see if it violates any data types defined in the schemas. You can check the instance data when you test the map or validate the instance data in BizTalk Editor.

Review the XSLT generated for your map

It is often useful to inspect the XSLT generated by the map compiler. Some of the benefits of inspecting XSLT include:

  • If you are using looping or custom functoids, you will better understand how the looping is performed and how the custom functoid is invoked.

  • If you have a complicated map, reviewing the XSLT will enable you to see how the map is translated into a transform and may give you insight about how to better structure, replace, or streamline one or more parts.

  • If you are using custom scripts or other artifacts, reviewing the XSLT will enable you to see how the scripts, artifacts, and other parts of the map interact.

    Fortunately, viewing the XSLT for a map is an easy process.

To view the XSLT generated by the map compiler
  1. From a Visual Studio BizTalk project, click the Solution Explorer tab, right-click a map, and then click Validate Map.

  2. Scroll the Output window to find the URL for the XSL file. Press CTRL and click the URL to view the file.

    If you decide to customize your map by hand, you can modify the version produced by the map compiler. Changes will not be reflected by the Mapper and will be lost the next time you build your solution.

Tune your map for specific scenarios using <mapsource>

You can modify some default behaviors of the Mapper by modifying attributes of the mapsource element directly in a map source (.btm) file. There are currently three behaviors that you can modify:

  • Optimize Value Mapping functoid code generation. You can modify the behavior that controls when a variable is used with if statements.

  • Accommodate schemas with large footprints. You can change the way internal compiler nodes are used in large maps.

  • Manage for-each usage with Looping, Conditional, and Value Mapping functoids. You can control where the xsl:for-each statement is used within the destination schema.

    For more information about modifying mapsource, see Managing Default Mapper Behavior Using <mapsource>.

See Also

General Troubleshooting Questions and Answers
Common Errors