Tallan's Technology Blog

Tallan's Top Technologists Share Their Thoughts on Today's Technology Challenges

BizTalk 2016 Feature Pack 1 Management REST API Tutorial

Kevin Morillo

One of the great new additions of the recently released Feature Pack 1 for Microsoft BizTalk 2016 is a REST API, which can be used to administer BizTalk Server.  Longtime users of BizTalk may have experience with using ExplorerOM.dll or WMI based scripts to manage their BizTalk environment.  The REST API introduced in Feature Pack 1 provides a more flexible alternative, including a Swagger definition providing rapid implementation of an application to consume the API.  In this post, I will walk through the process of installing the API as well as using Swagger to generate a C# client and demonstrating a simple command.

The process of installing the management API couldn’t be simpler – a few PowerShell commands is all that is needed!  One note is that IIS is a pre-requisite, but most BizTalk environments would have this already if you have used BAM or the ESB Toolkit.

To Install the API:

  • Open up PowerShell ISE as administrator
  • Add the following into the script
    • First, we will set the current directory to that of the BizTalk installation.  I have included the default location below, but you should update to match your environment.
      cd 'C:\Program Files (x86)\Microsoft BizTalk Server 2016'
      
    • Next, we call the ‘FeaturePack.ConfigureServices.ps1′ script, included in the installation directory, which will install the REST API site to IIS.
      FeaturePack.ConfigureServices.ps1 `
          -Service management `
          -WebSiteName 'Default Web Site' `
          -ApplicationPool DefaultAppPool `
          -ApplicationPoolUser <your_domain\your_username> `
          -ApplicationPoolUserPassword <your_password> `
          -AuthorizationRoles '<your_domain>\BizTalk Server Administrators'
          

      I have used common IIS settings. You will want to replace <your_domain\your_username> and <your_password> with appropriate settings.  The AuthorizationRoles parameter can be any group, I chose the BizTalk Server Administrators group as I only want to allow users who already have access to the Admin Console.

1

  • Run the script
  • Open up IIS and we should see the application has been installed

2

  • For this demonstration, we will enable Anonymous access for our client application, however this is not recommended for actual implementations.

15

 

  • To ensure that our changes are active, we will reset IIS.  Open up command prompt as administrator and run ‘iisreset’

3

  • Next, we will look at the Swagger Definition.  Open up a browser and navigate to http://localhost/BizTalkManagementService/swagger/

4

  • The Swagger site shows all of the endpoint operations available as part of the API.  More information on the Swagger spec can be found here
  • Even better, you can easily test the API and invoke any of the operations using sample input provided by the Swagger definition.  Below, I have executed a GET request for the Hosts, which shows my two host hosts; BizTalkServerApplication, and BizTalkServerIsolatedHost.

5

 

Going a step further, Swagger provides multiple ways to generate clients for several different programming languages using Swagger CODEGEN, or an online generator.  We will use the online tool to generate a C# client to can consume our BizTalk API and allow us to rapidly stand up a working application to manage the BizTalk environment.

6

 

  • The POST operation by default requires a link to the Swagger site for which to generate the client code. However, we can also paste in the Swagger spec, in JSON format of course, achieving the same outcome.  To do that, we will first need to retrieve our Swagger spec.  This can be retrieved from our BizTalkManagementService  http://localhost/BizTalkManagementService/swagger/docs/v1.  This JSON string is the entirety of the Swagger spec and will be used in the next step.

 

7

 

  • Next, we can expand the /gen/clients/{language} POST operation.  Within this section there is a sample request that can be used as a start.  Clicking on Example Value in the bottom right of the page will move it over to body text block on the left.

9

  • Select the desired language from the language drop down, in our case ‘csharp’.  Then, instead of using the swaggerUrl value, we will replace it with “spec”: <our copied swagger definition JSON string from the previous step>.  This can be seen below.  Tip: Don’t forget the comma at the end of your JSON string pasted!

8

  • Finally, click ‘Try It Out’ to send the request.  This should produce a HTTP 200 success, and an accompanying link to download the produced code.10
  • A zip file will be downloaded, unzip it with your program of choice and open up IO.Swagger.sln in Visual Studio.  I chose Visual Studio 2017.

11

 

12

  • Finally, we will create a Console App to test our new client.

 

13

  • First, add a reference to the IO.Swagger.Api project.  Below is a simple ‘hello world’ that will instantiate an instance of the HostApi class and invoke a ‘GET’ to retrieve a list of hosts in our environment and print it to the console.  This is similar to what we did in the Swagger site.

14

using IO.Swagger.Api;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace ConsoleApp2
{
    class Program
    {
        static void Main(string[] args)
        {
            var api = new HostsApi();
            var hosts = api.HostsGet();
            foreach (var h in hosts)
            {
                Console.WriteLine(h.Name);
            }
            Console.ReadKey();
        }
    }
}

The output should be the same as the output from the GET request performed in the Swagger API in a previous step; BizTalkServerApplication and BizTalkServerIsolatedHost

16

 

As can be seen above, it is easy to have a working client to invoke the commands in our BizTalk Management REST API.  Microsoft’s inclusion of Swagger makes a significant difference in ease of use, reducing the difficulty in programmatically managing BizTalk Servers, especially remote servers that aren’t easily managed with ExplorerOM.

More information on Swagger can be found on their site, including other tools like an IDE, the aforementioned code generators

http://swagger.io/

http://docs.swagger.io/spec.html

https://github.com/swagger-api/swagger-codegen#generating-a-client-from-local-files

_________________________________________________________________________________________

To learn more on how Tallan can help your organization deliver a successful integration solution with Microsoft BizTalk Server 2016, CLICK HERE.

Related Articles

No comments

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

\\\