Mary Kirtland

Microsoft Developer Network

Updated August 2001

Summary: This page introduces the Favorites Service, MSDN's first sample XML Web Service, and demonstrates the value of .NET, Microsoft's platform for XML Web Services. The Favorites Service allows users to save their favorites on the server. Server-side favorites are the same as browser favorites, except that the user's data is stored on a server rather than on the user's machine. The Favorites Service allows your Web site customers to save, organize, and access their favorite Web pages as they move from device to device.

The products and technologies used include: Microsoft? SQL Server? 2000, Microsoft SOAP Toolkit 2.0, Microsoft? Visual Basic? 6.0, Microsoft? Visual C++? Active Template Libraries (ATL), Microsoft? Windows? NT Server, and the Simple Mail Transfer Protocol (SMTP) service that comes as part of Microsoft Internet Information Services (IIS). The page below contains a description of the individual articles in the Favorites Service documentation set and related At Your Service columns, and explains how they all fit together. (7 printed pages)

You can download the Favorites Service source code from the MSDN Online Code Center.

To view the sample Web Service discussed in this article, go to http://www.coldrooster.com/favorites.asp.

Introduction

The Favorites Service is a sample created by the MSDN Architectural Samples Team that is designed to provide practical guidance regarding the key issues you should consider when building scalable, reliable, secure Web Services. The sample is accompanied by a set of documentation that describes the design, development, and deployment of the service. Although we have implemented a specific service, the issues we encountered, lessons learned, and techniques used through the life cycle of the project will apply to any Web Services project. This article provides an overview of the Favorites Service and describes the individual articles in the documentation set and how they fit together. For your convenience, it also describes At Your Service columns related to the Favorites Service and how these relate to the documentation set.

The Favorites Service

For each of the samples created by the MSDN Architectural Samples Team, we try to define a realistic but fictitious business scenario. We implement the sample as if our team worked for the company described in the business scenario. The business scenario we chose for this sample is defined in my At Your Service column, "Defining the Vision."

We then started looking for an appropriate teaser service. As avid users of the Web, we recognize that one of the problems end users face is locating pages they've previously visited. While you can use browser favorites to keep track of favorite pages, browser favorites are local to a specific machine. But what if you use multiple machines or devices? Continuing along this track, we came up with the idea of a Web Service that would enable Web sites to store links to an end user's favorite Web pages out on a server somewhere, so the end user could easily access the favorites from any machine.

Our next step was to create a vision for the Favorites Service itself, as described in "Defining the Vision."

Based on some early investigation into user privacy and authentication issues (discussed in the forthcoming "Licensing and Security" article), we decided to deliver the Favorites Service in phases. The first release of the service, covered by this documentation set, is known as Phase One. See our vision for Phase One in "Defining the Vision."

The complete vision document also includes user profiles, business objectives, and design goals for the Favorites Service.

The Favorites Documentation

The Favorites documentation serves two purposes:

First, it describes the final deliverables—the overall architecture of the system, the design and implementation of individual components of the system, how to build the system, how to deploy it, and so on.

Second, we attempt to give you some insight into the project itself. For example, we try to explain why one design was chosen over another, why we used one product and not another, as well as the problems we encountered and how we worked around them.

The articles are grouped into four categories: design, development, deployment, and project artifacts. Design articles focus on the logical design of the system. Development articles look at physical design and coding. Deployment articles cover test and operations issues. Finally, project artifacts are things like the project vision document and functional specification—documents written from the perspective of our fictitious company, Cold Rooster Consulting, during the creation of the Favorites Service.

It is not necessary to read every article in a particular category. However, you will probably find it helpful to read the Architectural Overview and the Physical Design Overview before reading other development or deployment articles.

Design Documentation

In this set of articles, we discuss some of the design decisions and trade-offs for creating a Web Service in the context of the Favorites Service. The design articles include:

Architectural Overview (April 2001)

Describes the overall structure of the Favorites Service, its major components, and deployed configuration.

At Your Service: Getting to Know Us (Jan. 3, 2001)

Provides a high-level introduction to the Web Services Guidance Team (part of the MSDN Architectural Samples Team) and the Favorites Service.

At Your Service: Defining the Vision (Jan. 10, 2001)

Describes the process we went through to refine the vision for the Favorites Service.

At Your Service: User Privacy (Feb. 14, 2001)

Describes the user privacy issues we identified as we defined the vision for the Favorites Service, how we changed the vision to avoid some hard problems, the remaining user privacy issues in Phase One and how those impacted our design and implementation.

Licensing and Security Design (May 2001)

Describes the business model used by the Favorites Service, licensing and security options considered to enforce the business model, and the final design selected for the Favorites Service. An introduction to these topics is provided in the following two columns:

At Your Service: Licensing (Feb. 21, 2001)

At Your Service: Authentication and Authorization (Feb. 28, 2001)

At Your Service: Licensee Requirements from Dev, Test, and Ops (Mar. 14, 2001)

