Applying Basic Profile Rules When Consuming Web Services

Article
06/22/2007

Microsoft Corporation

August 2003

Applies to:
Microsoft® Visual Studio® .NET

Summary: Adjust your code to make it comply with the constraints set forth in the Basic Profile. (50 printed pages)

Messaging
Service Description
Service Publication and Discovery
Security

Developers who write Web service clients may find that they need to adjust their code to make it comply with the constraints set forth in the Basic Profile. To provide some guidance on how to make these adjustments, we first made some general assumptions about how a developer will implement a client that consumes Web services.

These assumptions are made for the purposes of this chapter because otherwise they would apply very broadly. For example, if alternatives to using SoapHttpClientProtocol (such as HttpWebRequest) were considered for each rule, then a large portion of rules would be listed as potentially compliant since using something like HttpWebRequest allows very flexible control in the request allowing for a violation of the rule.

These assumptions are:

The Web client is implemented as a class derived from the .NET SoapHttpClientProtocol class, Microsoft® Visual Studio® .NET Add Web Reference wizard generates a template class derived from the SoapHttpClientProtocol class when it creates a client that consumes a Web service.
No parameters, return values, or headers contain XmlNode types.
The Web service and its WSDL description are compliant with the WS-I Basic Profile.

Next, we assigned each of the Basic Profile rules one of four possible levels of compliance. These levels indicate how closely a client written according to our assumptions complies with the rules' requirements. These levels are:

Compliant — this means that if the profile rule is applicable to your client or the Web service you are using, you will not need to make any code changes to meet the requirements of the rule. Note that "weak" rules that contain SHOULD or MAY are classified as compliant when the Web client does not meet their requirements. This is because these rules aren't mandatory. See R2008 for an example.
Typically compliant — this means that if the particular profile rule is applicable to your client or the Web service you are using, it probably meets the requirements of the rule but there is a possibility it needs code adjustments.
Potentially compliant — this means that if the particular profile rule is applicable to your client or the Web service you are using, you will probably need to make code adjustments to make your Web client meet the rule's requirements.
Unique — this means that if the profile rule is applicable to your client or the Web service you are using, you will need to make code adjustments such as using HttpWebRequest for more low-level control.

All directives are included in the same groups (such as messaging) and order as they are listed in the Basic Profile. Note that only the rule numbers and directives are included here. For the complete text, consult the WS-I Basic Profile. The next entry after the rule is the level of compliancy and the final entry includes comments, suggestions and code samples. Here is an example of the format:

R0001 © Profile rule number

An INSTANCE MUST be described by a WSDL 1.1 service description, by a UDDI binding template, or both. © Profile rule

Compliant © Level of compliancy

A .NET Web service supports generating a WSDL 1.1 service description by using reflection on the WebService class. © Comment

Messaging

Messaging is the exchange of protocol elements, usually over a network. Messages encapsulate information transmitted to and from a Web service. These messages do not provide programming instructions; rather they specify to a Web services server which operations to invoke. According to the WS-I Basic Profile, the messaging system uses the following standards at the specified version levels:

Simple Object Access Protocol (SOAP) 1.1
Extensible Markup Language (XML) 1.0 (Second Edition)
RFC2616: Hypertext Transfer Protocol —HTTP/1.1
RFC2965: HTTP State Management Mechanism

XML Representation of SOAP Messages

This section includes directives in section 3.1 of the Basic Profile, which deals with the XML representation of SOAP messages. All these directives are based on the SOAP 1.1, Section 4 standard.

R0001

An INSTANCE MUST be described by a WSDL 1.1 service description, by a UDDI binding template, or both.

Compliant

The Add Web Reference wizard in Visual Studio.NET supports importing a WSDL 1.1 description either directly or through a UDDI registry.

R0002

A DESCRIPTION MAY contain conformance claims regarding instances, as specified in the conformance claim schema.

Unique

