共用方式為


逐步解說—建立 C#/WinRT 元件並從 C++/WinRT 中加以取用

C#/WinRT 可讓使用 .NET 的開發人員透過類別庫專案,在 C# 中撰寫自己的 Windows 執行階段元件。 所撰寫的元件可於原生 Windows 傳統型應用程式中,以套件參考的形式或以專案參考 (需稍作修改) 的形式加以取用。

本逐步解說會示範如何使用 C#/WinRT 建立簡單的 Windows 執行階段元件、以 NuGet 套件的形式散發元件,以及從 C++/WinRT 主控台應用程式中取用元件。 如需可提供本文適用程式碼的完整範例,請參閱 C#/WinRT 撰寫範例。 如需如何進行撰寫的詳細資訊,請參閱撰寫元件

如需如何使用 C#/WinRT 撰寫 WinUI 控制項以特別用於 Windows 應用程式 SDK 應用程式的逐步解說,請參閱逐步解說:使用 WinUI 3 控制項撰寫 C# 元件並從 C++ Windows 應用程式 SDK 應用程式加以取用一文

必要條件

本逐步解說需要使用下列工具和元件:

使用 C#/WinRT 建立簡單的 Windows 執行階段元件

請先在 Visual Studio 中建立新專案。 選取 [類別庫] 專案範本,並將專案命名為 AuthoringDemo。 您必須對專案進行下列新增和修改:

  1. 更新 AuthoringDemo.csproj 檔案中的 TargetFramework,並將下列元素新增至 PropertyGroup

    <PropertyGroup>
        <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
        <Platforms>x64</Platforms>
    </PropertyGroup>
    

    若要存取 Windows 執行階段類型,您必須在 TFM 中設定特定的 Windows SDK 版本。 如需所支援版本的詳細資訊,請參閱 .NET 6 和更新版本:使用 TFM 選項

  2. Microsoft.Windows.CsWinRT NuGet 套件安裝到您的專案中。

    a. 在 [方案總管] 中,以滑鼠右鍵按一下專案節點,然後選取 [管理 NuGet 套件]

    b. 搜尋 Microsoft.Windows.CsWinRT NuGet 套件,並安裝最新版本。 本逐步解說使用 C#/WinRT 1.4.1 版。

  3. 新增可設定 CsWinRTComponent 屬性的 PropertyGroup 元素。 這會指定您的專案是 Windows 執行階段元件,而在您建置專案時產生 .winmd 檔案。

    <PropertyGroup>   
        <CsWinRTComponent>true</CsWinRTComponent>
    </PropertyGroup>
    

    如需 C#/WinRT 專案屬性的完整清單,請參閱 C#/WinRT NuGet 文件

  4. 您可以使用程式庫 .cs 類別檔案來撰寫執行階段類別。 以滑鼠右鍵按一下 Class1.cs 檔案,並將其重新命名為 Example.cs。 將下列程式碼新增至這個檔案,以將公用屬性和方法新增至執行階段類別。 請記得將您想要在執行階段元件中公開的任何類別標示為 public

    namespace AuthoringDemo
    {
        public sealed class Example
        {
            public int SampleProperty { get; set; }
    
            public static string SayHello()
            {
                return "Hello from your C# WinRT component";
            }
        }
    }
    
  5. 您現在可以建置專案以便為您的元件產生 .winmd 檔案。 在 [方案總管] 中以滑鼠右鍵按一下該專案,然後按一下 [建置]。 您便會在建置輸出檔案夾中看到所產生的 AuthoringDemo.winmd 檔案。

產生元件的 NuGet 套件

大多數開發人員會想要以 NuGet 套件的形式散發和共用其 Windows 執行階段元件。 另一個選項是以專案參考的形式取用元件。 下列步驟示範如何封裝 AuthoringDemo 元件。 當您產生套件時,C#/WinRT 會設定套件中的元件和裝載組件,以啟用從原生應用程式取用的功能。

有數種方式可以產生 NuGet 套件:

  • 如果您想要在每次建置專案時產生 NuGet 套件,請將下列屬性新增至 AuthoringDemo 專案檔,然後重建專案。

    <PropertyGroup>
        <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    </PropertyGroup>
    
  • 或者,您也可以在 [方案總管] 中以滑鼠右鍵按一下 [AuthoringDemo] 專案,然後選取 [封裝],以產生 NuGet 套件。

在建置套件時,[建置] 視窗應該會指出系統已成功建立 NuGet 套件 AuthoringDemo.1.0.0.nupkg。 如需使用 .NET CLI 時的 NuGet 套件屬性詳細資訊,請參閱使用 dotnet CLI 建立套件