Discusses the requirements that developers, testers, and operations staff from licensees using our service might have for the Favorites Service. For example, how does a Licensee's developer test calls to the Favorites Service without impacting production data stores, and how does a Licensee's operator determine whether the Favorites Service is live and processing requests? As it turns out, these requirements can represent a significant percentage of the overall requirements for a service.

At Your Service: Designing the Contract (June 5, 2001)

Discusses issues about the design of the interface to the Favorites Web Service, including globalization issues, factoring service functionality, and dealing with licensing and security.

Development Documentation

In this set of articles, we discuss the implementation of each major component of the Favorites Service, highlighting the major issues and techniques that will be useful in other Web Service projects. The development articles include:

Physical Design Overview (April 2001)

Describes the physical components that make up the Favorites Service, the technologies used, and why these technologies were selected.

At Your Service: Physical Architecture (June 20, 2001)

A high-level look at the physical design and the production configuration of the service is discussed, as well as the decisions you need to make to deploy the Web Service on a machine or collection of machines for use in the real world.

Account Web Service Development Details (May 2001)

Describes the implementation of the Web Service that performs user favorites management.

Licensing a Web Service (May 2001)

Describes the implementation of the components that manage licenses to use the Favorites Service.

Security Development Details (May 2001)

Describes the implementation of the components that implement authentication and authorization for the Favorites Service.

Auditing a Web Service (May 2001)

Describes the implementation of the components that track use of the Favorites Service.

Building the Source (May 2001)

Describes the source code of the Favorite Service and procedures for building the service using scripts provided in the Favorites Service download.

Favorites Service API Reference (June 2001)

Discusses errors and methods for the Favorites Web Service. The errors are returned as Simple Object Access Protocol (SOAP) faults and are divided into two main classes: client faults and server faults. The methods allow the user to store and manipulate user favorites.

The Favorites Service Reporting Service (August 2001)

Describes the implementation of the Web Service that provides usage reports to licensees.

Developer's Guide to the Favorites Service (August 2001)

Discusses the implementation of the sample client site that is part of the Favorites SDK, illustrating how to use the Favorites Service from an application. This article focuses on the portions of the sample client that call the Favorites Service.

Creating the Favorites Service Install (August 2001)

Discusses the implementation of the Setup program for the Favorites Service, focusing on those issues unique to Web Services.

At Your Service: Web Service Description and Discovery Using UDDI, Part II (October 17, 2001)

Discusses how we registered the Favorites Service with the UDDI Business Registry.

Deployment Documentation

In this set of articles, we discuss some of the test and operations issues we encountered, as well as procedures for deploying the Favorites Service. The deployment articles include:

Installing the Favorites Service (May 2001)

Discusses how to use the Setup program in the Favorites Download to install and configure the Favorites Service on your own computer.

Capacity Planning and Costs (August 2001)

Discusses how we determined what hardware was needed to meet estimated usage of our Web Service, our production configuration, and the costs of hardware and software required to deploy the service on our production configuration. An introduction to our production configuration is provided in the following At Your Service column:

Favorites Service Operations Configuration (August 2001)

Discusses how we set up the Web Servers in our production configuration.

How to Test a Web Service (August 2001)

Discusses issues encountered testing the interface to the Favorites Web Service.

Performance and Scalability Testing (August 2001)

Discusses the performance and scalability testing we performed on the Favorites Service, focusing on the techniques used to measure performance and diagnose bottlenecks.

Favorites Service Test Tools and Scripts (August 2001)

Discusses the test tools we used to automate testing of the Favorites Web Service.

Troubleshooting Web Services (August 2001)

Describes some troubleshooting techniques used by our developers while they were implementing the Favorites Service.

At Your Service: Defending Your XML Web Service Against Hackers, Part I (September 5, 2001)

At Your Service: Defending Your XML Web Service Against Hackers, Part II(September 19, 2001)

Discusses some operational procedures that can be used to protect the Favorites Service from attack, as well as how to respond to attacks in progress.

At Your Service: Interoperability Testing

Discusses tests to ensure that the Favorites Service can be accessed from applications written using a variety of different toolsets that support SOAP.

Project Artifacts

These are documents written from the perspective of Cold Rooster Consulting during the creation of the Favorites Service. The documents are referenced by some of the design, development, and deployment articles. You may also find them useful as templates for documents you create during your own Web Service projects.

Vision Document

Describes the Cold Rooster Consulting vision for the Favorites Service. Provides user profiles, business objectives, and overall design goals.

Phase 1 Functional Specification

Defines the requirements for Phase 1 of the Favorites Service.

Phase 2 Functional Specification

Defines the requirements for Phase 2 of the Favorites Service.

Conclusion

Through the development and documentation of this sample Web Service, the MSDN Architectural Samples Team is trying to show developers the benefits of implementing programmable services that other developers can use. With the proliferation of these types of services, creating integrated Web applications will become as easy to develop as Visual Basic applications with Visual Basic components. Throughout this documentation set, we hope to answer the questions developers run across when designing or developing their own Web Services.

For More Information

For more information on .NET, see the MSDN .NET Development page and the Microsoft .NET Web site.