建立和使用追蹤設定檔

追蹤設定檔可用於篩選追蹤資訊，讓您只會接收到您感興趣的追蹤資訊。 為了完成此操作，追蹤服務使用 TrackingProfile 物件來要求追蹤資訊。 新的工作流程執行個體啟動時，追蹤架構會呼叫已向執行階段註冊的每個追蹤服務上的 TryGetProfile。 工作流程執行個體的型別會提供做為這個呼叫的參數。 如果追蹤服務要接收有問題 (通常由執行的執行個體型別來決定) 的執行個體的追蹤資訊，它會傳回 true 並指定 TrackingProfile 物件做為 out 參數。 TrackingProfile 物件包含告知追蹤執行階段有關追蹤服務所要接收之事件和資料的資訊。 當追蹤架構接收到追蹤設定檔中指定的事件時，它會使用追蹤通道，將事件資訊傳送至追蹤服務。

追蹤設定檔可以表示為使用 TrackingProfile 結構描述 (在 Windows Workflow Foundation 中定義) 的 XML 檔案。 此外，追蹤設定檔也具有摘要詳細資訊的複雜物件模型。 您可以使用物件模型或 XML 來建立追蹤設定檔。 不過，因為執行階段需要 TrackingProfile 物件，所以，以 XML 形式表示的追蹤設定檔必須還原序列化為 TrackingProfile 物件。

追蹤設定檔物件模型項目

TrackingProfile 物件可讓您追蹤工作流程執行個體事件、個別活動事件和自訂使用者事件。 追蹤設定檔物件模型使用各種物件來建構追蹤設定檔，這個追蹤設定檔透過追蹤服務自執行階段引擎接收的服務來進行細微控制。

追蹤點

TrackingProfile 包含三種不同類型的追蹤點。 可篩選的追蹤事件有三種：

• 活動狀態事件

• 工作流程狀態事件

• 使用者事件

您可以將 WorkflowTrackPoint 物件加入至 WorkflowTrackPoints 屬性，以比對特定工作流程狀態事件，將 ActivityTrackPoint 物件加入至 ActivityTrackPoints 屬性，以比對特定活動狀態事件，以及將 UserTrackPoint 物件加入至 UserTrackPoints 屬性，以比對特定使用者事件。

WorkflowTrackPoint

每當工作流程執行個體的狀態變更時，工作流程執行個體都會發出以其中一個 TrackingWorkflowEvent 值為基礎的工作流程狀態事件到執行階段追蹤基礎結構。 WorkflowTrackPoint 會定義工作流程執行個體執行過程中發生特定類型工作流程狀態事件的點。 這些狀態事件是在 WorkflowTrackPoint 的 MatchingLocation 屬性中定義的。 如需追蹤位置和 WorkflowTrackPoint 之間關係的詳細資訊，請參閱本主題的「追蹤位置」一節。

WorkflowTrackPoint 也可以藉由新增 Annotations，來指定應由執行階段追蹤基礎結構傳送的其他相關資訊。 附註是您定義的字串，其中包含與 WorkflowTrackPoint 關聯的資訊。 例如，附註可能包含工作流程可以從此追蹤點取得的潛在執行路徑的資訊，或可能包含要在應用程式中顯示的資訊。

ActivityTrackPoint

每當活動的狀態變更時，工作流程執行個體都會發出以其中一個 ActivityExecutionStatus 值為基礎的活動狀態事件到執行階段追蹤基礎結構。 ActivityTrackPoint 會定義根工作流程潛在執行路徑中符合這類活動狀態事件的感興趣點。 ActivityTrackPoint 包含使用 MatchingLocations 屬性加入比對中的位置、使用 ExcludedLocations 屬性排除在比對外的位置，以及使用 Extracts 屬性在追蹤點符合時從工作流程執行個體中擷取的資料。

