Návod – Vytvoření komponenty jazyka C# s ovládacími prvky WinUI 3 a jeho využití z aplikace C++/WinRT, která používá Windows App SDK

C#/WinRT poskytuje podporu pro vytváření komponent prostředí Windows Runtime, včetně vlastních typů WinUI a vlastních ovládacích prvků. Tyto komponenty je možné využívat z aplikací C# nebo C++/WinRT, které používají Windows App SDK. K vytváření komponent modulu runtime s podporou balíčků NuGet doporučujeme použít C#/WinRT verze 1.6.4 nebo novější.

Další podrobnosti o podporovaných scénářích najdete v Tvorba komponent C#/WinRT v úložišti GitHub pro C#/WinRT.

Tento názorný postup ukazuje, jak vytvořit komponentu jazyka C# pomocí vlastního ovládacího prvku WinUI a jak tuto komponentu využívat z aplikace C++/WinRT pomocí šablon projektu Windows App SDK.

Požadavky

Tento názorný postup vyžaduje následující nástroje a komponenty:

• Visual Studio 2022 nebo novější
• .NET 8.0 SDK (LTS) nebo novější
• Windows App SDK VSIX (1.1 ze stabilního kanálu)

Vytvoření komponenty C#/WinRT pomocí Windows App SDK

