Building a WCF Service

Building a WCF service is not hard to accomplish. If you are working from a .NET Framework 2.0 environment, you need to install the .NET Framework 3.0.

Tip 

You can find out where to download the .NET Framework 3.0 from Microsoft’s .NET Framework portal at http://msdn.microsoft.com/netframework/.

From there, to build WCF services directly in Visual Studio 2005, you need to install the Visual Studio 2005 extensions for .NET Framework 3.0 (WCF and WPF). Download these Visual Studio extensions if you’re using Visual Studio 2005. At the end of 2007, Microsoft should release the next version of Visual Studio, which will include these extensions by default. Installing the extensions into Visual Studio 2005 will add a WCF project to your IDE. This view of the project from the New Project dialog is presented in Figure 30-2.

Figure 30-2

When you build a WCF project in this manner, the idea is that you build a traditional class library that is compiled down to a DLL that can then be added to another project. The separation of code and projects is a powerful division on larger projects. That said, though, you can also just as easily build a WCF service directly in your .NET project, whether that is a console application or a Windows Forms application. The approach taken for the examples in this chapter show you how to build a WCF service that is hosted in a console application. Keep in mind that for the services you actually build and deploy, it is usually better to build them directly as a WCF Service Library project and use the created DLL in your projects or in IIS itself.

Before we jump into building a WCF service, first consider what makes up a service built upon the WCF framework.

What Makes a WCF Service

When looking at a WCF service, it is important to realize that it is made up of three parts: the service, one or more endpoints, and an environment in which to host the service.

A service is a class that is written in one of the .NET-compliant languages. The class can contain one or more methods that are exposed through the WCF service. A service can have one or more endpoints. An endpoint is used to communicate through the service to the client.

Endpoints themselves are also made up of three parts. These parts are usually defined by Microsoft as the ABC of WCF. Each letter of WCF means something in particular in the WCF model. Similarly,

• “A” is for address

• “B” is for binding

• “C” is for contract

Basically, you can think of this as follows: “A” is the where, “B” is the how, and “C” is the what. Finally, a hosting environment is where the service is contained. This constitutes an application domain and process. All three of these elements (the service, the endpoints, and the hosting environment) are put together to create a WCF service offering, as depicted in Figure 30-3.

Figure 30-3

The next step is to create a basic service using the WCF framework.

Creating Your First WCF Service

To build your service, prior to hosting it, two main steps need to occur. The first is to create a service contract, followed by a step to create a data contract. The service contract is really a class with the methods that you want to expose from the WCF service. The data contract is a class that specifies the structure you want to expose from the interface.

Once you have a service class in place, you can host it almost anywhere you want. This example shows you how to host the WCF service inside a console application. Therefore, first create a new console application project called VbWCF_Service1.

To create a WCF service, you need to make a reference to the System.ServiceModel.dll. To do this, right-click on the console application project in the Solution Explorer and select Add Reference from the provided menu. In the .NET tab of the Add Reference dialog, shown in Figure 30-4, is the .NET Framework 3.0 version of the System.ServiceModel.dll (though it has a runtime version v2.0.50727).

Figure 30-4

Note that we are only going to host the WCF service from the console application. The WCF service is something that you would normally build as its own entity, such as the WCF Class Library project, and then include the created DLL into your host, such as the console application.

This example first demonstrates how to build the WCF service. The next step is the requirements that need to be put into place for the service to be hosted in the console application.

Creating the Interface

To create your service you need a service contract. The service contract is the interface of the service. This consists of all the methods exposed as well as the input and output parameters that are required to invoke the methods. To accomplish this task, create a class file in your project called Calculator.vb. The interface you need to create is presented here:

  Imports System Imports System.ServiceModel <ServiceContract()> _ Public Interface ICalculator     <OperationContract()> _     Function Add(ByVal a As Integer, ByVal b As Integer) As Integer     <OperationContract()> _     Function Subtract(ByVal a As Integer, ByVal b As Integer) As Integer     <OperationContract()> _     Function Multiply(ByVal a As Integer, ByVal b As Integer) As Integer     <OperationContract()> _     Function Divide(ByVal a As Integer, ByVal b As Integer) As Integer End Interface Public Class Calculator End Class 

This is pretty much the normal interface definition you would expect, but with a couple of new attributes included. To gain access to these required attributes, you need to make a reference to the System.ServiceModel namespace. This will give you access to the <ServiceContract()> and <OperationContract()> attributes.

