Export (0) Print
Expand All

How to: Design a WCF Service Contract for use with Service Bus

Updated: June 18, 2014

After you have created your Microsoft Azure Service Bus project, you can start writing code. The first step in writing the code is to define the interface that your service application uses to communicate with the client application. This interface, known as a service contract, is almost identical to a Windows Communication Foundation (WCF) contract: it defines the name of the interface, and also to the methods and properties exposed by the interface. You can use WCF-style attributes to add information to the contract, and you use the same syntax to do this. The main difference is that the Service Bus relay is an extension of WCF. Therefore, you must also define a channel to connect to Service Bus. However, other extensions of WCF use a similar channel. Therefore, the channel itself is not unique to Service Bus. The following discussion is a brief overview of creating a Service Bus contract.

As with WCF, both the service and client applications are required to have a copy of the contract in their code. There are four ways this can occur:

  1. Manually define the contract – this is the default, and is used most often when you are developing the interface. A simplified process for doing this is shown later in this section. For a complete discussion, see Designing Service Contracts in the WCF documentation.

  2. Copy the contract from the service code – this involves copying and pasting the contract from the service code, or sharing the project. This is accomplished when you have quick access to the code, for example, when you are also the developer writing the client. Many of the sample applications in the Azure SDK share the same interface definition, because both the client and service are in the same project.

  3. Use the ServiceModel Metadata Utility Tool (Scvutil.exe) – this is an application that you point to an exposed metadata endpoint on a running service application. It returns a file that contains the associated service contract. A simplified procedure for doing this is described later in this section. For a complete discussion, see Accessing Services Using a WCF Client and ServiceModel Metadata Utility Tool (Svcutil.exe) in the WCF documentation. The main difference in using Svcutil.exe on a Service Bus application is that the URI passed to the tool is for Service Bus, instead of the local host. Note that Svcutil.exe requires the target service to have the appropriate metadata exposed. For more information, see How to: Expose a Metadata Endpoint.

  4. Add a service reference through Visual Studio – this is the UI version of Svcutil.exe, and can be accessed through the Visual Studio environment. A simplified procedure for accessing the Add Service Reference dialog box is shown later in this section. For more information, see How to: Add, Update, or Remove a Service Reference in the Visual Studio documentation. As stated previously, adding a service reference requires that the target service expose the necessary information through a metadata endpoint.

  1. Create the service contract by applying the System.ServiceModel.ServiceContractAttribute attribute to the interface that defines the methods the service is to implement.

    [ServiceContract]
    public interface IMyContract
    {
        void Send(int count);
    }
    
    
  2. Indicate which methods in the interface a client can invoke by applying the System.ServiceModel.OperationContractAttribute attribute to them.

    [ServiceContract]
    public interface IMyContract
    {
        [OperationContract]
        void Send(int count);
    }
    
    
  3. It best to explicitly define the name of your contract, and also to the namespace of your application, when declaring the contract. Doing so prevents the infrastructure from using the default name and namespace values. Note that this is not the service namespace: in this case, it represents a unique identifier for your contract, and should contain some kind of versioning information.

    [ServiceContract(Name = "IMyContact", Namespace = "http://samples.microsoft.com/ServiceModel/Relay/MyContractV1")]
    public interface IMyContract
    {
        [OperationContract]
        void Send(int count);
    }
    
    
  4. Declare a channel that inherits from your interface and also from the IClientChannel interface.

    [ServiceContract(Name = "IMyContact", Namespace = "http://samples.microsoft.com/ServiceModel/Relay/MyContractV1")]
    public interface IMyContract
    {
        [OperationContract]
        void Send(int count);
    }
    
    public interface IOnewayChannel : IOnewayContract, IClientChannel { }
    
  5. If you are creating a service application, implement the interface elsewhere in your code.

  1. Ensure that the service is running before you try to retrieve the metadata.

  2. Use the command line to move to the location of the Svcutil.exe took in the Windows SDK.

    The default installation path is C:\Program Files\Microsoft SDKs\Windows\<version>\Bin.

    From the command line, run the following command:

    Svcutil.exe <service's Metadata Exchange (MEX) address or HTTP GET address>
    

    If the target address has the appropriate metadata exposed, you will retrieve a file that contains WCF client code that the client application can use to start the service application.

  1. In Solution Explorer, right-click the name of the project to which you want to add the service. Then click Add Service Reference.

    The Add Service Reference dialog box appears.

  2. In the Address box, enter the URL for the service. Then click Go to search for the service. If the service implements username/password security, you may be prompted for a username and password.

  3. In the Service list, expand the node for the service that you want to use, and then select a service contract.

  4. In the Namespace box, enter the namespace that you want to use for the reference.

  5. Click OK to add the reference to the project.

  6. A service client (proxy) is generated, and metadata describing the service is added to the App.config file.

Show:
© 2014 Microsoft