1. Vytvořte nový projekt knihovny C# pomocí šablony Class Library (WinUI in Desktop) šablony poskytované Windows App SDK. Pro účely tohoto názorného postupu jsme pojmenovali knihovnu project WinUIComponentCs a řešení AuthoringWinUI.

   Nechejte nezaškrtnuté políčko Place solution a projekt ve stejném adresáři (jinak složka packages pro aplikaci C++ v předchozí části bude zasahovat do projektu knihovny jazyka C#).

   Dialog nové knihovny

2. Class1.cs Odstraňte soubor, který je ve výchozím nastavení zahrnutý.

3. Nainstalujte nejnovější Microsoft.Windows. CsWinRT balíček NuGet ve vašem projektu.

   i. v Průzkumník řešení klikněte pravým tlačítkem myši na projektový uzel a vyberte Spravovat balíčky NuGet.

   ii. Vyhledejte Microsoft.Windows. CsWinRT balíček NuGet a nainstalujte nejnovější verzi.

4. Do project knihovny přidejte následující vlastnosti:

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

   • Vlastnost CsWinRTComponent určuje, že projekt je komponenta prostředí Windows Runtime, aby se při sestavování projektu vygeneroval soubor .winmd.

5. Přidejte do knihovny vlastní ovládací prvek nebo uživatelský ovládací prvek. Uděláte to tak, že kliknete pravým tlačítkem myši na projekt v Visual Studio, kliknete na Přidat>Nová položka a v levém podokně vyberete WinUI. Pro účely tohoto názorného postupu jsme přidali nový uživatelský ovládací prvek (WinUI) a pojmenovali ho NameReporter.xaml. Uživatelský ovládací prvek NameReporter umožňuje uživateli zadat jméno a příjmení do příslušného ovládacího prvku TextBox a kliknout na tlačítko. Ovládací prvek pak zobrazí pole se zprávou s názvem, které uživatel zadal.

6. Do souboru vložte následující kód NameReporter.xaml :

   <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. Do NameReporter.xaml.cspřidejte následující metodu:

   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. Teď můžete sestavit WinUIComponentCs project a vygenerovat pro komponentu soubor .winmd.

Poznámka:

Komponentu můžete také zabalit jako balíček NuGet pro koncové uživatele aplikací, na které se mohou odkazovat. Další podrobnosti najdete v tématu Tvorba komponent C#/WinRT v úložišti C#/WinRT GitHub.

Odkaz na komponentu z aplikace Windows App SDK C++/WinRT

Následující kroky ukazují, jak využívat komponentu vytvořenou z předchozí části z aplikace Windows App SDK C++/WinRT. Používání komponenty C#/WinRT z C++ v současné době vyžaduje použití šablony Prázdná aplikace WinUI s jedním projektem (zabalená). Všimněte si, že na komponenty jazyka C# lze odkazovat také z zabalených aplikací jazyka C# bez registrace tříd.

Spotřeba z zabalených aplikací, které používají samostatný projekt Windows Application Packaging (WAP) se v současné době nepodporuje. Podívejte se na Authoring C#/WinRT components v GitHubovém úložišti C#/WinRT pro nejnovější aktualizace o podporovaných konfiguracích projektů.

1. Přidejte do svého řešení nový projekt aplikace Windows App SDK C++. V Visual Studio klikněte pravým tlačítkem na řešení a vyberte Přidat>Nový Project. Vyberte šablonu Prázdná aplikace WinUI v jazyce C++ (zabalená) poskytovanou Windows App SDK. Pro účely tohoto názorného postupu jsme pojmenovali aplikaci CppApp.

2. Přidejte project odkaz z aplikace C++ do komponenty C#. V Visual Studio klikněte pravým tlačítkem na projekt C++ a zvolte Add>Reference a vyberte projekt WinUIComponentCs.

   Poznámka:

   Použití komponent jako odkazu na balíček NuGet je podporováno s určitými omezeními. Komponenty s vlastními uživatelskými ovládacími prvky se v současné době nedají využívat jako odkaz na balíček NuGet.

3. Do souboru záhlaví aplikace pch.h přidejte následující řádky:

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

4. Otevřete soubor manifestu balíčku. Package.appxmanifest

   Poznámka:

   Existuje známý problém, kdy se v Visual Studio Průzkumník řešení nezobrazí soubor Package.appxmanifest. Pokud chcete tento problém obejít, klikněte pravým tlačítkem na project C++, vyberte Unload Project a poklikáním na project otevřete soubor CppApp.vcxproj. Do souboru projektu přidejte následující položku a pak znovu načtěte projekt.

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

   Do Package.appxmanifestpole přidejte následující aktivovatelné registrace tříd. K aktivaci typů WinUI budete také potřebovat další ActivatableClass položku pro třídu WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider . Klikněte pravým tlačítkem myši na Package.appxmanifest soubor a vyberte Otevřít v>XML (Textový editor) a upravte soubor.

   <!--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. Otevřete soubor MainWindow.xaml.

   i. Přidejte odkaz na obor názvů komponenty v horní části souboru.

   xmlns:custom="using:WinUIComponentCs"
   

   ii. Přidejte uživatelský ovládací prvek do existujícího kódu XAML.

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

6. Nastavte CppApp jako spouštěcí project – klikněte pravým tlačítkem na CppApp a vyberte Set jako spouštěcí Project. Nastavte konfiguraci řešení na x86. Před sestavením možná budete muset své řešení přesměrovat, aby se sestavovalo pomocí nástrojů pro sestavení Visual Studio 2026. Klikněte pravým tlačítkem na řešení, vyberte Řešení Retarget a upgradujte sadu nástrojů platformy na verzi 143.

7. Sestavte a spusťte aplikaci pro zobrazení vlastního ovládacího prvku NameReporter.

Známé problémy

• Použití komponenty C# jako odkazu na projekt vyžaduje, aby PublishReadyToRun byla nastavena na False. Další podrobnosti najdete v GitHub Issue #1151.
• Používání komponenty jazyka C# vytvořené pro AnyCPU z aplikací v jazyce C++ je v současné době podporováno pouze z aplikací x86. x64 a Arm64 aplikace způsobí chybu za běhu podobnou této: %1 není platná aplikace Win32. Další podrobnosti najdete v tématu GitHub Issue č. 1093.

Související témata

• C#/WinRT Authoring Ukázková aplikace
• Tvorba komponentů C#/WinRT
• Hostování řízených komponent