Configuration Process in Windows Server AppFabric

The AppFabric extensions to IIS Manager and Windows PowerShell cmdlets for AppFabric provide straightforward ways for an application owner or IT professional to configure applications built on WCF or WF services. This topic describes what occurs in Web.config files when you configure a service or application in the IIS Manager extensions or by the AppFabric configuration cmdlets. The topic first describes the Web.config files that are used in configuring a service; it then describes how to configure a service directly; and finally it describes configuring defaults for a service to inherit.

For more information about the use of Web.config files in ASP.NET, see ASP.NET Configuration.

The Hierarchy of Web.config Files

Each of the items in the IIS configuration hierarchy can have its own Web.config file, and a service can inherit default configuration settings from Web.config files associated with the server, site, application, and subdirectory that the service belongs to. As a result, the configuration of a service is defined by a hierarchy of Web.config files. This section describes the rules that determine which Web.config files in the hierarchy define a service’s configuration, and which elements within those files take precedence.

When AppFabric is installed on a server, it creates a server Web.config file (if it does not already exist) in the same directory as the Machine.config file (<drive>:\Windows\Microsoft.NET\Framework\v4.0.xxxxx\Config). The configuration in this server Web.config file enables service tracking, workflow persistence, and workflow instance management. You can also have a Web.config file for a Web site, located in the Web site directory (<drive>:\inetpub\wwwroot); for an application in the application root directory; and for an application subdirectory. The site, application, and subdirectory Web.config files are not installed by AppFabric setup. Whenever you attempt to use the AppFabric extensions to IIS Manager to change the configuration at a scope, and a Web.config file is not present at that scope, the Web.config file will be created for you.

The Web.config file at any level can contain configuration settings that directly apply to a service, but if you want to define the service directly in the IIS Manager UI, you will be dealing with the service definition in the application Web.config file. In addition to those settings, Web.config files at the server, site, application, and subdirectory levels can contain default configuration settings that can be inherited by a service. The application configuration set by the AppFabric extensions to IIS Manager UI and configuration cmdlets affect only Web.config files, not machine.config or other files that define the environment configuration. An exception to that rule is that auto-start is defined for an application in the applicationHost.config file at the server level.

A Web.config file contains a nested hierarchy of XML tags and subtags with attributes that specify the configuration settings. Some configuration settings for a WCF- and WF-based service are defined within a service behavior. In AppFabric, most but not all of the configuration tooling edits behaviors. However, some configuration settings are defined outside of a service behavior. For example, monitoring, endpoint addresses, and binding transport quotas for a service are configured in the Web.config file, but outside of a behavior. Event collector and system diagnostics configuration, both of which are scoped at the application level or higher, are not defined in behaviors.

Configuring a Service Directly

You can configure a service by using a named service behavior in a Web.config file. To do so, you enter in the Web.config file a <service> tag with a behaviorConfiguration attribute that points to a service behavior tag. A named behavior can be defined for a service in a Web.config file at the application level or a higher level. The following is an example of a service named TestService whose configuration is defined in a named service behavior with the name TestGetMetaData:

<system.serviceModel>
   <services>
      <service name="TestService" behaviorConfiguration="TestGetMetaData" >
         <endpoint address="/TestService" binding="wsHttpBinding" contract="ITestService"/>
         <endpoint address="mex"  binding="mexHttpBinding"  contract="IMetadataExchange"/>
      </service>
   </services>

   <behaviors>
      <serviceBehaviors>
         <behavior name="TestGetMetaData"> <serviceMetadata httpGetEnabled="true" httpGetUrl=""/> </behavior>
      </serviceBehaviors>
   </behaviors>
</system.serviceModel>

In the .NET Framework 3.5, the most straightforward means to configure many aspects of a service was by using a named service behavior in the service’s application (or subdirectory) Web.config file. In the .NET Framework 4.0, the new templates promote the use of nameless behaviors by which a service inherits a default configuration. For more information, see “Configuring Defaults for a Service to Inherit” later in this section.

AppFabric configuration tools modify the following service behaviors:

