HOW TO：建立診斷資料配接器

發行項
08/12/2011

若要建立「診斷資料配接器」(Diagnostic Data Adapter)，您必須使用 Microsoft Visual Studio 2010 建立類別庫，然後將 Microsoft Visual Studio 2010 Premium 提供的診斷資料配接器 API 加入至類別庫。在處理測試回合期間引發的事件時，請以資料流或檔案的形式將您所需要的資訊傳送至架構所提供的 DataCollectionSink。測試完成時，傳送至 DataCollectionSink 的資料流或檔案會儲存為測試結果的附件。如果從這些測試結果建立 Bug，或當使用測試執行器時，檔案也會連結至 Bug。

您可以建立診斷資料配接器，其會影響執行測試所在機器，或屬於要用來執行待測應用程式環境的機器。例如，收集執行測試之測試機器上的檔案，或者收集擔任應用程式之 Web 伺服器角色的機器上的檔案。

您可以為診斷資料配接器指定一個易記的名稱，這個名稱會在使用測試管理員或使用 Microsoft Visual Studio 2010 建立測試設定時顯示。測試設定可讓您定義在執行測試時，要以環境中的哪個電腦角色執行特定診斷資料配接器。您也可以在建立測試設定時，設定診斷資料配接器。例如，您可建立從 Web 伺服器收集自訂記錄檔的診斷資料配接器。當建立測試設定時，您可以選取在執行這個 Web 伺服器角色的一部或多部電腦上執行此診斷資料配接器，並且可以修改測試設定的組態，以只收集最後建立的三個記錄檔。如需測試設定的詳細資訊，請參閱使用測試設定安裝電腦和收集診斷資訊。

當執行測試時會引發事件，如此診斷資料配接器便可以在該時間點執行工作。

重要事項
這些事件可能會在不同的執行緒上引發，尤其是您在多部電腦上執行測試時。因此，您必須留意可能發生的執行緒問題，並避免不慎損毀自訂配接器的內部資料。請確定您的診斷資料配接器符合執行緒安全。

以下是您在建立診斷資料配接器時可以使用之關鍵事件的部分清單。如需診斷資料配接器事件的完整清單，請參閱抽象 DataCollectionEvents 類別。

事件	描述
SessionStart	啟動測試回合
SessionEnd	結束測試回合
TestCaseStart	啟動測試回合中的每個測試
TestCaseEnd	結束測試回合中的每個測試
TestStepStart	啟動測試中的每個測試步驟
TestStepEnd	結束測試中的每個測試步驟

注意事項
當手動測試完成時，系統不會將其他資料收集事件傳送至診斷資料配接器。重新執行某項測試時，會使用新的測試案例識別項。如果使用者在測試期間重設測試 (這會引發 TestCaseReset 事件)，或變更測試步驟結果，則不會傳送任何資料收集事件至診斷資料配接器，但測試案例識別項仍會相同。若要判斷測試案例是否已重設，您必須追蹤診斷資料配接器中的測試案例識別項。

當手動測試完成時，系統不會將其他資料收集事件傳送至診斷資料配接器。重新執行某項測試時，會使用新的測試案例識別項。如果使用者在測試期間重設測試 (這會引發 TestCaseReset 事件)，或變更測試步驟結果，則不會傳送任何資料收集事件至診斷資料配接器，但測試案例識別項仍會相同。若要判斷測試案例是否已重設，您必須追蹤診斷資料配接器中的測試案例識別項。

使用下列程序建立診斷資料配接器，以收集根據您在建立測試設定時所設定之資訊的資料檔案。

如需診斷資料配接器專案的完整範例 (包括自訂組態編輯器)，請參閱建立診斷資料配接器的範例專案。

建立和安裝診斷資料配接器

若要建立和安裝診斷資料配接器

建立新的類別庫。
1. 按一下 [檔案] 功能表上的 [新增]，然後指向 [新增專案]。
2. 從 [專案類型] 選取要使用的語言。
3. 從 [Visual Studio 安裝的範本] 中選取 [類別庫]。
4. 輸入診斷資料配接器的名稱。
5. 按一下 [確定]。
加入組件 Microsoft.VisualStudio.QualityTools.ExecutionCommon。
1. 在 [方案總管] 中，以滑鼠右鍵按一下 [參考]，然後按一下 [加入參考] 命令。
2. 按一下 [.NET] 並尋找 Microsoft.VisualStudio.QualityTools.ExecutionCommon.dll。
3. 按一下 [確定]。
加入組件 Microsoft.VisualStudio.QualityTools.Common。
1. 在 [方案總管] 中，以滑鼠右鍵按一下 [參考]，然後選取 [加入參考] 命令。
2. 按一下 [/.NET]，然後找出 Microsoft.VisualStudio.QualityTools.Common.dll。
3. 按一下 [確定]。

