Posts Tagged ‘BizTalk Server 2013’

Every time I try to configure the BizTalk Accelerator for RosettaNet in BizTalk Server 2013 or BizTalk Server 2013 R2 of course using Windows Server 2012 or Windows Server 2012 R2 I encounter this error in the configuration logfile

[2015-05-14 16:37:40:0043 Error ConfigHelper] Failed to add member ‘user’ to NT Group IIS_WPG Error code: -2147022676
[2015-05-14 16:37:40:0043 Error ConfigHelper] The group name could not be found

BTARN-The-group-name-could-not-be-found

CAUSE

When, basically this is a bug that has not been fixed yet. BizTalk Accelerator for RosettaNet was introduced in BizTalk Server 2004 and since there only little or no changes were made.

BTARN requires the IIS_WPG group (group provided by IIS 6.0 that provides the minimum set of user rights and permissions required to run an application) but unfortunately for us this group doesn’t exist anymore…

SOLUTION

The solution is very simple… you just need to create it manually.

To accomplish that you need to:

  • Open Computer Management and in the console tree, expand “System Tools à Local Users and Groups” and then right-click Groups and select the option New Group .
  • In Group name
    • Type: IIS_WPG.
  • In Description
    • Type: RosettaNet IIS group
  • And then click Create, and then click Close

I really hope that Microsoft provide a hotfix for this or at least fix this problem in the next releases of the product

BizTalk Health Monitor (BHM) is a BizTalk snap-in that can be added to the existing BizTalk Administration Console or can be run individually, that helps you monitor the health of your BizTalk Server environment. Basically it’s similar to the “old” BizTalk MsgBoxViewer tool that we used monitor a BizTalk environment by gathering all information of a BizTalk group and detecting any issues, non-critical or critical warnings to detect any potential problems in advance.

BHM is now in is third version, released in March 6, 2015 that you can download here and know more about it here.

The goal of this post is not to explain what it is the BizTalk Health Monitor, but instead if you already have a previous version – V1 or V2 – how can you update to the latest one – V3. Do you need to uninstall the previous one?

Note: If you don’t have a previous version of BizTalk Health Monitor installed then check the post to describe the installation steps required.

How to upgrade BizTalk Health Monitor to the latest version

Basically you don’t need to uninstall V2 (or V1) to upgrade to the latest version, you just need to register the snap-in of the new one but there are some consideration that you need to be aware.

  • First, if you have BizTalk Health Monitor integrated with the BizTalk Administration Console you need to close all the BizTalk Administration Console in all sessions, if not you need to close BizTalk Health Monitor in all sessions again, otherwise you cannot replace or delete the existing files.

Error-While-replacing-BHM-filesNote: You shouldn’t replace or create a new BHM folder under “C:\Program Files (x86)\Microsoft BizTalk Server 2013 R2\SDK\Utilities\Support Tools” otherwise you will have issues installing BizTalk cumulative updates (see BizTalk 2013 R2 CU1 install failing with “Package does not contain compatible branch patch”)

  • After closing all consoles, choose a proper location in your drive, for example:
    • “C:\Program Files (x86)\Microsoft BizTalk Server Support Tools\BizTalkHealthMonitor”
  • And unzip the version of the BHM zip file to this folder
    • You could also replace the existing files by the new ones, however I already encountered some issues while registering the new version of the snap-in after doing that
    • Or you can create a new folder with this new resources.

Note: Once you register the BizTalk Health Monitor Snap-In you cannot delete or change the folder path or BHM will stop working.

  • Open a command prompt as an administrator
  • Navigate to the directory folder where you have the BHM resources
    • For example: “C:\Program Files (x86)\Microsoft BizTalk Server Support Tools\BizTalkHealthMonitor”
  • And from the command prompt type:
    • InstallUtil.exe MBVSnapIn.dll
  • And hit enter. This step will register the new version of the Snap-In to be used

Because you already add the BizTalk Health Monitor integrated in the BizTalk Administration Console you don’t need to do nothing more. Just open the BizTalk Administration Console and the last version of the BHM will be available.

BizTalk-Administration-Console-BHM-V3

Notes:

  • If you replace the existing BHM files by the new ones and then try open the BizTalk Administration Console without registering the new BHM version you will receive the following error:
    • “MMC has detected an error in a snap-in and will unload it”

BHM-MMC-detected-error-snap-in-unload-it

  • If you replace the existing BHM files by the new ones and you find some kind of error while trying to register the snap-in then:
    • Delete all files from the directory and then copy again the files to the new BHM version to the folder
    • And register again the BHM span-in

Important Note: If you already replace some files under “C:\Program Files (x86)\Microsoft BizTalk Server 2013 R2\SDK\Utilities\Support Tools\BizTalkHealthMonitor” or created a new BHM folder under “C:\Program Files (x86)\Microsoft BizTalk Server 2013 R2\SDK\Utilities\Support Tools”, you should:

  • Move the BHM folder to a place outside the “C:\Program Files (x86)\Microsoft BizTalk Server 2013 R2\SDK\Utilities\Support Tools” folder, for example to the suggested path described above
  • Register the BHM Snap-In from this directory
  • And delete all the BHM folders under the Utilities folder

otherwise you will have issues installing BizTalk cumulative updates (see BizTalk 2013 R2 CU1 install failing with “Package does not contain compatible branch patch”)

There is a lot of inconsistent and incorrect information about the BizTalk SAP Adapter (or in this case WCF-SAP Adapter) installation process and how it works – It is normal to see comments that the adapter only runs on 32-bit, or to see indications that we have to copy DLLs to two different places (System32 and SysWOW64) but which ones?

I hope with this step-by-step installation guide to clarify a bit and document a little better this task.

So, one of the key question that we need to clarify is: Does the WCF-SAP adapter runs under 64-bit Host Instance?

And the correct response to this question is: Yes, it does! The SAP adapter supports both the 32-bit and the 64-bit versions of the SAP RFC SDK, so it can run under 32 or 64-bit Host Instances.

The second important question that we need to clarify is that: Documentation specifies that we need to add the 32-bit version of the client DLLs for the SAP adapter to C:\Windows\SysWow64 folder and the 64-bit version of the DLLs must be added to C:\Windows\System32 folder, but what this means? Do need to add the same DLL in two different folders?

