Windows Runtime C++ Template Library (WRL)

Windows 執行階段 C++ 範本庫 (WRL) 是提供低階方式撰寫和使用 Windows 執行階段元件的範本庫。

優點

WRL 讓您更輕鬆地實作和使用 Component Object Model (COM) 元件。 它提供環境維護技術，如參考計數來管理物件的存留期，以及測試 HRESULT 值來判斷作業成功或失敗。 為了順利使用 WRL，您必須小心遵循這些規則和技術。

Visual C++ 元件擴充功能 (C++/CX) 是透過高階、以語言為基礎的方式使用 Windows 執行階段元件。 WRL 和 C++/CX 透過自動代表您執行環境維護工作，簡化 Windows 執行階段程式碼撰寫。

WRL 和 C++/CX 提供不同的優點。 建議使用 WRL 而不是 C++/CX，原因如下：

• WRL 在 Windows 執行階段應用程式二進位介面 (ABI) 上沒有加入太多抽象性，讓您可以控制基礎程式碼，更有效建立或使用 Windows 執行階段應用程式開發介面。

• C++/CX 是以例外狀況代表 COM HRESULT 值。 如果您繼承了使用 COM 或沒有使用例外狀況的程式碼基底，您可能會發現 WRL 是與 Windows 執行階段一起使用比較自然的方式，因為您不需要使用例外狀況。

  注意事項
  WRL 使用 HRESULT 值，且不會擲回例外狀況。此外，WRL 使用智慧型指標和 RAII 模式，確保在您的應用程式程式碼擲回例外狀況時物件正確被終結。如需智慧型指標和 RAII 的詳細資訊，請參閱智慧型指標 (現代 C++) 和物件擁有資源 (RAII)。

• WRL 的用途和設計受到 Active Template Library (ATL) 所啟發，這是一組簡化 COM 物件程式設計的範本架構 C++ 類別。 由於 WRL 使用 Standard C++ 包裝 Windows 執行階段，您可以更容易地將以 ATL 撰寫的許多現有 COM 元件移植至 Windows 執行階段並與之互動。 如果您已經知道 ATL，您可能會發現 WRL 程式設計更容易。

快速入門

以下是可幫助您立即開始使用 WRL 的一些資源。

• Windows 執行階段程式庫 (WRL)
  在這個 Channel 9 影片，進一步了解 WRL 如何協助您撰寫 Windows 市集應用程式，以及如何撰寫和使用 Windows 執行階段元件。

• 如何：利用 WRL 啟動與使用 Windows 執行階段元件
  顯示如何使用 WRL 初始化 Windows 執行階段，以及啟用和使用 Windows 執行階段元件。

• 如何：使用 WRL 完成非同步作業
  顯示如何使用 WRL，當作業完成時啟動非同步作業和執行工作。

• 如何：使用 WRL 處理事件
  顯示如何使用 WRL 來訂閱和處理 Windows 執行階段物件的事件。

• 逐步解說：使用 WRL 建立基本 Windows 執行階段元件
  顯示如何使用 WRL 建立將兩個數字相加的基本 Windows 執行階段元件。 文件中也會示範如何從使用 JavaScript 的 Windows 市集應用程式引發事件及使用元件。

• 逐步解說：使用 WRL 和媒體基礎建立 Windows 市集應用程式
  學習如何建立使用 Microsoft 媒體基礎的 Windows 市集應用程式。

• 如何：使用 WRL 建立傳統 COM 元件
  顯示如何使用 WRL 建立基本的 COM 元件，以及註冊和使用桌面應用程式 COM 元件的基本方法。

• 如何：直接執行個體化 WRL 元件
  了解如何使用 Microsoft::WRL::Make 和 Microsoft::WRL::Details::MakeAndInitialize 函式，從定義元件的模組中具現化元件。

• 如何：使用 winmdidl.exe 和 midlrt.exe 根據 Windows 中繼資料建立 .h 檔案
  顯示如何透過從 .winmd 中繼資料建立 IDL 檔案，使用 WRL 的自訂 Windows 執行階段元件。

