Orchestration Engine Configuration

Orchestration Engine Configuration

This topic was last updated on: December 5, 2007

The orchestration engine uses an XML file called BTSNTSvc.exe.config to determine certain behaviors. For example, dehydration properties and their default values are configured as XML in the BTSNTSvc.exe.config file and are read when all host instances containing an orchestration start. For more information, see Orchestration Dehydration and Rehydration.

A service reads this configuration information once, when it is started. Any changes to it will not be picked up unless the service is stopped and restarted.

See the examples below for different nodes and possible values.

Example: all validations on

<?xml version="1.0" ?>
<configuration>
       <configSections>
              <section 
                     name="xlangs"
                     type="Microsoft.XLANGs.BizTalk.CrossProcess.XmlSerializationConfigurationSectionHandler, Microsoft.XLANGs.BizTalk.CrossProcess" />
       </configSections>
       <runtime>
              <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
                     <probing privatePath="BizTalk Assemblies;Developer Tools;Tracking" />
              </assemblyBinding>
       </runtime>

       <xlangs>
              <Configuration>
                     <Debugging 
                            ValidateAssemblies="true"
                            ValidateSchemas="true"
                            ValidateCorrelations="true"
                            ExtendedLogging="true"
                     />
              </Configuration>
       </xlangs>
</configuration>

Example: assembly validation only

<?xml version="1.0" ?>
<configuration>
       <configSections>
              <section 
                     name="xlangs"
                     type="Microsoft.XLANGs.BizTalk.CrossProcess.XmlSerializationConfigurationSectionHandler, Microsoft.XLANGs.BizTalk.CrossProcess"
              />
       </configSections>
       <runtime>
              <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
                     <probing privatePath="BizTalk Assemblies;Developer Tools;Tracking" />
              </assemblyBinding>
       </runtime>
    
       <xlangs>
              <Configuration>
                     <Debugging 
                            ValidateAssemblies="true"
                            ExtendedLogging="false"
                     />
              </Configuration>
       </xlangs>
</configuration>

Example: remote debugging enabled

<?xml version="1.0" ?>
<configuration>
       <runtime>
              <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
                     <probing privatePath="BizTalk Assemblies;Developer Tools;Tracking" />
              </assemblyBinding>
       </runtime>

       <system.runtime.remoting>
              <customErrors mode="on"/>
              <channelSinkProviders>
                     <serverProviders>
                            <provider id="sspi"
                                    type="Microsoft.BizTalk.XLANGs.BTXEngine.SecurityServerChannelSinkProvider,Microsoft.XLANGs.BizTalk.Engine" securityPackage="negotiate" authenticationLevel="packetPrivacy" />
                     </serverProviders>
              </channelSinkProviders>

              <application>
                     <channels>
                            <channel ref="tcp" port="0" name="">
                                   <serverProviders>
                                          <provider ref="sspi" />
                                          <formatter ref="binary" typeFilterLevel="Full"/>
                                   </serverProviders>
                            </channel>
                     </channels>
              </application>
       </system.runtime.remoting>
</configuration>

Example: AppDomain configuration

Assemblies are assigned to named domains using assignment rules (see more below). If no rule is specified for some assembly, the assembly will be assigned to an ad hoc domain. The number of such assigned assemblies per ad hoc domain is determined by the value of AssembliesPerDomain.

<?xml version="1.0" ?>
<configuration>
    <configSections>
        <section name="xlangs" type="Microsoft.XLANGs.BizTalk.CrossProcess.XmlSerializationConfigurationSectionHandler, Microsoft.XLANGs.BizTalk.CrossProcess" />
    </configSections>
    <runtime>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
            <probing privatePath="BizTalk Assemblies;Developer Tools;Tracking" />
        </assemblyBinding>
    </runtime>
    <xlangs>
        <Configuration>
            <!-- 
                <!-- 
