Articles in this series

• Introduction
• Getting Started with WCF
• WCF Templates and Tools

There are several Visual Studio templates available to help you to be more productive with WCF. In addition there are a few essential tools – some that are most useful as you are getting started, and others that you will use more regularly. In this section I will summarize the available project templates and when to use each; discuss some side-effects and workarounds; and discuss the limitations and benefits of the core WCF tools.

Creating WCF-Enabled Projects

Getting started with WCF is easy when you use the new project and new web site templates listed in Figure 1. The first two templates are the most generally useful – adding necessary assembly references and a sample WCF service and configuration section for that service. The last three templates are specialized templates that support Workflow Services and syndication feeds – to create projects with additional assembly references and a sample WCF service for each. Figure 2 shows the same templates listed in the new project and new web site dialogs.

Figure 1: Visual Studio new project and new web site templates for WCF

Figure 2: New project and new web site dialogs

The main benefit of using these templates is to automatically add necessary assembly references, and to provide a sample WCF service with the associated <system.serviceModel> configuration to work with.

Although the templates are helpful productivity tools you should be aware of the following:

• The generated sample service and associated configuration are not production worthy and should be reviewed for recommended practices discussed throughout the various chapters of this whitepaper.
• For class libraries, an application configuration file (app.config) is generated so that you can test the service with the WCF Service Host and WCF Test Client. This app.config should not be deployed with the class library project since the host is responsible for configuration. The relevant settings from the app.config belong in the production host configuration file.
• Class library project files generated from these templates are wired to automatically launch the WCF Service Host and the WCF Test Client. The WCF Service Host relies on the presence of the app.config. These tools have limited value beyond rudimentary testing so you will want to know how to disable these and clean up the project. I will discuss this in an upcoming section.
• The WCF Service web site template generates a sample service beneath the \App_Code directory of the web site and associates this service type to the generated .svc file. You should always reference services from a class library rather than including them in the host project, and that includes web sites. This is further discussed in the “Hosting” chapter of this whitepaper.

Adding WCF Services to a Project

You can add a WCF service to any project and this will generate the appropriate assembly references and configuration settings. This is done using one of the new item templates such as those listed in Figure 3. For example you can create a new class library and add a WCF Service to that library after the fact.

Figure 3: Visual Studio new item templates for WCF

Figure 4 illustrates the new item templates listed in the new project and new web site dialogs. Workflow Service templates are only available to projects created using the Workflow Service project template, and the AJAX-enabled template is only available to web site projects. Once again, these templates will automatically add the appropriate assembly references, sample service and configuration.

Figure 4: Visual Studio new item dialogs

As with the new project templates there are some things you should consider when you generate WCF services with the new item templates:

• The generated sample service and associated configuration are not production worthy and should be reviewed for recommended practices discussed throughout chapters in this whitepaper.
• For class libraries, an application configuration file (app.config) is generated for the WCF test tools and this should not be deployed with the class library project.
• Services generated for a web site will be placed in beneath the \App_Code directory of the web site and the service type is associated to the generated .svc file. You should change this so that the .svc file points to a service in a referenced assembly. This is further discussed in the “Hosting” chapter of this whitepaper.

Limitations of the WCF Service Host and WCF Test Client

WCF project templates that generate class libraries are wired so that services can be tested immediately using the WCF Service Host (WcfServiceHost.exe) and WCF Test Client (WcfTestClient.exe) tools. In addition, when you add a new WCF Service item to a class library, the project is wired launch the WCF Service Host. This enables an F5 debugging experience from Visual Studio – even for a class library. Figure 5 shows the WCF Service Host and WCF Test Client.

Figure 5: WCF Service Host and WCF Test Client

The WCF Service Host is useful for simple hosting tests that don’t require programmatically customizing the ServiceHost instance. There are several drawbacks to the WCF Service Host:

