1 out of 5 rated this helpful - Rate this topic

WCF Web HTTP Service Help Page

.NET Framework 4

.NET Framework 4.5

.NET Framework version 4 provides an automatic help page for WCF WEB HTTP services. This help page lists a description of each operation, request and response formats, and schemas. This functionality is turned off by default. When a user browses to a WCF WEB HTTP service and appends "/Help" on to the end of the URL, for example http://localhost:8000/Customers/Help, a help page like the following is displayed.

Ee230442.edd33e88-2823-4a28-bbaf-fc6871602998(en-us,VS.100).gif

The user can then click any method listed in the help page and detailed page for that operation is displayed showing more information about the method, including message formats and example responses. The following image is an example of a help page for a method.

Ee230442.d22aafe8-f607-478d-9b02-403fedbc77f1(en-us,VS.100).gif

Using the WCF Web HTTP Help Page

The WCF WEB HTTP Help page displays a short description for each operation provided that you specify one using the DescriptionAttribute. This attribute takes a string that contains a short description of the operation it is applied to. For example, the following code shows how to use the DescriptionAttribute to provide a short description.

Copy

[OperationContract]
[WebGet(UriTemplate="/template1", BodyStyle = WebMessageBodyStyle.Bare)]
[Description("Description for GET /template1")]
SyndicationFeedFormatter GetTemplate1();

To turn on the WCF WEB HTTP Help page, you must add an endpoint behavior to your service's endpoints. This can be done in configuration or code. To enable the WCF WEB HTTP Help age in configuration, add an endpoint behavior with a <webHttp> element, set enableHelp to true, and add an endpoint and configure it to use the endpoint behavior. The following configuration code shows how to do this.

Copy

<endpointBehaviors>
   <behavior name="RESTEndpointBehavior">
      <webHttp helpEnabled="true"/>
   </behavior>
</endpointBehaviors>
<!-- ... -->
<services>
   <service behaviorConfiguration="RESTWebServiceBehavior" name="RESTWebService">      <endpoint address="" kind="webHttpEndpoint" behaviorConfiguration="RESTEndpointBehavior" contract="IHello" />
      
      <!-- ... -->
   </service>
</services>

To enable the WCF Web HTTP Help page in code, add a service endpoint and add a WebHttpBehavior to the endpoint setting EnableHelp to true. The following code shows how to do this.

Copy

using (WebServiceHost host = new WebServiceHost(typeof(Service), new Uri("http://localhost:8000/Customers")))
{
   host.AddServiceEndpoint(typeof(ICustomerCollection), new WebHttpBinding(), "");             
   host.Description.Endpoints[0].Behaviors.Add(new WebHttpBehavior { EnableHelp = true });
   // ...
}

The help page is XHTML based with mark-up that identifies the different parts of the page. This enables clients to programmatically access the page using XElement or other XLinq APIs.

Schemas Used in the WCF Web HTTP Service Help Page

The following schemas are used in the WCF Web HTTP service help page.

Copy

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns:tns="http://schemas.microsoft.com/2003/10/Serialization/" attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/2003/10/Serialization/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="anyType" nillable="true" type="xs:anyType" />
  <xs:element name="anyURI" nillable="true" type="xs:anyURI" />
  <xs:element name="base64Binary" nillable="true" type="xs:base64Binary" />
  <xs:element name="boolean" nillable="true" type="xs:boolean" />
  <xs:element name="byte" nillable="true" type="xs:byte" />
  <xs:element name="dateTime" nillable="true" type="xs:dateTime" />
  <xs:element name="decimal" nillable="true" type="xs:decimal" />
  <xs:element name="double" nillable="true" type="xs:double" />
  <xs:element name="float" nillable="true" type="xs:float" />
  <xs:element name="int" nillable="true" type="xs:int" />
  <xs:element name="long" nillable="true" type="xs:long" />
  <xs:element name="QName" nillable="true" type="xs:QName" />
  <xs:element name="short" nillable="true" type="xs:short" />
  <xs:element name="string" nillable="true" type="xs:string" />
  <xs:element name="unsignedByte" nillable="true" type="xs:unsignedByte" />
  <xs:element name="unsignedInt" nillable="true" type="xs:unsignedInt" />
  <xs:element name="unsignedLong" nillable="true" type="xs:unsignedLong" />
  <xs:element name="unsignedShort" nillable="true" type="xs:unsignedShort" />
  <xs:element name="char" nillable="true" type="tns:char" />
  <xs:simpleType name="char">
    <xs:restriction base="xs:int" />
  </xs:simpleType>
  <xs:element name="duration" nillable="true" type="tns:duration" />
  <xs:simpleType name="duration">
    <xs:restriction base="xs:duration">
      <xs:pattern value="\-?P(\d*D)?(T(\d*H)?(\d*M)?(\d*(\.\d*)?S)?)?" />
      <xs:minInclusive value="-P10675199DT2H48M5.4775808S" />
      <xs:maxInclusive value="P10675199DT2H48M5.4775807S" />
    </xs:restriction>
  </xs:simpleType>
  <xs:element name="guid" nillable="true" type="tns:guid" />
  <xs:simpleType name="guid">
    <xs:restriction base="xs:string">
      <xs:pattern value="[\da-fA-F]{8}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{12}" />
    </xs:restriction>
  </xs:simpleType>
  <xs:attribute name="FactoryType" type="xs:QName" />
  <xs:attribute name="Id" type="xs:ID" />
  <xs:attribute name="Ref" type="xs:IDREF" />
</xs:schema>

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns:tns="http://microsoft.com/wsdl/types/" elementFormDefault="qualified" targetNamespace="http://microsoft.com/wsdl/types/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:simpleType name="guid">
    <xs:restriction base="xs:string">
      <xs:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}" />
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="char">
    <xs:restriction base="xs:unsignedShort" />
  </xs:simpleType>