The <ServiceContract()> attribute is used to define the class or interface as the service class, and it needs to precede the opening declaration of the class or interface. In this case, the example in the preceding code is based upon an interface:

 <ServiceContract()> _ Public Interface ICalculator    ' Code removed for clarity End Interface Within the interface, four methods are defined. Each of these methods are going to be exposed through the WCF service as part of the service contract, and for this reason, they are all required to have the <OperationContract()> attribute applied to them.     <OperationContract()> _     Function Add(ByVal a As Integer, ByVal b As Integer) As Integer

Utilizing the Interface

The next step is to create a class that implements the interface. Not only is the new class implementing the interface defined, it is also implementing the service contract. You can add this class to the same Calculator.vb file. The following code illustrates the implementation of this interface:

 Imports System Imports System.ServiceModel <ServiceContract()> _ Public Interface ICalculator     <OperationContract()> _     Function Add(ByVal a As Integer, ByVal b As Integer) As Integer     <OperationContract()> _     Function Subtract(ByVal a As Integer, ByVal b As Integer) As Integer     <OperationContract()> _     Function Multiply(ByVal a As Integer, ByVal b As Integer) As Integer     <OperationContract()> _     Function Divide(ByVal a As Integer, ByVal b As Integer) As Integer End Interface

  Public Class Calculator     Implements ICalculator     Public Function Add(ByVal a As Integer, ByVal b As Integer) As Integer _        Implements ICalculator.Add         Return (a + b)     End Function     Public Function Subtract(ByVal a As Integer, ByVal b As Integer) As Integer _        Implements ICalculator.Subtract         Return (a - b)     End Function     Public Function Multiply(ByVal a As Integer, ByVal b As Integer) As Integer _        Implements ICalculator.Multiply         Return (a * b)     End Function     Public Function Divide(ByVal a As Integer, ByVal b As Integer) As Integer _        Implements ICalculator.Divide         Return (a / b)     End Function End Class 

From these new additions, you can see that nothing is done differently with the Calculator class than what you might do otherwise. It is a simple class that implements the ICalculator interface and provides implementations of the Add(), Subtract(), Multiply(), and Divide() methods.

With the interface and the class available, you now have your WCF service built and ready to go. The next step is to get the service hosted. Note that this is a simple service. One of the simplicities of the service is that it only exposes simple types, rather than a complex type. This enables you to build only a service contract and not have to deal with the construction of a data contract. The construction of data contracts is presented later in this chapter.

Hosting the WCF Service in a Console Application

The next step is to take the service just developed and host it in some type of application process. You have many available hosting options, including the following:

• Console applications

• Windows Forms applications

• Windows Presentation Foundation applications

• Managed Windows Services

• Internet Information Services (IIS) 5.1

• Internet Information Services (IIS) 6.0

• Internet Information Services (IIS) 7.0 and the Windows Activation Service (WAS)

As stated earlier, this example hosts the service in a simple console application. There are a couple of ways to activate hosting - either through the direct coding of the hosting behaviors or through declarative programming (usually done via the configuration file).

For this example, the console application will define the host through coding the behaviors of the host environment directly. Following is the code for the console application, through the Module1.vb file (this block is referred to later in the chapter as the console-application code example):

  Imports System Imports System.ServiceModel Imports System.ServiceModel.Description Module Module1     Sub Main()         Using serviceHost As ServiceHost = New ServiceHost(GetType(Calculator))             Dim ntb As NetTcpBinding = New NetTcpBinding(SecurityMode.None)             serviceHost.AddServiceEndpoint(GetType(ICalculator), ntb, _                New Uri("net.tcp://192.168.1.102:8080/Calculator/"))             Dim smb As New ServiceMetadataBehavior()             smb.HttpGetEnabled = True             smb.HttpGetUrl = New Uri("http://localhost:8000/docs")             serviceHost.Description.Behaviors.Add(smb)             serviceHost.Open()             Console.WriteLine("Press the <ENTER> key to close the host.")             Console.ReadLine()         End Using     End Sub End Module 

A couple of things are going on in this file. First, to gain access to working with any of the WCF framework pieces, you need a reference to the System.ServiceModel and the System.ServiceModel.Description namespaces in the file. The System.ServiceModel gives you access to defining things like the endpoints that you need to create, while the System.ServiceModel.Description namespace reference gives you access to defining things like the WSDL file.

Remember that creating endpoints uses the ABC model (address, binding, and contract). The address part here is net.tcp://192.168.1.102:8080/Calculator. The binding is a TCP binding - NetTcpBinding - while the contract part is the ICalculator interface.

Tip 

The 192.168.1.102 IP address is specific to my machine; you should use your own IP address for the example. You can get your IP address by typing ipconfig at a command prompt.

