PowerShell Adapter for Microsoft BizTalk

Requirements: /n software Adapters for Microsoft BizTalk

Introduction

The /n software Adapters for Microsoft BizTalk include fully-managed .NET Adapters that seamlessly integrate with the BizTalk Messaging Pipeline. The /n software Adapters extend the features of BizTalk with advanced Internet communications and secure messaging capabilities.

There are many different BizTalk adapters currently supported:  AS2 Adapters for EDI communications, FTPS, FTP, SFTP, SSH, Email adapters, etc. These adapters have completed the official adapter certification program (administered by Unisys) established by Microsoft for BizTalk server, which tests for scalability and interoperability with Microsoft BizTalk Server.

This guide will focus specifically on the PowerShell adapter, which is used to execute PowerShell scripts on local and remote servers.  Before you continue reading, I recommend that you go ahead and download the product and follow along with me through the tutorial.

Integrate PowerShell Scripting into BizTalk solutions quickly and easily

The PowerShell BizTalk Adapter provides an easy way to rapidly enhance BizTalk applications with dynamic processing capabilities with PowerShell. It can be used to create highly-flexible BizTalk configurations via easily configurable PowerShell scripts.

With the PowerShell BizTalk Adapter, BizTalk users can create Send Ports that process messages by executing PowerShell script. When BizTalk sends a message the PowerShell BizTalk Adapter executes the configured script and passes the message as a parameter.

How it works

The PowerShell BizTalk Adapter is a BizTalk Server transmit adapter that will execute PowerShell scripts whenever BizTalk sends a message through it. This allows you to easily create custom processing scripts for your messages and have it completely integrated into your BizTalk solution.

Each send port you configure to use the PowerShell BizTalk Adapter can define a different PowerShell script to execute. Scripts have read access to all the important parts of a BizTalk message, including the list of message parts, part streams and message context properties.

Using the PowerShell BizTalk Adapter

To use the PowerShell BizTalk Adapter, follow these simple steps:

1. Create a new Send Port in your BizTalk application
2. Select the PowerShell BizTalk Adapter as the adapter to use in the port
3. Configure the Adapter settings with the following:
   • A name that identifies this send port.
   • The PowerShell script to execute when a message is sent. You can just write your script directly in the port settings, or dot-source an external script file with your commands.
   • In order to pass additional input data to the script, fill in the Variables property. This should contain a list of name=value pairs, one per line. Each one will be visible in the PowerShell script as a variable called $name.

Interacting with BizTalk Messages

In your PowerShell BizTalk Adapter scripts, you will find that the BizTalk message being sent is available through the $message variable. This will contain a wrapper object around the real BizTalk message that makes it easier to use from PowerShell. The $message object has the following properties and methods:

• GetBody(): This method returns the BizTalk message body as a string.
• GetBodyB(): This method returns the BizTalk message body as a byte array.
• MessageID: This property can be used to get the unique ID assigned to this BizTalk Message.
• BodyPartName: This property will return the name of the body part of the message.
• GetProperty(): This method takes the name and namespace of a context property and returns its value.
• ReadBodyPart(): This method will return a System.IO.Stream object associated with the message Body Part.
• ReadPart(): This method takes the name of a specific part in the message and returns its data Stream.
• GetPartNames(): This method will return a list of the names of all parts available in the message.

Here is an example of a script that will read the request message content as XML and write it to a file named for its contents.

$xml = [xml] $message.GetBody()

# xml looks like: "<order><orderId>123422</orderId>....</order>"
$name = $xml.order.orderId

$xml.get_OuterXml() | set-content "C:\orders\$name.xml"

If the Adapter is used in a two-way, solicit/response send port, you can pass data back to your BizTalk Application through the response message.

The body data stream of the response message is created automatically in the following way:

• You can write directly to the response stream using the Write-Host cmdlet or by directly calling the Write() and WriteLine() methods in $host.UI.
• Objects written through Write-Output or returned by the script are fed through the default output formatter in PowerShell and written as text to the response stream.

The script can also interact directly with the response message through the $replyMessage variable. This object has the same methods/properties as the request message object mentioned before, and also adds:

• SetBody(): This method sets the BizTalk message body as a string. If this method is used, the original response body from the methods mentioned above will be discarded.
• SetBodyB(): This method sets the BizTalk message body as a byte array. If this method is used, the original response body from the methods mentioned above will be discarded.
• AddPart(): This method adds a new, non-body, part to the BizTalk message. It takes as arguments the name of the part (must be unique) and a Stream object with the data.
• SetProperty(): This method writes a property to the message context. It takes the name, namespace and value of the property.
• Promote(): This method promotes a property in the message context. It takes the name, namespace and value of the property.

Diagnosing Scripts

The Adapter provides an easy way for scripts to generate diagnostics data that you can use to troubleshoot their behavior, by providing ways for the scripts to write diagnostic messages directly to the Adapter log.

This is exposed to the script through the Write-Debug, Write-Warning and Write-Verbose cmdlets, or as an alternative, by calling the corresponding functions in $host.UI.

Executing Scripts on Remote Machines

PowerShell BizTalk Adapter also allows you to execute scripts on remote machines using the PowerShell V2 Remoting protocol or the PowerShell Server protocol.

To use PowerShell Remoting, you need to set the following options in the task properties:

• Host: The name or IP address of the remote computer.
• Protocol: set to prRemoting;.
• User and Password: Optional. If not specified, the connection will be attempted using the user the SSIS workflow is running under.

To use PowerShell Server, you need to have PowerShell Server installed and running in the remote machine, and configure the following properties:

• Host: The name or IP address of the remote computer.
• Protocol: set to prSSH.
• SSHAuthMode: Set to amPassword for username/password authentication or to amPublicKey for public key authentication. For the latter, this option needs to have been enabled in the remote PowerShell Server, and the task needs to have access to a certificate the server will accept.
• User: The username to be used for authentication.
• Password: Optional. The host key/certificate used to authenticate the server.
• SSHCert: The certificate to use for public key authentication.

Scripts executed using PowerShell Server don't have access to message objects or streams.