Windows Communication Foundation Using C#

Transcription

1 Windows Communication Foundation Using C# Student Guide Revision 2.1 Object Innovations Course 4153

2 Windows Communication Foundation Using C# Student Guide Information in this document is subject to change without notice. Companies, names and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Object Innovations. Product and company names mentioned herein are the trademarks or registered trademarks of their respective owners. is a registered trademark of Object Innovations. Authors: Robert J. Oberg, Julian Templeman and Ernani Cecon, Jr. Copyright 2010 Object Innovations Enterprises, LLC All rights reserved. Object Innovations Published in the United States of America. Copyright 2010 Object Innovations Enterprises, LLC ii

3 Table of Contents (Overview) Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5 Chapter 6 Chapter 7 Chapter 8 Introduction to WCF Addresses and Bindings Service Contracts Instance Management Data Contracts More about Service Contracts Handling Errors WCF Security Appendix A Appendix B Learning Resources Configuring IIS for ASP.NET Copyright 2010 Object Innovations Enterprises, LLC iii

4 Directory Structure Install the course software by running the selfextractor Install_WcfCs_21.exe. The course software installs to the root directory C:\OIC\WcfCs. Example programs for each chapter are in named subdirectories of chapter directories Chap01, Chap02 and so on. The Labs directory contains one subdirectory for each lab, named after the lab number. Starter code is frequently supplied, and answers are provided in the chapter directories. The Demos directory is provided for performing in-class demonstrations led by the instructor. Copyright 2010 Object Innovations Enterprises, LLC iv

5 Table of Contents (Detailed) Chapter 1: Introduction to WCF... 1 What Is WCF?... 3 WCF Services... 4 Service Orientation...6 WCF and Web Services... 7 WCF = ABC...8 Address, Binding, Contract... 9 Example Hello WCF Hosting Services Internet Information Services Internet Services Manager Virtual Directory Anonymous Access Configuring.svc Extension Demo Hello WCF A Service Contract A Website for the Service WCF Service Template Service Configuration Configuration Details Referencing the Class Library Examining the Service in the Browser WCF Clients Creating WCF Clients Demo A Client for Hello WCF Lab WCF Architecture WCF Architecture ServiceHost and ChannelFactory Service Contexts and Instances Summary Chapter 2: Addresses and Bindings Addresses Transports Bindings Message Exchange Patterns (MEPs) Security Choosing a Binding HTTP Bindings TCP and Named Pipe Bindings Copyright 2010 Object Innovations Enterprises, LLC v

6 MSMQ Bindings Working with Endpoints Importance of BasicHttpBinding Demo ASMX Web Service Client Lab 2A WCF Service Hosting ServiceHost Demo Self-Hosting Client Program without Proxy Class Using a Channel Factory Service Endpoints Multiple Endpoints Multiple Protocol Example Configuration Files Simplified Host Code Configuring Metadata Exchange Lab 2B Summary Chapter 3: Service Contracts Service Contracts at Class Level Service Contracts at Interface Level Benefits of Interface Level Definition A Service with Multiple Contracts ServiceContractAttribute ServiceContractAttribute Example Viewing WSDL Files Contract Inheritance Operation Overloading Enabling Operation Overloading Operation Overloading Client Lab Summary Chapter 4: Instance Management Behaviors WCF Behaviors Configuring Behaviors Configuring Behaviors in Code WCF Instancing Models Per-Call Instancing Per-Session Instancing Sessions and Threading Singleton Instancing Which Model to Use? PerSession Example Copyright 2010 Object Innovations Enterprises, LLC vi

7 PerCall Example Singleton Example Lab Summary Chapter 5: Data Contracts Data Contracts Data Contract Example Data Contract Demonstration XSD for Data Contract Client Demo Arrays Array in XML Schema Array in Proxy Generic Collections Generic Collection in XML Schema Generic Collection in Proxy Lab 5A Enumerations in Data Contracts Enumeration Data Contract Example Employee Client Program Saving and Restoring Serialization in WCF Serialization in.net Serialization Example SOAP Serialization DataContract Serialization JSON Serialization Using XmlSerializer XmlSerializer Example Restoring Data Versioning New and Missing Members Versioning Demonstration New Client of Old Service Round Trip Required Members OnDeserializing Event Lab 5B Summary Chapter 6: More about Service Contracts Versioning Service Contracts Versioning Example Version 1 Service Version 2 Service Copyright 2010 Object Innovations Enterprises, LLC vii

8 New Operations Version 3 Service Version 1 Client / Version 3 Service Message Exchange Patterns Request-Reply Oneway Oneway Example Duplex Callbacks Invoking a Callback Callback on the Client Asynchronous Proxies Threading Considerations Lab Summary Chapter 7: Handling Errors Errors in Distributed Systems Errors in.net and WCF Demo of WCF Error Behavior Service Library Code Client Code Client Exception Handling Exception Handling Demo Fault Exceptions Faults Exception Details in Faults Exception Details Demo Exceptions Dialog Fault Contracts Fault Contract Example Fault Contract Example Client Custom Faults Faulted Channels Lab Summary Chapter 8: WCF Security Services and Security Security Aspects of Services Transfer Security Transport Security Scenarios for Transport Security Configuring Transport Security Transport Security Example Host s Security Configuration Copyright 2010 Object Innovations Enterprises, LLC viii

9 Client s Security Configuration Message Security Scenarios for Message Security Configuring Message Security Other Security Modes Certificates Certificate Demo Client Certificate Configuration Sending Credentials Username Credentials Username Example Lab Summary Appendix A: Learning Resources Appendix B: Configuring IIS for ASP.NET ASP.NET Versions Side-by-Side Configuring for ASP.NET Installing ASP.NET Copyright 2010 Object Innovations Enterprises, LLC ix

10 Copyright 2010 Object Innovations Enterprises, LLC x

11 WcfCs Chapter 1 Chapter 1 Introduction to WCF Copyright 2010 Object Innovations Enterprises, LLC 1

12 WcfCs Chapter 1 Introduction to WCF Objectives After completing this unit you will be able to: Explain how WCF unites and extends existing distribution technologies. Understand the importance of address, binding and contract to WCF services. Create a simple WCF service hosted in IIS. Implement a client of a WCF service. Understand the WCF architecture and runtime. Copyright 2010 Object Innovations Enterprises, LLC 2

13 WcfCs Chapter 1 What Is WCF? Windows Communication Foundation (WCF) is a new service-oriented programming framework for creating distributed applications. It was previously known as Indigo and is part of.net 3.0. WCF is designed to provide one mechanism for building connected applications: Within app domains Across app domains Across machines WCF builds upon and extends existing ways of building distributed applications: ASMX Web services,.net Remoting, COM, MSMQ. All these do the same basic job (connecting elements in distributed applications) but they are very different at the programming level, with complex APIs and interactions. WCF provides one model for programming distributed applications. Developers only need to learn one API. WCF leverages existing mechanisms. It uses TCP, HTTP and MSMQ for transport. Copyright 2010 Object Innovations Enterprises, LLC 3

14 WcfCs Chapter 1 WCF Services When using WCF, you create and consume services. A service comprises a set of related operations, which the programmer sees as method calls. Services are described by metadata, which clients can use to determine what operations are available, and how the service can be contacted. Metadata for WCF services is similar to the WSDL used by web services. Clients and services exchange messages. A client (which can be another service) communicates with a WCF service by sending and receiving messages. WCF uses SOAP as its messaging mechanism, and SOAP messages can be sent using a number of transports. Using SOAP does not imply that WCF communication is inefficient; efficient binary encodings are employed whenever possible. WCF supports several transports out of the box. TCP, HTTP, HTTPS and MSMQ. Custom transports can be added. Copyright 2010 Object Innovations Enterprises, LLC 4

15 WcfCs Chapter 1 WCF Services WCF supports the WS-* family of Web service protocols. The WS-* family of protocols have been developed by various bodies (including OASIS and W3C) to provide features such as security, transactions and reliable messaging to web services. WCF is very good at interop. Support for a wide range of transports, encodings and the WS-* protocols means that WCF services can interoperate with a wide range of platforms and technologies, including J2EE and web services using WS-* protocols. WCF provides a foundation for service orientation. WCF helps developers write distributed applications in which loosely coupled services are called by clients and one another. Copyright 2010 Object Innovations Enterprises, LLC 5