Indeed, the documentation is correct and we need to add both 32 and 64-bit to different folder in our system… but this are different DLL and no the same ones – so if you only have one SDK resource, for example the SAP RFC SDK 32-bit, you just need to add this into one of the folders, copy for both places doesn’t make any difference because the adapter will only run in this case under a 32-bit Host Instance.

For each SAP Client version (6.4, 7.0 and so on) there are two SAP RFC SDK one for 32-bit and one for 64-bit and you need to download and install both… just like the BizTalk Server Adapter Pack.

There are SAP UNICODE and NON-UNICODE, so witch version of the SAP RFC SDK should I download?

The SAP adapter requires Unicode version of the RFC SDK irrespective of whether the SAP system is Unicode or non-Unicode.

Official documentation states that only the following SAP server versions are supported:

  • SAP 7.2, SAP 7.0, SAP ERP 6.0 with EHP 4.0, SAP ECC 6.0 Unicode

However earlier version, which were mentioned in previous versions of the documentation, are also supported:

  • SAP ECC 5.0 Non-Unicode, SAP ECC 5.0 Unicode, SAP R/3 4.7 Non-Unicode, SAP R/3 4.7 Unicode, SAP R/3 4.6c Non-Unicode, SAP ERP 6.0 with EHP 4.0

Also official documentation states that the only supported client version is the SAP RFC SDK 7.2 UNICODE – I always recommend to use the latest version… however, once again, as previous versions of the documentation mentioned, these client versions are also supported:

  • SAP client 6.4 version: SAP RFC SDK 6.40 UNICODE
  • SAP client 7.0 version: SAP RFC SDK 7.00 UNICODE
  • SAP client 7.1 version: SAP RFC SDK 7.10 UNICODE
  • SAP client 7.11 version: SAP RFC SDK 7.11 UNICODE

I’m not a SAP expert but I think that all depends if the SAP client version is supported in your SAP System version. For example, in one BizTalk Server 2013 R2 environment I have the SAP client 7.2 version installed and in another one, a BizTalk Server 2013, I have the 7.0 and both are working fine.

And finally: Can I install only the 64-bit version?

No, you can’t and for the exact same reason that we need to install both version of the BizTalk Server Adapter Pack: Visual Studio and BizTalk Administration console are 32-bit applications, so in order to configure the adapter in runtime (Receive Locations or Send Ports that will be using the SAP Adapter) or to use it to generate the schemas in the development phase you always need to have installed the 32-bit version of the SAP RFC SDK.

The 64-bit version of the SAP RFC SDK is optional, but, if you have a 64-bit BizTalk environment and you want to run it under 64-bit Host Instance, then you need to also install both versions of the SAP RFC SDK.

Download Prerequisites

As happen with other LOB adapters (like Oracle for example), installing the BizTalk Adapter pack is not enough and you will need the addition resources that will be specify bellow.

Download SAP Resources from SAP Service Marketplace

You need to obtain a few resources from the SAP Service Marketplace in order to properly install WCF-SAP adapter:

  • SAP RFC SDK <version> UNICODE 32-bit
  • SAP RFC SDK <version> UNICODE 64-bit
  • R3DLLINST.zip containing Microsoft run-time DLLs
  • SAPCAR – SAPCAR is a compress utility (similar to WinZip, tar and so on), that is used by SAP to compress and decompress nearly all delivered files

Unfortunately, SAP Service Marketplace is restricted, so if you like to benefit from the content and services offered in the different portals of the SAP Service Marketplace, you need to request your personal User ID otherwise you need to ask your client or your SAP team to give you this resources.

In additional to the links above you may also find useful to give these two SAP notes to your client or SAP team:

Unlike R3DLLINST.zip, that is a unique resource, on the SAP Service Marketplace portal SAP RFC SDK page you will find several resources and we must understand exactly what we need, in this case for example purposes, I’m using the SAP RFC SDK 7.20 page:

SAP-Service-Marketplace-portal-SAP-RFC-SDK-7.20

Depending in the SAP client version you want to install this may change a little, but it is practically the same for the other versions, as you can see in the case of SAP RFC SDK 7.00 page

SAP-Service-Marketplace-portal-SAP-RFC-SDK

What you need to download is the:

  • Windows Server on IA32 32bit” –> this is the SAP RFC SDK 7.00 UNICODE 32-bit
  • And the “Windows on x64bit” –> SAP RFC SDK 7.00 UNICODE 64-bit

You also need to download SAPCAR to extract (unzip) the SAP resources, I think you may found this resource at service.sap.com/patches under:

  • Download, Support Packages and Patches, Entry by Application Group, Additional Components and then SAPCAR

SAP-Service-Marketplace-portal-SAPCAR

Extract SAP Resources

Once we have downloaded all this SAP resources, we need to use the SAPCAR to extract the SAP resources, in this case (SAP RFC SDK 7.20):

  • “RFC_12-10009744.SAR” is the 64-bit SDK that we want to extract to “rfcsdk 64” folder
  • “RFC_12-100097446.SAR” is the 32-bit SDK that we want to extract to “rfcsdk 32” folder

BizTalk-Server-SAP-Software-resources

To accomplished that we need to:

  • Open a command line prompt
  • Change our directory to the location where we saved the “SAPCAR.exe” and execute the following command to extract the the SAR archive:
    • SAPCAR.exe -xfv “RFC_12-10009744.SAR”
      • This will create a folder call “rfcsdk”, rename that to “rfcsdk 64”

Extract-SAR-archive-with-SAPCAR

    • SAPCAR.exe -xfv “RFC_12-10009746.SAR”
      • This will create a folder call “rfcsdk”, rename that to “rfcsdk 32”

The final step regarding to SAP Resource is to unzip the “r3dllinst.zip” file using for example an open source Windows utility for manipulating archives like 7-Zip.

Download Microsoft Visual C++ 2005 SP1 Redistributable Package

Microsoft Visual C++ run-time DLLs, again both 32 and 64-bit are required for SAP 7.11 client or higher. This resources are available from download in the following links:

download-Microsoft-Visual-C  _2005_SP1_Redistributable_Package

download-Microsoft-Visual-C  _2005_SP1_Redistributable_Package-files

