演练 - 创建 C#/WinRT 组件,并从 C++/WinRT 使用它

C#/WinRT 使使用 .NET 5 或更高版本的开发人员能够使用类库项目在 C# 中创作自己的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. TargetFramework更新 AuthoringDemo.csproj 文件中的以下元素并将其PropertyGroup添加到:

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

    若要访问Windows 运行时类型,需要在 TFM 中设置特定的Windows SDK 版本。 有关受支持的版本的详细信息,请参阅 .NET 5 及更高版本:使用 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 包

大多数开发人员希望将其Windows 运行时组件作为NuGet包进行分发和共享。 另一个选项是使用组件作为项目引用。 以下步骤演示如何打包 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 应用使用组件

可以从任何Windows 运行时 (WinRT) 兼容的语言使用 C#/WinRT 创作的Windows 运行时组件。 以下步骤演示如何在 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 settings

      b. 配置包源后,搜索“AuthoringDemo”包并单击“安装”。

      Install NuGet package

    • 选项 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>
    

    非 MSIX 打包的应用需要应用程序清单文件。 对于 MSIX 打包的应用,应用使用者需要在其Package.appxmanifest包清单文件中注册可激活类,如演练:使用 WinUI 3 控件创建 C# 组件并从 C++ Windows应用 SDK 应用程序使用

    b. 修改项目以在部署项目时在输出中包含清单文件。 单击“解决方案资源管理器”中的“CppConsoleApp.exe.manifest”文件并将“Content”属性设置为“True”。 下面是该操作的一个示例。

    Deploy Content

  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 Console output