使用 TestStand API 進行程式設計

設計良好的模組化測試架構能提供卓越價值。您可在特定範圍內的測試系統上重複使用易於採用的一般化架構，以延長測試系統的使用壽命，並降低開發成本。TestStand 提供的平台以模組化特性為建置基礎，可簡化測試系統與對應測試的開發作業。TestStand 的優勢在於其開放式架構，您可用以建立複雜且高度靈活的測試解決方案。

TestStand 引擎提供適用於 TestStand 元件的功能，這些元件可透過 TestStand API 與引擎通訊

TestStand 在展示層 (使用者所看到的層) 與運作邏輯層 (在使用者行動背後的行動) 之間有清楚的區隔。這些層使用 TestStand API 通訊。此方法讓您可建置透過 TestStand API 使用 TestStand 引擎的額外元件，例如建立客制化使用者介面、動態控制測試流程、即時建立序列，以及開發其他進階解決方案，藉此延伸 TestStand 的功能。

TestStand 引擎是透過 API 發揮功能的 ActiveX/COM 自動化伺服器。Microsoft 開發了 ActiveX 應用通訊標準，提供可讓應用彼此通訊的方式。多年來受到業界廣泛採用的 ActiveX 是以 COM 技術為基礎。由於 TestStand 以 COM 為建置基礎，因此在 ActiveX 的使用壽命結束後，TestStand 仍可繼續於未來的 Windows 作業系統版本上運作。

ActiveX 採用伺服器/用戶端型態。ActiveX 伺服器應用可對依循 ActiveX 標準的用戶端提供特定功能。此外，ActiveX 應用採用物件導向程式設計 (OOP)。

可呼叫 ActiveX 程式碼的程式設計語言，例如 LabVIEW、LabWindows™/CVI™、C#、VB .NET 或 C++ 等，皆可透過 ActiveX 伺服器架構與 TestStand 引擎互動。使用 TestStand API 進行程式設計時，實作方式視您使用的語言而定。例如：

• LabVIEW 使用屬性與呼叫節點來進行 API 呼叫作業。
• LabWindows/CVI 對 API 呼叫使用儀器驅動程式封套。
• C# 或 VB .NET 使用 TestStand 提供的 Interop 組件呼叫 API。
• TestStand 本身提供 ActiveX/COM 轉接器以存取 API，您也可使用表式直接存取 API。

無論您使用何種方式存取 API，在任何環境中皆會產生相同動作，這是因為無論您使用的介面為何，都會在 TestStand 引擎內部實作功能。

API 類別

TestStand API 定義數種類別來代表 TestStand 物件類型，例如 SequenceFile 類別或 Execution 類別。每種類別皆定義了屬性與方法，可存取相關資料或執行行動。例如，SequenceFile 類別定義 Path 屬性，以儲存序列檔案在磁碟上的路徑，並定義儲存序列檔案的 Save 方法。

請參閱 TestStand API 參考說明主題，以取得 TestStand API 所定義之可用類別的完整清單。按一下特定類別可查看更多相關資訊，以及該類別定義的屬性與方法。 

類別繼承

TestStand 的許多類別皆是透過繼承建立相關性：較特定的類別可繼承較通用類別的屬性或方法。例如，SequenceFile 類別是 PropertyObject 類別的較特定版本。TestStand API 定義這些類別間的繼承關係，讓較特定類別的物件可存取較通用類別的屬性與方法。

SequenceFile 類別可繼承較通用的 PropertyObjectFile 與 PropertyObject 類別的屬性與方法

幾乎所有 TestStand API 類別皆可繼承基本的 PropertyObject 類別，此類別包含 TestStand 物件共有的常用方法與屬性。PropertyObject 類別定義通用屬性，例如 Name 與 Numeric Format，並提供適用於物件管理的常用方法，例如複製、設定與取得值、建立與刪除物件，或是操作陣列。因為大多數 TestStand API 類別皆可繼承 PropertyObject 類別，因此也可存取這些通用屬性與方法。例如，您可使用 PropertyObject.Clone() 方法建立步驟、序列或序列檔案物件的複本。

在許多開發環境中，皆無法直接存取母體類別的屬性。同樣地，在 TestStand 中，您無法直接於 SequenceFile 物件呼叫 Clone() 方法。不過，TestStand API 提供的方法可傳播物件，以存取較通用類別的屬性與方法。若要存取 PropertyObject 類別中定義的屬性與方法，您可以呼叫 AsPropertyObject 方法，以物件傳播至其母體類別內。例如，若要存取序列檔案物件的 Clone() 方法，可使用
SequenceFile.AsPropertyObject.Clone()。

