WCF REST Starter Kit Preview 2 Release Notes

For more details including screencasts, whitepapers and more content about the WCF REST Starter Kit Preview 2, please refer to the REST on WCF page.

This document lists several important notes related to the WCF REST Starter Kit CodePlex Preview 2 release.

Installed Content

The following is a list of relevant content installed by the starter kit setup.

Under %ProgramFiles%\Microsoft WCF REST\WCF REST Starter Kit Preview 2

• WCF REST Starter Kit Preview 2.zip - source code and code samples for all features listed below

Note: Some projects may not work in given Visual Studio 2008 Express Editions. For example the HttpClient sample project is not supported in Visual Web Developer 2008 SP1. Some projects may not work in Visual Studio 2008 Standard Edition since they contain unit tests, which are not supported by this edition.

Under %ProgramFiles%\Microsoft WCF REST\WCF REST Starter Kit Preview 2\Assemblies

• Microsoft.Http.dll - reference this assembly to use HttpClient class
• Microsoft.Http.Extensions.dll - reference this assembly to use HttpClient extensions
• Microsoft.ServiceModel.Web.dll - referenced by project templates

In Visual Studio under New > Project > Web

• Atom Feed WCF Service C# project template
• Atom Publishing Protocol WCF Service C# project template
• HTTP Plain XML WCF Service C# project template
• REST Collection WCF Service C# project template
• REST Singleton WCF Service C# project template

In Visual Studio under New > Web Site > (select any website type) > right-click the web site in Solution Explorer > Add New Item

• Atom Feed WCF Service C# item template
• Atom Publishing Protocol WCF Service C# item template
• HTTP Plain XML WCF Service C# item template
• REST Collection WCF Service C# item template
• REST Singleton WCF Service C# item template

Note: The project and item templates are not supported in any Visual Studio 2008 Express Editions except Visual Web Developer 2008 SP1.

In Visual Studio create a new project and click on the Edit menu

• Paste XML as Type command

Note: The Paste XML as Type command is not available on any Visual Studio 2008 Express Editions.

System, Environment and Security Considerations