AppDomain configuration.
                Assemblies are assigned to named domains using assignment rules (see more below). If no rule is specified for some assembly, the assembly will be assigned to an ad hoc domain. The number of such assigned assemblies per ad hoc domain is determined by the value of AssembliesPerDomain.
            -->--> 
            <AppDomains AssembliesPerDomain="10">
                <!-- 
                    <!-- 
In this section the user may specify defualt configuration for any app domain created that does not have a named configuration associated with it (see AppDomainSpecs below)
                    SecondsEmptyBeforeShutdown is the number of seconds that an app domain is empty (that is, it does not contain any orchestrations) before being unloaded. Specify -1 to signal that an app domain should never unload, even when empty.
                    Similarly, SecondsIdleBeforeShutdown is the number of seconds that an app domain is idle (that is, it contains only dehydratable orchestrations) before being unloaded. Specify -1 to signal that an app domain should never unload when idle but not empty. When an idle but non-empty domain is shut down, all of the contained instances are dehydrated first.
                -->
                --> 
<DefaultSpec SecondsIdleBeforeShutdown="1200" SecondsEmptyBeforeShutdown="1800">
                    <!-- 
                        <!-- 
BaseSetup is a serialized System.AppDomainSetup object. This is passed as-is to
                        AppDomain.CreateAppDomain() and can be used to influence assembly search path etc.
                    -->
                    --> 
<BaseSetup>
                        <ApplicationBase>c:\myAppBase</ApplicationBase>_0</ApplicationBase> 
                        <ConfigurationFile>c:\myAppBase\myConfig.config</ConfigurationFile>_0</ConfigurationFile> 
                    <DynamicBase>DynamicBase_0</DynamicBase> 
<DisallowPublisherPolicy>true</DisallowPublisherPolicy> 
<ApplicationName>ApplicationName_0</ApplicationName> 
<PrivateBinPath>PrivateBinPath_0</PrivateBinPath> 
<PrivateBinPathProbe>PrivateBinPathProbe_0</PrivateBinPathProbe> 
<ShadowCopyDirectories>ShadowCopyDirectories_0</ShadowCopyDirectories> 
<ShadowCopyFiles>ShadowCopyFiles_0</ShadowCopyFiles> 
<CachePath>CachePath_0</CachePath> 
<LicenseFile>LicenseFile_0</LicenseFile> 
<LoaderOptimization>NotSpecified</LoaderOptimization> 
</BaseSetup>
                </DefaultSpec>
                <!-- 
                    - <!-- 
In this section the user may specify named configurations for specific app domains, identified by their "friendly name". The format of any app-domain spec is identical to that of the default app-domain spec.
                -->--> 
                <AppDomainSpecs>
                    <AppDomainSpec Name="MyDomain1" SecondsIdleBeforeShutdown="-1" SecondsEmptyBeforeShutdown="12000">
                        <BaseSetup>
                            <PrivateBinPath>c:\PathForAppDomain1</PrivateBinPath>
                        <PrivateBinPath>PrivateBinPath_0</PrivateBinPath> 
<PrivateBinPathProbe>PrivateBinPathProbe_0</PrivateBinPathProbe> 
</BaseSetup>
                    </AppDomainSpec>
                    <AppDomainSpec Name="MyFrequentlyUnloadingDomainMyTrashyDomain" SecondsIdleBeforeShutdown="60" SecondsEmptyBeforeShutdown="60" /> 
                </AppDomainSpecs>
                <!-- 
                    <!-- 
The PatternAssignmentRules and ExactAssignmentRules control assignment of assemblies to app domains.
                    When a message arrives, the name of its corresponding orchestration's assembly is determined. Then, the assembly is assigned an app domain name. The rules guide this assignment. Exact rules are consulted first, in their order of definition, and then the pattern rules. The first match is used.
                    If no match is found, the assembly will be assigned to an ad-hoc domain. The configuration and number of assemblies per ad-hoc domain is controlled by the AssembliesPerDomain attribute and the DefaultSpec section.
                -->
               --> 
- <ExactAssignmentRules>
                    <!-- 
                        <!-- 