請參閱 NI TestStand 說明，以進一步了解 API 繼承以及 PropertyObject 類別的屬性與方法。

動態屬性與內建屬性

TestStand 物件具有 2 種不同的屬性類型：

• 內建屬性 (API 屬性)；此由物件類別定義，特定類別中的所有物件內皆存在此屬性。
• 動態屬性 (次要屬性)；此由物件定義，在同一類別中的物件之間，此屬性可能各有不同。

Step 物件具有動態屬性 (可能根據步驟類型而不同) 與靜態屬性 (由 TestStand API 的 Step 類別定義)

這 2 種不同的屬性類型可能易於混淆，因為兩者在 TestStand 表式中都可使用「.」 運算子。不過，在其他程式設計語言中使用 API 時，只有內建屬性可透過直接存取使用，例如在 LabVIEW 中使用屬性節點。

若要存取動態屬性，可使用 PropertyObject API 方法，例如 GetValString() 與 GetValNumber()，並使用 LookupString 指定動態屬性的名稱：

在某些情況下，無論是使用動態屬性或內建屬性，皆可透過多種方法存取屬性。在程式碼模組中使用 TestStand API 時，較佳做法是使用內建屬性，因為這類屬性可直接存取，無需維護查詢字串。 

TestStand 物件關係

TestStand 物件可能包含不同類別的其他物件，稱之為 API 內含項目。例如，SequenceFile 物件內含序列檔案定義之序列的 Sequence 物件。而每個 Sequence 物件皆包含 Step 物件。

TestStand API 中的物件通常包含不同類別的其他物件

了解物件間的內含項目關係，有助於瀏覽特定物件。如果母物件中包含特定類別的多個子物件，您必須提供屬性名稱或索引，以指定所需的子物件。針對大多數子物件，您可使用特定的 Getter 方法存取母物件的內含物件；Getter 方法可將物件名稱或索引做為參數。例如，若要存取序列檔案內的步驟，可使用：

SequenceFile.getSequenceByName(“MainSequence”).GetStepByName(“RAM Test”, StepGroup_Main)

此外，子物件可透過 API 存取其母物件。由於子物件一律只具有 1 個母物件，因此請使用屬性直接存取母物件，而非使用 Getter 方法。例如，若您有 SequenceContext 物件，並需要存取母執行，可使用：

ThisContext.Thread.Execution

在許多情況下，會提供內建屬性以存取較遠的母體。例如，您可直接存取 Sequence Context 物件的 Execution 物件：

ThisContext.Execution

透過 TestStand API 物件瀏覽

除了使用內含項目關係瀏覽外，許多類別皆提供可存取其他相關物件的屬性或方法。例如，Module 類別提供 Adapter 屬性，可存取執行中的對應轉接器。 

您可使用 TestStand API 參考說明主題所提供的圖表，判斷從目前物件存取所需物件的方法。下方所示為此圖表的子集。
 

您可從 SequenceContext 物件瀏覽物件關係，以存取其他物件

一般可使用 2 種方法存取 API，視您建立的應用類型而定：

• 若為獨立應用，您必須建立 TestStand 引擎的新個體。
• 若為從現有應用呼叫的程式碼模組或其他工具，必須傳遞對 TestStand 引擎的現有參照。

建立獨立 TestStand 應用

若要在新應用中使用 TestStand API，首先必須建立 TestStand 引擎的個體。例如 TestStand 使用者介面、Sequence Editor 或客制化公用程式等任何 TestStand 應用或程序，都會維護引擎的單一個體 (或稱「單例」)，以執行 TestStand 函式。引擎會維護對所有記憶體內物件的參照，並進行設定與控制執行，同時也會儲存 TestStand 工作階段的上下文資料、站點全域變數與使用者資訊。

TestStand 引擎提供可用於建立其他 TestStand 物件的方法，並以關鍵字「new」表示，例如下列方法：

• Engine.NewSequenceFile()
• Engine.NewStep()
• Engine.NewExecution()
• Engine.NewPropertyObject()

如需取得 Engine 物件提供之屬性與方法的完整清單，請參閱 TestStand 引擎主題以了解更多資訊。

應用結束時，您必須先關閉 TestStand 引擎後，再退出應用。此時必須採用 2 個步驟的關閉程序，以確保使用者有機會終止運作中的執行，如同 TestStand 說明的關閉引擎主題所述。

NI 建議使用 TestStand UI 控制元件來開發 TestStand 應用與使用者介面，而非直接建立 TestStand 引擎物件，以降低程式的複雜度。TestStand UI 控制元件提供了位於 TestStand API 上的抽象層，可更輕鬆地開發獨立 TestStand 應用。請參閱本文件的 UI 控制元件 API 部分，以進一步了解使用 UI 控制元件。