將下列 using 陳述式加入至類別檔：

using Microsoft.VisualStudio.TestTools.Common;
using Microsoft.VisualStudio.TestTools.Execution;
using System.Linq;
using System.Text;
using System.Xml;
using System;

將 DataCollectorTypeUriAttribute 加入至您診斷資料配接器的類別，以將其識別為診斷資料配接器，並且將 Company、Product 和 Version 取代為診斷資料配接器的適當資訊：
```
[DataCollectorTypeUri("datacollector://Company/Product/Version")]
```

將 DataCollectorFriendlyNameAttribute 屬性加入至類別，而將參數取代為診斷資料配接器的適當資訊：

[DataCollectorFriendlyName("Collect Log Files", false)]

這個易記的名稱顯示在測試設定活動中。

注意事項
您也可以加入 DataCollectorConfigurationEditorAttribute，針對此資料配接器指定自訂組態編輯器的 Type，以及選擇性地指定用於編輯器的說明檔。您也可以套用 DataCollectorEnabledByDefaultAttribute，將它指定為永遠啟用。

您也可以加入 DataCollectorConfigurationEditorAttribute，針對此資料配接器指定自訂組態編輯器的 Type，以及選擇性地指定用於編輯器的說明檔。

您也可以套用 DataCollectorEnabledByDefaultAttribute，將它指定為永遠啟用。

您的診斷資料配接器類別必須繼承自 DataCollector 類別，如下所示：
```
public class MyDiagnosticDataAdapter : DataCollector
```

加入如下的區域變數：

private DataCollectionEvents dataEvents;
private DataCollectionLogger dataLogger;
private DataCollectionSink dataSink;
private XmlElement configurationSettings;

加入 Initialize 方法和 Dispose 方法。在 Initialize 方法中，您可以初始化資料接收器、來自測試設定的任何組態資料，以及註冊您要使用的事件處理常式，如下所示：

public override void Initialize(
    XmlElement configurationElement, 
    DataCollectionEvents events, 
    DataCollectionSink sink, 
    DataCollectionLogger logger, 
    DataCollectionEnvironmentContext environmentContext)
{
       dataEvents = events;  // The test events
       dataLogger = logger;  // The error and warning log
       dataSink = sink;      // Saves collected data
       // Configuration from the test settings
       configurationSettings = configurationElement;

       // Register common events for the data collector
       // Not all of the events are used in this class
    dataEvents.SessionStart += 
        new EventHandler<SessionStartEventArgs>(OnSessionStart);
    dataEvents.SessionEnd += 
        new EventHandler<SessionEndEventArgs>(OnSessionEnd);
    dataEvents.TestCaseStart += 
        new EventHandler<TestCaseStartEventArgs>(OnTestCaseStart);
    dataEvents.TestCaseEnd += 
        new EventHandler<TestCaseEndEventArgs>(OnTestCaseEnd);
}

public override void Dispose(bool disposing)
{
    if (disposing)
    {
        // Unregister the registered events
        dataEvents.SessionStart -= 
            new EventHandler<SessionStartEventArgs>(OnSessionStart);
        dataEvents.SessionEnd -= 
            new EventHandler<SessionEndEventArgs>(OnSessionEnd);
        dataEvents.TestCaseStart -= 
            new EventHandler<TestCaseStartEventArgs>(OnTestCaseStart);
        dataEvents.TestCaseEnd -= 
            new EventHandler<TestCaseEndEventArgs>(OnTestCaseEnd);
    }
}

使用下列事件處理常式程式碼和私用方法來收集測試期間產生的記錄檔：

public void OnTestCaseEnd(sender, TestCaseEndEventArgs e)
{
    // Get any files to be collected that are
    // configured in your test settings
    List<string> files = getFilesToCollect();

    // For each of the files, send the file to the data sink
    // which will attach it to the test results or to a bug
    foreach (string file in files)
    {
        dataSink.SendFileAsync(e.Context, file, false);
    }
}

