[ Please contribute your knowledge and experience to this document. The community within and outside Microsoft regularly evaluates changes and accepts, refines, or reverts them as appropriate. To read the original document, click here. ]
Exposing services on the cloud is a key requirement for creating composite applications that can extend the reach of on-premises applications and services to clients that exist outside an organization’s firewall. AppFabric Connect for Services now enables users to expose their on-premises services on the Azure AppFabric Service Bus via a relay service.
Before we go deeper into details of exposing services on the cloud, and in particular LOB services, let us understand how the space of application and service deployment has evolved given the advent of cloud-related technologies. We can divide the application and service deployment space into two broad categories:
However, there can be a requirement where organizations want to extend their existing on-premises applications or services to the cloud so that the clients outside the organization’s firewall can also access and consume it. Windows Azure AppFabric Service Bus provides the capability to take web services that are accessible only from within an organization and extend their reach to external clients. Azure AppFabric Service Bus provides a relay service that can listen to external clients on behalf of the on-premise web services at a given public address.
While Azure AppFabric Service Bus provides a platform where service owners could expose the relay endpoint for their on-premises service, AppFabric Connect for Services enables service owners to create the relay endpoints in the first place. AppFabric Connect for Services provides an updated WCF Adapter Service Development Wizard (originally shipped with BizTalk Adapter Pack 2010) that enables users to expose operations on their on-premise line of business (LOB) applications as WCF services to external clients via the Service Bus relay service.
This whitepaper is intended for the following users:
This whitepaper assumes familiarity with Azure AppFabric Service Bus, Azure AppFabric Access Control Service (ACS), and Windows Communication Foundation (WCF).
The WCF Adapter Service Development Wizard essentially exposes the operations on LOB applications as WCF services. The wizard enables you to select the operations that you want to expose as services and then creates the following:
A Service Bus endpoint for exchanging metadata pertinent to the WCF service.
Whether an organization uses standard LOB applications or customized legacy applications, the data available through the applications is business-critical data. Security becomes of paramount concern when organizations expose the data, or operations that can be performed on the data, as services outside an organization’s protected environment. To address such concerns, organizations can follow certain security best-practices to ensure that only authenticated clients get access to the service.
Tip: It’s not essentially a security setting, but organizations can also secure the services hosted on the cloud by not making the endpoints publicly discoverable. Service Bus provides an ATOM feed which lists all the publicly discoverable endpoints under a given Service namespace. Making the endpoints discoverable or not is controlled through a property “EndpointDiscovery”, which can be set using the WCF Adapter Service Development wizard. The disadvantage of not making the endpoints publicly discoverable is that if you have a large number of clients that would be using the service you hosted, you will have to communicate the endpoint URL to each of those clients.
This whitepaper provides information on how to use the WCF Adapter Service Development Wizard in BizTalk Adapter Pack 2010 to expose operations on the on-premises LOB applications as web services that have a Service Bus relay service on the cloud, listening to external clients. This whitepaper is written around a business scenario to help demonstrate the feature. The scenario is as follows:
The whitepaper describes the procedures Contoso must follow to expose operations on the SQL Server database table as web services via the Service Bus relay service. The whitepaper also provides the procedures on how Fabrikam can write a client application to invoke the service exposed by Contoso.
Make sure you have the following components installed or configured before you proceed further:
Note: WCF LOB Adapter SDK 2010 can also be installed from BizTalk Server 2010 installation media.
Note: AppFabric Connect for Services can be used to only register Service Bus endpoints with Windows Azure AppFabric 1.0.
Important: If you choose to install Windows Server AppFabric, you must also install the hotfix 980423 (http://go.microsoft.com/fwlink/?LinkId=204211). This fixes some issues with Windows Server AppFabric.
In this section, we will provide step-by-step instructions on how to expose the Select operation on a SQL Server table as a service on the cloud. For ease of understanding, this section is divided into the following categories:
As mentioned in the scenario description, Contoso stores all the stock related information in a Stocks table. In this section, we provide you the script to create the Stock table in your SQL Server database. The script also populates the table with a few records. Let us assume that the Stocks table will be created in the ContosoDB database.
<put code excerpt here>
Once you have created the table, you are now ready to create the service to expose operations on the Stocks table.
As described in the business scenario, Contoso wants to enable its clients to retrieve information from the Stocks table, which means that Contoso must expose the Select operation on the Stocks table (in the ContosoDB database) as a service on the cloud. The following procedure provides information on how to use the WCF Adapter Service Development Wizard for exposing operations on a SQL Server database table as services.
Set this to True to enable metadata exchange for the WCF service. By setting this to True, you make the service metadata available using standardized protocols, such as WS-Metadata Exchange (MEX).
Default is False.
Note: For this procedure, you must set this property to True to generate a Service Bus metadata exchange endpoint. When you create a client to consume the service, you will need to specify the Service Bus metadata exchange endpoint. If you set this to False, the Service Bus metadata exchange endpoint is not generated.
Set this to True to include managed exception information in detail of SOAP faults returned to the client for debugging purposes.
Specify whether you want to use the message-level security mode of WCF. Default is True.
For this tutorial, you can set this to False.
Note: If you set this property to True, you must also enter the values for properties under the ServiceCertificate category.
A string that specifies the value to search for in the X.509 certificate store.
Note: Specify a value for this property only if UseServiceCertificate is set to True.
A value that specifies the location of the certificate store that the service can use to validate the client's certificate.
Name of the X.509 certificate store to open.
The type of X.509 search to be executed.
Set this to True to if you want the endpoints are publicly discoverable. This is especially useful in scenarios when an organization has a large customer base and it does not want to run the overhead of communicating all the endpoints to all the clients. While configuring the service, if an organization sets this option to True, the endpoints will be listed on the Service Bus ATOM Feed.
For this procedure, set this to True.
In the cloud endpoint behavior section, specify the following properties:
For the Property
Specify the Value
Specify the binding for the endpoint. You can select from netTcpRelayBinding, ws2007HttpRelayBinding, and basicHttpRelayBinding. The URL schemes are different for these bindings.
For this procedure, select the netTcpRelayBinding.
Note: The wizard generates a relay service endpoint only if you select netTcpRelayBinding. For the other two bindings, the wizard does not generate the relay endpoints. So, if you select a binding other than the netTcpRelayBinding, you will need to provide the metadata separately to the clients because there will be no endpoint using which the clients can generate metadata.
Specify properties for the selected binding. You can do so by clicking on the ellipsis (…) button that appears when you click the grid row for the binding configuration property.
Endpoint Details (properties for the Service bus endpoint)
Specify a name for the relay service endpoint.
Specify whether the service bus authenticates the client before routing the message from the client to the service. If you want the service bus to authenticate the client before relaying the client request to the service, set this property to RelayAccessToken. Otherwise, set this to None.
Tip: Hosting Service Bus endpoints on the Service Bus incur cost. If the Service Bus does not authenticate the client before it relays the request to the service, the service provider will have to bear the cost even if the client is not authorized to access the service. Microsoft recommends that you always set this property to RelayAccessToken for service endpoints so that only authenticated clients can traverse through the relay service.
For this procedure, set this property to RelayAccessToken.
Specify the service path that will be appended to the service URL to create a unique endpoint for the service. By default this is set to the contract name.
Displays the URI for the relay service endpoint. The values you entered for the Service Namespace and ServicePath properties are used to create the URI. For example, a URI would look like sb://ContosoNS.servicebus.windows.net/TableOp_dbo_Stocks/. Here, “sb” is the scheme, ContosoNS is the service namespace you entered in one of the previous wizard pages, servicebus.windows.net is the Service Bus base URL, and TableOp_dbo_Stocks is the service path.
Metadata (properties for the Service Bus metadata exchange endpoint)
Specify whether you want to enable the relay metadata exchange endpoint on the Service Bus. For this procedure, set this to True.
Note: If you had set EnableMetadataExchange to False in the Configure Behaviors page, you would not be able to set any property for the relay metadata exchange endpoint.
Note: Enabling Service Bus metadata exchange is not supported with BasicHttpRelayBinding and WS2007HttpRelayBinding because of known compatibility issues between SvcUtil and these bindings. Hence, EnableMexEndpoint is set to False if you choose any of the two bindings.
Similar to the RelayClientAuthentication for service, this property specifies whether the Service Bus authenticates the client before routing the request to the metadata exchange endpoint. For this procedure, set this property to None.
Note: For this topic, we will be using the Add Service Reference Visual Studio component to generate a proxy for the relay service. The Add Service Reference component requires the relay metadata exchange endpoint to generate the proxy. If we set this RelayClientAuthentication property to RelayAccessToken, we would have to modify the configuration file for Add Service Reference to include a behaviors element that will contain the token credentials for accessing the relay metadata exchange endpoint. So, for ease of use and demonstration, we are setting this to None.
Displays the URI for the relay metadata exchange endpoint. The value is derived by appending “_mex” to the relay service endpoint URI.
The following screenshot shows the specified properties:
Click Apply and then click Next.
In the Summary page, review the summary and click Finish. The wizard creates the WCF service (.svc) and a web.config for the service and adds it to the Visual Studio project.
As you saw in the last procedure, the wizard creates both on-premise and Service Bus endpoints for the WCF service. We also saw that the on-premise endpoint only supports wsHttpBinding and has to be hosted locally, which can only have an https scheme. Hence, to ensure that the local endpoint is hosted successfully, we must add https to the list of supported bindings. For information on how to add bindings to a site, see http://technet.microsoft.com/en-us/library/cc771629.aspx.
We are now all set to publish the service. Perform the follow steps to publish the service on the cloud:
Open IIS Manager and verify whether a site directory is created.
Note: The steps listed below are applicable to IIS 7.5 (as part of Windows Server 2008 R2 or Windows 7) with Windows Server AppFabric installed. These steps are not applicable to IIS 7.0 on Windows Server 2008 and Windows Vista. That is because IIS 7.0 does not support auto-start for services. For Windows Server 2008 and Windows Vista, the workaround to start to bring up the services is to hit the on-premises endpoints manually, which will bring up the entire service including the Service Bus endpoints.
You must configure auto-start for the service to start automatically. But why do you need to configure this? Here’s why: A client can consume a service only when the service endpoint is available to the client. For a service hosted on-premises, the corresponding relay service endpoint will be registered on the Service Bus only when the on-premises service starts. But the on-premises service will not start until the first client request comes through. So, there’s a deadlock where the client is waiting for the service to come up and the service is waiting for the client to invoke it. To get around this deadlock, we can configure the service to start automatically without waiting for the first client request.
This section provides information on how to configure auto-start for the services.
In the dialog box informing that all the services will be recycled, click Yes.
As a practice, you can verify if the Service Bus endpoints for the WCF service are published. While configuring the service, we had set a (EndpointDiscovery) property that would make all the endpoints publicly discoverable. So, to verify whether the endpoints are published, all we need to do is to view all the available endpoints in the Service Bus ATOM feed page for the specified service namespace. The URL for the Service Bus ATOM feed page has the following format:
In this procedure, the service namespace we used was ContosoNS. So the URL will be:
Type this URL in a Web browser and press Enter. It should list all the endpoints available under the specified service bus namespace. If the service you created is registered successfully with the Service Bus, the new endpoints will also be listed on the page.
In this section, we will create a client to consume the WCF service for which we created a relay service and hosted on the Service Bus. The client will take an employee number as an input and will present the stock details for that employee ID. You can create any type of client to invoke the service. For example, you can also create SharePoint client to invoke the Select operation that is invoked as a WCF service. However, to consume the WCF Service through a SharePoint client you must have selected the Create WCF Adapter Service for SharePoint client checkbox on the Welcome page of the WCF Adapter Service Development Wizard. In this section, for ease of understanding, we will create a simple console application.
Enter the employee ID for which you want to retrieve the stock details: 10001
The stock details for employee ID 10001 are:
Company Name :Fabrikam
Ticker Symbol :FABK
Total Value :924.80
Press any key to exit...
This section lists some known issues with suggested workarounds for the WCF Adapter Service Development wizard.
The WCF Adapter Service Development wizard may fail to work properly if it encounters Unicode characters. For example, the wizard might not give the desired results if the LOB artifacts being exposed as services have Unicode characters in their names. Similarly, the wizard might not function properly if the ServicePath you specified in the Configure Endpoints page has Unicode characters. You should not use Unicode characters when working with WCF Adapter Service Development wizard.
The WCF Adapter Service Development wizard has accessibility issues when used at low resolutions. Only resolutions higher than 1024 x 768 are recommended.
Windows Azure AppFabric SDK V1.0 September update fails to install on a 64-bit machine if only 32-bit version of BizTalk Adapter Pack 2010 is already installed on the same computer. This issue has been fixed in later updates of the SDK V1.0. To workaround this issue, you can do one of the following:
Through MSDN Code Gallery you can find the following sample based on this article:
There is no script for SQL Stocks Table.
Very good wiki article! Easy to read and understand!
I posted a sample on Code Gallery based on this Wiki Article: code.msdn.microsoft.com/BizTalk-AppFabric-Connect-cfa41a92