Step-by-Step WCF-SAP Adapter installation guide

The first thing you need to make sure that you have installed already is both 32 and 64-bit versions of the Microsoft BizTalk Adapter Pack.

  • The Microsoft BizTalk Adapter Pack contains adapters that enable enterprise applications and databases to interface with each other by implementing a common adapter framework. Similar to programming to Web services, adapters enable clients to program to different enterprise applications. Technically, adapters are a binding to Windows Communication Framework (WCF). The BizTalk Adapter Pack consists of the following adapters:
    • Microsoft BizTalk Adapter for Oracle Database (Oracle Database adapter).
    • Microsoft BizTalk Adapter for Oracle E-Business Suite (Oracle E-Business adapter).
    • Microsoft BizTalk Adapter for mySAP Business Suite (SAP adapter). This also includes the .NET Framework Data Provider for mySAP Business Suite (Data Provider for SAP).
    • Microsoft BizTalk Adapter for Siebel eBusiness Applications (Siebel adapter). This also includes the .NET Framework Data Provider for Siebel eBusiness Applications (Data Provider for Siebel).
    • Microsoft BizTalk Adapter for SQL Server (SQL adapter).
  • Find more about the BizTalk Adapter Pack installation process in the following articles:

Notice that, at this point, if you try to create a receive or send port using the WCF-SAP adapter you will get the following error:

Exception has been thrown by the target of an invocation. (mscorlib)
Could not load file or assembly ‘Microsoft.Adapters.SAP.SAPGInvoker.dll’ or one of its dependencies. The specified module could not be found. (Microsoft.Adapters.SAP)

Could-not-load-file-assembly-Microsoft.Adapters.SAP.SAPGInvoker.dll

This is because we need the SAP resources required to run the adapter are not install (or are i installed incorrectly).

So, now that we have install the Microsoft BizTalk Adapter Pack, we need to install the SAP Resources that we previous download in our BizTalk Server machine:

  • Open the “rfcsdk 64” folder containing the SAP RFC SDK 7.20 UNICODE 64-bit and access to the lib folder
    • “C:\SAP Resources\rfcsdk 64\lib”

SAP-rfcsdk-7.2-64-bit-lib-Resources

  • Install the SAP RFC SDK 64-bit DLLs by coping (or drag) them to the “System32” folder in your system “Windows” folder
    • “C:\Windows\System32”:

SAP-rfcsdk-7.2-64-bit-lib-Resources-Installation

  • And now we need to do the a similar process to the Open the SAP RFC SDK 7.20 UNICODE 32-bit
  • For that you need to open the “rfcsdk 32” folder containing the SAP RFC SDK 7.20 UNICODE 32-bit and access to the lib folder
    • “C:\SAP Resources\rfcsdk 32\lib”

SAP-rfcsdk-7.2-32-bit-lib-Resources

  • Install the SAP RFC SDK 32-bit DLLs by coping (or drag) them to the “SysWOW64” folder in your system “Windows” folder
    • “C:\Windows\SysWOW64”:

SAP-rfcsdk-7.2-32-bit-lib-Resources-Installation

  • Open the “r3dllinst\ ntpatch” folder containing the content of “r3dllinst.zip” file, ,and we need to execute the “R3DLLINS.EXE” tool, in order to install the SAP R/3 DLLs (Microsoft run-time DLLs):
    • msvcr71.dll
    • msvcp71.dll
    • mfc71.dll
    • mfc71u.dll

install-SAP-r3dllinst-R3DLLINS

  • The tool specifies that the DLLs were installed under “C:\Windows\System32” folder, however because I’m using a 64-bit environment instead they were installed in “c:\Windows\SysWOW64” folder

install-SAP-r3dllinst-R3DLLINS-SysWOW64

    • You should check if DLL are present in “C:\Windows\System32”, if they are not I advise you to:
      • Leave them in the ” c:\Windows\SysWOW64” folder
      • And, just to be sure, copy the same four DLLs to “C:\Windows\System32” folder

install-SAP-r3dllinst-R3DLLINS-windows-folder

  • And finally we also need to installed Microsoft Visual C++ 2005 SP1 Redistributable Package – 32-bit and 64-bit – containing the Visual C++ run-time DLLs required for SAP 7.20 (or 7.11) client:
    • Install the Microsoft Visual C++ 2005 SP1 Redistributable Package (x86) – 32-bit – by executing the “Vcredist_x86.exe” file that we previous download
      • On the Microsoft Visual C++ 2005 SP1 Redistributable Package window, click “Yes”

Microsoft-Visual-C  -2005-SP1-Redistributable-Package-x86

    • Do the same steps to install the Microsoft Visual C++ 2005 SP1 Redistributable Package (x64) – 64-bit – by executing the “Vcredist_x64.exe” file that we previous download
      • On the Microsoft Visual C++ 2005 SP1 Redistributable Package window, click “Yes”
Add adapters to BizTalk Administration Console

As it happens with all adapters that we installed on our BizTalk Servers environment, before we can begin to use them we need to register or add the adapters. So in the next step it will be describing how can we add the enterprise adapters, or any other custom adapter, on the BizTalk Administration Console. To accomplish that we need to:

  • Open BizTalk Administration Console by pressing the “Windows key” to switch to the Start screen, type “BizTalk Server Administration” or “BizTalk”, click “BizTalk Server Administration” option from the Search menu
  • In the console left tree, expand “BizTalk Server Administration –> BizTalk Group –> Platform Settings” and then “Adapters”
  • Right-click on “Adapters” and add a new adapter by selecting the option “New –> Adapter”

BizTalk-Administration-Console-Register-WCF-SAP-adapter-add-new

  • In the “Adapter Properties” window
    • In the Name box, type a descriptive name for this adapter.
      • WCF-SAP
    • In the Adapter combo box, select the adapter from the drop-down that you want to add.
      • WCF-SAP
    • In the Description box, type a description for the adapter (this is optional).
      • The WCF-SAP adapter provides a rich metadata layer on top of SAP that enables the consumption of RFCs and enables seamless BAPI and IDOC exchange in an interoperable manner. The SAP adapter exposes the SAP system as a WCF service to client applications.

