Windows 執行階段 C++ 範本庫 (WRL)

  • 文章

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

注意

WRL 現在已由 C++/WinRT 取代，這是Windows 執行階段 API 的標準 C++17 語言投影。 從 1803 版（10.0.17134.0）開始，Windows SDK 中提供 C++/WinRT。 C++/WinRT 完全實作于標頭檔中，並設計來為您提供新式 Windows API 的第一級存取權。

使用 C++/WinRT，您可以使用任何符合標準的 C++17 編譯器來取用和撰寫Windows 執行階段 API。 C++/WinRT 通常會執行得更好，而且會產生比Windows 執行階段任何其他語言選項更小的二進位檔。 我們將繼續支援 C++/CX 和 WRL，但強烈建議讓新的應用程式使用 C++/WinRT。 如需詳細資訊，請參閱 C++/WinRT。

優點

Windows 執行階段 C++ 樣板庫可讓您更輕鬆地實作和使用元件物件模型 （COM） 元件。 它提供管家技術，例如參考計數來管理物件的存留期，並測試 HRESULT 值，以判斷作業是否成功或失敗。 若要成功使用 Windows 執行階段 C++ 樣板庫，您必須仔細遵循這些規則和技術。

C++/CX 是使用Windows 執行階段元件的高階語言型方式。 Windows 執行階段 C++ 樣板庫和 C++/CX 都會代表您自動執行管家工作，簡化Windows 執行階段程式碼的撰寫。

Windows 執行階段 C++ 樣板庫和 C++/CX 提供不同的優點。 以下是您可能想要使用 Windows 執行階段 C++ 樣板庫而非 C++/CX 的一些原因：

  • Windows 執行階段 C++ 樣板庫在Windows 執行階段應用程式二進位介面 （ABI） 上新增了一些抽象概念，讓您能夠控制基礎程式碼，以更妥善地建立或取用Windows 執行階段 API。

  • C++/CX 會將 COM HRESULT 值表示為例外狀況。 如果您繼承了使用 COM 的程式碼基底，或不使用例外狀況的程式碼基底，您可能會發現Windows 執行階段 C++ 樣板庫是使用Windows 執行階段的更自然的方式，因為您不需要使用例外狀況。

    注意

    Windows 執行階段 C++ 樣板庫使用 HRESULT 值，而且不會擲回例外狀況。 此外，Windows 執行階段 C++ 樣板程式庫會使用智慧型指標和 RAII 模式，協助確保應用程式程式碼擲回例外狀況時，物件會正確終結。 如需智慧型指標和 RAII 的詳細資訊，請參閱 智慧型指標 和 物件擁有資源 （RAII）。

  • Windows 執行階段 C++ 樣板庫的用途和設計受到 Active Template Library （ATL） 的啟發，這是一組範本型 C++ 類別，可簡化 COM 物件的程式設計。 由於 Windows 執行階段 C++ 樣板程式庫會使用標準 C++ 來包裝Windows 執行階段，因此您可以更輕鬆地移植並與以 ATL 撰寫至Windows 執行階段的許多現有 COM 元件互動。 如果您已經知道 ATL，您可能會發現Windows 執行階段 C++ 樣板庫程式設計比較容易。

開始使用

以下是一些可協助您立即使用 Windows 執行階段 C++ 樣板庫的資源。

如何：啟動和使用Windows 執行階段元件
示範如何使用 Windows 執行階段 C++ 樣板庫來初始化Windows 執行階段並使用Windows 執行階段元件。

如何：完成非同步作業
示範如何使用 Windows 執行階段 C++ 樣板庫啟動非同步作業，並在作業完成時執行工作。

如何：處理事件
示範如何使用 Windows 執行階段 C++ 樣板庫來訂閱及處理Windows 執行階段物件的事件。

逐步解說： 使用 WRL 與媒體基礎建立 UWP 應用程式
瞭解如何建立使用 Microsoft Media Foundation 的 UWP 應用程式。

如何：建立傳統 COM 元件
示範如何使用 Windows 執行階段 C++ 樣板程式庫來建立基本 COM 元件，以及從傳統型應用程式註冊及取用 COM 元件的基本方式。

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

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

逐步解說：使用工作和 XML HTTP 要求連接
示範如何使用 IXMLHTTPRequest2 和 IXMLHTTPRequest2Callback 介面，以及將 HTTP GET 和 POST 要求傳送至 UWP 應用程式中 Web 服務的工作。

Bing 地圖車程優化器範例
HttpRequest使用逐步解說：在完整 UWP app 內容中使用工作和 XML HTTP 要求 連線 定義的類別。

使用 C++ 範例建立Windows 執行階段 DLL 元件
示範如何使用 Windows 執行階段 C++ 樣板庫來建立處理中的 DLL 元件，並從 C++/CX、JavaScript 和 C# 取用它。

DirectX 彈珠迷宮遊戲範例
示範如何在完整的 3D 遊戲內容中使用 Windows 執行階段 C++ 樣板程式庫來管理 COM 元件的存留期，例如 DirectX 和 Media Foundation。

來自傳統型應用程式的快顯通知
示範如何從傳統型應用程式傳送快顯通知。

與 ATL 比較Windows 執行階段 C++ 樣板庫

Windows 執行階段 C++ 樣板程式庫類似于使用中範本程式庫 （ATL），因為您可以使用它來建立小型快速的 COM 物件。 Windows 執行階段 C++ 樣板庫和 ATL 也共用概念，例如模組中的物件定義、介面的明確註冊，以及使用 Factory 開啟建立物件。 如果您熟悉 ATL，可能會熟悉Windows 執行階段 C++ 樣板程式庫。

Windows 執行階段 C++ 樣板庫支援 UWP 應用程式所需的 COM 功能。 因此，它與 ATL 不同，因為後者省略直接支援 COM 功能，例如：

  • 彙總

  • 內建實作

  • 雙重介面 (IDispatch)

  • 標準列舉程式介面

  • 連接點

  • Tear-Off 介面

  • OLE 內嵌

  • ActiveX 控制項

  • COM+

概念

Windows 執行階段 C++ 樣板程式庫提供代表一些基本概念的類型。 下列章節將說明這些類型：

ComPtr

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

RuntimeClass

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

模組

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

回撥

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

EventSource

EventSource 用來管理「 委派 」(Delegate) 事件處理常式。 使用 Windows 執行階段 C++ 樣板程式庫來實作委派，並使用 來新增、移除和叫用 EventSource 委派。

AsyncBase

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

FtmBase

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

WeakRef

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

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

依類別分類的主要 API
醒目提示 C++ 樣板庫類型、函式和宏的主要Windows 執行階段。

參考
包含Windows 執行階段 C++ 樣板庫的參考資訊。

快速參考 (C++/CX)
簡短描述支援Windows 執行階段的 C++/CX 功能。

在 Visual C++ 中使用Windows 執行階段元件
示範如何使用 C++/CX 來建立基本Windows 執行階段元件。