從現有應用呼叫程式碼模組或工具

在從其他 TestStand 應用呼叫的程式碼模組或工具中使用 API 時，應使用由最上層應用建立的 TestStand 引擎。如果是從執行中序列呼叫程式碼，例如程式碼模組，使用 SequenceContext 的輸入參數會是完成此作業的最佳方式。相較於直接傳輸 TestStand 引擎，採取上述方式較佳，因為序列上下文可供存取執行的目前狀態，也可供存取 TestStand 引擎物件。

SequenceContext 代表序列的目前執行狀態，可供存取特定執行序列的所有資料快照。每個在執行緒內的執行序列，皆有各自的 SequenceContext。

瀏覽變數檢視時，您所看到的清單為 SequenceContext 第一級屬性，其中包含所有變數類型、目前步驟與 RunState 屬性。SequenceContext 也提供對許多其他物件的參照，並做為內建屬性。

RunState 與 SequenceContext

RunState 屬性與 SequenceContext 兩者皆可供存取許多相同物件，例如目前執行、執行緒、序列檔案與序列。但是，RunState 屬性中的這些物件皆為動態屬性，不同於 SequenceContext 以內建屬性提供這些物件。

因此，存取 TestStand 表式狀態的相關資訊時，應使用 RunState 屬性，若為程式碼模組，使用 SequenceContext 則較為合適，因為此時無法直接存取動態屬性。

 SequenceContext 透過內建屬性與動態屬性提供執行狀態資訊，而 RunState 屬性則僅透過動態屬性提供狀態資訊。

序列資料的持續時間

在執行序列內的步驟前，TestStand 會先建立序列的執行階段複本，以便為每個序列調用維護獨立的區域變數與步驟屬性值。在大多數情況下，從位於執行序列內的 Runstate 或 SequenceContext 存取物件時，這些物件皆為上述執行階段複本。這代表您對這些物件所做的任何變更，在完成執行後皆不會繼續保留，例如變更區域變數值，或以程式設計方式建立參數的子屬性，都不會影響磁碟上的序列檔案：

Locals.SetValString("RuntimeVariable",1, "value")

從 PropertyObjectFile 類別繼承的物件，如 SequenceFile 物件等，都不具備獨立的執行階段複本，因此您透過這類物件所做的變更，在執行完成後仍會繼續保留。例如，透過 SequenceFile 物件存取 Locals 屬性，即可建立會持續保留的區域變數。

RunState.sequencefile.GetSequenceByName("MainSequence").Locals.SetValString("PersistantVariable",1, "value")

雖然 TestStand API 能夠將所有 TestStand 功能自動化，不過此 API 還有一些更常見的應用：

• 建立客制化屬性
• 建立新序列檔案
• 修改現有序列

建立客制化屬性

您可使用 TestStand API，在執行階段中以動態的方式產生客制化屬性，例如在測試因特定元件失敗時，將特定診斷資料新增至測試結果，或是對報告表頭新增客制化資料。 

您可利用多種方法透過 API 建立客制化屬性。針對初始資料類型，使用具有 InsertIfMissing 選項的「SetVal」方法，即可以最簡單的方式建立新屬性。例如，您可使用下列表式將新屬性新增至數值測試步驟：

RunState.Sequence.Main["Numeric Limit Test"].AsPropertyObject.SetValString(
"Result.extraResult",
PropOption_InsertIfMissing,
"this string is an extra result")

若要新增客制化屬性至報表，也必須設定物件的 IncludeInReport 標記，報表產生器會使用這項標記選擇應記錄的結果屬性：

RunState.Sequence.Main["Numeric Limit Test"].AsPropertyObject.SetFlags(
"Result.extraResult",
0,
PropFlags_IncludeInReport)

如需進一步了解使用 API 將資料新增至測試報表的資訊，請參閱新增客制化資料至報表範例。

針對容器等較複雜的屬性，則需要使用 NewSubProperty() 方法直接建立屬性，此方法讓您能建立容器、資料類型個體與陣列。例如，若要建立 Error 類型的新區域變數，您可使用表式：

Locals.NewSubProperty("ComplexContainer.Error",PropValType_NamedType, False, "Error",0)

如需進一步了解使用 API 建立屬性的資訊，請參閱「使用 API 建立新屬性」範例。

建立新序列