16 WcfCs Chapter 1 Service Orientation Service orientation is characterized by four concepts. Boundaries are explicit The boundary between client and service is explicit and highly visible, because calls are made via SOAP messages. There is no pretending as there is in DCOM and Java s RMI that you are simply playing with a remote object, and can thus ignore the cost of remoting. Services are autonomous Services are independent entities that each have their own life cycle; they may have been developed completely independently of one another. There is no run-time making sure that services work well together, and so services must be prepared to handle failure situations of all sorts. Share schemas and contracts, not classes Services are not limited to implementation in OO languages, and so service details cannot be provided in terms of classes. Services should share schemas and contracts, and these are typically described in XML. Use policy-based service compatibility Services should publish their requirements (i.e. Requiring message signing or HTTPS connections) in a machine readable form. This can be used at runtime to ensure compatibility between service and client. Copyright 2010 Object Innovations Enterprises, LLC 6

17 WcfCs Chapter 1 WCF and Web Services Even though it uses SOAP messaging, WCF is more than simply another way of writing Web services. WCF can be used to write traditional Web services, as well as more sophisticated services that can use the WS-* protocols. But the design of WCF means that it provides a far more general solution to distribution than Web services. WCF can use several transports. Web services tend to use HTTP or HTTPS, while WCF is configured to use TCP, HTTP, HTTPS and MSMQ. It is also possible to add new transports, should the need arise. WCF can work throughout the enterprise. WCF services can be hosted in-process, by a Windows Service or IIS. Message exchange will be optimized to use the most efficient method for exchanging data for a particular scenario. WCF is good at interop. WCF services can interoperate with a number of different platforms and technologies. WCF is highly customizable. It is possible to customize almost every part of WCF, adding or modifying transports, encodings and bindings, and plugging in new behaviors that affect the way WCF services work. Copyright 2010 Object Innovations Enterprises, LLC 7

18 WcfCs Chapter 1 WCF = ABC Client C B A A B C Service A B C A B C A B C = an endpoint A = address Where? B = binding How? C = contract What? Copyright 2010 Object Innovations Enterprises, LLC 8

19 WcfCs Chapter 1 Address, Binding, Contract An address defines where a service can be found. It will often be an HTTP address, although other addressing schemes are supported. A binding defines how a service can be contacted Via HTTP, TCP, MSMQ or some custom mechanism. A contract defines what a service can do. In terms of method calls, their arguments and return types. A combination of an address, a binding and a contract is called an endpoint. A service can expose more than one endpoint, and endpoint data can be made available to clients in the form of metadata. Copyright 2010 Object Innovations Enterprises, LLC 9

20 WcfCs Chapter 1 Example Hello WCF A contract defines a set of operations that a service supports. Define a contract as an interface decorated with the ServiceContract attribute. Decorate operations with the OperationContract attribute. [ServiceContract] public interface IHello [OperationContract] string SayHello(string name); A service class implements the interface. And so it has to implement all the operations defined in the contract. public class Hello : IHello public string SayHello(string name) return "Hello, " + name; Note that this code says nothing about how the client communicates with the service. It is only the 'C' of the service 'ABC'. Copyright 2010 Object Innovations Enterprises, LLC 10

21 WcfCs Chapter 1 Hosting Services There are three ways to host a WCF service. Self-hosting in an EXE. Use any type of EXE: Console application, Windows application (Windows Forms or WPF), or Windows Service. Need to manage service lifecycle yourself. Hosting in IIS. IIS will manage the service lifecycle for you, starting the service when the first request comes in. You can only use HTTP and port 80. Configure the service using a.svc file. Hosting in Windows Activation Service (WAS) WAS is a new feature that is part of Vista. Similar advantages to hosting in IIS, but you can use other transports and ports as well. WAS also uses.svc files. It is the preferred way of hosting services on Vista. Copyright 2010 Object Innovations Enterprises, LLC 11

22 WcfCs Chapter 1 Internet Information Services Our early examples use IIS hosting, so you will need to have Internet Information Services (IIS) installed on your system. IIS Version 5.x runs on Windows XP Professional, Version 6.x runs on Windows 2003, and version 7.0 runs on Vista. On Windows 2003 and Windows XP Professional, Internet Information Services is not installed by default. For Windows XP Professional, use the Control Panel and Add/Remove Windows Components. For Windows 2003 Installation details, see the instructions in MSDN. You can use either the Manage Your Server wizard or the Control Panel Add/Remove Windows Components. In this course we will illustrate the use of IIS 5.x on Windows XP. Appendix B discusses some IIS configuration issues, which are especially critical if you have more than one version of.net installed on your computer. Copyright 2010 Object Innovations Enterprises, LLC 12

23 WcfCs Chapter 1 Internet Services Manager The management tool for IIS is a Microsoft Management Console (MMC) snap-in, the Internet Services Manager, which you can find under Administrative Tools in the Control Panel. You can Start and Stop the Web server and perform other tasks by right-clicking on Default Web Site. Choosing Properties from the context menu will let you perform a number of configurations on the Web server. The default home directory for publishing Web files is \Inetpub\wwwroot on the drive where Windows is installed. You can change this home directory using Internet Services Manager. Copyright 2010 Object Innovations Enterprises, LLC 13

24 WcfCs Chapter 1 Virtual Directory You can access Web pages stored at any location on your hard drive by creating a virtual directory. The easiest way to create one is from Windows Explorer. Right-click over the desired directory, choose Properties..., select the Web Sharing tab, click on the Add button, and enter the desired alias, which will be the name of the virtual directory. The figure on the next page illustrates creating an alias WcfCs, or virtual directory, for the folder \OIC\WcfCs. You should perform this operation now on your own system in order that you may follow along as the course examples are discussed. Copyright 2010 Object Innovations Enterprises, LLC 14

25 WcfCs Chapter 1 Virtual Directory (Cont d) Once a virtual directory has been created, you can access files in it by including the virtual directory in the path of the URL. Copyright 2010 Object Innovations Enterprises, LLC 15

26 WcfCs Chapter 1 Anonymous Access After you have created the virtual directory, examine its properties in Internet Information Services. Right-click on WcfCs and select Properties. Click on the Directory Security tab. In the Anonymous access and authentication control area, click the Edit... button. Make sure that the Anonymous access checkbox is checked. Copyright 2010 Object Innovations Enterprises, LLC 16

27 WcfCs Chapter 1 Configuring.svc Extension In IIS, right-click over the root virtual directory you are using. Select Properties from the context menu. The Properties dialog will come up. Make sure you have the Virtual Directory tab selected. Click the Configuration button. Copyright 2010 Object Innovations Enterprises, LLC 17

28 WcfCs Chapter 1 Configuring.svc Extension (Cont d) The Application Configuration dialog will come up. Make sure the Mappings tab is selected. Select the.svc extension, if present. Click Edit. If.svc is not present, click Add. Copyright 2010 Object Innovations Enterprises, LLC 18

29 WcfCs Chapter 1 Configuring.svc Extension (Cont d) The Add/Edit Application Extension Mapping dialog comes up. Make sure that the Executable box specifies the version of aspnet_isapi.dll that you are using. Click the Browse button to navigate to the correct version, if necessary. Click OK, OK, and OK. You should now be assured that the.svc extension will be recognized by ASP.NET. Copyright 2010 Object Innovations Enterprises, LLC 19

30 WcfCs Chapter 1 Demo Hello WCF We ll create a Hello WCF service, hosted in IIS. Our solution will have three projects: A class library implementing the service A website exposing the service via HTTP A Windows client that invokes the service 1. Use Visual Studio 2008 to create a new blank solution HelloWCF in the Demos folder. 2. In Solution Explorer, right-click over the solution and choose Add New Project. Copyright 2010 Object Innovations Enterprises, LLC 20

31 WcfCs Chapter 1 Demo Hello WCF (Cont d) 3. From the WCF project types choose the WCF Service Library template. Enter HelloLib as the name of your new project. 4. Change the name of the file Service1.cs to Hello.cs, and IService1.cs to IHello.cs. Examine the contents of these files, which include comments and starter code for both a Service Contract and also a Data Contract. Copyright 2010 Object Innovations Enterprises, LLC 21

