跟踪配置文件

项目
02/28/2011

本主题适用于 Windows Workflow Foundation 4。

跟踪配置文件包含跟踪查询，这些查询允许跟踪参与者订阅当工作流实例的状态在运行时发生更改时发出的工作流事件。

跟踪配置文件

根据您的监视要求，可以编写一个非常一般的配置文件，用来订阅对工作流进行的一小组高级状态更改。相反，也可以创建一个非常详细的配置文件，其生成的事件足够丰富，可在以后重新构造详细的执行流。

跟踪配置文件将其自身列为标准 .NET Framework 配置文件中的 XML 元素或在代码中指定的 XML 元素。下面的示例摘自配置文件中的 .NET Framework 版本 4跟踪配置文件，跟踪参与者可利用它订阅 Started 和 Completed 工作流事件。

<system.serviceModel>
    …
    <tracking>  
      <trackingProfile name="Sample Tracking Profile">
        <workflow activityDefinitionId="*">
  <workflowInstanceQueries>
          <workflowInstanceQuery>
            <states>
              <state name="Started"/>
              <state name="Completed"/>
            </states>
          </workflowInstanceQuery>
  </workflowInstanceQueries>
        </workflow>
      </trackingProfile>        
    </profiles>
  </tracking>
    …
</system.serviceModel>

利用 ImplementationVisibility 特性，可以通过跟踪配置文件中的可见性模式筛选跟踪记录。复合活动是顶级活动，包含构成其实现的其他活动。可见性模式指定工作流活动中的复合活动发出的跟踪记录，这些跟踪记录用于指定是否跟踪构成实现的活动。可见性模式在跟踪配置文件级别应用。对工作流中单个活动的跟踪记录的筛选由跟踪配置文件中的查询控制。有关更多信息，请参见本文档中的跟踪配置文件查询类型部分。

跟踪配置文件中的 implementationVisibility 特性指定的两种可见性模式包括 RootScope 和 All。如果复合活动不是工作流的根，则使用 RootScope 模式会禁止构成活动实现的活动的跟踪记录。这意味着，如果将使用其他活动实现的某一活动添加到工作流中，并将 implementationVisibility 设置为 RootScope，则仅跟踪该复合活动中的顶级活动。如果活动是工作流的根，该活动的实现即为工作流自身，因此将发出构成实现的活动的跟踪记录。使用 All 模式允许发出根活动及其所有复合活动的所有跟踪记录。

例如，假定 MyActivity 是一个复合活动，其实现包含 Activity1 和 Activity2 两个活动。如果将此活动添加到工作流，并使用跟踪配置文件（已将 implementationVisibility 设置为 RootScope）启用跟踪，则仅发出 MyActivity 的跟踪记录，而不会发出 Activity1 和 Activity2 活动的记录。

但是，如果将跟踪配置文件的 implementationVisisbility 特性设置为 All，则不仅会发出 MyActivity 的跟踪记录，还会发出 Activity1 和 Activity2 活动的跟踪记录。

implementationVisibility 标志适用于以下跟踪记录类型：

ActivityStateRecord
FaultPropagationRecord
CancelRequestedRecord
ActivityScheduledRecord

注意：
implementationVisibility 设置无法筛选出活动实现发出的 CustomTrackingRecord。

在代码中，按如下方式在跟踪配置文件中指定 implementationVisibility 功能：

 TrackingProfile sampleTrackingProfile = new TrackingProfile()
{
                 Name = "Sample Tracking Profile"
                 ActivityDefinitionId="EmailWorkflow"
                 ImplementationVisibility = ImplementationVisibility.RootScope
}

在配置文件中，可按如下方式在跟踪配置文件中指定 implementationVisibility 功能：

<tracking>
      <profiles>
        <trackingProfile name="Shipping Monitoring" implementationVisibility="All">
          <workflow activityDefinitionId="*">
….
         </workflow>
        </trackingProfile>
      </profiles>
</tracking>

跟踪配置文件中的 ImplementationVisibility 设置是可选的。默认情况下，其值设置为 RootScope。此外，该特性的值还区分大小写。

跟踪配置文件查询类型

跟踪配置文件组织为跟踪记录的声明性订阅，利用这些订阅可以查询特定跟踪记录的工作流运行时。查询类型有多种，可用于订阅 TrackingRecord 对象的不同类。可以通过配置或代码指定跟踪配置文件。以下是最常见的查询类型：

WorkflowInstanceQuery - 用于跟踪工作流实例生命周期更改，例如，上面演示的 Started 和 Completed。WorkflowInstanceQuery 用于订阅下列 TrackingRecord 对象：

在 WorkflowInstanceStates 类中指定了可订阅的状态。

下面的示例演示使用 WorkflowInstanceQuery 订阅 Started 实例状态的工作流实例级跟踪记录所使用的配置或代码。

<workflowInstanceQueries>
    <workflowInstanceQuery>
      <states>
        <state name="Started"/>
      </states>
    </workflowInstanceQuery>
</workflowInstanceQueries>