The Add Web Reference wizard in Visual Studio.NET fails with a WSDL description that contains conformance claims. You need to manually remove the wsi:Claim elements to have the wizard properly process the WSDL description.

R0003

A DESCRIPTION's conformance claims MUST be children of the wsdl:documentation element of each of the elements: wsdl:port, wsdl:binding, wsdl:portType, wsdl:operation (as a child element of wsdl:portType but not of wsdl:binding) and wsdl:message.

Unique

R0004

A MESSAGE MAY contain conformance claims, as specified in the conformance claim schema.

Compliant

When you invoke a Web service using the proxy class generated by the Add Web Reference wizard in Visual Studio.NET, the default is to exclude conformance claims. To include a conformance claim, you must manually modify the proxy class to include a conformance claim header, and make sure to set the header property to a valid instance of the header before invoking the Web service. The following example demonstrates how to modify the proxy class to include the conformance claim (bold lines are the necessary additional code):

// Existing web service class declaration
public class MyWebService : SoapHttpClientProtocol {

  // Add claim header variable declaration
  public ClaimHeaderType ClaimHeaderValue;
  // Other existing header variable declarations

  // Add claim soap header
  [SoapHeaderAttribute("ClaimHeaderValue")]
  // Existing web method declaration

}

// Add ClaimHeaderType class
[XmlRoot ("Claim",    Namespace="http://ws-i.org/schemas/conformanceClaim/",    IsNullable=false)]public class ClaimHeaderType : SoapHeader{  [XmlAttribute ()]  public string conformsTo = "http://ws-i.org/profiles/basic/1.0";}

R4001

A RECEIVER MUST accept messages that include the Unicode Byte Order Mark (BOM).

Not applicable

This rule is not applicable to consuming a Web service. When you invoke a Web service using the proxy class generated by the Add Web Reference wizard in Visual Studio.NET, the default is to exclude the BOM. The following example demonstrates how to use the RequestEncoding property to include the BOM in the message:

localhost.Service1 myService = new localhost.Service1()
// passing true to the UTF8Encoding constructor tells
// it to include the Unicode BOM
myService.RequestEncoding = new System.Text.UTF8Encoding(true);
String result = myService.HelloWorld();

R1000

When a MESSAGE contains a soap:Fault element, that element MUST NOT have element children other than faultcode, faultstring, faultactor and detail.

A MESSAGE MUST be serialized as either UTF-8 or UTF-16.

Typically Compliant

When you invoke a Web service using the proxy class generated by the Add Web Reference wizard in Visual Studio.NET, it will, by default, use UTF-8 encoding. You can specify what encoding to use by setting the RequestEncoding property. In this case, you must use either UnicodeEncoding or UTF8Encoding. The following example shows how to specify UTF-16 encoding (Unicode):

localhost.Service1 myService = new localhost.Service1();
// Sets the encoding style to use UTF-16
myService.RequestEncoding = System.Text.Encoding.Unicode;
String result = myService.HelloWorld();

An INSTANCE MUST use HTTP status code "307 Temporary Redirect" when redirecting a request to a different endpoint.

Not Applicable

This rule is not applicable to consuming a Web service. When you invoke a Web service using the proxy class generated by the Add Web Reference wizard in Visual Studio.NET, it will treat a "307 Temporary Redirect" HTTP status code as an exception, allowing for the code to respond as needed.

R1131

A CONSUMER MAY automatically redirect a request when it encounters a "307 Temporary Redirect" HTTP status code in a response.

Compliant

When you invoke a Web service using the proxy class generated by the Add Web Reference wizard in Visual Studio.NET, it does not automatically redirect a request when it receives a "307 Temporary Redirect" HTTP status code. The following example shows how you can follow the redirect URL:

localhost.Service1 myService = new localhost.Service1();
string result;
bool redirect;
do
{
  redirect = false;
  try
  {
    result = myService.HelloWorld();
  }
  catch (WebException ex)
  {
    HttpWebResponse response = (HttpWebResponse)ex.Response;
    if (response.StatusCode == HttpStatusCode.TemporaryRedirect)
    {
      myService.Url = response.Headers["location"];
      redirect = true;
    }
    else
    {
      throw;
    }
  }
}
while (redirect == true);