BizTalk-Administration-Console-Register-WCF-SAP-adapter

    • Click “OK” to complete the process of adding the adapter.
      • We will receive a warning message saying that we need to restart the Host Instances
      • Click “Ok”, we will deal with it in a moment

BizTalk-Administration-Console-Register-WCF-SAP-adapter-warning-message

  • Now we need to create other send and receive adapter handlers for the WCF-SAP Adapter, to accomplished that we need to:
  • Expanded the adapter list, right-click the “WCF-SAP” adapter, point to New, and then:
    • click “Send Handler to create a send handler”
    • Or click “Receive Handler” to create a receive handler.

BizTalk-Administration-Console-Register-WCF-SAP-adapter-add-receive-send-handlers

Notice: that by default the adapter already have one Receive and one Send handler that are associated to the default Host Instance – normally the “BizTalkServerApplication” Host Instance

  • Add two send handler using Dedicated Send Hosts
    • One running under 32-bit: BizTalkServerSend32Host
    • One running under 64-bit: BizTalkServerSendHost
  • Add two receive handler using Dedicated Receive Hosts
    • One running under 32-bit: BizTalkServerSend32Host
    • One running under 64-bit: BizTalkServerSendHost
  • Delete the default handlers that use the “BizTalkServerApplication” Host (in my case it was “BizTalkServerApplication64Host”)

BizTalk-Administration-Console-Register-WCF-SAP-adapter-handler-configuration

Note: Now more about Create and Configure BizTalk Server Host and Host Instances in my TechNet Wiki article: BizTalk Server Best Practices: Create and Configure BizTalk Server Host and Host Instances

  • Finally we just need to restart our BizTalk Server Host Instances, for that you need to:
    • Expand the BizTalk group, click “Platform Settings”, and then click “Host Instances”.
    • In the details pane, right-click the host instance you want to start, and then click “Start”.

BizTalk-Administration-Console-restart-host-instances-final-step

Validate if the WCF-SAP adapter is properly installed

To do a preliminary test you to your WCF-SAP Adapter installation you can create a new receive port:

  • Right-click “Receive Ports”, point to “New”, and click “One-way Receive Port”

SAP-validation-add-new-receive-port

  • Just leave the default name and click on the “Receive Locations” tab and then click “New”.

SAP-validation-add-new-receive-location

  • In the Receive Location Properties dialog box, do the following:
    • From the Type drop-down list, select the “WCF-SAP” adapter you added earlier, and then click “Configure”.

SAP-validation-add-new-receive-port-configure-receive-location

If you were able to access the WCF-SAP Transport Properties window and the URI SAP configuration windows, this is half way thru and a good indication that the adapter is properly configured in your environment

WCF-SAP-Transport Properties-adn-URI-Windows

Of course now you need to actually test it against your SAP environment to see if you actually can receive or send messages from or to SAP System.

In my opinion there are a lack of documentation, or good documentation and many of the existing one is obsolete, regarding some topics/feature of BizTalk Server – Microsoft BizTalk Accelerator for RosettaNet is one of them.

Today while I was trying to extend Microsoft BizTalk 2013 Accelerator for RosettaNet (BTARN) with a new receive Partner Interface Process (PIP) schema I was receiving the following error in the event log:

Source module:
RNDisAssembler

Correlation information:

Description:
Receive pipeline rejected incoming message due to the following RNIF exception:
UNP.SCON.VALERR: A failure occurred while validating the service content.

Details:
The document specification <MyNamespace.MyPIP> from assembly <MyAssemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=…> failed to load. Verify the schema for this document specification is deployed and is in the Global Assembly Cache.

Note: this same error can occur in previous or new versions of BizTalk Server.

Based on the received error and according to a possible cause described by Microsoft at Troubleshooting: Microsoft BizTalk Accelerator for RosettaNet Issues and Resolutions either the document namespace or the root node property the deployed schema for the instance that you are trying to extend is incorrect.

In fact this could be the issue but I found really odd because in the error details my DLL, containing the schema that I was trying to extend, was being properly referenced, nevertheless I confirmed that it was properly deployed… But as I suspected this wasn’t my problem.

Note: this behavior does not happen with PIP that include out-of-the-box with BTARN (in the Microsoft.Solutions.BTARN.Schemas.RNPIPs dll) only with new ones and only in the incoming process.

Microsoft-Solutions-BTARN-Schemas-RNPIPs

Fortunately for us we have an extended BizTalk Server: List of Errors and Warnings, Causes, and Solutions at TechNet Wiki, I usually update with some frequency and that I used as a reference, which gave me some clues to the final solution. Nick Heppleston mention in his blog that:

“RN Disassembler does in-fact attempt to validate the message contained within the Service Content against a deployed schema just like the standard XmlDisassembler. The message that our trading partner was sending did not validate and hence the RosettaNet Accelerator threw this error message; once we had corrected the schema and redeployed, the error went away.

This is certainly one to be aware of if you are developing custom PIP’s to use with the RosettaNet Accelerator: ensure that the message in the Service Content validates against your custom PIP schema”

Again this isn’t my problem, because the Schema was properly deployed in the system, I only mention this because is important for understanding how the BTARN engine/processes works.

CAUSE

By default BTARN App Pool Settings are configured to use .NET framework 2.0, doesn’t enable 32-bit applications and the application pool is in Classic mode

BTARN-App-Pool-default-Settings

Important for you to know is that the accelerator requires both an in-process and out of process host, both of which must be marked as "Authentication Trusted" and "32-bit only".

To run the BTARN End to End scenario you need two important things:

  • Enable the BTARN Application Pools for 32 bit.
  • Add a HTTP Handler for *.dll refering the IsapiModule Filters.

But what I found today is that when you want to extend BTARN with new incoming PIP’s, the artifacts generated are going to be .NET 4.0/4.5 unless Visual Studio is configured to do otherwise, which we really cannot control using BizTalk projects:

re-targeting-Visual-Studio-BizTalk-Projects-error

This means along with setting the application pools for the 32-bit the .NET setting must be set to match.

SOLUTION

To solve this issue you must:

  • Type “Internet Information Services (IIS) Manager” or “IIS” in the Windows Start screen and click in “Internet Information Services (IIS) Manager” option on Apps menu.
  • Expand the server and click on “Application Pools” to display available application pools in center panel.
  • Right-click on “BTARNAppPool” and select “Advanced Settings”.
  • On the “Advanced Settings” window:
    • Change the value of “.NET Framework version” from “v2.0” to “v4.0”.
  • Change the value of “Enable 32-bit Applications” from “False” to “True”.
  • And then click “OK”.