TrackingProfile sampleTrackingProfile = new TrackingProfile()
{
                 Name = "Sample Tracking Profile"
                 ActivityDefinitionId="EmailWorkflow"
                 Queries = 
                   {
                     new WorkflowInstanceQuery()
                        {
                           States = { WorkflowInstanceStates.Started}

                        }
                    }
}

ActivityStateQuery - 用于跟踪组成工作流实例的活动的生命周期更改。例如，您可能希望对工作流实例中的“发送电子邮件”活动的每次完成进行跟踪。TrackingParticipant 需要用该查询来订阅 ActivityStateRecord 对象。在 ActivityStates 中指定了要订阅的可用状态。

下面的示例演示使用 ActivityStateQuery 订阅 SendEmailActivity 活动的活动状态跟踪记录所使用的配置和代码。

<activityStateQueries>
       <activityStateQuery activityName="SendEmailActivity">
           <states>
                  <state name="Closed"/>
           </states>
       </activityStateQuery>
</activityStateQueries>

TrackingProfile sampleTrackingProfile = new TrackingProfile()
{
     Name = "Sample Tracking Profile"
     ActivityDefinitionId="EmailWorkflow"
     Queries = {
          new ActivityStateQuery()
                   {                            
                   ActivityName = "SendEmailActivity",
                   States = { ActivityStates.Closed }
                   }
               }
}

ActivityScheduledQuery - 该查询用于跟踪安排给父活动来执行的活动。TrackingParticipant 需要用该查询来订阅 ActivityScheduledRecord 对象。

下面的示例演示使用 ActivityScheduledQuery 订阅与安排执行的 SendEmailActivity 子活动相关的记录所使用的配置和代码。

<activityScheduledQueries>
              <activityScheduledQuery activityName="ProcessNotificationsActivity" childActivityName=" SendEmailActivity" />
 </activityScheduledQueries>

TrackingProfile sampleTrackingProfile = new TrackingProfile()
{
     Name = "Sample Tracking Profile"
     ActivityDefinitionId="EmailWorkflow"
     Queries = {
                new ActivityScheduledQuery()
                  {
                  ActivityName = "ProcessNotificationsActivity",
                  ChildActivityName = "SendEmailActivity"
                  }
               }
}

FaultPropagationQuery - 用于跟踪对在活动中出现的错误进行的处理。TrackingParticipant 需要用该查询来订阅 FaultPropagationRecord 对象。

下面的示例演示使用 FaultPropagationQuery 订阅与错误传播相关的记录所使用的配置和代码。

<faultPropagationQueries>
              <faultPropagationQuery faultSourceActivityName="SendEmailActivity" faultHandlerActivityName="NotificationsFaultHandler" />
</faultPropagationQueries>

TrackingProfile sampleTrackingProfile = new TrackingProfile()
{
     Name = "Sample Tracking Profile"
     ActivityDefinitionId="EmailWorkflow"
     Queries = {
                       new FaultPropagationQuery()
                        {
                            FaultSourceActivityName = "SendEmailActivity",
                            FaultHandlerActivityName = "NotificationsFaultHandler"
                        }
                }
}

CancelRequestedQuery - 用于跟踪父活动取消子活动的请求。TrackingParticipant 需要用该查询来订阅 CancelRequestedRecord 对象。

下面的示例演示使用 CancelRequestedQuery 订阅与活动取消相关的记录所使用的配置和代码。

<cancelRequestedQueries>
      <cancelRequestedQuery activityName="ProcessNotificationsActivity" childActivityName="SendEmailActivity" />
</cancelRequestedQueries>

TrackingProfile sampleTrackingProfile = new TrackingProfile()
{ 
     Name = "Sample Tracking Profile"
     ActivityDefinitionId="EmailWorkflow"
     Queries = 
            {
              new CancelRequestedQuery()
                 {
                 ActivityName = "ProcessNotificationsActivity",
                 ChildActivityName = "SendEmailActivity"
                 }
              }
}

CustomTrackingQuery - 用于跟踪您在代码活动中定义的事件。TrackingParticipant 需要用该查询来订阅 CustomTrackingRecord 对象。

下面的示例演示使用 CustomTrackingQuery 订阅与自定义跟踪记录相关的记录所使用的配置和代码。

<customTrackingQueries>
     <customTrackingQuery name="EmailAddress" activityName="SendEmailActivity" />
</customTrackingQueries>

TrackingProfile sampleTrackingProfile = new TrackingProfile()
{
     Name = "Sample Tracking Profile"
     ActivityDefinitionId="EmailWorkflow"
     Queries = 
             {
             new CustomTrackingQuery() 
                        {
                         Name = "EmailAddress",
                         ActivityName = "SendEmailActivity"
                        }
             }
}

BookmarkResumptionQuery - 用于跟踪工作流实例中的书签恢复。TrackingParticipant 需要用该查询来订阅 BookmarkResumptionRecord 对象。

下面的示例演示使用 BookmarkResumptionQuery 订阅与书签恢复相关的记录所使用的配置和代码。

<bookmarkResumptionQueries>
             <bookmarkResumptionQuery name="SentEmailBookmark" />
            </bookmarkResumptionQueries>