Extracts 屬性是包含 ActivityDataTrackingExtract 或 WorkflowDataTrackingExtract 物件的 ExtractCollection。 當您將 ActivityDataTrackingExtract 物件加入至 ExtractCollection 時，Member 屬性會指向活動的欄位或屬性、這類欄位或屬性的成員，或實作 IEnumerable 介面的欄位或屬性 (或任一成員) 的單一項目。 當 ActivityTrackPoint 符合時，成員的值會放入關聯的 ActivityTrackingRecord 的 Body 屬性中。 WorkflowDataTrackingExtract 物件可用於在此特定活動事件期間擷取工作流程的成員。

UserTrackPoint

活動設計工具或工作流程設計工具可使用多載的 System.Workflow.ComponentModel.Activity.TrackData(System.Object) 和 System.Workflow.ComponentModel.ActivityExecutionContext.TrackData(System.Object) 方法，以指示工作流程發出資料到執行階段追蹤基礎結構做為使用者事件。 發出的資料稱為「使用者資料」(User Data)。 與活動狀態事件不同的是，工作流程狀態事件只發生在狀態變更時，使用者事件可能發生在工作流程中指示的任何位置。 指示工作流程發出使用者事件有很多原因。 例如，工作流程設計工具可能想要傳達有關工作流程進度的邏輯狀態資訊，或活動設計工具可能想要在活動狀態變更以外的時候提供機會給活動成員。

UserTrackPoint 定義根活動流程執行個體潛在執行路徑中與使用者事件關聯的點。 UserTrackPoint 包含加入比對中的位置、排除在比對外的位置，以及要在追蹤點符合時從工作流程執行個體中擷取的任何其他資料。 您可以將 UserTrackPoint 加入至 System.Workflow.Runtime.Tracking.TrackingProfile.UserTrackPoints，以指示執行階段追蹤基礎結構在追蹤點符合時傳送 UserTrackingRecord 至追蹤服務。 使用者資料會在 System.Workflow.Runtime.Tracking.UserTrackingRecord.UserData 中傳回。 一個 UserTrackPoint 可能會符合工作流程執行個體中的多個點。

UserTrackingLocation 包含與工作流程執行個體潛在執行路徑中的使用者事件關聯的位置比對條件。 您可以將 UserTrackingLocation 物件加入至 MatchingLocations 中，以定義要包含在追蹤點比對中的位置。 同樣地，您可以將 UserTrackingLocation 物件新增至 ExcludedLocations 中，以定義要排除在追蹤點比對外的位置。 如需追蹤位置和 UserTrackPoint 之間關係的詳細資訊，請參閱本主題的「追蹤位置」一節。

您可以將 ActivityDataTrackingExtract 物件和 WorkflowDataTrackingExtract 物件加入至 Extracts 中，以指定在追蹤點符合時要從工作流程執行個體中擷取的資料。 擷取的資料在 System.Workflow.Runtime.Tracking.UserTrackingRecord.Body 中傳回。

您可以加入 Annotations，以指定與追蹤點關聯的其他資訊。 這些附註在 Annotations 中傳回。

追蹤位置

上一節說明如何關聯追蹤點和 TrackingProfile，以便指定以 Windows Workflow Foundation 執行階段引擎中使用的追蹤服務來處理的事件類型。 這些追蹤點使用追蹤位置來比對工作流程定義中的特定類型。

WorkflowTrackingLocation

WorkflowTrackingLocation 用於追蹤每當工作流程執行個體變更狀態時發生的追蹤事件。 在 WorkflowTrackingLocation 類別中定義的 Events 屬性讓您設定將比對的工作流程狀態事件清單。 這些事件可以是任何在 TrackingWorkflowEvent 列舉中定義的值的組合。

ActivityTrackingLocation

每當工作流程執行個體中的活動狀態變更時，使用 ActivityTrackingLocation 追蹤事件。 ActivityTrackingLocation 符合自 ActivityTypeName 或 ActivityType 屬性中指定的活動引發的事件。 當您指定 Type 時，使用 ActivityType 屬性。 不過，ActivityTypeName 屬性可用於指定參考活動類型的非限定名稱。 例如，若要指定 CodeActivity 活動的非限定名稱，請將 ActivityTypeName 屬性設定為 "CodeActivity"。

