How to: Host a Workflow Service in IIS

  • Article

Workflow services can be hosted in Internet Information Services (IIS) in much the same way as Windows Communication Foundation (WCF) services are hosted in IIS—through the use of service and Web configuration files and some application code. Being hosted in IIS enables a workflow service to take advantage of IIS features such as automatic process recycling, process health monitoring, and so on.

There are three ways to host a workflow service in IIS. The first way is to reference a pre-compiled workflow definition in a .svc file. The second way is to use a workflow markup file with a .xoml extension. The third way is to reference a workflow markup file in a .svc file.

The second method provides auto-recycle functionality on an update to the .xoml or .rules file. The last method is provided for extensibility scenarios, such as implementing a custom WorkflowServiceHost for hosting workflow markup.

Note

When deploying a workflow service as code in stand-alone source files in the App_Code directory or deploying the service using the code-inline ASP.NET model, you should reference the workflow assemblies in your Web.config file through the <compilation> configuration element as shown in the following example:

<system.web>
    <compilation>
      <assemblies>
        <add assembly="System.Workflow.Activities, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
        <add assembly="System.Workflow.ComponentModel, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
        <add assembly="System.Workflow.Runtime, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
      </assemblies>
    </compilation>
  </system.web>

Note

The workflow compiler is not used when code-inline workflows are hosted in IIS. Only the language-specific compilers, such as the C# compiler, are used.

To host a pre-compiled workflow definition as a service in IIS

  1. Confirm that IIS is installed and running on your machine.

  2. Create a new virtual directory for your workflow service and ensure that ASP.NET has access to it.

  3. Create a new service file with a .svc extension. Edit this file by adding the appropriate ServiceHost directive information for the workflow service. The Factory value must reference the WorkflowServiceHostFactory class. The following example shows a service file with the appropriate values.

    <%@ServiceHost language=c# Debug="true" Service="Microsoft.WorkflowServices.Samples.StateMachineCalculatorService" Factory="System.ServiceModel.Activation.WorkflowServiceHostFactory" %>

  4. Create a Bin subdirectory within the virtual directory you created in step 2.

  5. Place the assembly containing your workflow service type in the Bin directory.

  6. Create a file named Web.config in the application directory. To run the service, the Web.config file must be located in the same directory as the service file.

  7. Add the appropriate configuration code in the file. At run time, the WCF infrastructure uses the information to construct an endpoint that client applications can communicate with. For the StateMachineCalculatorService sample, the configuration code is as follows:

    <?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <system.serviceModel>
    <services>
      <service name="Microsoft.WorkflowServices.Samples.StateMachineCalculatorService" behaviorConfiguration="ServiceBehavior" >
        <endpoint address="" 
                  binding="customBinding"
                  bindingConfiguration="basicHttpCookieBinding"
                  contract="Microsoft.WorkflowServices.Samples.ICalculator" />
        <endpoint address="ContextOverHttp" 
                  binding="wsHttpContextBinding" 
                  contract="Microsoft.WorkflowServices.Samples.ICalculator" />
      </service>
    </services>

    <behaviors>
      <serviceBehaviors>
        <behavior name="ServiceBehavior"  >
          <serviceMetadata httpGetEnabled="true" />
          <serviceDebug includeExceptionDetailInFaults="true" />
          <serviceCredentials>
            <windowsAuthentication
                allowAnonymousLogons="false"
                includeWindowsGroups="true" />
          </serviceCredentials>
          <!-- Comment out the following behavior to disable persistence store -->
          <workflowRuntime name="WorkflowServiceHostRuntime" validateOnCreate="true" enablePerformanceCounters="true">
            <services>
              <add type="System.Workflow.Runtime.Hosting.SqlWorkflowPersistenceService, System.Workflow.Runtime, Version=3.0.00000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
                   connectionString="Data Source=localhost\sqlexpress;Initial Catalog=NetFx35Samples_ServiceWorkflowStore;Integrated Security=True;Pooling=False"
                   LoadIntervalSeconds="1" UnLoadOnIdle= "true" />
            </services>
          </workflowRuntime>
        </behavior>
      </serviceBehaviors>
    </behaviors>

    <bindings>
      <customBinding>
        <binding name="basicHttpCookieBinding">
          <context contextExchangeMechanism="HttpCookie" />
          <textMessageEncoding messageVersion="Soap11" />
          <httpTransport authenticationScheme="Ntlm" />
        </binding>
      </customBinding>
    </bindings>

  </system.serviceModel>

  <system.web>
    <compilation>
      <assemblies>
        <add assembly="System.WorkflowServices, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
      </assemblies>
    </compilation>
  </system.web>

</configuration>

To host a declarative workflow definition as a service in IIS

  1. Confirm that IIS is installed and running on your machine.

  2. Create a new virtual directory for your workflow service and ensure that ASP.NET has access to it.

  3. Place the workflow markup file (with extension .xoml) and an optional rule markup file with the same name (with extension .rules) in the virtual directory.

  4. Create a file named Web.config in the application directory. To run the service, the Web.config file must be located in the same directory as the service file.

  5. Add the appropriate configuration code in the file. At run time, the WCF infrastructure uses the information to construct an endpoint that client applications can communicate with. For the StateMachineCalculatorService sample, the configuration code is as follows:

    <?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <system.serviceModel>
    <services>