</xs:schema>

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns:tns="http://schemas.datacontract.org/2004/07/System" elementFormDefault="qualified" targetNamespace="http://schemas.datacontract.org/2004/07/System" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:import namespace="http://schemas.microsoft.com/2003/10/Serialization/" />
  <xs:complexType name="DateTimeOffset">
    <xs:annotation>
      <xs:appinfo>
        <IsValueType xmlns="http://schemas.microsoft.com/2003/10/Serialization/">true</IsValueType>
      </xs:appinfo>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="DateTime" type="xs:dateTime" />
      <xs:element name="OffsetMinutes" type="xs:short" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="DateTimeOffset" nillable="true" type="tns:DateTimeOffset" />
  <xs:complexType name="DBNull">
    <xs:sequence />
  </xs:complexType>
  <xs:element name="DBNull" nillable="true" type="tns:DBNull" />
</xs:schema>

<?xml version="1.0" encoding="utf-16"?>
<xs:schema xmlns:tns="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:ser="http://schemas.microsoft.com/2003/10/Serialization/" elementFormDefault="qualified" targetNamespace="http://schemas.microsoft.com/2003/10/Serialization/Arrays" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:import namespace="http://schemas.microsoft.com/2003/10/Serialization/" />
  <xs:complexType name="ArrayOfboolean">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="boolean" type="xs:boolean" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfboolean" nillable="true" type="tns:ArrayOfboolean" />
  <xs:complexType name="ArrayOfchar">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="char" type="ser:char" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfchar" nillable="true" type="tns:ArrayOfchar" />
  <xs:complexType name="ArrayOfdateTime">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="dateTime" type="xs:dateTime" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfdateTime" nillable="true" type="tns:ArrayOfdateTime" />
  <xs:complexType name="ArrayOfdecimal">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="decimal" type="xs:decimal" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfdecimal" nillable="true" type="tns:ArrayOfdecimal" />
  <xs:complexType name="ArrayOfdouble">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="double" type="xs:double" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfdouble" nillable="true" type="tns:ArrayOfdouble" />
  <xs:complexType name="ArrayOffloat">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="float" type="xs:float" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOffloat" nillable="true" type="tns:ArrayOffloat" />
  <xs:complexType name="ArrayOfguid">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="guid" type="ser:guid" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfguid" nillable="true" type="tns:ArrayOfguid" />
  <xs:complexType name="ArrayOfint">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="int" type="xs:int" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfint" nillable="true" type="tns:ArrayOfint" />
  <xs:complexType name="ArrayOflong">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="long" type="xs:long" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOflong" nillable="true" type="tns:ArrayOflong" />
  <xs:complexType name="ArrayOfshort">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="short" type="xs:short" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfshort" nillable="true" type="tns:ArrayOfshort" />
  <xs:complexType name="ArrayOfstring">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="string" nillable="true" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfstring" nillable="true" type="tns:ArrayOfstring" />
  <xs:complexType name="ArrayOfduration">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="duration" type="ser:duration" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfduration" nillable="true" type="tns:ArrayOfduration" />
  <xs:complexType name="ArrayOfunsignedInt">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="unsignedInt" type="xs:unsignedInt" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfunsignedInt" nillable="true" type="tns:ArrayOfunsignedInt" />
  <xs:complexType name="ArrayOfunsignedLong">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="unsignedLong" type="xs:unsignedLong" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfunsignedLong" nillable="true" type="tns:ArrayOfunsignedLong" />
  <xs:complexType name="ArrayOfunsignedShort">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="unsignedShort" type="xs:unsignedShort" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfunsignedShort" nillable="true" type="tns:ArrayOfunsignedShort" />
  <xs:complexType name="ArrayOfQName">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="QName" nillable="true" type="xs:QName" />
    </xs:sequence>
  </xs:complexType>
  <xs:element name="ArrayOfQName" nillable="true" type="tns:ArrayOfQName" />
</xs:schema>

For more information about the data contract serialization schema, see Data Contract Schema Reference.

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

Community Content Add

FAQ

Custom / Override Help Page

Is there a way to override json sample in help page ??? thanks$0

History

5/28/2012
anmezaf

ASP.NET MVC 4.0 Web API

Can we do similar stuff for ASP.NET MVC 4.0 Web API? If so how?

Thanks for the help in advance.

History

5/4/2012
ptpavankumar

Configuration file segment

The <endpointBehavior> is an element of the <system.serviceModel><behaviors> branch of the configuration.

History

3/12/2012
Suncat2000

Actual URL for help page

More over when I tried to open a help page by url like "http://localhost:49855/Service1/help", it showed me 404 error page. Then I tried appending /help after the complete service url, i.e. " http://localhost:49855/Service1.svc", then it worked and I got a help page. $0$0 $0 $0So the actual help page url is "http://localhost:49855/Service1.svc/help".$0

History

1/3/2012
vishal sharma

Service description attribute was WebHelp, now Description

For those of you looking for the Microsoft.ServiceModel.Web.WebHelpAttribute class from the REST Starter Kit that previously allowed you to customize the service description, it was removed it in favor of the System.ComponentModel.DescriptionAttribute class. It took me several days and countless web searches to root this out, so I'm adding this note to help others marooned by Microsoft, as I was.

History

12/22/2011
Suncat2000

Small correction

The correct name of the attribute is "helpEnabled" as shown below NOT "enableHelp".

<endpointBehaviors>
   <behavior name="RESTEndpointBehavior">
      <webHttp helpEnabled="true"/>
   </behavior>
</endpointBehaviors>

History

6/5/2011
Nelson Paily Varghese