BTARN-App-Pool-correct-Settings

Advice: you should do the same for the “BTARNHttpReceivePool” application pool

After I fix these configurations I was able to successfully receive the PIP message from my external Partner.

Credits to LemMotlo – BTARN App Pool Settings for BizTalk 2010

Exciting news… Version 1.7.0.1 of BizTalk Mapper Extensions UtilityPack for BizTalk Server 2013 is now available!

Project Description

BizTalk Mapper Extensions UtilityPack is a set of libraries with several useful Functoids to include and use it in a map, which will provide an extension of BizTalk Mapper capabilities.

Here’s the change-log for this release:

  • Fixes bugs in the String Replace Functoid
What’s new in this minor version?

This is a minor release of this project that is intended to fix some one minor problem reported in the String Replace Functoid.

It was reported that when trying to be replace a Carriage Return\Line Feed (“\r\n”) inside an element the functoid didn’t work and the reason way this happen is that the XSLT code will translate the string “\r\n” to “\\r\\n”. This release will fix that problem. It may not work for every “special characters” however if you find some more problems you can report them that we will address them.

You can found and download Source Code, Application Binaries and Documentation in CodePlex BizTalk Mapper Extensions UtilityPack home page:

BizTalk Mapper Extensions UtilityPack
CodePlex

 

or from MSDN Code Gallery:

BizTalk Mapper Extensions UtilityPack for BizTalk Server 2013 (628.8 KB)
Microsoft | MSDN Code Gallery

BizTalk Health Monitor is a snap-in, basically it’s the same of BizTalk MsgBoxViewer tool that we used monitor a BizTalk environment by gathering all information of a BizTalk group and detecting any issues, non-critical or critical warnings to detect any potential problems in advance, but in this case is integrated more closely with the BizTalk Administration Console to provide BizTalk administrators a quick and complete dashboard of a BizTalk group which will help them monitor the health of their BizTalk platform.

You can see more info about BizTalk Health Monitor (BHM) at:

BHM was originally released as a new feature with BizTalk Server 2013 R2 but luckily for us Microsoft decided to release a standalone version of BHM for use with BizTalk Server 2010 and BizTalk Server 2013.

You can download the standalone version of BHM from Microsoft Download Center here: BizTalk Health Monitor

How to install BizTalk Health Monitor snap-in

Prerequisites:

  • BizTalk Server 2010 or 2013 should be installed and configured.
How to register BizTalk Health Monitor Snap-In

After you download and unzip the BHM.ZIP file from the Microsoft Download Center, you the “InstallUtil.exe” which comes with BizTalk Health Monitor tool to register the BHM snap in.

Important: You shouldn’t replace or create a new BHM folder under “C:\Program Files (x86)\Microsoft BizTalk Server 2013 R2\SDK\Utilities\Support Tools” otherwise you will have issues installing BizTalk cumulative updates (see BizTalk 2013 R2 CU1 install failing with “Package does not contain compatible branch patch”)

Important: Unzip the BHM.ZIP to a final destination before you register the snap-in for example: C:\Program Files (x86)\Microsoft BizTalk Support Tools\BHM. Once you register the BizTalk Health Monitor Snap-In you cannot delete the folder or BHM will stop working

Note: New versions of the BHM snap-in (version 3.1) don’t include anymore the “InstallUtil.exe” file

  • You can still use the old “InstallUtil.exe” file to register the snap-in (but you need to copy this file to the BHM folder)
  • But instead you should use now the “BHMSetup.exe” file which will register in more simpler way the snap-in (see BizTalk Health Monitor v3.1 released!)

 

To accomplished that we need to:

  • Open a command prompt as an administrator
  • Navigate to the directory file where you unzipped the BHM.ZIP file
    • For example: C:\Program Files (x86)\Microsoft BizTalk Support Tools\BHM
  • And from the command prompt type:
    • InstallUtil.exe MBVSnapIn.dll
  • And hit enter. This step will do some registry changes and register the SnapIn to be used

 

How to integrate BHM Snap-In into BizTalk Admin Console

Important note: BHM Snap-In can be used independently and need not to be integrated with BizTalk Administration Console. The handicap of this approach is that a BizTalk Administration will need to use two different places/tools to monitor and administrate the environment.

To be easier and more convenience for BizTalk Administrators BHM Snap-In can also be integrate it so that it can be used with BizTalk Administration Console.

To accomplished that we need to open a 32-bit Microsoft Management Console (MMC):

  • Click Start, click Run, type:
    • mmc /32
  • Press enter or click OK. This will open a new 32-bit version of MMC (MMC32).
  • From MMC console, go to File menu and select “Options…” option
    • In the text box, replace “Console1” for “BizTalk Administration Console”
    • In the Console mode combo box, select “User mode – full access”
    • And confirm that the option “Do not save changes to this console” is uncheck

MMC-console-properties

  • From MMC console, go to File menu and select “Add/Remove Snap-in…” option

MMC-window-Add-Remove-Snap-in

  • From the “Add or Remove Snap-ins” window, add following snap-ins and then click Ok
    • Microsoft BizTalk Server Administration
    • BizTalk Health Monitor

MMC-window-Add-or-Remove-Snap-ins-selection

    • You can add the snap-ins by selecting them from the “Available snap-ins” list and click “Add >”
    • Is recommend that you respect the order present in the “Selected snap-ins” list as showed in the picture above
  • This will generate for us a new MMC which contains both the BizTalk Server Administration and BizTalk Health Monitor. And by now your new MMC is ready which shows both the BizTalk Server Administration and BizTalk Health Monitor

new-BizTalk-Administration-Console

Now you might want to save this as a new .msc file so that you don’t have to repeat these steps again but before we complete the creation process of the “new” BizTalk Administration Console, I recommend that you navigate to the BizTalk Server Installation folder:

  • Example: C:\Program Files (x86)\Microsoft BizTalk Server 2010
  • And rename “BTSmmc.msc” file, for example: “BTSmmc-old.msc”