• The starter kit supports Visual Studio 2008 SP1 on 32 bit or 64 bit Windows Server 2008, Windows Server 2003, Windows XP, and Windows Vista. The starter kit uses RSS feeds, which are supported on Internet Explorer 7 or later. Using Internet Explorer 6 is not recommended. If you are using IIS to publish your Web site or Web application, it is recommended to use IIS 7.
• The starter kit will successfully install on Visual Studio 2008 Express Editions, however its full feature set may not be supported.
• There is a known issue that the starter kit installer will successfully complete if Microsoft Visual C++ 2008 Redistributable is installed, even if a supported version of Visual Studio 2008 is not present on the machine. This configuration will fail as Visual Studio 2008 is required for the starter kit to run.
• The Visual Studio templates are available only in Visual C#.
• The Visual Studio templates and code samples are not intended to be used directly in a production environment. Once you create a service using a template or sample, you must configure and modify it appropriately to meet your business requirements before deploying it in production. For example, the templates use an in-memory representation of the data, whereas real world applications may require a persistent store for their data. Please consult the corresponding documentation on MSDN to understand various configuration and other choices available.
• The Visual Studio templates currently do not have any security built into them, barring some samples that show how to use certain security features. It is recommended that you follow the security guidance available on MSDN and the patterns & practices Improving Web Services Security Guide (http://www.codeplex.com/WCFSecurityGuide), in order to identify the correct security design and implementation for your needs.
• The Visual Studio item templates provided in this starter kit are meant to be added to an ASP.NET Web Site. We do not recommend the use of these item templates in other project types as of this release. Also, these services cannot be called from ASP.NET AJAX clients. To create a WCF service for use with ASP.NET AJAX, please use the AJAX-enabled WCF Service item template, which is part of the default Visual Studio 2008 installation.

Guidance and Known Limitations

Visual Studio Templates

• When debugging or running a project based on one of the starter kit templates inside the Visual Studio ASP.NET Development Server, be sure to navigate to the .svc file in order to activate the service.
• The starter kit setup installs the project and item templates in the Visual Studio installation directory. If you would like to modify the templates source code and deploy them, please copy modified project templates to %MyDocuments%\Visual Studio 2008\Templates\ProjectTemplates\Visual C#\Web and modified item templates to %MyDocuments%\Visual Studio 2008\Templates\ItemTemplates\Visual Web Developer\CSharp.
• When adding an item template to an ASP.NET Web Site, Visual Studio puts the service code-behind file (for example Service.svc.cs) in the App_Code directory and the Service.svc file in the root folder.
• If you double-click the .svc file in Solution Explorer inside Visual Studio, the code behind file (.svc.cs file) may be opened. To view the markup (.svc) file, right-click the .svc file and select "View Markup".
• If a services uses the declarative caching feature of the starter kit and is hosted under Medium Trust in IIS 7, and there is a <caching> element in the service configuration file, then a SecurityException may be thrown. To work around this, remove the <caching> element from the configuration file and use [WebCache(Duration = 60, VaryByParam="none")] in the operation contract.

Hosting WCF REST Services

• The starter kit offers an advanced zero-configuration REST service feature, similar to the zero-configuration hosting is available out of the box in .Net 3.5 via the WebServiceHostFactory class. The Microsoft.ServiceModel.Web.WebServiceHostFactory2 class lets you retain the zero-config experience, while allowing you to adjust common deployment settings (maximum message size, quotas, etc). To use WebServiceHostFactory2, you need to modify the service .svc file, as demonstrated by all Visual Studio templates shipped in this release.

If you choose to use an item template that is provided in the starter kit, and you want to use ASP.NET compatibility features (http://blogs.msdn.com/wenlong/archive/2006/01/23/516041.aspx) such as using the ASP.NET pipeline for forms authentication/caching and other similar features, please remember to add an entry to the Web.config file to enable ASP.NET Compatibility.

• When developing REST-style service, developers often want to avoid the use of .svc extension that is common to WCF services. This can be achieved in IIS 7 using the URI rewriting module (http://learn.iis.net/page.aspx/465/url-rewrite-module-configuration-reference).

Paste XML as Type Command

• The command is not supported on Visual Studio 2008 Express Editions.
• The command will fail if trying to paste code into a Visual Studio window, while that window is in debugging mode.
• The command may add unnecessary references to System.Xml.Linq and System.Xml.Serialization (if pasting inside a Silverlight project). These can be safely removed if the generated code continues to compile.
• Users may build the Paste XML as Type command from sources in order to implement their own improvements. The feature is installed into Visual Studio by placing an .AddIn file and a .dll file in the %MyDocuments%\Visual Studio 2008\Addins folder. Please note that upon running Visual Studio for the first time after placing an updated set of files in the Addins folder, it needs to be started from the command line as follows devenv.exe /resetaddin PasteXmlAsType.Connect to ensure the new files are picked up.
• When generating types from a XML example:
  • the xsi:schemaLocation attribute and the xsi:noNamespaceSchemaLocation attributes are not honored
  • the encoding of the XML document is assumed to be UTF8
  • sequences of complex types will be recognized instances of those types appear under the same root element; different CLR types may be generated for the same complex type, if instances of that type appear in various places in the XML tree, and do not share a common root node
  • if the XML example on the clipboard does not contain a root node, the tool assumes two separate XML examples are being provided
  • the CLR types generated from a XML example will not be as accurate as types generated from a XSD schema (for example an enumeration will cause the generation of a String type, and a double may cause the generation of a decimal); if a schema is provided, please use that instead of the XML example.
• When generating types from a XSD schema:
  • <xs:import namespace="Test" schemaLocation= "test.xsd" />  elements are not honored and the schema will not be downloaded
  • any elements referenced using the ref attribute need to be local to the current schema
  • wildcards cannot be used at the top level of a schema
  • when importing the WCF enums schema (<xs:element name="FlagsEnum" nillable="true" type="tns:FlagsEnum" /> ), the generated code will not serialize correctly unless the IsNullable property on the XmlRootAttribute of the generated type is set to false
  • generating types from WCF service schema for IXmlSerializable types is not supported
  • generating types from WCF service schema for DateTimeOffset[] and DBNull[] is not supported.

HttpClient

• HttpClient uses the System.Net.WebRequest.DefaultWebProxy property. By default, this will use the settings configured in Internet Explorer. If Internet Explorer is set to "Automatically detect settings", the first request sent using HttpClient may take more time than subsequent requests. The proxy can be disabled or overridden on a per-HttpClient basis by setting the value of client.TransportSettings.Proxy. To disable the proxy, set the WebRequest.DefaultWebProxy or client.TransportSettings.Proxy to null.
• HttpClient also uses the settings specified by the System.Net.ServicePointManager. To modify the connection limit for a specific host, set the value of ServicePointManager.FindServicePoint(uri).ConnectionLimit.
  This behavior is subject to change in future versions of the HttpClient.

Samples, Unit Tests, and Resources

• The starter kit setup installs a WCF REST Starter Kit Preview 2.zip file to disk, which contains folders for each main set of features: HttpClient, Microsoft.ServiceModel.Web, and PasteXmlAsType. Each feature folder may contain "Samples" and "Tests" subfolders with code samples and unit tests.
• As noted in the "Installed Content" section, not all of the provided project and solution files will work on all Visual Studio Editions. For example, the starter kit project templates are not supported in Visual C# 2008 Express Edition, and the unit tests are not supported in Visual Studio 2008 Standard Edition.
• Additional learning resources are available at http://msdn.microsoft.com/wcf/rest.

Testing WCF REST Services using Fiddler

Fiddler is a client tool that allows you to test WCF REST services by constructing HTTP requests (using different verbs such as GET, POST, etc), sending them to a URI, and reading the responses. Fiddler can be downloaded for free from http://fiddlertool.com. The website contains a useful introductory video.

Note: Please ensure you have downloaded the latest version of Fiddler, as previous versions do not support some of the functionality described below.

The following sections go through the steps of debugging a service.

Using Fiddler with the ASP.NET Development Server in Visual Studio

When debugging a Web service, Visual Studio will launch the project in the ASP.NET Development Server, at a URI similar to http://localhost:27999/Service.svc, where the port number will vary. In order for the Fiddler tool to be able to capture the traffic, you need to replace "localhost" with "ipv4.fiddler". The requests will complete as though localhost was being used, but the HTTP traffic will be recorded in the Fiddler UI.

Sending a HTTP GET Request

1. Open the Request Builder tab in the right pane.
2. Select GET in the drop down menu.
3. Type in the URI if your service. Remember to use "ipv4.fiddler" instead of "localhost" if the service is hosted in the ASP.NET Development Server.
4. You can set the Content-Type to specify the content type that you expect in return. You can, for example, use text/xml or application/json for XML or JSON respectively. Get requests normally do not contain a body, and any data to be passed to the service can be passed as URI parameters.
5.  Press the Execute button.
6. There is now a new entry in the Web Sessions pane on the left and the result field contains the HTTP response code. In this example, the field shows 200 or Success.

1. To inspect the response message further, double-click the specific request you want to inspect in the Web Sessions pane on the left. The "Session Inspector" tab is displayed on the right. Select the "Raw" view for the request and the response.

When you call HTTP GET on a URI from Fiddler, you may get unexpected errors (such as 400 Bad Request). Make sure that the request body is completely empty (by deleting all whitespace until the red highlight on the request body is gone) before calling GET.

Sending HTTP POST and Other Requests

Calling HTTP POST on the service is different from HTTP GET only in the fact that the POST request contains data in the request body. The rest of the steps are identical.

1. Select the POST verb in the Request Builder view.
2. Set the request body. In this example we show a XML message.

Sending a HTTP PUT is similar to sending HTTP POST, as you usually pass a request body.

Sending a HTTP DELETE is similar to sending HTTP GET, as you usually do not pass a request body.

When you call HTTP methods on the service, you may get some unexpected behavior such as a 307 Temporary Redirect response code. To fix this issue try appending a forward slash ("/") at the end of the URI.

Testing WCF REST Services using HttpClient sample

If you do not wish to use Fiddler, or you need a lighter-weight solution, you can use one of the samples provided in the starter kit. The sample is located in the source code download package under HttpClient\Samples\WpfSample.

The functionality provided by the sample is similar to Fiddler.

Here is a description of some of the fields available:

1. Address of the service
2. HTTP verb used for the request
3. Headers can be modified in this area, and message credentials can also be specified
4. The message body can be specified for POST and PUT requests
5. Request headers that were set in #3
6. The response headers sent back by the service
7. The body of the response