• sqlWorkflowInstanceStore (persistence)

• etwTracking (monitoring)

• serviceThrottling (performance)

• serviceCredentials/serviceCertificate (security)

• workflowIdle

• workflowUnhandledException

• workflowInstanceManagement

Configuring Defaults for a Service to Inherit

Using a named service behavior in the application Web.config file is not the only way to configure a service. A service can also inherit default configuration settings from the Web.config files for the server, site, application, and subdirectory that the service belongs to. Some default configuration settings for WCF- and WF-based services are defined within a nameless service behavior.

Using Nameless Behaviors

If a named service behavior exists, and the service’s behaviorConfiguration attribute points to it, the service will use the settings in the named behavior. It will also inherit settings from any other named behaviors with the same name in the levels above. It will not use the default service behavior settings defined in the subdirectory, application, site, and server Web.config files that apply to the service. You can, however, change the <service> tag in the application Web.config file so that the service will inherit defaults. You do so by defining a nameless service behavior in the Web.config file for one or more levels, and specifying that your service uses that nameless behavior. The service will use the nameless behavior when the name of the behaviorConfiguration attribute of the service element is set to an empty string, as shown in the following code:

<services>
   <service name=”TutorialService” behaviorConfiguration=””
      <endpoint address=”” binding=”wsHttpBinding” contract=”IService” />
   </service>
</services>

Leaving the behaviorConfiguration attribute out, as shown in the following code, has the same effect. Above, the nameless behavior is explicitly used, whereas below it is implicitly used.

<services>
   <service name=”TutorialService”
      <endpoint address=”” binding=”wsHttpBinding” contract=”IService” />
   </service>
</services>

The effect of the nameless behaviorConfiguration element is that the service will inherit its configuration from one or more nameless behaviors defined in the serviceBehavior element. The following is the nameless serviceBehavior element that is defined by default at the server level. This default configuration for the server (as created by AppFabric setup) enables service tracking, workflow persistence, and workflow instance management.

<behaviors>
   <serviceBehaviors>
      <behavior name=””>
         <workflowIdle timeToUnload="00:01:00" timeToPersist="infinite" />
         <workflowInstanceManagement authorizedWindowsGroup=”AS_Administrators" />
         <etwTracking profileName="HealthMonitoring Tracking Profile" />
      </behavior>
   </serviceBehaviors>
</behaviors>

A nameless behavior can be defined in a Web.config file at any level of the hierarchy. If nameless behaviors are defined at more than one level that contains the service, the configuration for the service will consist of the merged settings of each nameless behavior defined in its hierarchy. If two or more nameless behaviors in a service’s hierarchy contain conflicting settings, then the setting at the lower or lowest level would be used. This process of aggregating configuration settings for a service from multiple nameless behaviors is known as behavior merge.

Remove and clear tags can also be used in behavior sections in Web.config files. A remove tag removes a setting for the nameless behavior that contains it. A clear tag removes all behaviors for a service.

All services that have behaviorConfiguration set to an empty string will inherit default configuration values from the nameless behaviors defined in their hierarchy. There can be only one nameless behavior in a Web.config file for a level.

A nameless behavior is used implicitly (with the behaviorConfiguration attribute left out) in the case of implicit (also known as “tagless”) services. A tagless service is one that is not declared in a Web.config file. It does not have an associated service node in a Web.config file. By default, new project types in Visual Studio 10 create tagless services. When the runtime encounters a tagless service, it automatically applies the default values merged from the applicable nameless behaviors to the service. Note that you cannot modify the endpoints of a tagless service in the IIS Manager extensions; to do this, you have to add a named service element to the Web.config file.

While some default configuration settings for WCF- and WF-based services are defined within a nameless service behavior, others are defined outside of a nameless service behavior. For example, for connection strings or collections, a service will inherit configuration values from all the configuration files in the hierarchy.

Configuring Defaults in IIS Manager

