Exposing WCF services from orchestrations

Our first task is to take a BizTalk orchestration workflow and expose one of its ports as a WCF-enabled web service. Fortunately for us, this is a fairly straightforward undertaking that requires no actual coding.

Setting up the project

The use case we will use throughout this chapter involves the ordering of pharmaceutical products. Our initial assignment is to define the shape of the data representing a "new order". I've built a schema named NewOrder_XML.xsd with a root node name of NewOrder and a structure that holds the characteristics of the order, the particular items that made up the order, and the corresponding sales territory information. The namespace of my schema, http://BizTalkSOA.Chapter3.OrderManagement.BizTalk/Contract, will surface again once the service WSDL is generated. As shown in the following screenshot:

Now that we have a contract definition representing a new order where we have distinguished the Status field, we will assemble an orchestration workflow that consumes this data entity. Recall from Chapter 1, Building BizTalk Server 2013 Applications that a BizTalk orchestration depends on messages which equate to the data being sent and received by the orchestration. These messages are immutable so their data cannot be manipulated by the orchestration except during message creation. For our first simple orchestration, we have a message representing the inbound request and a separate message for the acknowledgement returned to the caller. In this case, both messages are of the same schema type, as shown in the following screenshot:

Once our messages have been defined, we sketch out the orchestration's sequential flow. In this case, let's do a very simple orchestration that receives the new order and then constructs and returns a response message with an altered Status value:

Finally, I set up a public, request-response logical port, which acts as the interface and entry point to the orchestration. This port has a single operation named SubmitNewOrder, as shown in the following screenshot:

The final orchestration looks like this:

Note that absolutely nothing we've done within this orchestration hints at its role as the realization of a WCF service. Ideally, an orchestration's ports are not tightly coupled to a runtime transport scheme, which in return means greater flexibility and reuse. The orchestration port only dictates a message type and message exchange pattern while remaining transport neutral.

Note

Before continuing, I built and deployed this project to the BizTalkSOA.Chapter3 application to ensure that my BizTalk application was created and refreshed.

Generating the WCF endpoint

Unlike most BizTalk receive adapters, which poll or listen to existing URIs (such as file locations, databases, queues), the WCF adapters require us to create new endpoints that BizTalk uses to get data absorbed into the system. Fortunately, Microsoft makes generating such endpoints fairly easy by introducing the BizTalk WCF Service Publishing Wizard tool.

Note

Pitfall

Unlike the classic ASMX-based BizTalk Web Services Publishing wizard, the BizTalk project in Visual Studio does not have to be deployed in the Global Assembly Cache in order for the BizTalk WCF Service Publishing Wizard to locate it. However, if the BizTalk project assembly had been deployed at any time previously, the freshly updated assembly must be deployed to the GAC so that the Visual Studio wizard pulls the latest version of the assembly.

While one can launch the BizTalk WCF Service Publishing Wizard from the Microsoft BizTalk Server 2013 folder on the Start menu, it's much simpler to trigger this wizard from within Visual Studio itself. We initiate this wizard by going to the Tools menu of Visual Studio and choosing BizTalk WCF Service Publishing Wizard. What we see next is a new window that will walk us through all the steps necessary to generate the service and endpoint we desire.

You need to perform the following steps:

1. The first thing that this wizard needs to know is what type of WCF service we'd like to produce. Our choices are as follows:

   

2. Choose the Service endpoint with a WCF-WSHttp transport while also enabling the metadata endpoint and auto-generation of a receive location in the BizTalk application named BizTalkSOA.Chapter3:
   
3. After selecting the desired service type, our next task is to identify which artifacts the wizard should use to generate the WCF service. Our current scenario will use the Publish BizTalk orchestrations as WCF service option, which means that key service attributes such as data contract, communication pattern, and operation name are all retrieved from an existing orchestration's logical port.
4. On the next page is a new feature of BizTalk Server 2013, which will ask if you want to Add a Service Bus endpoint. This will be covered in Chapter 6, Azure Service Bus so we will leave this unchecked for now and click Next. As shown in the following screenshot:
   
5. On the following screen, leave it at the default selection of Publish BizTalk orchestrations as WCF service and click Next:
   
6. On the next screen of the wizard, we are asked to designate which .NET assembly contains the orchestration that we'd like to use to generate the service. If you launched this wizard from within Visual Studio with the BizTalk project open, then the assembly's file path will already be populated by the wizard.
7. If the orchestration was successfully loaded by the wizard, we should see the (public) orchestration ports available for selection:
   