This because we will save the “new” BizTalk Administration Console as “BTSmmc.msc” so that you don’t need to create new shortcuts or having different ways to access the BizTalk Administration Console – however this step is optional!

To finished the creation process of the “new” BizTalk Administration Console

  • From MMC console, go to File menu and select “Save As…” option:
    • Give a name and then save it.
      • Access to BizTalk Server Installation folder
        • C:\Program Files (x86)\Microsoft BizTalk Server 2010
      • Save the file as “BTSmmc.msc”

From next time onwards, when you open the BizTalk Server Administration Console

start-BizTalk-Administration-Console

The “new” BizTalk Administration Console will be incorporated with the BizTalk Health Monitor

BizTalk-Administration-Console-with-BizTalk-Health-Monitor

You can download the standalone version of BHM from Microsoft Download Center here: BizTalk Health Monitor

In my last post I explained how to implement Unit Testing in Schemas and Maps in BizTalk Server 2013 project within Visual Studio 2012. I also describe that there is an issue when we try to perform Unit Testing in maps and each time we try to run the unit test it give us the following error: “Microsoft.BizTalk.TestTools.BizTalkTestAssertFailException: Transform Failure

Until Microsoft fix this bug, probably in next releases of CU’s, one workaround that you can implement was described also in my last post, i.e., using a custom wrapper classes based on Microsoft.BizTalk.TestTools.dll to solved the current issues.

However Paul Nichols from Mexia alerted me with a Michael Stephenson post: BizTalk 2013 Map Unit Testing Gotcha, to the fact that I could use a Test Settings file which forces the tests to run in 32-bit mode and solve the problem that I was facing with maps without having the necessity to use a custom assembly… so I decide to try it.

Unit tests in Visual Studio 2012 can be configured by using a “.runsettings” file (“.runsettings” is new in Visual Studio 2012 – if you’re familiar with unit testing in previous versions of Visual Studio, you might know about “.testsettings files”). For example, you can change the .NET Framework on which the tests will be run, the directory where test results are delivered, and the data collected during a test run.

You can still use “.testsettings” in Visual Studio 2012, so any test configurations you wrote for previous editions will still work. But “.testsettings” can be used only to configure tests written for the MSTest adapter. By contrast, “.runsettings” can be used with any of the adapters built for the extensible unit test framework in Visual Studio 2012, such as xUnit.net and NUnit.

You still need a “.testsettings” file for some kinds of tests:

  • Tests that are deployed on a lab environment.
  • Web performance and load tests.
  • Customizing some types of diagnostic data adapters, such as IntelliTrace and ent log
  • BizTalk Server maps (workaround)
Maps Unit Testing Workaround 2 (add .testsettings file)

Unfortunately, if we add a “.runsettings” file and forces the tests to run in 32-bit mode, see an example of this Test Settings file here, our test project still doesn’t work!

However if we take the “.testsettings” file that was generated for example in Visual Studio 2010/BizTalk Server 2010 and add this file to our Test project in Visual Studio 2012/BizTalk Server 2013 or if we add a new “.testsettings” file from our BizTalk solution it works and solve the problem that I was facing, I really don’t know why but is the best workaround that we can implement to solve all the problems.

So to accomplish this we need to:

  • Right click on the BizTalk solution name: “Solution ‘UnitTestingFeatureWithMaps’ (2 projects)”, and select “Add” and them “New Item…”

Visual-Studio-2012-Add-New-TestSettings-file

  • In the “Add New Item – Solution Items” dialog box, expand "Installed" and then choose "Test Settings".
  • From the list of items, select "Test Settings".

Visual-Studio-2012-Add-New-Item-Solution-Items

  • In the Name box, enter "TestSettings.testsettings", and then click "Add".
  • This will open a new window for us to specify the settings of the test settings file, just leave the default setting by click “Close”.

Visual-Studio-2012-Test-Settings-Window

You can add more than one test settings file if you want to be able to switch quickly between different settings.

  • On the Visual Studio main menu choose "Test", choose "Test Settings", and then choose "Test Settings File".

Test-Settings-Select-Test-Settings-File

  • In the "Open Setting File" window select the test setting file that we previous create: "TestSettings.testsettings"

Test-Settings-Select-Test-Settings-File-2

So if we perform the tests again, we will notice that the "Microsoft.BizTalk.TestTools.BizTalkTestAssertFailException: Transform Failure" is solved and the only error that is happening is about a Map output validation failure (intentionally present)

BizTalk-Server-2013-Map-Unit-Testing-result

Thanks Paul Nichols for your comments.

To implement BizTalk Server 2013 unit test within Visual Studio 2012 to test Schemas and Map we need to:

  • Open your BizTalk Project in Visual Studio.NET 2012, in this sample: “UnitTestingFeatureWithMaps.sln”
  • In Solution Explorer, right-click in the BizTalk Server project, in this sample “UnitTestingFeatureWithMaps”, and then click Properties.
    • In Project Designer, click the Deployment property page tab and set “Enable Unit Testing” option to “True”.

BizTalk-Server-2013-Project-Designer-Deployment-property

    • Close the project properties page saving the changes.
  • In main menu, click Build, and then click Rebuild Solution.

To create a unit test project

  • On the File menu, choose “Add”, and then choose “New Project….”
  • In the New Project dialog box, expand “Installed”, expand “Visual C#”, and then choose “Test”.
  • From the list of templates, select “Unit Test Project”.

BizTalk-Server-2013-New-Unit-Test-Project

  • In the Name box, enter “UnitTestProject1”, and then choose “OK”.
  • The “UnitTestProject1” project is added to the the “UnitTestingFeatureWithMaps” solution.
  • In the “UnitTestProject1” project, for us to be able to accomplished testing BizTalk Schemas and Maps, we need to manually add the following references to the solution:
    • Microsoft.BizTalk.TestTools – you can find this assembly in the following directory: “C:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE\PublicAssemblies\Microsoft.BizTalk.TestTools.dll”
    • Microsoft.XLANGs.BaseTypes – you can find this assembly in the following directory: “C:\Program Files (x86)\Microsoft BizTalk Server 2013\Microsoft.XLANGs.BaseTypes.dll”
    • BizTalk Server project assembly – in this case “UnitTestingFeatureWithMaps”
  • You can accomplish this by:
    • In Solution Explorer, select “References” in the “UnitTestProject1” project and then choose “Add Reference…” from the context menu.