TrackingProfile sampleTrackingProfile = new TrackingProfile()
{
     Name = "Sample Tracking Profile"
     ActivityDefinitionId="EmailWorkflow"
     Queries = 
             {
             new BookmarkResumptionQuery()
                        {
                        Name = "sentEmailBookmark"
                        }
                }
}

变量和参数

当跟踪工作流的执行时，提取数据往往很有用。这在访问跟踪记录后续执行时可提供其他上下文。在 .NET Framework 4 中，您可以使用跟踪在工作流的任意活动范围内提取所有可见变量或参数。跟踪配置文件简化了对数据的提取。

变量和参数在活动发出 ActivityStateRecord 时提取。仅当变量位于活动范围中时，才能提取该变量。按如下方式指定要通过活动提取的变量

如果变量用变量名称指定，跟踪则在正跟踪的当前活动和父活动中查找变量。系统将在当前活动范围和父范围中搜索变量。
如果要提取的变量使用 name="*" 指定，则提取正跟踪的当前活动中的所有变量。此种情况下，将不会提取范围中在父活动中定义的变量。

当提取参数时，提取的参数依赖于活动状态。当活动状态为 Executing 时，只能提取 InArguments。对于任何其他活动状态（Closed、Faulted、Canceled），则可以提取所有参数，即 InArguments 和 OutArguments。

下面的示例演示用于在发出活动的 Closed 跟踪记录时提取变量和参数的活动状态查询。变量和参数只能使用 ActivityStateRecord 来提取，因此使用 ActivityStateQuery 在跟踪配置文件内进行订阅。

<activityStateQuery activityName="SendEmailActivity">
  <states>
    <state name="Closed"/>
  </states>
  <variables>
    <variable name="FromAddress"/>
  </variables>
  <arguments>
    <argument name="Result"/>
  </arguments>
</activityStateQuery>

保护存储在变量/参数中的信息

默认情况下，跟踪变量或参数对 WF 运行时可见。工作流开发人员可以采取以下适当步骤，阻止访问这些变量或参数。

对变量的值进行加密。
控制跟踪配置文件的创作，以阻止提取变量或参数。
对于自定义跟踪参与者，请确保 WF 代码不会泄露存储在变量或参数中的敏感信息。

批注

通过批注，可以使用可在生成时后配置的某个值任意标记跟踪记录。例如，可能希望使用“Mail Server”==“Mail Server1”来标记跨多个工作流的多个跟踪记录。这样便于在以后查询跟踪记录时查找带有此标记的所有记录。

为此，可以在跟踪查询中添加一个批注，如下面的示例所示。

<activityStateQuery activityName="SendEmailActivity">
  <states>
    <state name="Closed"/>
  </states>
  <annotations>
    <annotation name="MailServer" value="Mail Server1"/>
  </annotations>
</activityStateQuery>

如何创建跟踪配置文件

跟踪查询元素用于通过使用 XML 配置文件或 .NET Framework 4 代码创建跟踪配置文件。以下是使用配置文件创建跟踪配置文件的示例。

<system.serviceModel>
         <tracking>
                 <profiles>
                       <trackingProfile name="Sample Tracking Profile ">
                            <workflow activityDefinitionId="*">
                           <!—Specify the tracking profile query elements to subscribe for tracking records
                            -->
                             </workflow>
                        </trackingProfile>
                 </profiles>
          </tracking>
</system.seriviceModel>

警告：
对于使用工作流服务主机的 WF，跟踪配置文件通常是使用配置文件创建的。也可以通过代码使用跟踪配置文件和跟踪查询 API 来创建跟踪配置文件。

配置为 XML 配置文件的配置文件适用于使用行为扩展的跟踪参与者。该配置文件添加到 WorkflowServiceHost 中，如下一节为工作流配置跟踪中所述。

主机发出的跟踪记录的详细信息由跟踪配置文件中的配置设置确定。跟踪参与者通过向跟踪配置文件添加查询来订阅跟踪记录。若要订阅所有跟踪记录，跟踪配置文件需要在每个查询的名称字段中使用 "*" 指定所有跟踪查询。

下面是跟踪配置文件的一些常见示例。

用于获取工作流实例记录和错误的跟踪配置文件。

<trackingProfile name="Instance and Fault Records">
  <workflow activityDefinitionId="*">
    <workflowInstanceQueries>   
      <workflowInstanceQuery>
        <states>
          <state name="*" />
        </states>
      </workflowInstanceQuery>
    </workflowInstanceQueries>
    <activityStateQueries>
      <activityStateQuery activityName="*">
        <states>
          <state name="Faulted"/>
        </states>
       </activityStateQuery>
    </activityStateQueries>
  </workflow>
</trackingProfile>

用于获取所有自定义跟踪记录的跟踪配置文件。

<trackingProfile name="Instance_And_Custom_Records">
      <workflow activityDefinitionId="*">
            <customTrackingQueries>
                 <customTrackingQuery name="*" activityName="*" />
            </customTrackingQueries>
      </workflow>
</trackingProfile>

通过

跟踪配置文件

跟踪配置文件

跟踪配置文件查询类型

变量和参数

保护存储在变量/参数中的信息

批注

如何创建跟踪配置文件

其他资源