<!-- Service name is workflow Name -->
      <service name="StateMachineCalculatorService" behaviorConfiguration="ServiceBehavior" >
        <endpoint address="" 
                  binding="customBinding"
                  bindingConfiguration="basicHttpCookieBinding"
                  contract="Microsoft.WorkflowServices.Samples.ICalculator" />
        <endpoint address="ContextOverHttp" 
                  binding="wsHttpContextBinding" 
                  contract="Microsoft.WorkflowServices.Samples.ICalculator" />
      </service>
    </services>

    <behaviors>
      <serviceBehaviors>
        <behavior name="ServiceBehavior"  >
          <serviceMetadata httpGetEnabled="true" />
          <serviceDebug includeExceptionDetailInFaults="true" />
          <serviceCredentials>
            <windowsAuthentication
                allowAnonymousLogons="false"
                includeWindowsGroups="true" />
          </serviceCredentials>
          <!-- Comment out the following behavior to disable persistence store -->
          <workflowRuntime name="WorkflowServiceHostRuntime" validateOnCreate="true" enablePerformanceCounters="true">
            <services>
              <add type="System.Workflow.Runtime.Hosting.SqlWorkflowPersistenceService, System.Workflow.Runtime, Version=3.0.00000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
                   connectionString="Data Source=localhost\sqlexpress;Initial Catalog=NetFx35Samples_ServiceWorkflowStore;Integrated Security=True;Pooling=False"
                   LoadIntervalSeconds="1" UnLoadOnIdle= "true" />
            </services>
          </workflowRuntime>
        </behavior>
      </serviceBehaviors>
    </behaviors>

    <bindings>
      <customBinding>
        <binding name="basicHttpCookieBinding">
          <context contextExchangeMechanism="HttpCookie" />
          <textMessageEncoding messageVersion="Soap11" />
          <httpTransport authenticationScheme="Ntlm" />
        </binding>
      </customBinding>
    </bindings>

  </system.serviceModel>

  <system.web>
    <compilation>
      <assemblies>
        <add assembly="System.WorkflowServices, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
      </assemblies>
    </compilation>
  </system.web>

</configuration>

Note

The workflow markup file will be the part of the base address for the workflow service. For example, the base address might be the following:

https://servername:port/workflowmarkupfile.xoml/

To host a declarative workflow definition as a service with a .svc file

  1. Confirm that IIS is installed and running on your machine.

  2. Create a new virtual directory for your workflow service and ensure that ASP.NET has access to it.

  3. Place the workflow markup file (with extension .xoml) and an optional rule markup file with the same name (with extension .rules) in the virtual directory.

  4. Place the service directive (with extension .svc) with the following markup in the same directory:

    <%@ServiceHost language=c# Debug="true" Service="Calculator.xoml" Factory="System.ServiceModel.Activation.WorkflowServiceHostFactory" %>

  5. Create a file named Web.config in the application directory - to run the service, the Web.config file must be located in the same directory as the service file.

  6. Add the appropriate configuration code in the file. At run time, the WCF infrastructure uses the information to construct an endpoint that client applications can communicate with. For the StateMachineCalculatorService sample, the configuration code is as follows:

    <?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <system.serviceModel>
    <services>
<!-- Service name is workflow Name -->
      <service name="StateMachineCalculatorService" behaviorConfiguration="ServiceBehavior" >
        <endpoint address="" 
                  binding="customBinding"
                  bindingConfiguration="basicHttpCookieBinding"
                  contract="Microsoft.WorkflowServices.Samples.ICalculator" />
        <endpoint address="ContextOverHttp" 
                  binding="wsHttpContextBinding" 
                  contract="Microsoft.WorkflowServices.Samples.ICalculator" />
      </service>
    </services>

    <behaviors>
      <serviceBehaviors>
        <behavior name="ServiceBehavior"  >
          <serviceMetadata httpGetEnabled="true" />
          <serviceDebug includeExceptionDetailInFaults="true" />
          <serviceCredentials>
            <windowsAuthentication
                allowAnonymousLogons="false"
                includeWindowsGroups="true" />
          </serviceCredentials>
          <!-- Comment out the following behavior to disable persistence store -->
          <workflowRuntime name="WorkflowServiceHostRuntime" validateOnCreate="true" enablePerformanceCounters="true">
            <services>
              <add type="System.Workflow.Runtime.Hosting.SqlWorkflowPersistenceService, System.Workflow.Runtime, Version=3.0.00000.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
                   connectionString="Data Source=localhost\sqlexpress;Initial Catalog=NetFx35Samples_ServiceWorkflowStore;Integrated Security=True;Pooling=False"
                   LoadIntervalSeconds="1" UnLoadOnIdle= "true" />
            </services>
          </workflowRuntime>
        </behavior>
      </serviceBehaviors>
    </behaviors>

    <bindings>
      <customBinding>
        <binding name="basicHttpCookieBinding">
          <context contextExchangeMechanism="HttpCookie" />
          <textMessageEncoding messageVersion="Soap11" />
          <httpTransport authenticationScheme="Ntlm" />
        </binding>
      </customBinding>
    </bindings>

  </system.serviceModel>

  <system.web>
    <compilation>
      <assemblies>
        <add assembly="System.WorkflowServices, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/>
      </assemblies>
    </compilation>
  </system.web>

</configuration>

See Also

Other Resources

Creating Workflow Services and Durable Services

Copyright © 2007 by Microsoft Corporation. All rights reserved.