若要將根據使用者輸入建立序列檔案的程序自動化，您可使用 TestStand API 產生新序列檔案，或建立現有檔案的經修改複本。例如，您可能會想建立能根據特定使用者輸入產生起始點序列檔案的工具，或是能對現有序列檔案的步驟執行特定修改的工具。

如需進一步了解使用 API 建立新序列檔案的資訊，請參閱使用 API 建置序列範例。

您也可使用 TestStand API 開發序列檔案編譯器，以使用客制化檔案格式產生序列檔案。建立序列檔案編譯器時，可根據您指定之檔案內的資料，使用 TestStand API 產生序列檔案、序列、步驟與屬性。編譯器架構讓您能將此程式碼與 TestStand 整合，並能直接以客制化格式開啟檔案。 

如需進一步了解使用序列檔案編譯器的資訊，請參閱 TestStand 說明中的序列檔案編譯器主題。

修改序列

您可在所使用的客制化工具中使用 TestStand API，以對現有序列檔案執行修改。例如，您可能想建立工具來檢查以絕對路徑指定的程式碼模組，並將其替換為相對路徑。 

請參閱建立序列檔案迭代工具範例以了解更多資訊。

除了核心 TestStand API 外，TestStand 也提供其他 API，可延伸功能與提供其他功能：

• UI 控制元件 API
• 轉接器 API
• 同步化伺服器 API

不同於核心 TestStand API，您無法透過表式直接存取這些 API，而是要透過 ActiveX 步驟或獨立程式碼模組來使用這些 API。

UI 控制元件 API

TestStand 內含一組使用者介面控制元件，讓您可快速開發 TestStand 使用者介面。上述控制元件包含用於顯示 TestStand 資料的可見控制元件，例如步驟檢視或變數檢視，並包含不可見的管理工具控制元件，與 TestStand 使用者介面的 TestStand 引擎 API 所進行的通訊作業，大多由這類控制元件處理。

開發獨立的 TestStand 應用時，NI 建議使用 UI 控制元件來開發應用，而非直接建立 TestStand 引擎的個體。

UI 控制元件 API 讓您可透過管理工具控制元件實作一般使用者介面作業，例如開啟與執行序列檔案、回應 UI 訊息與處理應用關閉作業等。UI 控制元件 API 也提供可用於設定 UI 控制元件的連結方法。 

如需進一步了解使用者介面控制元件與 UI 控制元件 API 的使用資訊，請參閱下列說明主題：

• TestStand UI 控制元件 – 概述使用 UI 控制元件開發 TestStand 使用者介面應用。
• TestStand UI 控制元件 API 參考說明 – UI 控制元件 API 的類別參考資訊。
• 開發使用者介面的最佳做法 – 使用 UI 控制元件與 API 的最佳做法。

您可以將 TestStand UI 控制元件想像為在 TestStand 引擎 API 最上方的軟體層。這些控制元件囊括您在使用者介面內所需的眾多功能，例如開啟序列、執行測試、顯示測試進度等等。TestStand UI 控制元件具有豐富功能，並擁有各自的 API。雖然本文件的範圍並未涵蓋說明使用者介面控制元件的功能，不過請留意這些控制元件提供的功能都是以 TestStand 引擎 API 為基礎。

轉接器 API

轉接器 API 可對 TestStand 中包含的不同轉接器提供特定類別。一般而言，在核心 API 中使用轉接器或模組類別時，您可針對轉接器專屬資訊或功能使用轉接器 API。在此情況下，會將物件的類型轉換為適當的轉接器 API 類別。例如，您可使用 LabVIEWModule 類別，針對 LabVIEW 步驟內的模組物件，存取 LabVIEW 專屬屬性與方法。

使用轉接器 API 可存取模組或轉接器類別的轉接器專屬屬性與方法

請參閱 TestStand 轉接器 API 參考，以取得轉接器 API 所提供的類別清單

同步化伺服器 API

同步化伺服器 API 可供直接存取 TestStand 同步化物件，例如佇列、鎖定或通知。若要使用此 API，首先須使用 Engine.GetSyncManager 方法，取得對同步化管理工具的參照。將此物件傳播至同步化伺服器 API 定義的同步化管理工具類別後，就可用其存取或建立新的同步化物件。

使用 SyncManager 與同步化伺服器 API 以建立與存取程式碼中的 TestStand 同步化物件

若開發的應用會與 TestStand 測試一起執行，並需要存取狀態監控應用等執行狀態的相關資訊，那麼此 API 可以派上用場。

如需進一步了解可用的類別，請參閱同步化伺服器 API 參考主題。

按一下即可檢視 TestStand 進階架構系列內的其他文件，其中涵蓋了進階 NI TestStand 開發人員會感興趣的主題。