從 C++/WinRT 應用程式中取用元件

以 C#/WinRT 撰寫的 Windows 執行階段元件可從任何與 Windows 執行階段 (WinRT) 相容的語言加以取用。 下列步驟示範如何在 C++/WinRT 主控台應用程式中呼叫上面所撰寫的元件。

注意

套件參考或專案參考都支援從 C#/.NET 應用程式取用 C#/WinRT 元件。 此案例相當於取用任何一般 C# 類別庫,而且在大部分情況下不會牽涉到 WinRT 的啟用。 從 C#/WinRT 1.3.5 開始,C# 取用者的專案參考需要使用 .NET 6。

  1. 將新的 C++/WinRT 主控台應用程式專案新增至您的解決方案。 請注意,如果您想要的話,此專案也可以成為不同解決方案的一部分。

    a. 在 [方案總管] 中,以滑鼠右鍵按一下您的解決方案節點,然後按一下 [新增] ->[新增專案]

    b. 在 [新增專案] 對話方塊中,搜尋 C++/WinRT 主控台應用程式專案範本。 選取範本,然後按 [下一步]

    c. 將新專案命名為 CppConsoleApp,然後按一下 [建立]

  2. 將 AuthoringDemo 元件的參考新增為 NuGet 套件或專案參考。

    • 選項 1 (套件參考)

      a. 以滑鼠右鍵按一下 [CppConsoleApp] 專案,然後選取 [管理 NuGet 套件]。 您可能需要設定套件來源,以新增 AuthoringDemo NuGet 套件的參考。 若要這樣做,請按一下 NuGet 套件管理員中的 [設定] 圖示,並將套件來源新增至適當路徑。

      NuGet 設定

      b. 在設定套件來源後,請搜尋 AuthoringDemo 套件,然後按一下 [安裝]

      安裝 NuGet 套件

    • 選項 2 (專案參考)

      a. 以滑鼠右鍵按一下 [CppConsoleApp] 專案,然後選取 [新增] -> [參考]。 在 [專案] 節點下,新增 AuthoringDemo 專案的參考。

  3. 若要裝載元件,您必須新增適用於可啟用類別註冊的資訊清單檔案。 如需受控元件裝載的詳細資訊,請參閱受控元件裝載

    a. 若要新增資訊清單檔案,請再次以滑鼠右鍵按一下專案,然後選擇 [新增] -> [新增項目]。 搜尋文字檔範本,並將其命名為 CppConsoleApp.exe.manifest。 貼上下列內容,以使用可啟用類別註冊項目指定執行階段類別:

    <?xml version="1.0" encoding="utf-8"?>
    <assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
        <assemblyIdentity version="1.0.0.0" name="CppConsoleApp"/>
        <file name="WinRT.Host.dll">
            <activatableClass
                name="AuthoringDemo.Example"
                threadingModel="both"
                xmlns="urn:schemas-microsoft-com:winrt.v1" />
        </file>
    </assembly>
    

    未封裝的應用程式需要使用應用程式資訊清單檔案。 若為已封裝的應用程式,則應用程式取用者必須在其 Package.appxmanifest 套件資訊清單檔案中註冊可啟用類別,如逐步解說:使用 WinUI 3 控制項建立 C# 元件並從 C++ Windows 應用程式 SDK 應用程式加以取用中所述。

    b. 修改專案,以在部署專案時將資訊清單檔案納入輸出中。 按一下 [方案總管] 中的 [CppConsoleApp.exe.manifest] 檔案,並將 [內容] 屬性設定為 [True]。 以下是其外觀的範例。

    部署內容

  4. 在專案的 [標頭檔] 底下開啟 pch.h,並新增下面這行程式碼以包含您的元件。

    #include <winrt/AuthoringDemo.h>
    
  5. 在專案的 [原始程式檔] 底下開啟 main.cpp,並使用下列內容加以取代。

    #include "pch.h"
    #include "iostream"
    
    using namespace winrt;
    using namespace Windows::Foundation;
    
    int main()
    {
        init_apartment();
    
        AuthoringDemo::Example ex;
        ex.SampleProperty(42);
        std::wcout << ex.SampleProperty() << std::endl;
        std::wcout << ex.SayHello().c_str() << std::endl;
    }
    
  6. 建置並執行 CppConsoleApp 專案。 您現在應該會看到下列輸出。

    C++/WinRT 控制台輸出