• The ServiceHost instance is not shut down gracefully – thus any pending requests are aborted when the WCF Service Host is closed. This is not a significant issue for testing however it is an inaccurate representation of how the ServiceHost handles already executing requests on shutdown.
• You cannot customize ServiceHost initialization – and it is common to programmatically initialize fixed behaviors and provide exception handling. It is best to test with a host representative of code that will run in production to discover problems early on.
• The WCF Service Host requires an app.config file be included in the class library project, which can be confusing since this file should not be deployed with the library since configuration is provided by the host environment.
• Even if you use Visual Studio to debug your own host within the solution the WCF Service Host will launch – and an exception will occur if you have deleted the app.config from the service library.

Rather than using the WCF Service Host I recommend you create a simple Console application with code to initialize the ServiceHost type, for each service or perhaps for a group of co-hosted services. The extra effort to add assembly references and a few lines of code is minimal. That means you will need to know how to disable the default behavior for launching the WCF Service Host if you are using WCF Service Library projects. I’ll talk about this in the next section.

The WCF Test Client is useful for quick and dirty testing of service operations. It does provide a way to invoke service operations, supply complex type values, and view the request and response XML messages. The limitations of the WCF Test Client include:

• The WCF Test Client does not provide a way to save and reload inputs to service operations – thus you must retype those inputs each time you run the test client.
• The user interface for supplying test values is automatically generated and cumbersome to use.

I recommend that you create a custom test client for each service using a Console, Windows Forms or WPF application template. This way you can create reusable tests, supply logic based on dynamic application heuristics if applicable, and share the values used for these tests with other developers or test engineers. Of course you can also use your favorite Test Driven Development (TDD) tool such as Visual Studio Team Suite.

Disabling the WCF Service Host and WCF Test Client

WCF class library projects are wired to launch the WCF Service Host for automatic hosting – thanks to a project file setting. If you view the project file you can see a <ProjectTypeGuids> element that includes a special GUID which triggers automatic service hosting:

<ProjectTypeGuids>{3D9AD99F-2412-4246-B90B-4EAA41C64699};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>

The first GUID is used for automatic service hosting and the second GUID indicates this is a C# project (the latter would be different for a Visual Basic project). Before Visual Studio SP1 you were forced to manually edit the project file and remove the first GUID in order to disable automatic hosting. As of Visual Studio 2008 SP1 there is a new tab called WCF Options which has a checkbox you can disable (it is shown enabled in Figure 6) so that Visual Studio will ignore the GUID and refrain from automatically launching the WCF Service Host for the WCF Service Library.

Figure 6: WCF Options tab supplied with Visual Studio 2008 SP1

WCF Service Library projects are also automatically wired to launch the WCF Test Client through a setting in the Debug tab under Start Options (see Figure 7). To disable this debugging behavior, simply remove the command line argument to launch WcfTestClient.exe.

Figure 7: Debug start options to launch the WCF Test Client

Add Service Reference vs. SvcUtil

You can generate a proxy for your WCF client applications using the Add Service Reference dialog. The advanced options of this dialog (see Figure 8) give you access to most of the SvcUtil (SvcUtil.exe) features you need to generate a proxy including:

• Generating asynchronous proxies
• Selecting the appropriate CLR type to handle arrays and dictionaries
• Referencing types in existing assemblies

Figure 8: Advanced features of the Add Service Reference dialog

If you are going to generate a proxy as opposed to constructing your own with ChannelFactory<T>, you will almost always use Add Service Reference. However, you can use SvcUtil directly for command line automation of proxy generation, and it can be useful for reverse engineering service contracts and related metadata definitions from pre-existing WSDL documents.

Tracing and Debugging with Service Trace Viewer

The Service Trace Viewer (SvcTraceViewer.exe) is a WCF utility for analyzing trace logs and detailed messages for WCF clients and services. It is particularly handy for the following:

• Finding the underlying cause of an exception when the reported exception is too high level.
• Viewing SOAP messages passed between clients and services to diagnose interoperability issues or diagnose other messaging incompatibilities.
• Tracing the underlying messaging when channel features are enabled. For example viewing the messages generated for reliable sessions or secure sessions.
• Troubleshooting activities that cross client and service boundaries by loading multiple trace logs produced independently.

Figure 9 shows how to select an activity and track down warnings and exceptions using the Service Trace Viewer.

Figure 9: Viewing warnings and exceptions with Service Trace Viewer