在 ActivityTrackingLocation 類別中定義的 ExecutionStatusEvents 屬性可讓您篩選由追蹤服務處理的活動層級事件的類型。 ExecutionStatusEvents 集合中的至少一個 ActivityExecutionStatus 值必須符合，而且 ExecutionStatusEvents 屬性中的每個 TrackingCondition 必須是 true，ActivityTrackingLocation 才能比對。 空的清單表示不比對任何事件。

ActivityTrackingCondition 讓您可以對要追蹤的活動精細度有其他控制能力。 ActivityTrackingCondition 類別的 Member 屬性會指定屬性或欄位、活動屬性或欄位的成員，或實作 IEnumerable 介面 (定義於您要追蹤的活動中) 的活動屬性或欄位 (或任一成員) 的單一項目。 Value 屬性代表您要使用指定的 Operator 與 Member 屬性比較的值。 藉由使用在附有 ActivityTrackingLocation 的 ActivityTrackingCondition 類別中的這三個屬性，您可以指定例如您只要追蹤 CodeActivity 活動，這些活動的 Name 屬性等於 "CodeActivity1"。

UserTrackingLocation

活動設計工具或工作流程設計工具可使用任何多載的 System.Workflow.ComponentModel.Activity.TrackData(System.Object) 和 System.Workflow.ComponentModel.ActivityExecutionContext.TrackData(System.Object) 方法，以指揮工作流程發出資料到執行階段追蹤基礎結構做為使用者事件。 發出的資料稱為使用者資料。 有別於活動狀態事件，以及只發生在活動或工作流程狀態變更時的工作流程狀態事件，使用者事件可能發生在工作流程中指示的任何位置。 UserTrackingLocation 會指定使用者資料類型、必須發出資料的活動類型、可更精確地限定此活動之執行個體的條件集合、使用者資料必須與其產生關聯的索引鍵名稱 (選擇性)、是否應比對使用者資料的衍生類型，以及是否應比對衍生自指定活動類型之活動上發出的使用者資料，藉此定義這類位置的比對參數。

您可以將 UserTrackingLocation 加入至 System.Workflow.Runtime.Tracking.UserTrackPoint.MatchingLocations 或 System.Workflow.Runtime.Tracking.UserTrackPoint.ExcludedLocations 屬性中，以定義 TrackingProfile 中 UserTrackPoint 的比對參數。

條件

若要由執行階段追蹤基礎結構比對 UserTrackingLocation，有三個必須依下列順序符合的一般條件：

• 已發出使用者事件的活動必須符合由 ActivityType、ActivityTypeName、Conditions 和 MatchDerivedActivityTypes 屬性指定的活動集合。

• 如果存在索引鍵，則與使用者資料關聯的索引鍵必須符合 KeyName 屬性。

• 使用者事件發出的使用者資料類型必須符合由 ArgumentType、ArgumentTypeName 和 MatchDerivedArgumentTypes 屬性指定的使用者資料類型集合。

只有這三個條件全都符合時，執行階段追蹤基礎結構才會將 UserTrackingLocation 視為符合。

若要設定 UserTrackingLocation，您必須設定 ArgumentTypeName 屬性或 ArgumentType 屬性，以指定要比對的使用者資料型別。 此外，您也必須指定 ActivityTypeName 屬性或 ActivityType 屬性，以指定要比對的發出使用者資料的活動型別。 您可以將 ActivityTrackingCondition 物件加入至 Conditions 中，以便更完整地限定發出使用者資料的來源活動。 您可以設定 MatchDerivedArgumentTypes 屬性來指定衍生自 ArgumentTypeName 或 ArgumentType 屬性指定的使用者資料型號的使用者資料應該相符，而且您可以設定 MatchDerivedActivityTypes 屬性來指定衍生自 ActivityTypeName 或 ActivityType 屬性指定的活動型別的活動發出的使用者資料應該相符。

您可以將 KeyName 設為指定只針對此 UserTrackingLocation 比對與指定之索引鍵名稱關聯的使用者資料。 如果 KeyName 屬性是 null 參考 (在 Visual Basic 中為 Nothing)，執行階段追蹤結構不會嘗試比對與使用者資料關聯的索引鍵。