An exact assembly rule specifies a strong assembly name and an app domain name. If the strong assembly name equals the rule's assembly name, it is assigned to the corresponding app domain.
                    -->--> 
                    <ExactAssignmentRule AssemblyName="BTSAssembly1, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9c7731c5584592ad"
                       AssemblyName_0" AppDomainName="MyDomain1" />AppDomainName_1" /> 
                    <ExactAssignmentRule AssemblyName="BTSAssembly2, Version=1.0.0.0, Culture=neutral, PublicKeyToken=9c7731c5584592ad"AssemblyName_0" AppDomainName="AppDomainName_1" /> 
                        AppDomainName="MyFrequentlyUnloadingDomain " />
                <ExactAssignmentRule AssemblyName="AssemblyName_0" AppDomainName="AppDomainName_1" /> 
</ExactAssignmentRules>
                <PatternAssignmentRules>
                    <!-- 
                        <!-- 
A pattern assignment rule specifies a regular expression and an app domain name. If the strong assembly name matches the expression, it is assigned to the corresponding app domain. This allows version independent assignment, assignment by public key token, or assignment by the custom assembly key.
                    -->--> 
                    <!--
                        assign all assemblies with name BTSAssembly3, regardless of version and public key,
                        to the MyDomain1 app domain 
                    -->
                    <PatternAssignmentRule AssemblyNamePattern=" BTSAssembly3, Version=\d.\d.\d.\d, Culture=neutral, PublicKeyToken=.{16}"AssemblyNamePattern_0" AppDomainName=" MyDomain1" />
                <PatternAssignmentRule AssemblyNamePattern="AssemblyNamePattern_0" AppDomainName="AppDomainName_1" /> 
<PatternAssignmentRule AssemblyNamePattern="AssemblyNamePattern_0" AppDomainName="AppDomainName_1" /> 
</PatternAssignmentRules>
            </AppDomains>
        </Configuration>
    </xlangs>
</configuration>

Modifying other sections of the BTSNTSvc.exe.config file

For information about modifying the dehydration values in BTSNTSvc.exe.config, see Dehydration Default Properties.

The BTSNTSvc.exe configuration file contains several other sections documented in the .NET Framework General Reference. For more information about the modification of these sections see the Configuration File Schema of the .NET Framework General Reference at http://go.microsoft.com/FWLink/?LinkID=52964.

In addition to BizTalk-specific configuration information, the BTSNTSvc.exe.config file is also where .NET application components which run in the context of an orchestration, adapter or pipeline obtain their configuration information at run time using the standard .NET <appSettings> tag under the <configuration> tag. Because BizTalk already provides a mechanism for custom adapters and pipeline components to obtain configuration information, the <appSettings> tag in the BTSNTSvc.exe.config file would typically be used by custom .NET components called from within an orchestration. For example:

<appSettings>
     <add key="configParamName" value="configParamValue" />
</appSettings>

Throttling Messages Per Orchestration

This property, specified in the btsntsvc.exe.config file, will prevent an orchestration from consuming too much memory by limiting the number of outstanding messages it can have. All messages will continue to be delivered to the MessageBox; however, queued messages will not be delivered to the orchestration until it processes some of its outstanding messages.

To specify this property in the btsntsvc.exe.config file (located in the Microsoft BizTalk Server 2006 root directory), add the following parameter under Application node:

<configuration>
            <application>
                        <Throttling PauseAt="100" ResumeAt="50" />
            </application>
</configuration>

In this example, once an orchestration has 100 outstanding messages, the MessageBox will stop sending additional messages. When the orchestration's number of outstanding messages is down to 50, it will specify the MessageBox can resume sending messages. You can specify other values.

You must also enable this feature, per-host, in the database. To enable message throttling for a host, you must edit the dbo.Applications table in the BizTalkMsgBoxDb database. For each host you want to enable message throttling per orchestration, set the fAttributes flag bit to 1. Only those hosts with the fAttribute set to 1 will allow message throttling per orchestration.

Concepts

XLANG/s Language

Other Resources

Debugging Orchestrations

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads

Concepts

Other Resources