Deploying an Internet Information Services-Hosted WCF Service

Article
07/06/2011

Visual Studio 2010 provides two different ways to deploy a WCF service to be hosted under IIS. Within a WCF Service Application Project you can tell Visual Studio to host the service on the local IIS instance. Or from any WCF project type you can instruct Visual Studio to deploy the service to any IIS instance. You can also manually deploy a WCF service to IIS. For a detailed walkthrough of creating an IIS-hosted WCF service, see How to: Host a WCF Service in IIS.

Before hosting or deploying a WCF service to IIS, make sure that IIS, ASP.NET, and WCF are installed and configured correctly.

Ensure That IIS, ASP.NET and WCF Are Correctly Installed and Registered

WCF, IIS, and ASP.NET must be installed for IIS-hosted WCF services to function correctly. The procedures for installing WCF (as part of the .NET Framework 3.0), ASP.NET and IIS vary depending on the operating system version being used. For more information about installing WCF and the .NET Framework 3.0, see Microsoft .NET Framework 4.0 Web Installer. Instructions for installing IIS can be found at Installing IIS.

The installation process for the .NET Framework 3.0 automatically registers WCF with IIS if IIS is already present on the machine. If IIS is installed after the .NET Framework 3.0, an additional step is required to register WCF with IIS and ASP.NET. You can do this as follows, depending on your operating system:

Windows XP SP2 and Windows Server 2003: Use the ServiceModel Registration Tool (ServiceModelReg.exe) tool to register WCF with IIS: To use this tool, type ServiceModelReg.exe /i /x in the Visual Studio command prompt. You can open this command prompt by clicking the start button, selecting All Programs, Microsoft Visual Studio 2010, Visual Studio Tools, and Visual Studio Command Prompt (2010).
Windows Vista: Install the Windows Communication Foundation Activation Components subcomponent of the .NET Framework 3.0. To do this, in Control Panel, click Add or Remove Programs and then Add/Remove Windows Components. This activates the Windows Component Wizard.

Finally you must verify that ASP.NET is configured to use the .NET Framework version 4.0. You do this by running the ASPNET_Regiis tool with the –i option. For more information, see ASP.NET IIS Registration Tool

Using Visual Studio 2010 to Host a WCF Service on the Local IIS Instance

Open or create a WCF Service Application project. Right click the project in the solution explorer and select Properties. In the project properties window select the Web tab on the left hand side of the window. On the right hand side of the window, under Servers, select the Use Local IIS Web Server and type in a URL. Next, click the Create Virtual Directory button and build the solution. This will create the virtual directory in IIS and map it to your project directory. The service will then be hosted on the local IIS server for building and debugging purposes. To verify the service has been hosted, open Internet Explorer and type the service’s URL in the address box. You must type in the complete URL path to the .svc file. For example, with a default WCF Service Application project hosted under https://localhost/MyFirstService the complete URL would be https://localhost/MyFirstService/Service1.svc. This will display the default WCF Service page.

Using Visual Studio to Deploy a WCF Service to IIS

From any WCF service project type, go to the Build menu and select the Publish <Project Name> item. In the Publish WCF Service dialog type in the URL to publish to and click the Publish button. For WCF Service Library Projects Visual Studio will generate a .svc file named <Project Name>.<Service Class Name>.svc where <Project Name> is the project name and <Service Class Name> is the name of the class that implements the service. For WCF Service Application Projects, the existing .svc file will be used. To verify the service has been hosted, open Internet Explorer and type the service’s URL in the address box. You must type in the complete URL path to the .svc file. For example, with a default WCF Service Application project hosted under https://localhost/MyFirstService the complete URL would be https://localhost/MyFirstService/Service1.svc. This will display the default WCF Service page.

Manually Deploy a WCF service to IIS

IIS-hosted WCF services must reside inside of an IIS application. You can create a new IIS application to host WCF services exclusively. Alternatively, you can deploy an WCF service into an existing application that is already hosting ASP.NET 2.0 content (such as .aspx pages and ASP.NET Web services [ASMX]). For more information about these options, see the "Hosting WCF Side-by-Side with ASP.NET" and "Hosting WCF Services in ASP.NET Compatibility Mode" sections in WCF Services and ASP.NET.

Note that IIS 6.0 and later versions periodically restart applications. The default value is 1740 minutes. The maximum value supported is 71,582 minutes. This restart can be disabled. For more information about this property, see the PeriodicRestartTime.

Create an .svc File for the WCF Service

