Contents Overview 1 Datatype Constraints 2 Scalability 9 Performance 13 Reliability 26 Versioning 32 ISP and ASP Deployment 34 Architectural Elements 36 Review 39 Module 8: Designing Web Services 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 8: Designing Web Services iii Instructor Notes This module teaches students the tradeoffs and issues that must be evaluated when implementing a real-world Web Service. After completing this module, students will be able to: ! Identify the restrictions imposed on datatypes by the various Web Services protocols. ! Explain how the use of Application and Session state can affect the performance and scaling of Web Services. ! Explain how output and data caching can be used to improve Web Service performance. ! Explain the need for instrumenting Web Services. ! Identify the components of a Web Service that can be versioned. ! Explain how deploying a Web Service at an Internet Service Provider (ISP) or an Application Service Provider (ASP) can affect the design of the Web Service. ! Explain the limitations in using two-phase commit transactions and eventing in Web Services. 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_08.ppt. Preparation Tasks To prepare for this module: ! Read all of the materials for this module. ! Review the sample code files in the <install folder>\Democode\Mod08 folder. Presentation: 60 Minutes Lab: 00 Minutes iv Module 8: Designing Web Services Module Strategy Use the following strategy to present this module: ! Datatype Constraints Explain that even though Microsoft ASP.NET Web Services support a rich set of data types, not all of the Microsoft .NET Framework data types are appropriate for Web Services. Tell the students that Simple Object Access Protocol (SOAP) is the preferred protocol for Web Services. Explain how using Hypertext Transfer Protocol (HTTP)-GET and POST limit the types of data a Web Service can support. Teach the module as a set of tradeoffs. Explain to the students that circumstances may dictate different choices in different scenarios. ! Scalability Explain that failure to scale is a bug, and should be approached in the same way as other bugs. Point out that scalability and performance are not synonymous and that a scalable Web Service can often perform more poorly than a non-scalable Web Service when the load on the Web Services is light. Emphasize that there are many different issues to consider for achieving scalability and discuss the different metrics for measuring scalability that are listed in the topic. Also discuss scale-up and scale-out as alternate and complementary solutions. ! Performance Start out by discussing general performance considerations. Then examine the issues that the students must consider when implementing Web Services using ASP.NET. Finally, discuss the ASP.NET output and data caching capabilities and how they can be used in Web Services. ! Reliability In this topic, discuss how the .NET common language runtime enables better application reliability without compromising on performance. Also, explain how the ASP.NET process recovery model enhances reliability by supporting automatic restart of applications if the Aspnet_wp.exe worker process fails, and by allowing scheduled restarts in order to reclaim leaked resources. Also, emphasize the importance of having the ability to monitor the health of a running Web Service to support early detection of impending application failure. ! Versioning Explain that all developers of Web Services will have to deal issues with versioning. Emphasize that Web Services Description Language (WSDL) documents should not be versioned for production Web Services. Discuss strategies for handling evolving interfaces by using generic Extensible Markup Language (XML) fragments. Do not get into an in-depth discussion on assembly versioning. Rather, refer the students to Course 2350A, Securing and Deploying Assemblies. ! ISP and ASP Deployment Explain how deploying a Web Service at an ISP or an ASP can affect the design of a Web Service. Specifically focus on the lack of control of the security policies that will be applied to a Web Service. Module 8: Designing Web Services v ! Architectural Elements Explain that the Web Services programming model and the constraints imposed by using the Internet make many common architectural elements found in traditional distributed applications inappropriate for Web Service based solutions. Specifically focus your discussion on transactions. Explain why long-running transactions with compensation are appropriate for cross- organizational processes while two-phase commit transactions are essentially limited to a single operation. Module 8: Designing Web Services 1 Overview ! Datatype Constraints ! Scalability ! Performance ! Reliability ! Versioning ! ISP and ASP Deployment ! Architectural Elements ***************************** ILLEGAL FOR NON - TRAINER USE ****************************** It is relatively easy to implement a simple Web Service. However, if you implement a Web Service that must be interoperable, scalable, reliable, and able to perform well, then there are a number of issues that you must be consider when designing your Web Service. In this module, you will step back from pure implementation details and examine some of the important issues that you must consider when designing a real-world Web Service. After completing this module, you will be able to: ! Identify the restrictions imposed on datatypes by the various Web Services protocols. ! Explain how the use of Application and Session state can affect the performance and scaling of Web Services. ! Explain how output and data caching can be used to improve Web Service performance. ! Explain the need for instrumenting Web Services. ! Identify the components of a Web Service that can be versioned. ! Explain how deploying a Web Service at an Internet Service Provider (ISP) or an Application Service Provider (ASP) can affect the design of the Web Service. ! Explain the limitations in using two-phase commit transactions and eventing in Web Services. Topic Objective To provide an overview of the module topics and objectives. Lead-in In this module, you will learn about the issues that you must consider when designing a Web Service. 2 Module 8: Designing Web Services Datatype Constraints ! Protocol Constraints ! Structures vs. Classes ! Typed vs. Untyped DataSets ! Arrays vs. Collections ! Exceptions ***************************** ILLEGAL FOR NON - TRAINER USE ****************************** Although the Microsoft ® .NET Framework supports a rich set of datatypes, not all datatypes can or should be used as part of the interface of a Web Service. In this topic, you will first look at how the choice of protocol for your Web Service can limit the datatypes that can be used in the service. You will then look at some guidelines for choosing between similar datatypes, such as, structures and classes. Finally, you will look at how Web Services expose exceptions, and the results of throwing custom exception types. Protocol Constraints Although Microsoft ASP.NET Web Services automatically support Hypertext Transfer Protocol (HTTP)-GET/POST and Simple Object Access Protocol (SOAP), these protocols are not equally capable when it comes to datatypes supported. The following table summarizes the datatypes that can be used for each of the protocols supported by Web Services. Type Description SOAP POST GET Primitive types Standard primitive types, which are as follows: String, Int32, Byte, Boolean, Int16, Int64, Single, Double, Decimal, DateTime, and XmlQualifiedName " " " Enumeration types " " " Arrays of primitives and enumeration types " " " Topic Objective To explain the trade-offs inherent in choosing datatypes for the methods of a Web Service. Lead-in Although the .NET Framework supports a rich set of datatypes, not all datatypes can or should be used as part of the interface of a Web Service. Module 8: Designing Web Services 3 (continued) Type Description SOAP POST GET Classes and structures class and struct types with public fields or properties. The public properties and fields are serialized. " # # Arrays of classes and structures " # # XmlNode Represent an Extensible Markup Language (XML) node in an XML document. " # # Arrays of XmlNode " # # The key points to remember when choosing the protocol for your Web Service are: ! GET and POST support only primitive data types (int, string, etc.), enums, and arrays of primitives. These datatypes are passed as name/value pairs. ! SOAP supports rich data types by packaging data in XML and standardizing the call format. ! SOAP provides for a rich extensibility mechanism. ! SOAP is not tied to HTTP as an underlying protocol. In the future, SOAP will soon become usable over File Transfer Protocol (FTP) and Simple Mail Transfer Protocol (SMTP). It might seem obvious that it is best to choose SOAP as the protocol for your Web Service, but there are few other issues to consider: ! HTTP-GET and HTTP-POST are much more widely used than SOAP, and therefore, you are limiting the clients that can use your Web Service. ! SOAP requests use a lot more bytes to transmit than HTTP-GET or HTTP- POST requests. ! By default, ASP.NET based Web Services support all of the three protocols as long as you restrict the Web Service methods to use only simple datatypes. 4 Module 8: Designing Web Services If you want to restrict the protocols that your Web Service will support, you can do this by making an entry in Web.config. The following code shows how to remove HTTP-GET and HTTP-POST protocols, and as a result the Web Service will support only SOAP. <configuration> <system.web> <webServices> <protocols> <remove name="HttpGet" /> <remove name="HttpPost" /> </protocols> </webServices> </system.web> </configuration> If you remove the HTTP-GET protocol, you will not be able to test your Web Service methods using the Web Service Method Description page provided for a Web Service project in Microsoft Visual Studio ® .NET. Structures vs. Classes It is very important to remember that Web Services are not about object remoting. When a Web Service method returns an object, the public fields and properties of the object are remoted. None of the functionality of the class is remoted. As a result, from a Web Service consumer’s perspective, classes and structures are superficially indistinguishable. Module 3, “The Underlying Technologies of Web Services,” in Course 2524A, Developing XML Web Services Using Microsoft Visual C# .NET Beta 2, described how XML Schema Definition Language (XSD) allows you to define derived datatypes. The flexibility of XSD is demonstrated in the following example. Consider the following class: public class Acct { public string description; public string number; public string type; public decimal balance; public string status; } public class CreditCardAcct : Acct { public int payPeriod; } Note Delivery Tip Explain the code for representing a class hierarchy using XSD by using the file <install folder>\Democode\Mod08\ ClassToXSD.txt. [...]... can use the capabilities of the NET Framework to improve the performance of your Web Service Specifically, you will learn about caching and state management for Web Services 14 Module 8: Designing Web Services General Considerations Topic Objective To provide an overview of activities that can affect performance of Web Services ! ! Asynchronous Calls ! Measuring ! There are a number of performance-related... dependency on an XML file 22 Module 8: Designing Web Services Delivery Tip Explain the code sample for inserting an item into a cache with a dependency using the file \Democode\Mod08\ CacheDepend.txt XmlDocument doc = new XmlDocument(); Doc. Load(Server.MapPath("employees.xml"); CacheDependency depend(Server.MapPath("employees.xml"); Context.Cache.Insert("Employees", doc, depend); The CacheDependency... to access the Web Service is not SOAP, the Web Service consumer will just receive an HTTP error with the error code value of 500 8 Module 8: Designing Web Services If a Web Service consumer invokes a method using SOAP, the exception is caught on the server and wrapped inside a new object of a type SoapException A SoapException can either be thrown by the common language runtime or by a Web Service method... to Web Services data, which you must consider are: ! Can your system scale to hundreds of millions of data items? For example, your Web Service might cache a list of the last three actions performed for each user ! If your site is designed to support millions of users actively using your Web Service, what techniques are you using to store, index, and retrieve the items? 10 Module 8: Designing Web Services. .. to associate metadata with a UDDI description of a Web Service.) In a situation, where a Web Service becomes unavailable, you can use this feature of UDDI to locate a Web Service that uses the same tModel as the unavailable Web Service For more information, see Module 6, “Publishing and Deploying Web Services, ” in Course 2524A, Developing XML Web Services Using Microsoft Visual C# NET Beta 2 Delivery... execute their code 16 Module 8: Designing Web Services Making Asynchronous Calls If you must execute an operation that takes a significant amount of time, then use asynchronous calls to execute the operation For example, if your Web Service calls another Web Service in a method named GetAccountHistory, then you should use the Beginxxxx/Endxxxx methods of the proxy for the second Web Service If the GetAccountHistory... Trace.WriteIf(mySwitch.TraceVerbose, "Deposit failed") 17 18 Module 8: Designing Web Services NET-Specific Considerations Topic Objective To explain some of the NET-specific considerations related to Web Services ! Disable Session State Lead-in ! Choose an Appropriate State Provider ! Avoid Exceptions ! Use Native Database Providers ! Use ASP NET Web Gardening ! Disable Debug Mode If you are not careful... through the Application object may cause your Web Service to have node affinity For example, if a Web Service stores some form of counter in Application state, it is likely that the value of the counter on a different computer will be different If a Web Service is sensitive to these kinds of inconsistency, it will not scale out well Module 8: Designing Web Services 13 % Performance Topic Objective To... the callback function 24 Module 8: Designing Web Services The following code shows how to receive notification when an item is removed from the cache All of the following code would be part of the class implementing a Web Service: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 internal class CacheData { internal Cache cache; internal XmlDocument doc; internal string path;... and performance in your Web Service AppDomains provide application isolation within the same process boundary Because of this feature, it is often a good idea to migrate any unmanaged code that your Web Service uses to the managed environment This will reduce the performance penalty incurred when your Web Service calls a component outside the AppDomain Module 8: Designing Web Services 27 Process Recovery . that will be applied to a Web Service. Module 8: Designing Web Services v ! Architectural Elements Explain that the Web Services programming model. Elements 36 Review 39 Module 8: Designing Web Services Information in this document, including URL and other Internet Web site references, is subject