Udostępnij przez

Przewodnik — tworzenie składnika języka C# za pomocą kontrolek WinUI 3 i używanie go z poziomu aplikacji C++/WinRT korzystającej z zestawu SDK aplikacji systemu Windows

Język C#/WinRT zapewnia obsługę tworzenia składników środowiska uruchomieniowego systemu Windows, w tym niestandardowych typów WinUI i kontrolek niestandardowych. Te składniki mogą być używane z poziomu aplikacji C# lub C++/WinRT korzystających z zestawu SDK aplikacji systemu Windows. Zalecamy używanie języka C#/WinRT w wersji 1.6.4 lub nowszej do tworzenia składników środowiska uruchomieniowego z obsługą pakietów NuGet.

Aby uzyskać więcej informacji na temat obsługiwanych scenariuszy, zobacz Tworzenie składników języka C#/WinRT w repozytorium GitHub języka C#/WinRT.

W tym przewodniku pokazano, jak utworzyć składnik języka C# z niestandardową kontrolką WinUI 3 oraz jak korzystać z tego składnika z poziomu aplikacji C++/WinRT przy użyciu szablonów projektów zestawu SDK aplikacji systemu Windows.

Wymagania wstępne

Ten przewodnik wymaga następujących narzędzi i składników:

Tworzenie składnika C#/WinRT przy użyciu zestawu SDK aplikacji systemu Windows

  1. Utwórz nowy projekt biblioteki języka C# przy użyciu szablonu Biblioteka klas (WinUI 3 w programie Desktop) udostępnianym przez zestaw SDK aplikacji systemu Windows. W tym przewodniku nazwaliśmy projekt biblioteki WinUIComponentCs, a rozwiązanie AuthoringWinUI.

    Pozostaw niezaznaczone pole Umieść rozwiązanie i projekt w tym samym katalogu (w przeciwnym razie folder packages dla aplikacji języka C++ w poprzedniej sekcji będzie powodować interferencję z projektem biblioteki języka C#).

    okno dialogowe Nowa biblioteka

  2. Class1.cs Usuń plik dołączony domyślnie.

  3. Zainstaluj najnowszą Pakiet NuGet Microsoft.Windows.CsWinRT w projekcie.

    punkt i. W Eksploratorze rozwiązań kliknij prawym przyciskiem myszy węzeł projektu i wybierz pozycję Zarządzaj pakietami NuGet.

    ii. Wyszukaj pakiet NuGet Microsoft.Windows.CsWinRT i zainstaluj najnowszą wersję.

  4. Dodaj następujące właściwości do projektu biblioteki:

    <PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
    • Właściwość CsWinRTComponent określa, że projekt jest składnikiem środowiska uruchomieniowego systemu Windows, tak aby .winmd plik był generowany podczas kompilatora projektu.

  5. Dodaj kontrolkę niestandardową lub kontrolkę użytkownika do biblioteki. Aby to zrobić, kliknij prawym przyciskiem myszy projekt w programie Visual Studio, kliknij Dodaj>Nowy elementi wybierz pozycję WinUI w okienku po lewej stronie. W tym przewodniku dodaliśmy nową kontrolkę użytkownika (WinUI 3) i nazwaliśmy ją NameReporter.xaml. Kontrolka użytkownika NameReporter umożliwia użytkownikowi wprowadzenie imienia i nazwiska do odpowiedniej kontrolki TextBox oraz kliknięcie przycisku. Kontrolka wyświetla następnie pole komunikatu o nazwie wprowadzonej przez użytkownika.

  6. Wklej następujący kod w NameReporter.xaml pliku:

    <UserControl
x:Class="WinUIComponentCs.NameReporter"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:WinUIComponentCs"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d">

    <StackPanel HorizontalAlignment="Center">
        <StackPanel.Resources>
            <Style x:Key="BasicTextStyle" TargetType="TextBlock" BasedOn="{StaticResource BodyTextBlockStyle}">
                <Setter Property="Margin" Value="10,10,10,10"/>
            </Style>
        </StackPanel.Resources>

        <TextBlock Text="Enter your name." Margin="0,0,0,10"/>
        <StackPanel Orientation="Horizontal" Margin="0,0,0,10">
            <TextBlock Style="{StaticResource BasicTextStyle}">
                First Name:
            </TextBlock>
            <TextBox Name="firstName" />
        </StackPanel>
        <StackPanel Orientation="Horizontal" Margin="0,0,0,10">
            <TextBlock Style="{StaticResource BasicTextStyle}">
                Last Name:
            </TextBlock>
            <TextBox Name="lastName" />
        </StackPanel>
        <Button Content="Submit" Click="Button_Click" Margin="0,0,0,10"/>
        <TextBlock Name="result" Style="{StaticResource BasicTextStyle}" Margin="0,0,0,10"/>
    </StackPanel>
</UserControl>

  7. Dodaj następującą metodę do NameReporter.xaml.cs:

    using System.Text;
...
private void Button_Click(object sender, RoutedEventArgs e)
{
    StringBuilder displayText = new StringBuilder("Hello, ");
    displayText.AppendFormat("{0} {1}.", firstName.Text, lastName.Text);
    result.Text = displayText.ToString();
}

  8. Teraz możesz skompilować projekt WinUIComponentCs , aby wygenerować .winmd plik dla składnika.

Uwaga / Notatka

Możesz również spakować składnik jako pakiet NuGet, aby użytkownicy aplikacji końcowych mogli się odwołać. Aby uzyskać więcej informacji, zobacz Authoring C#/WinRT components w repozytorium GitHub C#/WinRT.

Odwołanie do składnika z aplikacji C++/WinRT w zestawie Windows App SDK

Poniższe kroki pokazują, jak używać składnika utworzonego w poprzedniej sekcji w aplikacji zestawu SDK Systemu Windows C++/WinRT. Korzystanie ze składnika C#/WinRT z języka C++ obecnie wymaga użycia szablonu pustej aplikacji jednoproduktowej, pakowanej (WinUI 3 na komputerze stacjonarnym). Należy pamiętać, że do składników języka C# można również odwoływać się z aplikacji spakowanych w języku C# bez rejestracji klas.

Korzystanie z aplikacji spakowanych, które używają osobnego projektu Windows Application Packaging (WAP), nie jest obecnie obsługiwane. Zobacz Tworzenie składników języka C#/WinRT w repozytorium GitHub języka C#/WinRT, aby uzyskać najnowsze aktualizacje dotyczące obsługiwanych konfiguracji projektu.

  1. Dodaj nowy projekt aplikacji zestawu WINDOWS App SDK języka C++ do rozwiązania. Kliknij prawym przyciskiem myszy rozwiązanie w programie Visual Studio, a następnie wybierz pozycję Dodaj>nowy projekt. Wybierz szablon C++ Pusta aplikacja, spakowana (WinUI 3 na komputery stacjonarne) udostępniony przez Windows App SDK. W tym przewodniku nazwaliśmy aplikację CppApp.

  2. Dodaj odwołanie do projektu z aplikacji C++ do składnika C#. W programie Visual Studio kliknij prawym przyciskiem myszy projekt C++, a następnie wybierz Dodaj>Odnośnik, a potem projekt WinUIComponentCs.

    Uwaga / Notatka

    Korzystanie ze składników jako referencji pakietu NuGet jest obsługiwane z pewnymi ograniczeniami. Mianowicie składniki z niestandardowymi kontrolkami użytkownika nie mogą być obecnie używane jako odwołanie do pakietu NuGet.

  3. W pliku nagłówkowym pch.h aplikacji dodaj następujące wiersze:

    #include <winrt/WinUIComponentCs.h>
#include <winrt/WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.h>

  4. Otwórz plik manifestu pakietu, Package.appxmanifest.

    Uwaga / Notatka

    Istnieje znany problem polegający na tym, że Package.appxmanifest plik nie jest wyświetlany w Eksploratorze rozwiązań programu Visual Studio. Aby obejść ten problem, kliknij prawym przyciskiem myszy na projekt C++, wybierz opcję Rozładuj projekt, a następnie kliknij dwukrotnie, aby otworzyć plik CppApp.vcxproj. Dodaj następujący wpis do pliku projektu, a następnie załaduj ponownie projekt:

    <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
    <SubType>Designer</SubType>
    </AppxManifest>
</ItemGroup>

    Wprowadź następujące rejestracje klas możliwych do aktywacji w Package.appxmanifest. Aby aktywować typy WinUI, potrzebny będzie również dodatkowy wpis dla klasy WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider. Kliknij plik prawym przyciskiem myszy Package.appxmanifest i wybierz polecenie Otwórz za pomocą>kodu XML (Edytor tekstów), aby edytować plik.

    <!--In order to host the C# component from C++, you must add the following Extension group and list the activatable classes-->
<Extensions>
    <Extension Category="windows.activatableClass.inProcessServer">
        <InProcessServer>
            <Path>WinRT.Host.dll</Path>
            <ActivatableClass ActivatableClassId="WinUIComponentCs.NameReporter" ThreadingModel="both" />
            <ActivatableClass ActivatableClassId="WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider" ThreadingModel="both" />
        </InProcessServer>
    </Extension>
</Extensions>

  5. Otwórz plik MainWindow.xaml.

    punkt i. Dodaj odwołanie do przestrzeni nazw składnika w górnej części pliku.

    xmlns:custom="using:WinUIComponentCs"

    ii. Dodaj kontrolkę użytkownika do istniejącego kodu XAML.

    <StackPanel>
    ...
    <custom:NameReporter/>
</StackPanel>

  6. Ustaw aplikację CppApp jako projekt startowy — kliknij prawym przyciskiem myszy pozycję CppApp, a następnie wybierz pozycję Ustaw jako projekt startowy. Ustaw konfigurację rozwiązania na x86. Przed kompilacją może być również konieczne dostosowanie docelowej wersji rozwiązania do narzędzi kompilacji programu Visual Studio 2022. Kliknij rozwiązanie prawym przyciskiem myszy, wybierz rozwiązanie Retargeti uaktualnij zestaw narzędzi platformy do v143.

  7. Skompiluj i uruchom aplikację, aby zobaczyć niestandardową kontrolkę NameReporter.

Znane problemy

  • Korzystanie ze składnika języka C# jako odwołania do projektu wymaga PublishReadyToRun ustawienia wartości False. Aby uzyskać więcej informacji, zobacz problem z usługą Github #1151.
  • Korzystanie ze składnika C# utworzonego na AnyCPU podstawie języka C++ jest obecnie obsługiwane tylko z x86 aplikacji. x64 i Arm64 aplikacje powodują błąd środowiska uruchomieniowego podobny do: %1 nie jest prawidłową aplikacją Win32. Aby uzyskać więcej informacji, zobacz Problem z usługą Github #1151 .
  • Last updated on