• 逐步解說：使用工作和 XML HTTP 要求連線
  說明如何在 Windows 市集應用程式中使用 IXMLHTTPRequest2 和 IXMLHTTPRequest2Callback 介面，以及將 HTTP GET 和 POST 要求傳送至 Web 服務的工作。

• Bing 地圖服務路線最佳化程式範例
  在完整 Windows 市集應用程式的內容中，使用定義在逐步解說：使用工作和 XML HTTP 要求連線中的 HttpRequest 類別。

• 使用 C++ 範例建立 Windows 執行階段 DLL 元件
  顯示如何使用 WRL 建立同處理序 DLL 元件，以及從 C++/CX、JavaScript 和 C# 使用它。

• DirectX 彈珠迷宮遊戲範例
  示範如何在完整 3D 遊戲的內容中使用 WRL 管理 COM 元件的存留期，如 DirectX 和媒體基礎。

• 從桌面應用程式範例傳送快顯通知
  示範如何使用 WRL 以處理來自桌面應用程式的快顯通知。

WRL 和 ATL 比較

WRL 類似 Active Template Library (ATL)，因為您可以用它來建立小型、快速的 COM 物件。 WRL 和 ATL 也共用概念，例如在模組中定義物件、明確註冊介面，以及使用 Factory 開放式建立物件。 如果您熟悉 ATL，可能對 WRL 立即上手。

WRL 支援 Windows 市集應用程式所需的 COM 功能。 因此，它與 ATL 不同，因為後者省略直接支援 COM 功能，例如：

• 彙總

• 內建實作

• 雙重介面 (IDispatch)

• 標準列舉程式介面

• 連接點

• Tear-Off 介面

• OLE 內嵌

• ActiveX 控制項

• COM+

概念

WRL 提供代表某些基本概念的類型。 下列章節將說明這些類型：

ComPtr

ComPtr 是智慧型指標類型，表示由範本參數指定之介面。 使用 ComPtr 來宣告變數，以存取從介面衍生之物件的成員。 ComPtr 自動維護基礎介面指標的參考計數，並在參考計數歸零時釋放介面。

RuntimeClass

RuntimeClass 表示繼承一組指定之介面的具現化類別。 RuntimeClass 物件可提供一個或多個 Windows 執行階段 COM 介面的支援組合，或提供元件的弱式參考。

Module

Module 表示相關物件的集合。 Module 物件管理 Class Factory 和註冊，前者會建立物件，後者讓其他應用程式使用物件。

回呼

Callback 函式建立成員函式是事件處理常式的物件 (回呼方法)。 使用 Callback 函式撰寫非同步作業。

EventSource

EventSource 用來管理「委派」(Delegate) 事件處理常式。 使用 WRL 實作委派，而使用 EventSource 加入、移除及叫用委派。

AsyncBase

AsyncBase 提供代表 Windows 執行階段非同步程式撰寫模型的虛擬方法。 覆寫這個類別中的成員，建立可以啟動、停止或檢查非同步作業進度的自訂類別。

FtmBase

FtmBase 代表無限制執行緒封送處理器物件。 FtmBase 建立全域介面表 (GIT)，並協助管理封送處理和 Proxy 物件。

WeakRef

WeakRef 是代表弱式參考的智慧型指標類型，會參考不一定可存取的物件。 WeakRef 物件只能供 Windows 執行階段使用，不可供傳統 COM 使用。

WeakRef 物件通常代表其存在是由外部執行緒或應用程式所控制的物件。 例如，WeakRef 物件可以參考檔案物件。 在檔案開啟時，WeakRef 有效，而且參考的檔案是可存取的。 不過，在檔案關閉時，WeakRef 是無效，而且檔案無法存取。

相關主題

WRL 類別庫專案範本	說明如何存取 WRL 類別庫專案範本。 這個範本可協助簡化使用 Visual Studio 建立 Windows 執行階段元件之工作。
依分類區分的重要 WRL 應用程式開發介面	強調主要 WRL 類型、函式和巨集。
WRL 參考	包含 WRL 的參考資訊。
快速參考 (Windows 執行階段和 Visual C++)	簡要說明支援 Windows 執行階段的 C++/CX 功能。
在 Visual C++ 中使用 Windows 執行階段元件	說明如何使用 C++/CX 以建立基本 Windows 執行階段元件。