Module 4: Consuming Web Services Contents Overview WSDL Documents Web Service Discovery Web Service Proxies 18 Implementing a Web Service Consumer Using Visual Studio NET 26 Lab 4: Implementing a Web Service Consumer Using Visual Studio NET 36 Review 45 Information in this document, including URL and other Internet Web site references, is subject to change without notice Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, places or events is intended or should be inferred Complying with all applicable copyright laws is the responsibility of the user Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property  2001 Microsoft Corporation All rights reserved Microsoft, MS-DOS, Windows, Windows NT, Active Directory, Authenticode, Biztalk, Intellisense, Jscript, MSDN, PowerPoint, Visual Basic, Visual C++, Visual C#, Visual Studio, Win32, and Windows Media are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A and/or other countries The names of actual companies and products mentioned herein may be the trademarks of their respective owners Module 4: Consuming Web Services Instructor Notes Presentation: 120 Minutes This module teaches students how to implement Web Service consumers using Microsoft® Visual Studio® NET Beta Lab: 75 Minutes After completing this module, students will be able to: ! Explain the structure of a Web Service Description Language (WSDL) document ! Explain the Web Services Discovery process ! Locate service contracts by using Disco.exe ! Generate Web Service proxies by using Wsdl.exe ! Implement a Web Service consumer by using Visual Studio NET ! Invoke a Web Service synchronously and asynchronously by using a Web Service proxy Materials and Preparation This section provides the materials and preparation tasks that you need to teach this module Required Materials To teach this module, you need the Microsoft PowerPoint® file 2524A_04.ppt Preparation Tasks To prepare for this module: ! Read all of the materials for this module ! Try the walkthroughs and demonstrations in this module ! Complete the lab iii iv Module 4: Consuming Web Services Module Strategy Use the following strategy to present this module: ! WSDL Documents You should approach the topics in this section as a progressive development of an example of a WSDL document Explain the concepts in the first topic with a simple Web Service that has only one operation that returns a class, (the code is defined in the student notes) Progressively build upon this example WSDL document when you explain each of the WSDL topics The intent of teaching WSDL syntax is not for students to write a WSDL document from scratch on their own The intent is for students to be able to describe the structure of a WSDL document and explain how the definitions in a WSDL document correspond to the code they will implement in a Web Service ! Web Service Discovery Explain that the problem focused on by this section is how to find WSDL documents and the endpoints for Web Services that implement the interfaces defined in the WSDL documents For completeness, it is important that you briefly describe Universal Description, Discovery, and Integration (UDDI) as part of the solution, but defer any in-depth discussion of UDDI until Module 6, “Publishing and Deploying Web Services,” in Course 2524A, Developing XML Web Services Using Microsoft Visual C# NET Beta Explain how Disco.exe can be used to generate local copies of WSDL documents and other discovery documents ! Web Service Proxies This section is intended to help students understand the benefits of implementing proxies to Web Services Remind the students about the lab exercises in Module 3, “The Underlying Technologies of Web Services,” in Course 2524A, Developing XML Web Services Using Microsoft Visual C# NET Beta 2, to emphasize how manual construction of Hypertext Transfer Protocol (HTTP) and Simple Object Access Protocol (SOAP) messages is tedious and error-prone Point out that module did not cover the steps involved in decoding response messages Explain that decoding response messages is an essential functionality in a Web Service consumer Explain that this functionality can be encapsulated in a Web Service proxy Discuss the code that is generated for the proxies from a high level Discuss the properties of a proxy that can be configured Do not spend too much time on this discussion, because students will be learning about how to implement Web Service consumers in the next section Module 4: Consuming Web Services ! v Implementing a Web Service Consumer Using Visual Studio NET This section is intended to familiarize students with the steps required to allow a managed application to consume a Web Service Stress that the steps outlined in this section not apply to unmanaged applications Emphasize the similarity between the steps involved in implementing a Web Service consumer that is a console application and a Web Service consumer that is a Web Forms application Also, discuss the importance of asynchronous invocation of Web Service methods Point out the similarity between invoking Web Service methods asynchronously and issuing asynchronous HTTP requests using the WebRequest class, which is demonstrated in Module 3, “The Underlying Technologies of Web Services,” in Course 2524A, Developing XML Web Services Using Microsoft Visual C# NET Beta Module 4: Consuming Web Services Overview Topic Objective To provide an overview of the module topics and objectives ! WSDL Documents Lead-in ! Web Service Discovery ! Web Service Proxies ! Implementing a Web Service Consumer Using Visual Studio NET In this module, you will learn how to implement Web Service consumers by using Microsoft Visual Studio NET *****************************ILLEGAL FOR NON-TRAINER USE****************************** To be able to consume (use) Web Services as well as develop them, you need to know how to implement the consumer for a Web Service Web Service developers must understand how a Web Service will be consumed before implementing it Also, Web Service developers need to implement Web Service consumers for test the Web Services that they implement In this module, you will learn how to implement Web Service consumers by using Microsoft® Visual Studio® NET After completing this module, you will be able to: ! Explain the structure of a Web Service Description Language (WSDL) document ! Explain the Web Services Discovery process ! Locate service contracts by using Disco.exe ! Generate Web Service proxies by using Wsdl.exe ! Implement a Web Service consumer by using Visual Studio NET ! Invoke a Web Service synchronously and asynchronously by using a Web Service proxy Module 4: Consuming Web Services WSDL Documents Topic Objective To explain the structure of WSDL documents Lead-in To be able to consume a Web Service, you first need to know how to interact with it ! What Is WSDL? ! Structure of a WSDL Document " The types element " The message element " The portType element " The binding element " The service element *****************************ILLEGAL FOR NON-TRAINER USE****************************** To be able to use or consume a Web Service, you first need to know how to interact with it What Is WSDL? Web Services Description Language (WSDL) is an XML grammar used for describing a Web Service in terms of the messages it accepts and generates In other words, a WSDL file acts as a contract between a Web Service consumer (client) and a Web Service In a WSDL document, you define the types used in the operations (methods) of a Web Service, and the documents that are exchanged for each operation Then, you associate these definitions with a network protocol and group them into messages to define an endpoint (the network location of a Web Service) WSDL can describe endpoints and their operations without specifying the message formats or the network protocols to which an endpoint is bound The only protocol bindings that are examined in this section are Simple Object Access Protocol (SOAP) 1.1 and HTTP-GET/POST As a Web Service consumer, it is important that you are familiar with WSDL to understand the contract defined in a WSDL document Also, when you implement a Web Service, you might not want to use an automatically generated WSDL file Instead, you might choose to generate the default WSDL file and then modify it Again, for this purpose you need to know WSDL Module 4: Consuming Web Services Structure of a WSDL Document A WSDL document is just a list of definitions In a WSDL file, the root element is named definitions This element contains five primary child elements used to define the Web Service The following five elements appear within the definitions element in a WSDL file in the order specified: Delivery Tip Explain the WSDL elements to the students by walking them through the sample code provided in \Democode\Mod04\ WoodgroveBank.wsdl ! The types element defines the various data types used to exchange messages ! The message element describes the messages to be communicated ! The portType element identifies a set of operations and the messages involved with each of those operations ! The binding element specifies the protocol details for various service operations and describes how to map the abstract content of these messages into a concrete format ! The service element groups a set of related ports together Let us examine the preceding elements by looking at how these elements can be used in a WSDL file that describes the following Web Service: [XmlRoot("account")] public class Acct { [XmlElement("description")] public string Description; [XmlElement("number")] public string Number; [XmlElement("type")] public string Type; [XmlElement("balance")] public decimal Balance; [XmlAttribute("status")] public string Status; } public class TheBank { [WebMethod] public Acct GetAccount(string acctNumber) { Acct a = new Acct(); a.Description = "Adam's savings acct"; a.Balance=10000.0M; a.Number="1234-XX"; a.Status="active"; a.Type="SV"; return a; } } Let us look at how to define a WSDL document that describes the preceding Web Service Module 4: Consuming Web Services The types element First you define the types used in the message exchange This is mostly just a matter of defining the types using XML Schema Definition Language (XSD) The acctNumber parameter is defined as follows: The type definition for the Acct class, which is returned by the GetAccount method, is slightly more complex than the previous definition The type definition for this class can be as follows: The preceding type definition describes the structure of the account element in the following XML document: Adam's savings acct 1234-XX SV 10000 Next, the structure of the messages that are to be exchanged is defined In this example, the method name is GetAccount and we use the following naming convention: ! The inbound message has the same name as the method ! The outbound message has the name of the method with the word Response appended ... types element Module 4: Consuming Web Services The portType element A Web Service provider (a network node, which is a Web Server) may expose multiple Web Services A single Web Service can support... Web Service whose endpoints are unknown, see Module 6, “Publishing and Deploying Web Services,” in Course 2524A, Developing XML Web Services Using Microsoft Visual C# NET Beta 10 Module 4: Consuming. .. that a Web Service provider would publish the service descriptions of all the Web Services through a Web Service broker Therefore the service descriptions must be discoverable by Web Service