32 WcfCs Chapter 1 A Service Contract 5. Edit IHello.cs to include only a simple service contract IHello with one method, SayHello(). namespace HelloLib [ServiceContract()] public interface IHello [OperationContract] string SayHello(string name); 6. Edit Hello.cs to include the class Hello, which implements the service contract. namespace HelloLib public class Hello : IHello public string SayHello(string name) return "Hello: " + name; 7. Build the service library project. Copyright 2010 Object Innovations Enterprises, LLC 22

33 WcfCs Chapter 1 A Website for the Service We will host our new WCF service using IIS. To do this, we ll add a website project to our solution. 1. In Solution Explorer, right-click on the solution and choose Add New Web Site. 2. For template choose WCF Service. For location select HTTP. Browse to the Demos\HelloWCF folder. You will be informed that HelloWCF is not marked as an application in IIS. Click Yes to open it anyway. Type in HelloSvc at the end of the path. Select the appropriate language. Copyright 2010 Object Innovations Enterprises, LLC 23

34 WcfCs Chapter 1 WCF Service Template 3. Examine the generated website files: IService.cs contains a sample service contract (in App_Code folder). Service.cs contains a sample service implementation (in App_Code folder). Service.svc provides a.svc endpoint, which helps the service model find the correct service type to host. Web.config provides service model configuration settings for the sample service. 4. Delete the files IService.cs and Service.cs from the project. We have already provided the service contract and implementation in the class library project. Our approach is flexible, making it easy to provide different hosts for our service. 5. Edit the file Service.svc to specify the service type, based on the namespace and class name of the service implementation. (This file is analogous to the.asmx file in ASP.NET Web services.) Also, delete the CodeBehind specification. Language=C# Debug="true" Service="HelloLib.Hello" %> Copyright 2010 Object Innovations Enterprises, LLC 24

35 WcfCs Chapter 1 Service Configuration Services can be configured in code or using config files XML configuration files are preferred, because they make it easier to reconfigure services, and to reuse services in different contexts without needing to rebuild the service code. When configuring IIS-hosted services, information on the service can be included in the Web.config file for the website. Data is placed in the <system.servicemodel> element 6. Continuing the demo, edit the generated Web.config file to show the service name and contract as specified in the class library project. <?xml version="1.0"?> <configuration xmlns="...">... <system.servicemodel> <services> <service name="hellolib.hello" behaviorconfiguration="servicebehavior"> <!-- Service Endpoints --> <endpoint contract="hellolib.ihello" binding="wshttpbinding">... </service> </services>... </system.servicemodel>... </configuration> Copyright 2010 Object Innovations Enterprises, LLC 25

36 WcfCs Chapter 1 Configuration Details From the XML configuration file shown above, you can deduce that An application can support more than one service By default, Visual Studio 2008 uses a combination of the namespace and the name you gave for the service as the service name in the config file. A service can define more than one endpoint Endpoints are independent of the hosting application type. Even though the simple service is hosted in a console application, it can specify an HTTP address in its endpoint. It is the job of the WCF runtime to make this work; it is of no concern to the service how client contact it. Endpoints are defined by address, binding and contract Any or all of these three can be defined in code, if you wish. It provides most flexibility if you specify them all in XML. Visual Studio 2008 will specify the address in code, leaving the binding and contract in the configuration file. Copyright 2010 Object Innovations Enterprises, LLC 26

37 WcfCs Chapter 1 Referencing the Class Library 7. In Solution Explorer, right-click over the website and choose Add Reference. 8. Select the Projects tab and make sure the HelloLib project is selected. 9. Observe that a Bin folder is created containing HelloLib.dll. Also, a number of assemblies are added to Web.config. Copyright 2010 Object Innovations Enterprises, LLC 27

38 WcfCs Chapter 1 Examining the Service in the Browser Since our service is hosted in IIS, we can examine the Service.svc file in the browser. 10. Build the solution. 11. Right-click over the website in Solution Explorer and choose Set as Startup Project. 12. Run the solution. When Internet Explorer comes up, point it to the Service.svc file. You should see a page similar to this: Copyright 2010 Object Innovations Enterprises, LLC 28

39 WcfCs Chapter 1 WCF Clients As in all common distribution technologies, clients interact with services through proxies. The proxy hides details of the communication mechanism being used from the client code. The proxy implements the same interface as the service, so that the client can use exactly the same calls. Proxies are created using metadata provided by the service. Note that the page shown in the previous page gives instructions for generating a proxy. The ABC (address, binding, contract) information provided by the service can be used to construct a proxy that Knows where to contact the service. Implements code to use the appropriate communication mechanism (eg. HTTP call versus TCP). Implements the operations defined in the service interface. Copyright 2010 Object Innovations Enterprises, LLC 29

40 WcfCs Chapter 1 Creating WCF Clients Visual Studio 2008 can create clients to WCF services in the same way as it creates them for Web services. The configuration file contains endpoint details. You can use the svcutil.exe command line tool to generate proxies. Useful when not using Visual Studio. It also provides more control over the proxy generation process. The client code creates a proxy and calls methods Use exception handling, because lots can go wrong in distributed applications. Copyright 2010 Object Innovations Enterprises, LLC 30

41 WcfCs Chapter 1 Demo A Client for Hello WCF We ll create a Windows Forms client. 1. Add a third project to the solution, this time a Windows Forms Application. Specify HelloWin as the name of your new project. Copyright 2010 Object Innovations Enterprises, LLC 31

42 WcfCs Chapter 1 Client Demo (Cont d) 2. Provide the following user interface. 3. In preparation for generating the proxy, one more time run the website project, and copy the URL you see to the Clipboard. (We are running the project simply to see what the URL is.) 4. In Solution Explorer, right-click over the HelloWin project and select Add Service Reference from the context menu. Copyright 2010 Object Innovations Enterprises, LLC 32

43 WcfCs Chapter 1 Client Demo (Cont d) 5. Paste in the URI for the service. Copyright 2010 Object Innovations Enterprises, LLC 33

44 WcfCs Chapter 1 Client Demo (Cont d) 6. In HelloWin verify that there is a reference to System.ServiceModel. (Added automatically when the service reference is added.) 7. Build the solution to make sure you get a clean compile for all three projects. 8. In Solution Explorer, click the Show All Files button. Observe there is now a file Reference.cs under Service References, that you can find in the structure shown in the figure. 9. Examine the file Reference.cs. This contains the code for the proxy. Note in particular that the proxy class is HelloClient, in the namespace HelloWin.ServiceReference In Form1.cs import the namespace HelloWin.ServiceReference1. using HelloWin.ServiceReference1; Copyright 2010 Object Innovations Enterprises, LLC 34

45 WcfCs Chapter 1 Client Demo (Cont d) 11. Add a handler for the Greet button and provide the following code to invoke the SayHello() method on the proxy. private void btngreet_click(object sender, EventArgs e) HelloClient proxy = new HelloClient(); txtresponse.text = proxy.sayhello(txtname.text); 12. Make HelloWin the startup project. 13. Build and run. You should be able to enter any name and get back a greeting from the service. 14. A copy of this completed demo is provided in the Chap01\HelloWCF folder. Copyright 2010 Object Innovations Enterprises, LLC 35

46 WcfCs Chapter 1 Lab 1 Creating a Simple Service and Client In this lab, you will use Visual Studio 2008 to create a simple WCF service that is hosted in IIS. You will then create a client Console application, use svcutil.exe to create a proxy for the service, and demonstrate that the client can contact the service. Detailed instructions are contained in the Lab 1 write-up at the end of the chapter. Suggested time: 45 minutes Copyright 2010 Object Innovations Enterprises, LLC 36

47 WcfCs Chapter 1 WCF Architecture Services and clients exchange SOAP messages. But they are not limited to text format; they can be sent in binary if that is more efficient. Channels abstract the communication process. Channels can be composed, so that the output from one channel acts as the input to another. There are two types of channel. Transport channels implement transport mechanisms Such as HTTP and TCP/IP. Protocol channels implement elements of the SOAPbased messaging protocol For example, the security channel implements SOAP security. The channel stack can be specified in configuration files or in code. Behaviors extend or modify service and client operation For example, whether metadata is published, or authentication is required. Behaviors can be specified in configuration or code. Copyright 2010 Object Innovations Enterprises, LLC 37