R1125

An INSTANCE MUST use a 4xx HTTP status code for responses that indicate a problem with the format of the request.

Compliant

When you invoke a Web service using the proxy class generated by the Add Web Reference wizard in Visual Studio.NET, it properly processes a response that adheres to this rule.

R1113

An INSTANCE SHOULD use a "400 Bad Request" HTTP status code, if the request message is a malformed HTTP request, or not well-formed XML.

Compliant

When you invoke a Web service using the proxy class generated by the Add Web Reference wizard in Visual Studio.NET, it properly processes a response that adheres to this rule. The proxy class always generates a properly formed HTTP request containing well-formed XML.

Compliant

The Add Web Reference wizard in Visual Studio.NET properly interprets a WSDL description in a manner that adheres to this rule.

XML Schema

An XML schema represents the interrelationship between the attributes and elements of an XML object (for example, a document or a portion of a document). To create a schema for a document, you analyze its structure, defining each structural element as you encounter it. For example, within a schema for a document describing a Web site, you would define a Web site element, a Web page element, and other elements that describe possible content divisions within any page on that site. Just as in HTML, elements are defined within a set of tags.

R2800

A DESCRIPTION MAY use any construct from XML Schema 1.0.

Compliant

The Add Web Reference wizard in Visual Studio.NET properly processes a WSDL description that adheres to this rule.

R2801

A DESCRIPTION MUST use XML Schema 1.0 Recommendation as the basis of user defined datatypes and structures.

Compliant

The Add Web Reference wizard in Visual Studio.NET properly processes a WSDL description that adheres to this rule.

Service Publication and Discovery

The purpose of a UDDI registry is to give people a way to find and use a Web service. The UDDI registry accepts information describing a business, including the Web services it offers, and allows users to perform online searches and to download information. The two main parts of UDDI are registration (or publication) and discovery. Registration means that businesses can post information to UDDI that other businesses can search for and discover. UDDI registration is contained in a variety of data structures, two of which, binding templates and tModels, are addressed in the Basic Profile.

Binding Templates

A binding template is a UDDI data structure that organizes information for specific instances of service types. When businesses want to make their specification-compliant services available to the registry, they include a reference to the tModelKey (see below) for that service type in their binding template data. Binding templates provide information for physically accessing a Web service that is registered with UDDI. Examples of the access points in the bindingTemplate structure include mailto:, http:, and phone:.

R3100

REGDATA of type uddi:bindingTemplate representing a conformant INSTANCE MUST contain the uddi:accessPoint element.

Not applicable

Visual Studio.NET does not provide a tool for registering a Web service in a UDDI registry.

tModels

When you invoke a Web service using the proxy class generated by the Add Web Reference wizard in Visual Studio.NET, you can use the ClientCertificates property of the proxy class to pass a client certificate to the Web service that requires mutual authentication.

Applying Basic Profile Rules When Consuming Web Services

Contents

R0001 © Profile rule number

Messaging

XML Representation of SOAP Messages

R0001

R0002

R0003

R0004

R0005

R0006

R0007

R3020

R3030

R3021

R3005

R3004

R4001

R1000

R1001

R1002

R1003

R1016

R1004

R1031

R1005

R1006

R1007

R1008

R1009

R1010

R1011

R1012

R1018

R1013

R1014

R1015

R1017

The Soap Processing Model

R1025

R1027

R1028

R1029

R1030

Using SOAP in HTTP

R1140

R1141

R1107

R1132

R1108

R1109

R1119

R1110

R1124

R1111

R1112

R1130

R1131

R1125

R1113

R1114

R1115

R1126

R1120

R1122

R1121

R1123

Service Description

Document Structure

R2028

R2029

R2001

R2002

R2003

R2004

R2009

R2010

R2011

R2007

R2008