We need two test class, one for testing the Schema and the other to test the map. We can use the UnitTest1.cs that was generated by the project template, but we should give the file and class more descriptive names. We can do that in one step by renaming the file in Solution Explorer.

To unit test a schema you can leveraging the unit test framework in Visual Studio. In the Unit Test Class you can test methods like below for validating XML document instance:

        /// <summary>
        ///A test for PersonOrigin Constructor
        ///</summary>
        [TestMethod()]
        public void PersonOriginConstructorTest()
        {
            PersonOrigin target = new PersonOrigin();

            //=== Schema input file for validation ===//
            string strSourcePO_XML = testContextInstance.TestDir + "..\\..\\..\\Files\\PersonOrigin.xml";

            //=== Validate the XML Input message against the schema ===//
            Assert.IsTrue(target.ValidateInstance(strSourcePO_XML, 
                Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML));
        }

To unit test a map you can leveraging the unit test framework in Visual Studio. In the Unit Test Class you can test method like below for testing a mapping:

        [TestMethod()]
        public void HowMapsWorksMapTest()
        {
            /*********************************************************************************
             * There is a bug with Map Unit Test inside Microsoft.BizTalk.TestTools.dll 
             * Microsoft had missed on to upgrade TestableMapBase class. They still using the 
             * BTSXslTransform instead of using XslCompiledTransform witch will cause the 
             * TestMap() function to failed.
             * 
             * The following code was the expected code for BizTalk Map unit testing 
             *********************************************************************************/

            HowMapsWorks map = new HowMapsWorks();

            //=== Use the HelloWorld sample directory path for the message files ===//
            string strSourcePO_XML = testContextInstance.TestDir + "..\\..\\..\\Files\\PersonOrigin.xml";
            string strDestInvoice_XML = testContextInstance.TestDir + "\\OUT\\PersonTarget2.xml";


            //=== Test the map by using the TestMap method of the TestableMapBase class ===//
            map.ValidateOutput = true;
            map.TestMap(strSourcePO_XML,
                           Microsoft.BizTalk.TestTools.Schema.InputInstanceType.Xml,
                           strDestInvoice_XML,
                           Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML);


            //=== Output file should be created as a result of testing the map ===//
            Assert.IsTrue(File.Exists(strDestInvoice_XML));
        }

Maps Unit Testing Workaround (until the hotfix is unavailable)

Unfortunately there is a bug in BizTalk Server 2013 with Map Unit Test inside Microsoft.BizTalk.TestTools.dll, so each time we try to run the unit test for the map it give us the following error:

Microsoft.BizTalk.TestTools.BizTalkTestAssertFailException: Transform Failure
Result StackTrace:   
at Microsoft.BizTalk.TestTools.Mapper.TestableMapBase.PerformTransform(String inputXmlFile, String outputXmlFile)
   at Microsoft.BizTalk.TestTools.Mapper.TestableMapBase.TestMap(String inputInstanceFilename, InputInstanceType inputType, String outputInstanceFilename, OutputInstanceType outputType)

Microsoft had missed on to upgrade TestableMapBase class. They still using the BTSXslTransform instead of using XslCompiledTransform witch will cause the TestMap() function to failed.
You can find a wrapper (provide by  shadabanwer) here: Map Unit test does not work in BizTalk 2013 because TestableMapBase class is not correct. However there is also a problem with schema (input and output) validation options… so I decide to recreated a new custom wrapper based on Microsoft.BizTalk.TestTools.dll and the solution provided by shadabanwer and fixed all the problems because validating the output instance generated by the map is an important step to validate your maps using Unit Testing. You can find this DLL here: BizTalk Server 2013: Wrapper classes to perform Unit Testing in Maps

You must use this workaround until Microsoft fix this bug.

So to be able to successfully test our maps we need to:

        [TestMethod()]
        public void HowMapsWorksMapTest()
        {
            HowMapsWorks map = new HowMapsWorks();

            //=== Map input file instance to be mapped  ===//
            string strSourcePO_XML = testContextInstance.TestDir + "..\\..\\..\\Files\\PersonOrigin.xml";
            //=== Path for the Map output file instance with the result of the transformation  ===//
            string strDestInvoice_XML = testContextInstance.TestDir + "\\Out\\PersonTarget2.xml";

            //WORKAROUND SOLUTION to test maps
            SandroPereira.BizTalk.MapTestTools.TestableMapBase mapper = new SandroPereira.BizTalk.MapTestTools.TestableMapBase();

            mapper.Mapper = map;
            mapper.Mapper.ValidateOutput = true;

            //=== Test the map by using the TestMap method of a custom TestableMapBase class ===//
            //=== that uses the XslCompiledTransform. This class is basically an improved    ===//
            //=== clone of the class present in the Microsoft.BizTalk.TestTools DLL          ===//
            mapper.TestMap(strSourcePO_XML,
                Microsoft.BizTalk.TestTools.Schema.InputInstanceType.Xml,
                strDestInvoice_XML,
                Microsoft.BizTalk.TestTools.Schema.OutputInstanceType.XML);

            //=== Output file should be created as a result of testing the map ===//
            Assert.IsTrue(File.Exists(strDestInvoice_XML));
        }

Check the full detailed article here: BizTalk Server 2013: Step-by-Step to implement Unit Testing in Schemas and Maps

BizTalk Server 2013: Using the Unit Testing Feature with Schemas and Maps (500.3 KB)
Microsoft | TechNet Gallery

Recently I work in a project when I need to communicate with Oracle database in which I encountered some platform configuration problems. In general, communicate with Oracle is very simple and somewhat similar to SQL Server.

In development phase I didn’t have any problem, but notice that before you start developing you need to make sure that you have BizTalk Adapter Pack installed and Oracle client (or at least Oracle Data Access Components (ODAC) – 32 and 64 bits) installed to use BizTalk Adapter for Oracle in your BizTalk environment.