48 WcfCs Chapter 1 WCF Architecture Client Endpoints Service Proxy Dispatcher Protocol Channel(s) Protocol Channel(s) Transport Channel Transport Channel Client code creates a proxy. The client often uses a ChannelFactory object to create the proxy. The proxy sends messages through the channel stack to the Dispatcher, which makes a call to an endpoint on the service. Service code often uses ServiceHost objects to manage WCF services. Copyright 2010 Object Innovations Enterprises, LLC 38

49 WcfCs Chapter 1 ServiceHost and ChannelFactory ServiceHost is used on the server side. A ServiceHost is used to host services in code (ie. Selfhosted services). The ServiceHost creates a ServiceDescription object, which consists of a type (implementing the service), a collection of behaviors (which control how the service behaves) and descriptions of one or more endpoints. The WCF runtime uses the ServiceDescription to build the channel stack and configure the endpoints. ChannelFactory is used on the client side. A ChannelFactory creates a ClientDescription. This consists of a collection of behaviors, and one endpoint. There is no need for a type, because clients don t implement service contracts. The WCF runtime uses the ClientDescription to build the channel stack and proxy. Copyright 2010 Object Innovations Enterprises, LLC 39

50 WcfCs Chapter 1 Service Contexts and Instances Each.NET host process can contain one or more app domains, and each app domain may contain zero or more ServiceHosts. Within a ServiceHost, service instances live in contexts; a WCF context is similar to a COM+ (Enterprise Services) context or a.net context-bound object, in that it provides an environment in which service instances live. Properties and methods on the context allow the developer to control the behavior of the service instance, especially with respect to concurrency and object lifetime. A context can host at most one instance of a service object, so it is possible to have empty contexts. Host Process AppDomain ServiceHost Context Empty Context Service Object Copyright 2010 Object Innovations Enterprises, LLC 40

51 WcfCs Chapter 1 Summary WCF unifies a number of existing technologies for creating distributed applications. WCF services can be hosted in IIS, Windows applications, or WAS. WCF services and clients exchange SOAP messages. WCF services and clients can be configured in code, or via XML configuration files. WCF services are defined by addresses, bindings and contracts. Copyright 2010 Object Innovations Enterprises, LLC 41

52 WcfCs Chapter 1 Introduction Lab 1 Creating a Simple WFC Service and Client In this lab, you will use Visual Studio 2008 to create a simple WCF service that is hosted in IIS. You will then create a client Console application, use svcutil.exe to create a proxy for the service, and demonstrate that the client can contact the service. Suggested Time: 45 minutes. Root Directory: OIC\WcfCs Directories: Labs\Lab1 (create solution here) Chap01\Add (contains lab solution) Part 1: Creating the Service Library 1. Use Visual Studio 2008 to create an empty solution Add in the working directory. 2. Add a new project AddLib to your solution using the WCF Service Library template. 3. Rename the file IService1.cs to IAdd.cs and the file Service1.cs to Add.cs. 4. In the files IAdd.cs and Add.cs, delete the starter code except for the namespace imports and the declaration of the AddLib namespace. 5. In the file IAdd.cs, provide the following simple service contract ICalc. namespace AddLib [ServiceContract] public interface ICalc [OperationContract] int Add(int x, int y); 6. In the file Add.cs, provide the following implementation: public class Calc : ICalc public int Add(int x, int y) return x + y; Copyright 2010 Object Innovations Enterprises, LLC 42

53 WcfCs Chapter 1 7. Build the solution. Part 2: Creating the Service Website 1. Add a new Web Site AddSvc to your solution, using the WCF Service template. Use HTTP and the following URL: 2. Delete the files Service.cs and IService.cs from the Web Site. 3. Add a reference to the AddLib project. Observe that a Bin folder has been created, containing the assembly AddLib.dll. 4. Edit the file Service.svc to specify AddLib.Calc as the service. Language=C# Debug="true" Service="AddLib.Calc" %> 5. Edit Web.config to provide the proper names of the service and contract. <?xml version="1.0"?> <configuration xmlns=" <system.servicemodel> <services> <service name="addlib.calc" behaviorconfiguration="servicebehavior"> <!-- Service Endpoints --> <endpoint address="" binding="wshttpbinding" contract="addlib.icalc">... </endpoint> <endpoint address="mex" binding="mexhttpbinding" contract="imetadataexchange"/> </service> </services>... </system.servicemodel> 6. In Solution Explorer make the Web Site the startup project. 7. Build and run this project. When Internet Explorer comes up, point the browser to the Service.svc file. It should display a page with instructions for creating a proxy by running svcutil.exe. 8. Copy the syntax for running svcutil.exe at the command line into a new text file, which you should save under the name MakeProxy.bat. Copyright 2010 Object Innovations Enterprises, LLC 43

54 WcfCs Chapter 1 Part 3: Creating a Console Client 1. Add a third project to your solution, a Console application named AddCon. 2. Add a reference to System.ServiceModel. 3. Bring up the Visual Studio 2008 command prompt and run the MakeProxy.bat batch file that you created at the end of Part Copy the generated Calc.cs and output.config files to the AddCon folder. Rename output.config to app.config. 5. Add these files to the AddCon project. 6. Provide the following code in Program.cs to instantiate a proxy object and call the Add() method, displaying the result. static void Main(string[] args) CalcClient proxy = new CalcClient(); int sum = proxy.add(5, 7); Console.WriteLine("sum = 0", sum); Console.WriteLine("Press ENTER to exit"); Console.ReadLine(); 7. Make AddCon the startup project. 8. Build and run. Copyright 2010 Object Innovations Enterprises, LLC 44

55 WcfCs Chapter 3 Chapter 3 Service Contracts Copyright 2010 Object Innovations Enterprises, LLC 91

56 WcfCs Chapter 3 Service Contracts Objectives After completing this unit you will be able to: Define service contracts at either the class or interface level. Implement a service with multiple contracts. Show how contracts can be inherited. Explain operation overloading. Copyright 2010 Object Innovations Enterprises, LLC 92

57 WcfCs Chapter 3 Service Contracts at Class Level A service contract can be defined at the class level. Apply ServiceContract and OperationContract attributes directly to the class and its methods. [ServiceContract()] public class Hello [OperationContract] public string SayHello(string name) return "Hello: " + name; The class name becomes the name of the contract. <endpoint address="hello" binding="basichttpbinding" name="basichttp" contract="hellolib.hello" /> See ClassHello in the chapter directory for a complete example. Copyright 2010 Object Innovations Enterprises, LLC 93

58 WcfCs Chapter 3 Service Contracts at Interface Level A service contract can be defined at the interface level. Apply ServiceContract and OperationContract attributes to the interface and its methods. [ServiceContract()] public interface IHello [OperationContract] string SayHello(string name); A class then provides the implementation. public class Hello : IHello public string SayHello(string name) return "Hello: " + name; The interface name becomes the name of the contract. <endpoint address="hello" binding="basichttpbinding" name="basichttp" contract="hellolib.ihello" /> See InterfaceHello in the chapter directory for a complete example. Copyright 2010 Object Innovations Enterprises, LLC 94

59 WcfCs Chapter 3 Benefits of Interface Level Definition Defining a contract at the interface level is more flexible. You can then use this contract in other contexts. With contracts defined in interfaces, you can easily implement a service that supports multiple contracts. [ServiceContract()] public interface IHello [OperationContract] string SayHello(string name); [ServiceContract()] public interface IString [OperationContract] string Concat(string name1, string name2); public class Hello : IHello, IString public string SayHello(string name) return "Hello: " + name; public string Concat(string name1, string name2) return name1 + name2; Copyright 2010 Object Innovations Enterprises, LLC 95

60 WcfCs Chapter 3 A Service with Multiple Contracts The Hello service on the preceding page implements the contracts IHello and IString. See HelloString for the complete example. App.config in the Host project defines an endpoint for the second contract. <endpoint address="hello" binding="basichttpbinding" name="basichttp" contract="hellolib.ihello" /> <endpoint address="hello" binding="basichttpbinding" name="basichttp2" contract="hellolib.istring" /> There is an additional generated proxy class StringClient, which is used in the handler of the Concatenate button. private void btnconcat_click(object sender, EventArgs e) StringClient proxy = new StringClient(); txtresponse.text = proxy.concat( txtname1.text, txtname2.text); Copyright 2010 Object Innovations Enterprises, LLC 96