8. After accepting the currently selected items, we enter a namespace for the service. In this case, I supplied the namespace http://BizTalkSOA.Chapter3/Service, as shown in the following screenshot:
   
9. Finally, we need to specify the web server and address where our shiny new service will be deployed:
   
10. Once we've picked a valid URL, we see a read-only view of the pending WCF service configuration. If everything looks good, click on Create, wait for confirmation that all the necessary actions succeeded, and click on Finish.

Configuring the generated components

We told the BizTalk WCF Service Publishing Wizard to build a receive location for us, so we should investigate exactly what we got as a result of that choice. In opening BizTalk Administration Console and probing the BizTalkSOA.Chapter3 application, we should see a new receive location with a staggeringly long name that is hard to miss. Like all auto-generated messaging ports, this receive location is in a Disabled state. The next step is to enable this receive location, and in the Orchestrations section of the application, both bind and start the deployed orchestration.

Double-clicking this new receive location reveals that it has been set up using the WCF-WSHttp adapter and the BizTalk isolated host. However, the real meat of this endpoint lies in the adapter configuration. We inspect this by clicking the Configure button next to the chosen adapter. The standard (non-custom) WCF adapters all have a similar look and feel to their configuration pages, with the same set of tabs along the top. Here, we see the first critical piece of the endpoint: the address:

The second tab in this receive location configuration, named Binding, shows a subset of available WCF-WSHttp binding switches that we may alter for the adapter. Take note of the fact that, while the default number of concurrent calls for a WCF service is 16, the BizTalk WCF endpoint sets this value to 200 for performance reasons. If we desire deeper control over this binding configuration or wish to affix service behavior extensions, then the WCF-CustomIsolated adapter should be used instead.

The third tab is named Security and provides us with a fairly straightforward way to apply standard WCF security schemes to our endpoint. We'll stick with the default Message security mode shown here:

Finally, the last tab, named Messages, is where we tell BizTalk where to extract the message body from the WCF payload. We could send the entire SOAP payload to the BizTalk MessageBox (SOAP envelope included) or even rip out a specific node in the SOAP body. In our case, we just need the message body:

You may have noticed that nowhere in this receive location do we designate the C in the ABCs of WCF. Where is the contract? All BizTalk receive locations are typeless, and the WCF receive locations are no different. A BizTalk WCF endpoint exposes a generic contract that will accept any valid SOAP message. This is why the generation of a metadata endpoint is critical; otherwise, we'd have no clear way to tell consumers how to structure the payload their service requests.

If you recall, our preceding run through the BizTalk WCF Service Publishing Wizard produced this receive location and an actual WCF service hosted in IIS 8.0. If we had tried to visit the service in our web browser immediately after the wizard had completed, we would have seen an error telling us that the receive location was offline. Note that the receive location for the associated WCF service must be enabled in order to browse the service. Once the receive location gets enabled, we should see a standard WCF service metadata page instead of an exception.

Let's take advantage of this metadata endpoint by referencing and consuming our new WCF service. In a new Visual Studio console application, we choose Add Service Reference and point to the generated WCF service WSDL. Only a small bit of code is needed to consume this simple service. However, note the unwieldy type names that the orchestration-generated WCF service imparts upon us:

static void Main(string[] args)
{
  OrchSvc.BizTalkSOA_Chapter3_OrderManagement_BizTalk_Orch_ManageNewOrder_ReceiveNewOrderPortClient client =
  new OrchSvc.BizTalkSOA_Chapter3_OrderManagement_BizTalk_Orch_ManageNewOrder_ReceiveNewOrderPortClient("WSHttpBinding_ITwoWayAsync");
    
    try
    {
      OrchSvc.NewOrder order = new OrchSvc.NewOrder();
      order.OrderID = "123";
      order.OrganizationID = "987";
      order.PhysicianID = "555";
      order.Status = "submitted";

      Console.WriteLine("Calling WCF service ...");

      client.SubmitNewOrder(ref order);

      Console.WriteLine("Result status is: " + order.Status);
      client.Close();
      Console.ReadLine();
    }
    catch (System.ServiceModel.CommunicationException) { client.Abort(); }
    catch (System.TimeoutException) { client.Abort(); }
    catch (System.Exception) { client.Abort(); throw; }
}

At this point, we've designed an orchestration, exposed its port interface as a WCF service, and consumed that service from a WCF client.

Anatomy of a generated WCF WSDL

Attributes set while building a BizTalk project seep into the WSDL of a generated WCF service. Here is a quick look at which design-time properties map to runtime WSDL attributes.