Figure 10 shows a listing of one possible configuration you might add to your WCF clients and services to enable service model tracing in a development and test environment. With this configuration the entire message is logged at both the transport and service level, which means that you can view the message just before writing to or after reading from the wire (often this is encrypted) or view the message just before encryption or after decryption as well as other transport-related processing. In addition, detailed service model trace events with activity tracing for correlating activities across boundaries are produced.

Figure 10: Diagnostics configuration for service model tracing in development or test environments

<configuration>
 <system.serviceModel>
  <diagnostics >
    <messageLogging logEntireMessage="true" logMalformedMessages="true"
logMessagesAtServiceLevel="true" logMessagesAtTransportLevel="true"
maxMessagesToLog="100000"  />
  </diagnostics>
</system.serviceModel>
<system.diagnostics >
  <sharedListeners>
    <add name="sharedListener"
type="System.Diagnostics.XmlWriterTraceListener"
initializeData="d:\logs\servicetrace.svclog" />
  </sharedListeners>
  <sources>
    <source name="System.ServiceModel"
switchValue="Verbose, ActivityTracing" >
      <listeners>
        <add name="sharedListener" />
      </listeners>
    </source>
    <source name="System.ServiceModel.MessageLogging" >
      <listeners>
        <add name="sharedListener" />
      </listeners>
    </source>
  </sources>
 </system.diagnostics>
</configuration>

I am not a fan of enabling service model tracing for production environments, unless there is a problem to track down. In that case, I would avoid message logging unless it is absolutely necessary to view the XML to solve the problem – and instead stick to a simple configuration like that shown in Figure 11 on production.

Figure 11: A simpler diagnostics configuration for production environments

<configuration>
 <system.diagnostics >
  <sharedListeners>
    <add name="sharedListener"
type="System.Diagnostics.XmlWriterTraceListener"
initializeData="d:\logs\servicetrace.svclog" />
  </sharedListeners>
  <sources>
    <source name="System.ServiceModel"
switchValue="Warning">
      <listeners>
        <add name="sharedListener" />
      </listeners>
    </source>
  </sources>
 </system.diagnostics>
</configuration>

WCF Configuration Editor

The WCF Configuration Editor (WcfConfigEditor.exe) is useful for creating and editing service model configuration sections when you are first getting started with WCF. It is particularly useful for learning the various sections (services, bindings, behaviors, etc.) and for selecting values from a drop down list (see Figure 12) that don’t otherwise appear with Intellisense when you directly edit the configuration file in Visual Studio.

Figure 12: Selecting a binding using the WCF Configuration Editor

You can launch the editor from Visual Studio from the Tools->WCF Service Configuration Editor menu  however it is much easier to right-click the app.config or web.config file in Solution Explorer since this launches the editor with the correct file loaded.

Once you get the hang of each service model configuration section you will find it more of a burden than a benefit to launch the WCF Configuration Editor – since configuration file Intellisense works very nicely for guiding you through filling in each section.

Recommendations: WCF Templates and Tools

1. Use the WCF Service Library template to generate new services for a solution. Delete the generated app.config file, delete the command line instruction to launch wcfclient.exe, and disable the debug setting for automatically starting the WCF Service Host from the WCF Options tab.
2. Use the WCF Service template when creating a new web site if you know you will be hosting WCF services. Use the WCF Service template to add services to a web site. In both cases delete the generated service files under the \App_Code directory and associate the .svc files with service types from referenced class library assemblies.
3. Use the WCF Service new item template when adding services to a class library. Delete the generated app.config file.
4. Create a Console host project for your services so that you can write code to programmatically configure the service host as it will be in production. When ready, also test the real hosting environment (Windows Service, IIS or WAS) in development prior to delivering to test engineers.
5. Create custom test clients with exhaustive tests that execute each service operation in different ways that are relevant.
6. Use the advanced settings from the Add Service Reference dialog to configure proxies to use List<T> and Dictionary<K,T> for arrays, and to configure asynchronous support if needed.
7. Rely on the Service Trace Viewer in development to help you find the source of an exception and to view detailed message logs. Use it sparingly in production.
8. Rely on the WCF Configuration Editor to become familiar with service model configuration settings, but spend time getting familiar with configuration Intellisense as this is more productive in the long term.