WCF services hosted in IIS are represented as special content files (.svc files) inside the IIS application. This model is similar to the way ASMX pages are represented inside of an IIS application as .asmx files. A .svc file contains a WCF-specific processing directive (@ServiceHost) that allows the WCF hosting infrastructure to activate hosted services in response to incoming messages. The most common syntax for a .svc file is in the following statement.

<% @ServiceHost Service="MyNamespace.MyServiceImplementationTypeName" %>

It consists of the @ServiceHost directive and a single attribute, Service. The value of the Service attribute is the common language runtime (CLR) type name of the service implementation. Using this directive is basically equivalent to creating a service host using the following code.

      new ServiceHost( typeof( MyNamespace.MyServiceImplementationTypeName ) );

Additional hosting configuration, such as creating a list of base addresses for the service can also be done. You can also use a custom ServiceHostFactory to extend the directive for use with custom hosting solutions. The IIS applications that host WCF services are not responsible for managing the creation and lifetime of ServiceHost instances. The managed WCF hosting infrastructure creates the necessary ServiceHost instance dynamically when the first request is received for the .svc file. The instance is not released until either it is closed explicitly by code or when the application is recycled.

For more information about the syntax for .svc files, see @ServiceHost.

Deploy the Service Implementation to the IIS Application

WCF services hosted in IIS use the same dynamic compilation model as ASP.NET 2.0. Just as with ASP.NET, you can deploy the implementation code for IIS-hosted WCF services in several ways at various locations, as follows:

As a precompiled .dll file located in the global assembly cache (GAC) or in the application’s \bin directory. Precompiled binaries are not updated until a new version of the class library is deployed.
As un-compiled source files located in the application’s \App_Code directory. Source files located in this directory are dynamically required when processing the application’s first request. Any changes to files in the \App_Code directory cause the entire application to be recycled and recompiled when the next request is received.
As un-compiled code placed directly in the .svc file. Implementation code can also be located inline in the service’s .svc file, after the @ServiceHost directive. Any changes to inline code cause the application to be recycled and recompiled when the next request is received.

For more information about the ASP.NET 2.0 compilation model, see ASP.NET Compilation Overview.

Configure the WCF Service

IIS-hosted WCF services store their configuration in the applications Web.config file. IIS-hosted services use the same configuration elements and syntax as WCF services hosted outside of IIS. However, the following constraints are unique to the IIS hosting environment:

Base addresses for IIS-hosted services.
Applications hosting WCF services outside of IIS can control the base address of the services they host by passing a set of base address URIs to the ServiceHost constructor or by providing a <host> element in the service’s configuration. Services hosted in IIS do not have the ability to control their base address; the base address of an IIS-hosted service is the address of its .svc file.

Endpoint Addresses for IIS-Hosted Services

When hosted in IIS, endpoint addresses are always considered to be relative to the address of the .svc file that represents the service. For example, if the base address of a WCF service is https://localhost/Application1/MyService.svc with the following endpoint configuration.

<endpoint address="anotherEndpoint" .../>

This provides an endpoint that can be reached at "https://localhost/Application1/MyService.svc/anotherEndpoint".

Similarly, the endpoint configuration element that uses an empty string as the relative address provides an endpoint reachable at https://localhost/Application1/MyService.svc, which is the base address.

<endpoint address="" ... />

You must always use relative endpoint addresses for IIS-hosted service endpoints. Supplying a fully-qualified endpoint address (for example, https://localhost/MyService.svc) can lead to errors in the deployment of the service if the endpoint address does not point to the IIS-application that hosts the service exposing the endpoint. Using relative endpoint addresses for hosted services avoids these potential conflicts.

Available Transports

WCF services hosted in IIS 5.1 and IIS 6.0 are restricted to using HTTP-based communication. On these IIS platforms, configuring a hosted service to use a non-HTTP binding results in an error during service activation. For IIS 7.0, the supported transports include HTTP, Net.TCP, Net.Pipe, Net.MSMQ, and msmq.formatname for backwards compatibility with existing MSMQ applications.

HTTP Transport Security

IIS-hosted WCF services can make use of HTTP transport security (for example, HTTPS and HTTP authentication schemes such as Basic, Digest, and Windows Integrated Authentication) as long as the IIS virtual directory that contains the service supports those settings. The HTTP Transport Security settings on a hosted endpoint’s binding must match the transport security settings on the IIS virtual directory that contains it.

For example, a WCF endpoint configured to use HTTP digest authentication must reside in an IIS virtual directory that is also configured to allow HTTP digest authentication. Unmatched combinations of IIS settings and WCF endpoint settings result in an error during service activation.