You can configure an application directly in the AppFabric extensions to IIS Manager UI. When you do this, AppFabric sets the named service behavior in the applicable Web.config files (usually at the application level). You can also use IIS Manager to change the service configuration to use defaults from the subdirectory, application, site, and server levels, instead of configuring the service directly. When you do so, the nameless behaviors of the Web.config file are changed. AppFabric performs behavior merge to create the full set of application configuration parameters.

If the same configuration property is set to a different value in two or more Web.config files, AppFabric will use the value from the lower or lowest level. The fields of the Configure service dialog box for the service are populated from the nameless behaviors in the Web.config files that apply. You can change these values in the configuration UI at the service level, in which case the nameless behavior for the appropriate application will be changed. Or you can change the default values at the subdirectory, site, and server level. If you change a default setting in the nameless behavior at a higher level after the application nameless behavior has been created, the change to the higher-level nameless behavior will be propagated to the service level unless it is overridden at the lower level.

To define the default settings for the application, subdirectory, site, or server level in IIS Manager, you select the level in the Connections pane, and then click Configure in the Actions pane under Manage WCF and WF Services. You can also right-click the level in the Connection pane, point to Manage WCF and WF Services, and then click Configure. This displays the Configuration dialog box for the level. If there is no Web.config file for a level when you change the default settings for the level in the UI, AppFabric will create one.

In the AppFabric extensions to IIS Manager, when you configure a service, you do not select the named behavior configuration that will be used. You enter values or make selections in the Configure Service dialog box for the service; AppFabric edits the Web.config file. You can also use Windows PowerShell cmdlets for AppFabric to set many behavior configuration settings.

Using Location Tags

AppFabric supports read operations on location tags in Web.config files. A location tag is another way to define the configuration of a service, besides using a named service behavior or defining default behaviors using a nameless service behavior or a tagless service. A location tag is an element embedded in a Web.config file that applies configuration settings to an entity that it specifically identifies. A location tag contains one or more configuration settings. It also contains a path specifying the entity that the configuration properties will be applied to. Unlike a named service behavior (which must be in the <services> node of the applicable application Web.config file), a location tag can be entered into any Web.config file. Unlike a nameless behavior, the location tag does not require a nameless behaviorConfiguration element in the <service> node of the application Web.config file to render it applicable.

The following is an example of a location tag in a site Web.config file that applies a configuration setting to a service s1 in an application app1:

<location path=”app1/s1.svc” overrideMode=”Allow”>
   <defaultDocument enabled=”true”>
      <files>
         <add value=”Developer.htm” />
      </files>
   </defaultDocument>
</location>

If no path is declared, then the path is from the level where the location tag is defined and below to all child paths (the equivalent of specifying a dot (.)). Doing so in applicationHost.config results in specifying the configuration for the global level. If the overrideMode element in the location tag is set to “Allow”, then the configuration set in the location tag can be edited and overridden at lower levels of the hierarchy. If the overrideMode element is not set and more than one location tag exists specifying different values for the same configuration setting in the same service, a set of prioritization rules will be applied to determine which setting to use.

A configuration setting that is applied to a service from a location tag cannot be changed either in the AppFabric extensions to IIS Manager UI or by an AppFabric configuration cmdlet. The contents of a location tag are read-only for either the UI or a cmdlet. If you attempt to change the location tag using IIS Manager or a cmdlet, the action will return an error. To change a setting applied by a location tag, you would have to manually change the location tag in the Web.config file.

Recycling

Any time that you click Apply or OK in the Configure Service dialog box in IIS Manager, changing a Web.config file, the system will recycle the associated application domain. Any time that you click Apply or OK to establish default settings at the subdirectory, application, site, or server level, changing the corresponding Web.config file, the application domains for all services beneath that scope will be recycled. We recommend that you minimize the number of re-configuration processes that you incur, especially at higher levels, in order to lower the costs of recycling. When you configure defaults, you should proceed as follows: configure the server defaults and the site defaults (in any order), then import your applications, and then configure the applications and the services that they contain. The reason for this order is that configuring defaults can cause all of the tree to recycle. If possible, perform configuration steps before any application actually runs to avoid the cost of recycling applications.