// A private method that returns the file names
private List<string> getFilesToCollect()
{
    // Get a namespace manager with our namespace
    XmlNamespaceManager nsmgr =
        new XmlNamespaceManager(
            configurationSettings.OwnerDocument.NameTable);
    nsmgr.AddNamespace("ns", 
        "http://MyCompany/schemas/MyDataCollector/1.0");

    // Find all of the "File" elements under our configuration
    XmlNodeList files =
        configurationSettings.SelectNodes(
            "//ns:MyDataCollector/ns:File");

    // Build the list of files to collect from the 
    // "FullPath" attributes of the "File" nodes.
    List<string> result = new List<string>();
    foreach (XmlNode fileNode in files)
    {
        XmlAttribute pathAttribute = 
            fileNode.Attributes["FullPath"];
        if (pathAttribute != null &&
            !String.IsNullOrEmpty(pathAttribute.Value))
        {
            result.Add(pathAttribute.Value);
        }
    }

    return result;
}

這些檔案會附加至測試結果。如果從這些測試結果建立 Bug，或當您使用測試執行器時，檔案也會附加至 Bug。

如果您想要使用自己的編輯器收集要在測試設定中使用的資料，請參閱 HOW TO：為您的診斷資料配接器建立資料的自訂編輯器。

若要在測試完成時根據使用者在測試設定中進行的設定收集記錄檔，您必須建立 App.config 檔並且將它加入方案中。此檔案的格式如下所示，而且必須包含 URI，診斷資料配接器才能識別該檔案。請將 "Company/ProductName/Version" 替換為實際值。

注意事項
如果您不需要為診斷資料配接器設定任何資訊，則不需要建立組態檔。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="DataCollectorConfiguration" 
      type="Microsoft.VisualStudio.TestTools.Execution.DataCollectorConfigurationSection, 
      Microsoft.VisualStudio.QualityTools.ExecutionCommon, 
      Version=4.0.0.0, Culture=neutral, 
      PublicKeyToken=b03f5f7f11d50a3a" />
  </configSections>
  <DataCollectorConfiguration 
    xmlns="https://microsoft.com/schemas/VisualStudio/TeamTest/2010">
    <DefaultConfiguration>
      <!-- Your default config settings -->
        <File FullPath="C:\temp\logfile1.txt"/>
        <File FullPath="C:\temp\logfile2.txt"/>
    </DefaultConfiguration>
  </DataCollectorConfiguration>
</configuration>

注意事項
預設組態項目可以包含您需要的任何資料。如果使用者未在測試設定中設定診斷資料配接器，則在診斷資料配接器執行時預設資料會傳遞給它。由於您加入至 <DefaultConfigurations> 區段的 XML 不可能是宣告之結構描述的一部分，因此您可以忽略它產生的任何 XML 錯誤。下列路徑中會有其他組態檔範例，取決於您的安裝目錄：Program Files\Microsoft Visual Studio 10.0\Common7\IDE\PrivateAssemblies\DataCollectors。

預設組態項目可以包含您需要的任何資料。如果使用者未在測試設定中設定診斷資料配接器，則在診斷資料配接器執行時預設資料會傳遞給它。由於您加入至 <DefaultConfigurations> 區段的 XML 不可能是宣告之結構描述的一部分，因此您可以忽略它產生的任何 XML 錯誤。

下列路徑中會有其他組態檔範例，取決於您的安裝目錄：Program Files\Microsoft Visual Studio 10.0\Common7\IDE\PrivateAssemblies\DataCollectors。

如需如何設定測試設定以便在執行測試時使用環境的詳細資訊，請參閱建立手動測試的測試設定或將自動化測試的測試設定建立成測試計劃的一部分。

如需有關安裝組態檔的詳細資訊，請參閱 HOW TO：安裝自訂的診斷資料配接器。

建置方案以建立您的診斷資料配接器組件。
如需安裝自訂編輯器的詳細資訊，請參閱 HOW TO：安裝自訂的診斷資料配接器。
如需如何設定測試設定以便在執行測試時使用環境的詳細資訊，請參閱建立手動測試的測試設定或將自動化測試的測試設定建立成測試計劃的一部分。
若要選取診斷資料配接器，您必須先從 Microsoft 測試管理員或 Microsoft Visual Studio 2010 選取現有的測試設定或建立新的測試設定。配接器會顯示在測試設定的 [資料和診斷] 索引標籤上，並使用您指派給類別的易記名稱。
如果您從 Microsoft 測試管理員執行測試，您可以在執行測試前將這些測試設定指派給測試計劃，或使用 [以選項執行] 命令來指派測試設定和覆寫測試設定。如需測試設定的詳細資訊，請參閱使用測試設定安裝電腦和收集診斷資訊。

如果從 Microsoft Visual Studio 2010 執行測試，則必須將這些測試設定設為作用中。如需測試設定的詳細資訊，請參閱建立測試設定以便從 Visual Studio 執行自動化的測試。
使用已選取您診斷資料配接器的測試設定來執行您的測試。

您指定的資料檔案會附加至測試結果。