Many different bindings are available to you when coding WCF services. In this case, this example makes use of the NetTcpBinding. The full list available is as follows:

• System.ServiceModel.BasicHttpBinding

• System.ServiceModel.Channels.CustomBinding

• System.ServiceModel.MsmqBindingBase

• System.ServiceModel.NetNamedPipeBinding

• System.ServiceModel.NetPeerTcpBinding

• System.ServiceModel.NetTcpBinding

• System.ServiceModel.WSDualHttpBinding

• System.ServiceModel.WSHttpBindingBase

Clearly, several bindings are available to you. In the preceding example, the NetTcpBinding class is the named pipe being used. This means that the service being built will be delivered over TCP.

In the first step of the example, for console-application code, a ServiceHost is established:

 Using serviceHost As ServiceHost = New ServiceHost(GetType(Calculator))    ' Code removed for clarity End Using

By working with the Using keyword, when the End Using statement is encountered, the ServiceHost object is destroyed. In the creation of the host, the Calculator type is assigned. From there, the endpoint is established. In this case, a NetTcpBinding object is created with a security setting of None through the command SecurityMode.None:

 Dim ntb As NetTcpBinding = New NetTcpBinding(SecurityMode.None)

This means that no security is applied to the message. The other options include Message, Transport, and TransportWithMessageCredential. The Message option signifies that the security credentials will be included in the message itself (in the SOAP header, for instance), while the Transport option signifies that the transport protocol will take care of the security implementation. The last option, TransportWithMessageCredential, means that the message contains some security credentials along with the transport protocol working for the same cause.

Once the NetTcpBinding object is in place, the next step is to finalize the endpoint creation. This is done through the use of the ServiceHost object’s AddServiceEndpoint() method:

 serviceHost.AddServiceEndpoint(GetType(ICalculator), ntb, _                New Uri("net.tcp://192.168.1.102:8080/Calculator/"))

From this, you can see that the entire ABC statement is used in the creation of the endpoint, although not necessarily in ABC order; in fact, the first item defined is actually the “C” - the contract. This is done through the GetType(ICalculator) setting. The “B” is next (the binding) with the reference to the NetTcpBinding object. Then, finally, the “A” is defined through an instantiation of a Uri object pointing to net.tcp://192.168.1.102:8080/Calculator/.

The next step is a process to bring forth the WSDL document so that it can be viewed by the developer consuming this service:

 Dim smb As New ServiceMetadataBehavior() smb.HttpGetEnabled = True smb.HttpGetUrl = New Uri("http://localhost:8000/docs") serviceHost.Description.Behaviors.Add(smb)

This bit of code is the reason the System.ServiceModel.Description namespace is imported into the file at the beginning. Here, a ServiceMetadataBehavior object is created, the object’s HttpGetEnabled property is set to True, and the HttpGetUrl property is provided an address of http://localhost:8000/docs. The documents can be located at any location of your choosing.

Once the ServiceMetadataBehavior object is created as you wish, the next step is associate this object to the ServiceHost through the serviceHost.Description.Behaviors.Add() method.

After all of these items are defined, you only need to open the ServiceHost for business, using the serviceHost.Open() method. The console application is kept alive through the use of a Console.ReadLine() method call, which waits for the end user to press the Enter key before shutting down the application. You want the Console.ReadLine() command there because you want to keep the host open.

Compiling and running this application produces the results illustrated in Figure 30-5.

Figure 30-5

Reviewing the WSDL Document

The preceding console-application code provides an instantiation of the ServiceMetadataBehavior object and defines a Uri object for it as well. You can simply type in that address to get at the WSDL file for the service you just built. Therefore, calling http://localhost:8000/docs provides the WSDL file shown in Figure 30-6.

Figure 30-6

With this WSDL file, you can now consume the service it defines through TCP. Note the following element at the bottom of the document:

  <wsdl:service name="Calculator">    <wsdl:port name="NetTcpBinding_ICalculator"     binding="tns:NetTcpBinding_ICalculator">       <soap12:address location="net.tcp://192.168.1.102:8080/Calculator/" />       <wsa10:EndpointReference>          <wsa10:Address>net.tcp://192.168.1.102:8080/Calculator/</wsa10:Address>       </wsa10:EndpointReference>    </wsdl:port> </wsdl:service> 

This element in the XML document indicates that in order to consume the service, the end user needs to use SOAP 1.2 over TCP. This is presented through the use of the <soap12:address> element in the document. The <wsa10:EndpointReference> is a WS-Addressing endpoint definition.

Using this simple WSDL document, you can now build a consumer that makes use of this interface.