61 WcfCs Chapter 3 ServiceContractAttribute The ServiceContract attribute is used on an interface or class to define a service contract. The ServiceContractAttribute class has a number of properties. Namespace specifies a target namespace for messages, used to disambiguate messages on the wire. The default namespace is Name provides a friendly name for the contract. The default is the CLR name of the interface used. ConfigurationName locates the service element in the configuration file. The default is the CLR name of the implementation class. SessionMode specifies whether the contract requires a binding that supports sessions. CallbackContract specifies the return contract in a duplex conversation. HasProtectionLevel specifies whether all messages supporting the contract have an explicit protection level. ProtectionLevel specifies the value of the protection level. Copyright 2010 Object Innovations Enterprises, LLC 97

62 WcfCs Chapter 3 ServiceContractAttribute Example The ExplicitHello example illustrates specifying a Namespace and a Name. [ServiceContract(Namespace=" Name="HelloContract")] public interface IHello [OperationContract] string SayHello(string name); The target Namespace and friendly contract Name show up in the WSDL specification. <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions xmlns:soap=" targetnamespace=" xmlns:wsdl=" <wsdl:message name="hellocontract_sayhello_inputmessage">... <wsdl:message name="hellocontract_sayhello_outputmessage"> <wsdl:porttype name="hellocontract"> <wsdl:operation name="sayhello">... </wsdl:definitions> Copyright 2010 Object Innovations Enterprises, LLC 98

63 WcfCs Chapter 3 Viewing WSDL Files To view the WSDL for a self-hosted application, make sure that you have httpgetenabled="true" in the <servicemetadata> element of the host s configuration file. <behavior name="servicebehavior"> <servicemetadata httpgetenabled="true"/> </behavior> You can then view the WSDL for the service by appending?wsdl to the URI of the service. You can do also do this for IIS hosted services, and you don t have to supply any special configuration to enable it. Copyright 2010 Object Innovations Enterprises, LLC 99

64 WcfCs Chapter 3 Contract Inheritance Contract interfaces can inherit from each, letting you define a hierarchy of contracts. But the ServiceContract attribute cannot be inherited. You must explicitly provide it at every level of the hierarchy. [ServiceContract()] public interface IHello [OperationContract] string SayHello(string name); [ServiceContract()] public interface IFlexHello : IHello [OperationContract] string Greet(string greeting, string name); A single class can implement the whole hierarchy. public class Hello : IFlexHello public string SayHello(string name) return "Hello: " + name; public string Greet(string greeting, string name) return greeting + ": " + name; Copyright 2010 Object Innovations Enterprises, LLC 100

65 WcfCs Chapter 3 Contract Inheritance (Cont d) The configuration file for the host can provide a single endpoint for the interface at the bottom of the hierarchy. <endpoint address="hello" binding="basichttpbinding" name="basichttp" contract="hellolib.iflexhello" /> The client proxy provides a flattened hierarchy. There is a single contract, named after the bottom interface, that includes all the methods of the hierarchy. For a complete example, see InheritHello. private void btnflexgreet_click(object sender, EventArgs e) FlexHelloClient proxy = new FlexHelloClient(); txtresponse.text = proxy.greet(txtgreeting.text, txtname.text); Copyright 2010 Object Innovations Enterprises, LLC 101

66 WcfCs Chapter 3 Operation Overloading In languages like C# you can overload method names as long as the parameter lists are different. But in WCF it is illegal to have operations with the same name in a contract. Thus the following example won t work: [ServiceContract()] public interface IHello [OperationContract] string SayHello(string name); [OperationContract] string SayHello(string greeting, string name); It will compile, but an InvalidOperationException will be thrown at the time the service host loads. OverloadHello\Step0 illustrates this problem. Copyright 2010 Object Innovations Enterprises, LLC 102

67 WcfCs Chapter 3 Enabling Operation Overloading You can enable operation overloading by using the Name property of the OperationContract to set up aliases for the operations having the same name. See OverloadHello\Step1. [ServiceContract()] public interface IHello [OperationContract(Name = "Greet")] string SayHello(string name); [OperationContract(Name = "FlexGreet")] string SayHello(string greeting, string name); public class Hello : IHello public string SayHello(string name) return "Hello: " + name; public string SayHello(string greeting, string name) return greeting + ": " + name; Copyright 2010 Object Innovations Enterprises, LLC 103

68 WcfCs Chapter 3 Operation Overloading Client The client proxy will use the aliased names of the operation. private void btngreet_click(object sender, EventArgs e) HelloClient proxy = new HelloClient(); txtresponse.text = proxy.greet(txtname.text); private void btnflexgreet_click(object sender, EventArgs e) HelloClient proxy = new HelloClient(); txtresponse.text = proxy.flexgreet( txtgreeting.text, txtname.text); Here is the user interface of the client program: Copyright 2010 Object Innovations Enterprises, LLC 104

69 WcfCs Chapter 3 Lab 3 Working with Service Contracts In this lab, you will create several variations of our simple math service to illustrate a number of the features of service contracts that we ve been discussing. Detailed instructions are contained in the Lab 3 write-up at the end of the chapter. Suggested time: 90 minutes Copyright 2010 Object Innovations Enterprises, LLC 105

70 WcfCs Chapter 3 Summary A service contract can be defined at either the class or interface level. You can implement a service with multiple contracts. Service contracts can be inherited. Operations can be overloaded by using the Name property of the OperationContract attribute. Copyright 2010 Object Innovations Enterprises, LLC 106

71 WcfCs Chapter 3 Introduction Lab 3 Working with Service Contracts In this lab, you will create several variations of our simple math service to illustrate a number of the features of service contracts that we ve been discussing. Suggested Time: 90 minutes. Root Directory: OIC\WcfCs Directories: Labs\Lab3\MathOverload (do Parts 1 & 2 work here) Chap03\MathOverload\Step0 (Part 1 starter code backup) Chap03\MathOverload\Step1 (answer to Part 1) Chap03\MathOverload\Step2 (answer to Part 2) Labs\Lab3\MathInterfaces (do Parts 3 & 4 work here) Chap03\MathInterfaces\Step0 (Part 3 starter code backup) Chap03\MathInterfaces\Step1 (answer to Part 3) Chap03\MathInterfaces\Step2 (answer to Part 4) Part 1: Class-Level Definition versus Interface-Level Definition 1. Open the starter solution in Visual Studio. There are three projects: A WCF service library A console service host A Windows Forms client with the user interface shown above. 2. Build the solution. Copyright 2010 Object Innovations Enterprises, LLC 107

72 WcfCs Chapter 3 3. Start the host project. (Right-click on HostCon in Solution Explorer and choose Debug Start new instance from the context menu.) Wait until the message giving instructions to terminate appears. 4. Start the Windows client program. Verify that you can add and subtract integers. 5. Examine the code for the MathService class in the MathLib project. Observe that the ServiceContract and OperationContract attributes are applied directly to the class. [ServiceContract()] public class MathService [OperationContract] public int Add(int x, int y) return x + y; [OperationContract] public int Subtract(int x, int y) return x - y; 6. Add a new class file to the MathLib project (right-click it and select Add, then New Item, then select the Class template) named IAddMath.cs, that defines a service contract by an interface IAddMath. [ServiceContract()] public interface IAddMath [OperationContract] int Add(int x, int y); [OperationContract] int Subtract(int x, int y); 7. Modify the MathService class to implement the contract through a class that derives from IAddMath. public class MathService : IAddMath public int Add(int x, int y) return x + y; public int Subtract(int x, int y) return x - y; Copyright 2010 Object Innovations Enterprises, LLC 108

73 WcfCs Chapter 3 8. Modify the App.config file in the HostCon project to refer to the contract as IAddMath rather than MathService. <services> <service behaviorconfiguration="servicebehavior" name="mathlib.mathservice"> <endpoint address="mathservice" binding="basichttpbinding" name="basichttp" contract="mathlib.iaddmath" /> <endpoint binding="mexhttpbinding" name="mex" contract="imetadataexchange" /> <host> <baseaddresses> <add baseaddress=" /> </baseaddresses> </host> </service> </services> 9. We ll need a new proxy and modified client code. Delete ServiceReference1 from the Service References in the MathWin project. This will also cause the file Reference.cs to be deleted. 10. Build the service library and host projects. (For each of them, right-click over the project in Solution Explorer and choose Build from the context menu.) 11. Start the HostCon project outside Visual Studio To do this, open Windows Explorer, navigate to the bin\debug folder of the HostCon project and open HostCon.exe. Wait until the message giving instructions to terminate appears. 12. Add a new service reference to the MathWin project. For the service URI specify (You may copy this base address from the App.config file in the HostCon project.) Terminate the host. 13. With the Show All Files button activated, examine the file Reference.cs under Service References to see the name of the proxy class. It is AddMathClient. 14. Modify the handlers of the Add and Subtract button to use this proxy class name. int x = Convert.ToInt32(txtX.Text); int y = Convert.ToInt32(txtY.Text); AddMathClient client = new AddMathClient(); Build the solution. Run the host. Run the Windows client program. Verify that it works. Part 2: Operation Overloading 1. In the service library project, add definitions to the interface for adding and subtracting floats. Do not provide new names for the method but overload the method names Add() and Subtract(). Copyright 2010 Object Innovations Enterprises, LLC 109

74 WcfCs Chapter 3 [ServiceContract()] public interface IAddMath [OperationContract] int Add(int x, int y); [OperationContract] float Add(float x, float y); [OperationContract] int Subtract(int x, int y); [OperationContract] float Subtract(float x, float y); 2. Provide code in the class to implement these overloaded methods. public class MathService : IAddMath public int Add(int x, int y) return x + y; public float Add(float x, float y) return x + y; public int Subtract(int x, int y) return x - y; public float Subtract(float x, float y) return x - y; 3. Compile the modified project. It will compile fine, as this is perfectly legal C# code. 4. Try to run the host. You will get an InvalidOperation exception, with a message that you cannot have two operations in the same contract with the same name. 5. Modify the code in the service library to disambiguate the operation names using the Name property. Also, provide a namespace for the service contract. [ServiceContract(Namespace=" public interface IAddMath [OperationContract] int Add(int x, int y); [OperationContract(Name="AddFloat")] float Add(float x, float y); [OperationContract] int Subtract(int x, int y); [OperationContract(Name="SubtractFloat")] float Subtract(float x, float y); Copyright 2010 Object Innovations Enterprises, LLC 110

75 WcfCs Chapter 3 6. You will continue to get a clean compile, and now you can run the host successfully. Terminate the host. 7. In the MathWin project delete the service reference. 8. Start up the host outside Visual Studio In the MathWin project add a service reference to the modified service, continuing to use the URI Terminate the host. 9. Modify the handler for the Add button to add either integers or floats depending on which radio button is checked, calling the appropriate method of the proxy. private void btnadd_click(object sender, EventArgs e) AddMathClient client = new AddMathClient(); if (radint.checked) int x = Convert.ToInt32(txtX.Text); int y = Convert.ToInt32(txtY.Text); int result = client.add(x, y); txtresult.text = result.tostring(); else if (radfloat.checked) float x = Convert.ToSingle(txtX.Text); float y = Convert.ToSingle(txtY.Text); float result = client.addfloat(x, y); txtresult.text = result.tostring(); client.close(); 10. Modify the handler of the Subtract button in a similar manner. 11. Build the solution. Start the host, and start the Windows client project. You should now be able to add both integers and floats. Copyright 2010 Object Innovations Enterprises, LLC 111

76 WcfCs Chapter 3 Part 3: Interface Inheritance 1. Open the starter solution in Visual Studio. There are three projects: A WCF service library A console service host A Windows Forms client with the user interface shown below 2. Build and run (do the usual thing with starting the host first). You can add and subtract integers. A user interface is provided for multiply and divide, but these operations are not implemented yet. 3. Examine the starter code for the service library. There is an interface IAddMath with operations Add and Subtract and a class implementing this interface. 4. Add a new class file to the service library project named ICalculator.cs. In this file, define a new interface ICalculator inheriting from IAddMath with new operations Multiply and Divide. Provide suitable service and operation attributes. [ServiceContract(Namespace = " public interface ICalculator : IAddMath [OperationContract] int Multiply(int x, int y); [OperationContract] int Divide(int x, int y); 5. Modify the code for the class to implement ICalculator. public class MathService : ICalculator public int Add(int x, int y) return x + y; public int Subtract(int x, int y) Copyright 2010 Object Innovations Enterprises, LLC 112

77 WcfCs Chapter 3 return x - y; public int Multiply(int x, int y) return x * y; public int Divide(int x, int y) return x / y; 6. Edit App.config for the host project to refer to the ICalculator interface. Build the solution. <endpoint address="mathservice" binding="basichttpbinding" name="basichttp" contract="mathlib.icalculator" /> 7. Build the solution. 8. Delete the service reference in the MathWin project. 9. Start up the host outside Visual Studio In the MathWin project add a service reference to the modified service, continuing to use the URI Terminate the host. 10. In the MathWin project add handlers for the Multiply and Divide buttons. 11. Implement the handler for the Multiply button. Note that the name of the proxy class is now CalculatorClient. private void btnmultiply_click(object sender, EventArgs e) int x = Convert.ToInt32(txtX.Text); int y = Convert.ToInt32(txtY.Text); CalculatorClient client = new CalculatorClient(); int result = client.multiply(x, y); client.close(); txtresult.text = result.tostring(); 12. Provide a similar handler for the Divide button. 13. Modify the handlers for the Add and Subtract button to use CalculatorClient as the proxy class. 14. Build and run (as usual start the host first). All four operations should now be operational! Copyright 2010 Object Innovations Enterprises, LLC 113

78 WcfCs Chapter 3 Part 4: Multiple Interfaces 1. Rename the file ICalculator.cs to IMultMath.cs. Note that Visual Studio 2008 will automatically rename the interface name to IMultMath and update the references for you inside this project. 2. Modify the IMultMath interface so that it does not inherit from anything, keeping the code that defines the two operations Multiply and Divide. 3. Modify the class to inherit from the two interfaces IAddMath and IMultMath. It should implement all four methods. 4. Edit App.config in the host project to use IAddMath as the contract in the first endpoint. Provide a second endpoint that uses IMultMath as the contract. <endpoint address="mathservice" binding="basichttpbinding" name="basichttp" contract="mathlib.iaddmath" /> <endpoint address="mathservice" binding="basichttpbinding" name="basichttp2" contract="mathlib.imultmath" /> 5. Build the service library and host projects. Verify that you get clean compiles and that you can load the host. Terminate the host. 6. Delete the service reference from the MathWin project. 7. Start the host outside Visual Studio 2008, and add a new service reference to the MathWin project, using our usual URI 8. Examine the proxy code in Reference.cs. Observe that there are proxy classes AddMathClient and MultMathClient corresponding to the two contracts. 9. Modify the handlers for the buttons to use these proxy classes. For example, here is the handler for the Divide button. private void btndivide_click(object sender, EventArgs e) int x = Convert.ToInt32(txtX.Text); int y = Convert.ToInt32(txtY.Text); MultMathClient client = new MultMathClient(); int result = client.divide(x, y); client.close(); txtresult.text = result.tostring(); 10. Build and run (as usual start the host first). All four operations should now be operational. Copyright 2010 Object Innovations Enterprises, LLC 114

79 WcfCs Chapter 7 Chapter 7 Handling Errors Copyright 2010 Object Innovations Enterprises, LLC 227

80 WcfCs Chapter 7 Handling Errors Objectives After completing this unit you will be able to: Explain the use of exceptions and faults in WCF. Generate and handle faults in your programs. Specify and implement fault contracts. Explain the behavior of faults in bindings that maintain a session. Copyright 2010 Object Innovations Enterprises, LLC 228

81 WcfCs Chapter 7 Errors in Distributed Systems Effective error handling is critical in distributed. An error in servicing a particular client should not take down the whole service. The service should remain available to other clients. A key issue is how errors should be reported back to clients. Exceptions and exception handling is specific to a particular technology and is not suitable for crossing a service boundary. Moreover, in a service-oriented system, the service is encapsulated so that the client has little concern over the internal operations of the service. Details about an error on the service have little or no meaning to a client. When the details of an error are meaningful to a client, the error should be part of the contract between the client and the service. Copyright 2010 Object Innovations Enterprises, LLC 229

82 WcfCs Chapter 7 Errors in.net and WCF In.NET errors cause an exception to be thrown. An unhandled exception causes the process in which the exception occurred to be terminated. WCF behavior is different. When a service encounters an error on behalf of a client, the whole service must not be taken down. Other clients using the service should not be affected. The WCF dispatcher silently catches unhandled exceptions and handles it by sending a return message to the client. The proxy will then throw an exception on the client side. The service remains available to other clients. Copyright 2010 Object Innovations Enterprises, LLC 230

83 WcfCs Chapter 7 Demo of WCF Error Behavior Let s illustrate the behavior of errors in WCF. See MathFault\Step0 in the chapter directory. 1. Build the solution. 2. Run the host process outside of Visual Studio by doubleclicking on HostCon.exe in the bin\debug folder of the HostCon project. 3. Wait until the host has started, as evidenced by the message Press ENTER to terminate the service host. 4. Run two instances of the client program outside of Visual Studio by double-clicking on MathWin.exe in the bin\debug folder of the MathWin project. 5. Enter 0 for Y and click the Divide button. Copyright 2010 Object Innovations Enterprises, LLC 231

84 WcfCs Chapter 7 Demo of WCF Error Behavior (Cont d) 6. The Windows shell catches an unhandled exception in the client application. 7. Click Quit. 8. Go to the other running instance of the client and click the Multiply button. 9. It is evident that the host process has continued running, even though the service library code did not handle the DivideByZero exception. Close both the client and the host. Copyright 2010 Object Innovations Enterprises, LLC 232

85 WcfCs Chapter 7 Service Library Code [ServiceContract(Namespace=" public interface IMultMath [OperationContract] int Multiply(int x, int y); [OperationContract(Name = "MultiplyDouble")] double Multiply(double x, double y); [OperationContract] int Divide(int x, int y); [OperationContract(Name = "DivideDouble")] double Divide(double x, double y); public class MathService : IMultMath public int Multiply(int x, int y) return x * y; public double Multiply(double x, double y) return x * y; public int Divide(int x, int y) return x / y; public double Divide(double x, double y) return x / y; The service provides no exception handling code. Copyright 2010 Object Innovations Enterprises, LLC 233

86 WcfCs Chapter 7 Client Code private void btndivide_click(object sender, EventArgs e) MultMathClient client = new MultMathClient(); if (radint.checked) int x = Convert.ToInt32(txtX.Text); int y = Convert.ToInt32(txtY.Text); int result = client.divide(x, y); txtresult.text = result.tostring(); else if (raddouble.checked) double x = Convert.ToSingle(txtX.Text); double y = Convert.ToSingle(txtY.Text); double result = client.dividedouble(x, y); txtresult.text = result.tostring(); client.close(); The client also provides no exception handling code. This is the reason the exception was only caught by the Windows shell. Copyright 2010 Object Innovations Enterprises, LLC 234

87 WcfCs Chapter 7 Client Exception Handling Step 1 provides exception handling in the client. txtresult.text = ""; txtstatus.text = ""; MultMathClient client = null; try client = new MultMathClient(); if (radint.checked) int x = Convert.ToInt32(txtX.Text); int y = Convert.ToInt32(txtY.Text); int result = client.divide(x, y); txtresult.text = result.tostring(); else if (raddouble.checked) double x = Convert.ToSingle(txtX.Text); double y = Convert.ToSingle(txtY.Text); double result = client.dividedouble(x, y); txtresult.text = result.tostring(); catch (Exception ex) txtstatus.text = ex.gettype().tostring(); MessageBox.Show(ex.Message, "Exception"); finally client.close(); We show the type of the exception in a text box and the exception message in a message box. Copyright 2010 Object Innovations Enterprises, LLC 235

88 WcfCs Chapter 7 Exception Handling Demo 1. Build the Step 1 solution. Observe that the service library code is identical to Step Start the host process as before and start a single instance of the client program. 3. Again try doing an integer divide by zero. This time we catch an exception. 4. The client user interface now provides a text box docked to the bottom of the main window to display status messages. We show the type of the exception. 5. Try entering non-numeric characters for one of the numbers. You will hit a format exception. Copyright 2010 Object Innovations Enterprises, LLC 236

89 WcfCs Chapter 7 Exception Handling Demo (Cont d) 6. Try doing a division by zero with double numbers. In floating point arithmetic, according to the IEEE standard, you do not generate an exception but get the result Infinity. 7. Exit the client and the host. Copyright 2010 Object Innovations Enterprises, LLC 237

90 WcfCs Chapter 7 Fault Exceptions WCF uses a new kind of exception, FaultException, to pass information about error conditions. FaultException is untyped, and the derived generic class FaultException<T> provides strongly typed access to detailed information about a fault. The diagram shows the class hierarchy of fault exceptions. Exception SystemException CommunicationException FaultException FaultException<T> Copyright 2010 Object Innovations Enterprises, LLC 238

91 WcfCs Chapter 7 Faults Exceptions are technology specific and should not be shared across a service boundary. What is needed in a distributed environment is a neutral format for error information. SOAP faults provide such a neutral format. The SOAP specification defines an XML standard format for messages. Part of this specification defines SOAP faults, a structure for the contents of the message body in the case of errors. Because of its basis in XML, SOAP messages are highly interoperable. WCF works with both.net exceptions and SOAP faults. An exception in the service is converted to a SOAP fault for transmission over the wire. The client proxy in turn converts the SOAP fault into a fault exception, which can be handled by client code through.net exception handling. Copyright 2010 Object Innovations Enterprises, LLC 239

92 WcfCs Chapter 7 Exception Details in Faults For debugging purposes it may be useful for the fault to carry detailed diagnostic information. For security purposes you would normally not want such detailed information to be passed to the client in released code. There are several ways to specify in the service that such exception details should be passed in the fault. Specify it for the entire service in the configuration file using the <servicedebug> element. <behavior name="servicebehavior"> <servicedebug includeexceptiondetailinfaults="true"/> <servicemetadata httpgetenabled="true"/> </behavior> Use the ServiceBehavior attribute in front of a particular class. [ServiceBehavior( IncludeExceptionDetailInFaults = true)] public class MathService : IMultMath In code for a particular method. DivideByZeroException ex = new DivideByZeroException(); ExceptionDetail detail = new ExceptionDetail(ex); throw new FaultException<ExceptionDetail>( detail, "Division by zero not allowed"); Copyright 2010 Object Innovations Enterprises, LLC 240

93 WcfCs Chapter 7 Exception Details Demo Step 2 of the MathFault example illustrates two of these techniques for passing detailed exception information. #if DEBUG [ServiceBehavior( IncludeExceptionDetailInFaults = true)] #endif public class MathService : IMultMath... public int Divide(int x, int y) if (y == 0) DivideByZeroException ex = new DivideByZeroException(); ExceptionDetail detail = new ExceptionDetail(ex); throw new FaultException<ExceptionDetail> (detail, "Division by zero not allowed"); return x / y; public double Divide(double x, double y) if (y == 0) DivideByZeroException ex = new DivideByZeroException(); throw ex; return x / y; Copyright 2010 Object Innovations Enterprises, LLC 241

94 WcfCs Chapter 7 Exception Details Demo (Cont d) Notice that in the method that does division of double numbers we explicitly throw an exception, but our code does not call for passing exception details. The ServiceBehavior attribute is specified conditionally for debug builds. Hence, in release builds we will not pass any detailed information that might pose a security risk. #if DEBUG [ServiceBehavior( IncludeExceptionDetailInFaults = true)] #endif public class MathService : IMultMath 1. Build the Step 2 solution. 2. This time try starting the host in the debugger from within Visual Studio rather than by the shell from the bin\debug folder. Then start the client program. 3. Try doing an integer divide by zero. Now you will break within Visual Studio and never hit the client program. (If you don t hit an exception in Visual Studio, check the Debug Exceptions dialog as shown on the next page.) 4. Stop the program in Visual Studio. Copyright 2010 Object Innovations Enterprises, LLC 242

95 WcfCs Chapter 7 Exceptions Dialog 5. Visual Studio allows you to control debugging behavior under exceptions through the Exceptions dialog. You can bring it up from the menu Debug Exceptions Uncheck User-unhandled for Common Language Runtime Exceptions. Click OK. 7. Now start the host within Visual Studio. Start the client. 8. Again try doing an integer divide by zero. This time you will hit the exception in the client program. Note that your custom error message is displayed. 9. Terminate the program within Visual Studio. Copyright 2010 Object Innovations Enterprises, LLC 243

96 WcfCs Chapter 7 Fault Contracts Exceptions thrown by the service reach the client as FaultExceptions. To allow clients to distinguish among different types of faults, WPF provides the concept of fault contract. The service lists the types of errors it can throw. These types are the same as the type parameters used in the generic FaultContract<T>. Here is how a service specifies a fault contract: [OperationContract] [FaultContract(typeof(DivideByZeroException))] int Divide(int x, int y); Here is how a service throws such a fault: DivideByZeroException ex = new DivideByZeroException(); throw new FaultException<DivideByZeroException>( ex, "Attempted to divide by zero"); Here is how a client catches such a fault: catch (FaultException<DivideByZeroException> ex) txtstatus.text = ex.gettype().tostring(); MessageBox.Show(ex.Message, "DivideByZeroException"); Copyright 2010 Object Innovations Enterprises, LLC 244

97 WcfCs Chapter 7 Fault Contract Example Step 3 of the MathFault example illustrates fault contracts. Here is the full contract: public interface IMultMath [OperationContract] [FaultContract(typeof(OverflowException))] int Multiply(int x, int y); [OperationContract(Name = "MultiplyDouble")] double Multiply(double x, double y); [OperationContract] [FaultContract(typeof(DivideByZeroException))] int Divide(int x, int y); [OperationContract(Name = "DivideDouble")] [FaultContract(typeof(DivideByZeroException))] double Divide(double x, double y); Besides divide by zero, we also check for integer overflow in multiply by using the C# checked arithmetic. try result = checked(x * y); catch (OverflowException ex) ex = new OverflowException(); throw new FaultException<OverflowException>( ex, "Integer overflow in multiplication"); return result; Copyright 2010 Object Innovations Enterprises, LLC 245

98 WcfCs Chapter 7 Fault Contract Example Client Here is the client code for multiply: try client = new MultMathClient(); if (radint.checked) int x = Convert.ToInt32(txtX.Text); int y = Convert.ToInt32(txtY.Text); int result = client.multiply(x, y); txtresult.text = result.tostring(); else if (raddouble.checked) double x = Convert.ToSingle(txtX.Text); double y = Convert.ToSingle(txtY.Text); double result = client.multiplydouble(x, y); txtresult.text = result.tostring(); catch (FaultException<OverflowException> ex) txtstatus.text = ex.gettype().tostring(); MessageBox.Show(ex.Message, "OverflowException"); catch (Exception ex) txtstatus.text = ex.gettype().tostring(); MessageBox.Show(ex.Message, "Exception"); Copyright 2010 Object Innovations Enterprises, LLC 246

99 WcfCs Chapter 7 Custom Faults When a fault is not due to a built-in exception known to the CLR, you may create your own type for the fault and specify a data contract for it. For an example, see SessionFault\Step2. [DataContract] public class BalanceFault [DataMember] public string Message; [DataMember] public int Shortage; public BalanceFault(string message, int shortage) this.message = message; this.shortage = shortage; You may now use the BalanceFault type in the service contract to create a fault contract. [ServiceContract()] public interface IAccount [OperationContract] void Deposit(int amount); [OperationContract] [FaultContract(typeof(BalanceFault))] void Withdraw(int amount); [OperationContract] int GetBalance(); Copyright 2010 Object Innovations Enterprises, LLC 247

100 WcfCs Chapter 7 Faulted Channels In the MathFault example the service uses the percall instancing model and the communication channel remains open even after a fault has occurred. But in the case of a per-session instancing model, uncaught exceptions on the service will cause the service channel to fault. This means that subsequent calls on this channel will fail, with a CommunicationObjectFaultedException. See SessionFault\Step1 for an illustration of this behavior. You will fully develop this example in the lab. Copyright 2010 Object Innovations Enterprises, LLC 248

101 WcfCs Chapter 7 Lab 7 Custom Faults with a Session In this lab you will implement fault contracts for a simple bank example where an account balance is stored in session state. You will also experiment with a fault without a contract, including providing detailed exception information to the client. Starter code implements deposit and withdraw operations, and a text box is provided for displaying status information regarding exceptions encountered. Detailed instructions are contained in the Lab 7 write-up at the end of the chapter. Suggested time: 45 minutes. Copyright 2010 Object Innovations Enterprises, LLC 249

102 WcfCs Chapter 7 Summary While exceptions are platform specific, faults are neutral and are a suitable means of propagating error conditions in a distributed environment. The.NET Framework provides the FaultException and FaultException<T> classes as a means to encapsulate exceptions in faults. A fault contract allows a service to list the type of errors it can throw. When a channel maintains a session, uncaught exceptions will cause the channel to fault and subsequent calls on the channel will fail. Copyright 2010 Object Innovations Enterprises, LLC 250

103 WcfCs Chapter 7 Introduction Lab 7 Custom Faults with a Session In this lab you will implement fault contracts for a simple bank example where an account balance is stored in session state. You will also experiment with a fault without a contract, including providing detailed exception information to the client. Starter code implements deposit and withdraw operations, and a text box is provided for displaying status information regarding exceptions encountered. Suggested Time: 45 minutes. Root Directory: OIC\WcfCs Directories: Labs\Lab7\SessionFault (do your work here) Chap07\SessionFault\Step1 (starter code backup) Chap07\SessionFault\Step2 (answer) Part 1: Examine the Starter Project 1. Run the starter solution. There are three projects: a service library, a host, and a Windows client program. Build the solution and start the host. Then start the Windows client. You will be able to make deposits and withdrawals. You can overdraw the account, making the balance negative. If you try to deposit a negative amount, you will hit an exception. Terminate the program. 2. If on hitting an exception you are brought into Visual Studio, bring up the Exceptions dialog from the Debug menu and clear the User-unhandled checkbox for Common Language Runtime Exceptions. 3. Examine the file BankService.cs in the BankLib project. Observe that the InstanceContextMode is set to PerSession. Copyright 2010 Object Innovations Enterprises, LLC 251

104 WcfCs Chapter 7 4. Examine the file Form1.cs in the BankWin project. Basic exception handling is implemented, displaying a message box with an exception message. Part 2: Experiment with Exceptions and Faults 1. Add code in the client to display in the status text box the type of exceptions that are handled. Here is the code for the Deposit handler, and the code for the Withdraw handler is similar. private void btndeposit_click(object sender, EventArgs e) txtstatus.text = ""; try int amount = Convert.ToInt32(txtAmount.Text); proxy.deposit(amount); txtbalance.text = proxy.getbalance().tostring(); catch (Exception ex) txtstatus.text = ex.gettype().tostring(); MessageBox.Show(ex.Message, "Exception"); 2. Build and run. Try making a blank deposit. You will hit a System.Format exception. Try making a negative deposit. You will hit a System.ServiceModel.FaultException. The message box displays a lengthy explanation about how to display detailed exception information (normally suppressed for security considerations). 3. In the MathFault example we saw two ways of displaying detailed exception information. Now let s do it by adding a <servicedebug> element to <behavior> in the service s configuration file. <servicebehaviors> <behavior name="servicebehavior"> <servicedebug includeexceptiondetailinfaults="true"/> <servicemetadata httpgetenabled="true"/> </behavior> </servicebehaviors> 4. Build and run. Now the message box will display a nice descriptive error message. Copyright 2010 Object Innovations Enterprises, LLC 252

105 WcfCs Chapter 7 5. Click OK in the message box and now try to deposit a positive amount. You will hit another exception, because the communication channel is now in the faulted state. 6. Close the message box. Exit the application. You will hit yet another exception in the handler for the FormClosed event when the code tries to close the proxy. Terminate the program in Visual Studio. 7. Add code to the FormClosed handler to check that the communication state is open. For the program to compile you will need to import the System.ServiceModel namespace. private void Form1_FormClosed(object sender, FormClosedEventArgs e) // Make sure open (not faulted) before close if (proxy.innerchannel.state == CommunicationState.Opened) proxy.close(); 8. Build and run, repeating the same scenario of hitting an exception by trying to deposit a negative amount. Now you will be able to close the application cleanly. Part 3: Implement a Fault Contract 1. In the BankLib project add a new class file Faults.cs. Specify a data contract for a fault AmountFault. You will need the System.Runtime.Serialization namespace. [DataContract] public class AmountFault [DataMember] public string Message; public AmountFault(string message) this.message = message; Copyright 2010 Object Innovations Enterprises, LLC 253