The BizTalk Adapter Pack consists of the following adapters:

  • Microsoft BizTalk Adapter for Oracle Database (Oracle Database adapter).
  • Microsoft BizTalk Adapter for Oracle E-Business Suite (Oracle E-Business adapter).
  • Microsoft BizTalk Adapter for mySAP Business Suite (SAP adapter). This also includes the .NET Framework Data Provider for mySAP Business Suite (Data Provider for SAP).
  • Microsoft BizTalk Adapter for Siebel eBusiness Applications (Siebel adapter). This also includes the .NET Framework Data Provider for Siebel eBusiness Applications (Data Provider for Siebel).
  • Microsoft BizTalk Adapter for SQL Server (SQL adapter).

And you can found more information how to install it here: BizTalk 2013 Installation and Configuration – Installing BizTalk Adapter Pack (Part 12)

The Microsoft BizTalk Adapter for Oracle Database is a Windows Communication Foundation (WCF) custom binding. This binding contains a single custom transport binding element that enables communication with an Oracle database.

The following figure shows part of “BizTalk Oracle Adapter Architecture”:

BizTalk-Oracle-Adapter-Architecture

According to BizTalk official documentation, the support version of Oracle are:

  • Oracle database version 11.1,
  • Oracle database version 10.2,
  • Oracle database version 10.1,
  • Oracle database version 9.2

And supported client versions:

  • Oracle Data Access Components for Oracle Client 11.1.0.6 with Patch Set 11.1.0.7,
  • Oracle Data Access Components for Oracle Client 11.1.0.7

You can read more on how to install Oracle client here:

As I said earlier, I didn’t had any problem in development phase however in runtime I catch the following error:

The adapter failed to transmit message going to send port “SEND_Oracle” with URL “oracledb://connection”. It will be retransmitted after the retry interval specified for this Send Port. Details:”System.IO.FileNotFoundException: Could not load file or assembly ‘Oracle.DataAccess, Version=2.112.1.2, Culture=neutral, PublicKeyToken=89b483f429c47342’ or one of its dependencies. The system cannot find the file specified.

File name: ‘Oracle.DataAccess, Version=2.112.1.2, Culture=neutral, PublicKeyToken=89b483f429c47342’ —> System.IO.FileNotFoundException: Could not load file or assembly ‘Oracle.DataAccess, Version=2.111.7.0, Culture=neutral, PublicKeyToken=89b483f429c47342’ or one of its dependencies. The system cannot find the file specified.
File name: ‘Oracle.DataAccess, Version=2.111.7.0, Culture=neutral, PublicKeyToken=89b483f429c47342’
WRN: Assembly binding logging is turned OFF.
To enable assembly bind failure logging, set the registry value [HKLM\Software\Microsoft\Fusion!EnableLog] (DWORD) to 1.
Note: There is some performance penalty associated with assembly bind failure logging.

So I tried to check in the GAC if the correct assemblies were there and I realized that the client add installed a different version of the Oracle Client: Oracle 11g R2.

BizTalk-Oracle-Client-GAC-dll

CAUSE

When installing the Oracle WCF Adapter for BizTalk there is a design time requirement to use Oracle.DataAccess Version 2.111.7.0.

Official the Oracle 11g R2 is not supported and again according to official documentation I should use one of the supported clients. However my client only had access to this version and did not want to use another. Although not officially supported you can connect to Oracle 11g R2 database and use Oracle 11g R2 client with minor configuration adjustments.

SOLUTION

One possible solution to fix this problem is configuring Assembly Binding Redirection in the machine configuration file (Machine.config):

  • 32-bit: c:\Windows\Microsoft.NET\Framework\[version]\config\machine.config
  • 64-bit: c:\Windows\Microsoft.NET\Framework64\[version]\config\machine.config

Note: You should apply this in both 32 and 64-bit machine configuration files.

By using the <assemblyBinding> Element for <runtime> that will contain all the information about assembly version redirection and the locations of assemblies.

In this case you should apply the following configurations:

<runtime>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
            <dependentAssembly>
        <assemblyIdentity name="Oracle.DataAccess"
          publicKeyToken="89b483f429c47342" />
 
        <bindingRedirect oldVersion="2.111.7.0" newVersion="2.112.1.2" />
      </dependentAssembly>
       </assemblyBinding>
</runtime>

Just to be sure, I add this configuration in both 32 and 64-bit in .NET Framework 2.0 and 4.0 machine configuration files.

Exciting news for the BizTalk Community… specially the 200 persons that attended the BizTalk Summit 2014 London that already know the potential of BizTalk NoS addin!

Nino Crudele just public announce in is blog: BizTalk NoS Add-in Beta version has been officially released through Visual Studio Gallery that the BizTalk NoS Addin is now available for you to download it in install it on Visual Studio gallery at: BizTalk NoS Addin!!!!!

What is BTSG NoS Addin purpose?

The purpose of BTSG NoS addin is to help all BizTalk Developer, why not, all BizTalk Administrator too in a lot of different situations, by improving the developer experience and why not reduce the development time in new or existent BizTalk projects.

It will provide several functionalities like quick search inside artifact, fast register/unregister in GAC, find critical, internal or external dependencies… and many fore functionalities like JackHammering, which will compare your VS artifact with the artifact deployed in BizTalk environment, you can also extract the artifact (Orchestration, map, schema and so on) from BizTalk environment and put it in the VS solution or even test your pipeline in VS simply… several features that are usefully in our day by day work and a time saver in a lot of situations.

How can I install BTSG NoS Addin

You can install BTSG NoS Addin directly from Visual Studio “Extensions and Updates” option. For that you must:

  • Open Visual Studio as Administrator, go to the “Tools” menu and select the “Extensions and Updates” option.
  • In the “Extensions and Updates”, in the right panel select “Online” tab and search for “BizTalk” or for “BizTalk NoS Addin”.
  • And Download the BizTalk Nos Addin”.

The rest of the installation process is described in one of my previous post: How to install BTSG NoS Addin for Visual Studio 2012

You can find all the documentation about this addin in:

Or in my posts:

Special Note

It has been a challenge, an extreme playfulness and a privilege to work with my dear friend Nino Crudele! I feel extremely honored that Nino have chosen me to help in this final phase of his work and for that THANKS Nino!

_DSC2735

Now is time to take a small vacations of BizTalk NoS addin and finish my ongoing work: BizTalk Mapper Pattern eBook… witch of course Nino will be one of the reviewers J