Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1363 Chapter 29: Building and Consuming Services 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 understand 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.ThesepartsareusuallydefinedbyMicrosoftas the ABC of WCF. Each letter of WCF means something in particular in the WCF model, including the following: ❑ ‘‘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 29-19. Endpoint Endpoint Endpoint Endpoint Endpoint Endpoint Service method Service method WCF Service Application Domain Process Figure 29-19 The next step is to create a basic service using the WCF framework. 1363 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1364 Chapter 29: Building and Consuming Services Creating Your First WCF Service To build your service, prior to hosting it, you must perform two main steps. First, you need to create a service contract. Second, you must 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 speci- fies the structure you want to expose from the interface. Once you have a service class in place, you can host it almost anywhere. When running this from Visual Studio 2008, you w ill be able to use the same built-in hosting mechanisms that are used by any standard ASP.NET application. To build your first WCF application, select File➪New➪Web Site from the Visual Studio 2008 menu and call the project WCFService1 . The example this chapter will run through here demonstrates how to build the WCF service by build- ing the interface, followed by the service itself. Creating the service framework The first step is to create the services framework in the project. To do this, right-click on the project and select Add New Item from the provided menu. From this dialog box, select WCF Service, and name the service Calculator.svc, as illustrated in Figure 29-20. Figure 29-20 This step creates a Calculator.svc file, a Calculator.cs file, and an ICalculator.cs file. The Calcu- lator.svc file is a simple file that includes only the page directive, whereas the Calculator.cs does all the heavy lifting. The Calculator.cs file is an implementation of the ICalculator.cs interface. 1364 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1365 Chapter 29: Building and Consuming Services Working with 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, turn to the ICalculator.vb or ICalculator.cs (depending on the language you are using). The interface you need to create is presented in Listing 29-27. Listing 29-27: Creating the interface VB 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 C# using System.ServiceModel; [ServiceContract] public interface ICalculator { [OperationContract] int Add(int a, int b); [OperationContract] int Subtract(int a, int b); [OperationContract] int Multiply(int a, int b); [OperationContract] int Divide(int a, int b); } 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. 1365 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1366 Chapter 29: Building and Consuming Services 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 method is going to be exposed through the WCF ser- vice as part of the service contract. For this reason, each method is required to have the < OperationContract() > attribute applied. <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 defined interface, it is also implementing the service contract. For this example, add this class to the same Calculator.vb or .cs file. The following code, illustrated in Listing 29-28, shows the implementation of this interface. Listing 29-28: Implementing the interface VB 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 _ 1366 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1367 Chapter 29: Building and Consuming Services Implements ICalculator.Divide Return (a / b) End Function End Class C# public class Calculator : ICalculator { public int Add(int a, int b) { return (a + b); } public int Subtract(int a, int b) { return (a - b); } public int Multiply(int a, int b) { return (a * b); } public int Divide(int a, int b) { return (a / b); } } From these new additions, you can see that you don’t have to do anything different to the Calculator class. It is a simple class that implements the ICalculator interface a nd 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 — it exposes only 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 1367 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1368 Chapter 29: Building and Consuming Services ❑ 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 the developer Web server provided by Visual Studio 2008. 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). Compiling and running this application produces the results illustrated in Figure 29-21. Figure 29-21 You will notice that this is quite similar to how it appears when you build an ASP.NET Web service. Reviewing the WSDL Document The page presented in Figure 29-21 was the information page about the service. In the image, notice that there is also a link to the WSDL file of the service. As with ASP.NET Web services, you find that a WCF service can also auto-generate the WSDL file. Clicking on the WSDL link shows the WSDL in the browser, as illustrated in Figure 29-22. 1368 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1369 Chapter 29: Building and Consuming Services Figure 29-22 With this WSDL file, you can consume the service it defines through an HTTP binding. Note the following element at the bottom of the document, as shown in Listing 29-29. Listing 29-29: The part of the WSDL file showing the service’s endpoint <wsdl:service name="Calculator"> <wsdl:port name="WSHttpBinding_ICalculator" binding="tns:WSHttpBinding_ICalculator"> <soap12:address location="http://localhost:51715/WCFService1/Calculator.svc" /> <wsa10:EndpointReference> <wsa10:Address>http://localhost:51715/WCFService1/Calculator.svc </wsa10:Address> <Identity xmlns="http://schemas.xmlsoap.org/ws/2006/02/addressingidentity"> <Upn>Lipper-STL-LAP \ Bill</Upn> </Identity> </wsa10:EndpointReference> </wsdl:port> </wsdl:service> 1369 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1370 Chapter 29: Building and Consuming Services This element in the XML document indicates that in order to consume the service, the end user needs to use SOAP 1.2 over HTTP. This is presented through the use of t he < 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. Building the WCF Consumer Now that an HTTP service is out there, which you built using the WCF framework, the next step is to build a consumer application in ASP.NET that uses the simple Calculator service. The consumer sends its request via HTTP using SOAP. This section describes how to consume this service. The first step is to open Visual Studio 2008 and create a new ASP.NET application. Although we are using an ASP.NET application, you can make this consumer call through any other application type within .NET as well. Call the new ASP.NET application WCFConsumer . This application consumes the Calculator service, so it should be laid out with two text boxes and a button to initiate the service call. For this example, we will only use the Add() method of the service. Adding a Service Reference Once you have laid out your ASP.NET page, make a reference to the new WCF service. You do this in a manner quite similar to how it is done with XML Web service references. Right-click on the solution name from the Solution Explorer in Visual Studio and select Add Service Reference from the dialog box. This capability to add a service reference is new to Visual Studio 2008 — previously, you had only the Add Reference and Add Web Reference options. Once you have selected Add Service Reference, you are presented with the dialog box shown in Figure 29-23. The Add Service Reference dialog box asks you for two things: the Service URI or Address (basically a pointer to the WSDL file) and the name you want to give to the reference. The name you provide the refer- ence is the name that will be used for the instantiated object that enables you to interact with the service. Referring to Figure 29-23, you can see that the name provided to the Service Address setting is what is used for the running service from earlier in this chapter. Press OK in the Add Service Reference dia- log box. This adds to your project a Service References folder containing some proxy files, as shown in Figure 29-24. Indeed, the Service References folder is added and two files are contained within this folder: CalculatorService.map and CalculatorService.vb . The other important addition to note is the Sys- tem.ServiceModel reference, made for you in the References folder. This reference was not there before you made reference to the service through the Add Service Reference dialog. 1370 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1371 Chapter 29: Building and Consuming Services Figure 29-23 Figure 29-24 1371 Evjen c29.tex V2 - 01/28/2008 3:53pm Page 1372 Chapter 29: Building and Consuming Services Configuration File Changes Looking at the web.config file, you can see that Visual Studio has placed information about the service inside the document, as illustrated in Listing 29-30. Listing 29-30: Additions made to the web.config file by Visual Studio <system.serviceModel> <bindings> <wsHttpBinding> <binding name="WSHttpBinding_ICalculator" closeTimeout="00:01:00" openTimeout="00:01:00" receiveTimeout="00:10:00" sendTimeout="00:01:00" bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard" maxBufferPoolSize="524288" maxReceivedMessageSize="65536" messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true" allowCookies="false"> <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384" maxBytesPerRead="4096" maxNameTableCharCount="16384"/> <reliableSession ordered="true" inactivityTimeout="00:10:00" enabled="false"/> <security mode="Message"> <transport clientCredentialType="Windows" proxyCredentialType="None" realm=""/> <message clientCredentialType="Windows" negotiateServiceCredential="true" algorithmSuite="Default" establishSecurityContext="true"/> </security> </binding> </wsHttpBinding> </bindings> <client> <endpoint address="http://localhost:51715/WCFService1/Calculator.svc" binding="wsHttpBinding" bindingConfiguration="WSHttpBinding_ICalculator" contract="ServiceReference.ICalculator" name="WSHttpBinding_ICalculator"> <identity> <userPrincipalName value="Lipper-STL-LAP \ Bill"/> </identity> </endpoint> </client> </system.serviceModel></ServiceReference> The important part of this configuration document is the < client > element. This element contains a child element called < endpoint > that defines the where and how of the service consumption process. The < endpoint > element provides the address of the service — http://localhost:51715/ WCFService1/Calculator.svc — and it specifies which binding of the available WCF bindings should be used.Inthiscase,the wsHttpBinding is the required b inding. Even though you are using an established binding from the WCF framework, from the client side you can customize how this binding behaves. The settings that define the behavior of the binding are specified using the bindingConfiguration attribute of the < endpoint > element. In this case, the value provided to the bindingConfiguration attribute 1372 . applications 136 7 Evjen c29.tex V2 - 01/28/2008 3: 53 pm Page 136 8 Chapter 29: Building and Consuming Services ❑ Managed Windows Services ❑ Internet Information Services (IIS) 5. 1 ❑ Internet Information. dialog. 137 0 Evjen c29.tex V2 - 01/28/2008 3: 53 pm Page 137 1 Chapter 29: Building and Consuming Services Figure 29- 23 Figure 29-24 137 1 Evjen c29.tex V2 - 01/28/2008 3: 53 pm Page 137 2 Chapter 29: Building. in Listing 29 -30 . Listing 29 -30 : Additions made to the web.config file by Visual Studio <system.serviceModel> <bindings> <wsHttpBinding> <binding name="WSHttpBinding_ICalculator"