使用追蹤設定檔物件模型

如先前所述，您可以使用 Windows Workflow Foundation API 來建立要在您的追蹤服務中使用的 TrackingProfile 物件。 追蹤設定檔物件模型使用在上一節描述的類別組來建立 TrackingProfile。 TrackingProfile 物件包含與工作流程、活動和使用者追蹤點相關的追蹤點。 每個追蹤點也都有一組比對位置。 比對位置描述將追蹤的事件和要追蹤的活動。 除了比對位置以外，您還可以定義排除位置。

在追蹤設定檔中使用的活動屬性應該對應活動物件模型中的名稱。

下列程式碼範例會示範如何建立追蹤 CodeActivity 活動和三個事件的追蹤設定檔：Initialized、Executing 和 Closed。 設定檔具有一個 ActivityTrackPoint，搭配一個比對位置。

static void CreateSimpleTrackingProfile()
{

    TrackingProfile myProfile = new TrackingProfile();
    ActivityTrackPoint myTrackPoint = new ActivityTrackPoint();
    ActivityTrackingLocation myLocation = new ActivityTrackingLocation(typeof(CodeActivity));
    myLocation.MatchDerivedTypes = false;
    myLocation.ExecutionStatusEvents.Add(ActivityExecutionStatus.Initialized);
    myLocation.ExecutionStatusEvents.Add(ActivityExecutionStatus.Executing);
    myLocation.ExecutionStatusEvents.Add(ActivityExecutionStatus.Closed);
    myTrackPoint.MatchingLocations.Add(myLocation);
    myProfile.ActivityTrackPoints.Add(myTrackPoint);
    myProfile.Version = new Version("1.0.0.0");
    TrackingProfileSerializer trackingProfileSerializer = new TrackingProfileSerializer();
    StringBuilder trackingProfileString = new StringBuilder();
    using (StringWriter writer = new StringWriter(trackingProfileString, CultureInfo.InvariantCulture))
    {
        trackingProfileSerializer.Serialize(writer, myProfile);
        Console.WriteLine(writer.ToString());
    }
}

建立和使用 TrackingProfile 的 XML

您也可以使用 XML 寫入追蹤設定檔。 執行此操作時，您必須將 XML 還原序列化為 TrackingProfile。 在上一節建立的 TrackingProfile 的對應 XML 表示如下所示。

<?xml version="1.0" encoding="utf-16" standalone="yes"?>
<TrackingProfile xmlns="https://schemas.microsoft.com/winfx/2006/workflow/trackin
gprofile" version="1.0.0.0">
    <TrackPoints>
        <ActivityTrackPoint>
            <MatchingLocations>
                <ActivityTrackingLocation>
                    <Activity>
                        <Type>System.Workflow.Activities.CodeActivity, System.Wo
rkflow.Activities, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad36
4e35</Type>
                        <MatchDerivedTypes>false</MatchDerivedTypes>
                    </Activity>
                    <ExecutionStatusEvents>
                        <ExecutionStatus>Initialized</ExecutionStatus>
                        <ExecutionStatus>Executing</ExecutionStatus>
                        <ExecutionStatus>Closed</ExecutionStatus>
                    </ExecutionStatusEvents>
                </ActivityTrackingLocation>
            </MatchingLocations>
        </ActivityTrackPoint>
    </TrackPoints>
</TrackingProfile>

使用追蹤設定檔物件模型和包括在 Windows Workflow Foundation 中的 TrackingProfileSerializer 類別也可以建構 TrackingProfile 的 XML 表示。

下列範例會示範如何將 TrackingProfile 物件序列化為 XML 資料。

TrackingProfileSerializer serializer = new TrackingProfileSerializer();
StringWriter writer = new StringWriter(new StringBuilder(),CultureInfo.InvariantCulture);
serializer.Serialize(writer, profile);
string trackingprofile = writer.ToString();

請參閱

參考

TrackingProfile

概念

建立自訂追蹤服務

Copyright © 2007 by Microsoft Corporation. All rights reserved.