Dela via

Vara värd för en anpassad WinRT XAML-kontroll i en WPF-app med XAML Islands

Viktigt!

Det här avsnittet använder eller nämner typer från CommunityToolkit/Microsoft.Toolkit.Win32 GitHub-lagringsplats. Viktig information om stöd för XAML Islands finns i XAML Islands-meddelande i den lagringsplatsen.

Den här artikeln visar hur du använder WindowsXamlHost-kontrollen i Windows Community Toolkit som värd för en anpassad WinRT XAML-kontroll i en WPF-app som riktar sig mot .NET Core 3.1. Den anpassade kontrollen innehåller flera kontroller från första part från Windows SDK och binder en egenskap i en av WinRT XAML-kontrollerna till en sträng i WPF-appen. Den här artikeln visar också hur du även är värd för en kontroll från WinUI-biblioteket.

Även om den här artikeln visar hur du gör detta i en WPF-app är processen liknande för en Windows Forms-app. För en översikt över hur man värdar WinRT XAML-kontroller i WPF- och Windows Forms-appar, se den här artikeln.

Anmärkning

Användning av XAML-öar som värd för WinRT XAML-kontroller i WPF- och Windows Forms-appar stöds för närvarande endast i appar som riktar sig mot .NET Core 3.x. XAML-öarna stöds ännu inte i appar som riktar sig mot .NET eller i appar som har någon version av .NET Framework.

Nödvändiga komponenter

För att vara värd för en anpassad WinRT XAML-kontroll i en WPF-app (eller Windows Forms) behöver du följande komponenter i din lösning. Den här artikeln innehåller instruktioner för att skapa var och en av dessa komponenter.

  • Projektet och källkoden för din app. Att använda WindowsXamlHost--kontrollen för att vara värd för anpassade kontroller stöds endast i appar som riktar sig mot .NET Core 3.x.

  • Den anpassade WinRT XAML-kontrollen. Du behöver källkoden för den anpassade kontroll som du vill vara värd för så att du kan kompilera den med din app. Vanligtvis definieras den anpassade kontrollen i ett UWP-klassbiblioteksprojekt som du refererar till i samma lösning som ditt WPF- eller Windows Forms-projekt.

  • Ett UWP-appprojekt som definierar en rotprogramklass som härleds från XamlApplication. Ditt WPF- eller Windows Forms-projekt måste ha åtkomst till en instans av klassen Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication som tillhandahålls av Windows Community Toolkit så att den kan identifiera och läsa in anpassade UWP XAML-kontroller. Det rekommenderade sättet att göra detta är att definiera det här objektet i ett separat UWP-appprojekt som ingår i lösningen för din WPF- eller Windows Forms-app.

    Anmärkning

    Lösningen kan bara innehålla ett projekt som definierar ett XamlApplication objekt. Alla anpassade WinRT XAML-kontroller i din app delar samma XamlApplication objekt. Projektet som definierar XamlApplication objektet måste innehålla referenser till alla andra WinRT-bibliotek och projekt som används som värd för kontroller på XAML-ön.

Skapa ett WPF-projekt

Innan du börjar följer du de här anvisningarna för att skapa ett WPF-projekt och konfigurera det som värd för XAML-öar. Om du har ett befintligt WPF-projekt kan du anpassa de här stegen och kodexemplen för projektet.

Anmärkning

Om du har ett befintligt projekt som är avsett för .NET Framework måste du migrera projektet till .NET Core 3.1. Mer information finns i den här bloggserien.

  1. Om du inte redan har gjort det installerar du den senaste versionen av .NET Core 3.1 SDK.

  2. I Visual Studio 2019 skapar du ett nytt WPF App-projekt (.NET Core).

  3. Kontrollera att paketreferenser är aktiverade:

    1. I Visual Studio klickar du på Tools –> NuGet Package Manager –> Package Manager-inställningar.
    2. Kontrollera att PackageReference har valts för Standardpakethanteringsformat.

  4. Högerklicka på DITT WPF-projekt i Solution Explorer och välj Hantera NuGet-paket.

  5. Välj fliken Bläddra, sök efter paketet Microsoft.Toolkit.Wpf.UI.XamlHost och installera den senaste stabila versionen. Det här paketet innehåller allt du behöver för att använda WindowsXamlHost-kontrollen som värd för en WinRT XAML-kontroll, inklusive andra relaterade NuGet-paket.

    Anmärkning

    Windows Forms-appar måste använda paketet Microsoft.Toolkit.Forms.UI.XamlHost .

  6. Konfigurera din lösning för att rikta in dig på en specifik plattform, till exempel x86 eller x64. Anpassade WinRT XAML-kontroller stöds inte i projekt som riktar in sig på Alla CPU.

    1. Högerklicka på lösningsnoden i Solution Explorer och välj Egenskaper ->Konfigurationsegenskaper ->Configuration Manager.
    2. Under Aktiv lösningsplattform väljer du Ny.
    3. I dialogrutan Ny lösningsplattform väljer du x64 eller x86 och trycker på OK.
    4. Stäng de öppna dialogrutorna.

Definiera en XamlApplication-klass i ett UWP-appprojekt

Lägg sedan till ett UWP-appprojekt i din lösning och ändra standardklassen App i det här projektet för att härleda från klassen Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication som tillhandahålls av Windows Community Toolkit. Den här klassen stöder gränssnittet IXamlMetadataProvider , som gör att din app kan identifiera och läsa in metadata för anpassade UWP XAML-kontroller i sammansättningar i den aktuella katalogen för ditt program vid körning. Den här klassen initierar även UWP XAML-ramverket för den aktuella tråden.

  1. Högerklicka på lösningsnoden i Solution Explorer och välj Lägg till ->Nytt projekt.

  2. Lägg till ett Tom App (Universal Windows) projekt i din lösning. Kontrollera att målversionen och den lägsta versionen båda är inställda på Windows 10, version 1903 (version 18362) eller en senare version.

  3. I UWP-appprojektet installerar du Microsoft.Toolkit.Win32.UI.XamlApplication NuGet-paketet (senaste stabila versionen).

  4. Öppna filen App.xaml och ersätt innehållet i den här filen med följande XAML. Ersätt MyUWPApp med namnområdet för ditt UWP-appprojekt.

    <xaml:XamlApplication
    x:Class="MyUWPApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:xaml="using:Microsoft.Toolkit.Win32.UI.XamlHost"
    xmlns:local="using:MyUWPApp">
</xaml:XamlApplication>

  5. Öppna filen App.xaml.cs och ersätt innehållet i den här filen med följande kod. Ersätt MyUWPApp med namnområdet för ditt UWP-appprojekt.

    namespace MyUWPApp
{
    public sealed partial class App : Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication
    {
        public App()
        {
            this.Initialize();
        }
    }
}

  6. Ta bort filen MainPage.xaml från UWP-appprojektet.

  7. Rensa UWP-appprojektet och skapa det sedan.

Lägga till en referens till UWP-projektet i ditt WPF-projekt

  1. Ange den kompatibla ramverksversionen i WPF-projektfilen.

    1. Dubbelklicka på WPF-projektnoden i Solution Explorer för att öppna projektfilen i redigeraren.

    2. I det första PropertyGroup-elementet lägger du till följande underordnade element. Ändra den 19041 delen av värdet efter behov för att matcha UWP-projektets mål- och lägsta operativsystemversion.

      <AssetTargetFallback>uap10.0.19041</AssetTargetFallback>

      När du är klar bör elementet PropertyGroup se ut ungefär så här.

      <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <UseWPF>true</UseWPF>
    <Platforms>AnyCPU;x64</Platforms>
    <AssetTargetFallback>uap10.0.19041</AssetTargetFallback>
</PropertyGroup>

  2. Högerklicka på noden Beroenden under WPF-projektet i Solution Explorer och lägg till en referens till ditt UWP-appprojekt.

Instansiera XamlApplication-objektet i startpunkten för DIN WPF-app

Lägg sedan till kod i startpunkten för DIN WPF-app för att skapa en instans av klassen App som du precis definierade i UWP-projektet (det här är den klass som nu härleds från XamlApplication).

  1. Högerklicka på projektnoden i WPF-projektet, välj Lägg till ->Nytt objekt och välj sedan Klass. Ge klassen namnet Program och klicka på Lägg till.

  2. Ersätt den genererade Program klassen med följande kod och spara sedan filen. Ersätt MyUWPApp med namnområdet för ditt UWP-appprojekt och ersätt MyWPFApp med namnområdet för ditt WPF-appprojekt.

    public class Program
{
    [System.STAThreadAttribute()]
    public static void Main()
    {
        using (new MyUWPApp.App())
        {
            MyWPFApp.App app = new MyWPFApp.App();
            app.InitializeComponent();
            app.Run();
        }
    }
}

  3. Högerklicka på projektnoden och välj Egenskaper.

  4. På fliken Program i egenskaperna klickar du på listrutan Startobjekt och väljer det fullständigt kvalificerade namnet på den Program klass som du lade till i föregående steg.

    Anmärkning

    Som standard definierar WPF-projekt en Main startpunktsfunktion i en genererad kodfil som inte är avsedd att ändras. Det här steget ändrar startpunkten för projektet till Main metoden för den nya Program klassen, vilket gör att du kan lägga till kod som körs så tidigt som möjligt i startprocessen för appen.

  5. Spara ändringarna i projektegenskaperna.

Skapa en anpassad WinRT XAML-kontroll

För att vara värd för en anpassad WinRT XAML-kontroll i din WPF-app måste du ha källkoden för kontrollen så att du kan kompilera den med din app. Vanligtvis definieras anpassade kontroller i ett UWP-klassbiblioteksprojekt för enkel portabilitet.

I det här avsnittet definierar du en enkel anpassad kontroll i ett nytt klassbiblioteksprojekt. Du kan också definiera den anpassade kontrollen i UWP-appprojektet som du skapade i föregående avsnitt. Dessa steg gör dock detta i ett separat klassbiblioteksprojekt i illustrativa syften eftersom det vanligtvis är så här anpassade kontroller implementeras för portabilitet.

Om du redan har en anpassad kontroll kan du använda den i stället för den kontroll som visas här. Du måste dock fortfarande konfigurera projektet som innehåller kontrollen enligt de här stegen.

  1. Högerklicka på lösningsnoden i Solution Explorer och välj Lägg till ->Nytt projekt.

  2. Lägg till ett klassbiblioteksprojekt (Universellt Windows) i din lösning. Kontrollera att både målversionen och den lägsta versionen är inställda på samma målversion och lägsta operativsystemversion som UWP-projektet.

  3. Högerklicka på projektfilen och välj Ta bort projekt. Högerklicka på projektfilen igen och välj Redigera.

  4. Innan du stänger </Project> elementet lägger du till följande XML för att inaktivera flera egenskaper och sedan spara projektfilen. Dessa egenskaper måste vara aktiverade för att vara värd för den anpassade kontrollen i en WPF-app (eller Windows Forms).

    <PropertyGroup>
  <EnableTypeInfoReflection>false</EnableTypeInfoReflection>
  <EnableXBindDiagnostics>false</EnableXBindDiagnostics>
</PropertyGroup>

  5. Högerklicka på projektfilen och välj Läs in projekt igen.

  6. Ta bort standardfilen Class1.cs och lägg till ett nytt användarkontrollobjekt i projektet.

  7. I XAML-filen för användarkontrollen lägger du till följande StackPanel som ett underordnat element till standard Grid. Det här exemplet lägger till en TextBlock kontroll och binder sedan attributet för den Text kontrollen till fältet XamlIslandMessage .

    <StackPanel Background="LightCoral">
    <TextBlock>This is a simple custom WinRT XAML control</TextBlock>
    <Rectangle Fill="Blue" Height="100" Width="100"/>
    <TextBlock Text="{x:Bind XamlIslandMessage}" FontSize="50"></TextBlock>
</StackPanel>

  8. I kod-bakgrundsfilen för användarkontrollen, lägg till fältet XamlIslandMessage i användarkontrollklassen enligt exemplet nedan.

    public sealed partial class MyUserControl : UserControl
{
    public string XamlIslandMessage { get; set; }

    public MyUserControl()
    {
        this.InitializeComponent();
    }
}

  9. Skapa UWP-klassbiblioteksprojektet.

  10. I WPF-projektet högerklickar du på noden Beroenden och lägger till en referens till UWP-klassbiblioteksprojektet.

  11. I UWP-appprojektet som du konfigurerade tidigare högerklickar du på noden Referenser och lägger till en referens till UWP-klassbiblioteksprojektet.

  12. Återuppbygg hela lösningen och se till att alla projekt kompileras framgångsrikt.

Hantera den anpassade WinRT XAML-kontrollen i din WPF-app

  1. I Solution Explorer expanderar du WPF-projektet och öppnar filen MainWindow.xaml eller något annat fönster där du vill vara värd för den anpassade kontrollen.

  2. I XAML-filen lägger du till följande namnområdesdeklaration i elementet <Window> .

    xmlns:xaml="clr-namespace:Microsoft.Toolkit.Wpf.UI.XamlHost;assembly=Microsoft.Toolkit.Wpf.UI.XamlHost"

  3. Lägg till följande kontroll i elementet <Grid> i samma fil. InitialTypeName Ändra attributet till det fullständigt kvalificerade namnet på användarkontrollen i ditt UWP-klassbiblioteksprojekt.

    <xaml:WindowsXamlHost InitialTypeName="UWPClassLibrary.MyUserControl" ChildChanged="WindowsXamlHost_ChildChanged" />

  4. Öppna filen bakom koden och lägg till följande kod i Window klassen. Den här koden definierar en ChildChanged händelsehanterare som tilldelar värdet för fältet XamlIslandMessage i den anpassade UWP-kontrollen till värdet för fältet WPFMessage i WPF-appen. Ändra UWPClassLibrary.MyUserControl till det fullständigt kvalificerade namnet på användarkontrollen i ditt UWP-klassbiblioteksprojekt.

    private void WindowsXamlHost_ChildChanged(object sender, EventArgs e)
{
    // Hook up x:Bind source.
    global::Microsoft.Toolkit.Wpf.UI.XamlHost.WindowsXamlHost windowsXamlHost =
        sender as global::Microsoft.Toolkit.Wpf.UI.XamlHost.WindowsXamlHost;
    global::UWPClassLibrary.MyUserControl userControl =
        windowsXamlHost.GetUwpInternalObject() as global::UWPClassLibrary.MyUserControl;

    if (userControl != null)
    {
        userControl.XamlIslandMessage = this.WPFMessage;
    }
}

public string WPFMessage
{
    get
    {
        return "Binding from WPF to UWP XAML";
    }
}

  5. Skapa och kör appen och bekräfta att UWP-användarkontrollen visas som förväntat.

Lägg till en kontroll från WinUI 2-biblioteket i den anpassade kontrollen

Traditionellt har WinRT XAML-kontroller släppts som en del av Windows-operativsystemet och gjorts tillgängliga för utvecklare via Windows SDK. WinUI-biblioteket är en alternativ metod där uppdaterade versioner av WinRT XAML-kontroller från Windows SDK distribueras i ett NuGet-paket som inte är kopplat till Windows SDK-versioner. Det här biblioteket innehåller även nya kontroller som inte ingår i Windows SDK och UWP-standardplattformen.

Det här avsnittet visar hur du lägger till en WinRT XAML-kontroll från WinUI 2-biblioteket till din användarkontroll.

Anmärkning

För närvarande stöder XAML-öarna endast värdkontroller från WinUI 2-biblioteket. Stöd för värdkontroller från WinUI 3-biblioteket kommer i en senare version.

  1. I UWP-appprojektet installerar du den senaste versionen eller förhandsversionen av NuGet-paketet Microsoft.UI.Xaml .

    Anmärkning

    Om din skrivbordsapp är paketerad i ett MSIX-paketkan du använda antingen en förhandsversion eller släppt version av Microsoft.UI.Xaml NuGet-paketet. Om din skrivbordsapp inte paketeras med MSIX måste du installera en förhandsversion av NuGet-paketet Microsoft.UI.Xaml .

  2. Lägg till följande underordnade element i <xaml:XamlApplication>-elementet i det här projektets App.xaml-fil.

    <Application.Resources>
    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
</Application.Resources>

    När du har lagt till det här elementet bör innehållet i den här filen nu se ut ungefär så här.

    <xaml:XamlApplication
    x:Class="MyUWPApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:xaml="using:Microsoft.Toolkit.Win32.UI.XamlHost"
    xmlns:local="using:MyUWPApp">
    <Application.Resources>
        <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
    </Application.Resources>
</xaml:XamlApplication>

  3. I UWP-klassbiblioteksprojektet installerar du den senaste versionen av NuGet-paketet Microsoft.UI.Xaml (samma version som du installerade i UWP-appprojektet).

  4. I samma projekt öppnar du XAML-filen för användarkontrollen och lägger till följande namnområdesdeklaration i elementet <UserControl> .

    xmlns:winui="using:Microsoft.UI.Xaml.Controls"

  5. I samma fil lägger du till ett <winui:RatingControl />-element som ett barn till <StackPanel>. Det här elementet lägger till en instans av klassen RatingControl från WinUI-biblioteket. När du har lagt till det här elementet <StackPanel> bör nu se ut ungefär så här.

    <StackPanel Background="LightCoral">
    <TextBlock>This is a simple custom WinRT XAML control</TextBlock>
    <Rectangle Fill="Blue" Height="100" Width="100"/>
    <TextBlock Text="{x:Bind XamlIslandMessage}" FontSize="50"></TextBlock>
    <winui:RatingControl />
</StackPanel>

  6. Skapa och kör din app och bekräfta att den nya klassificeringskontrollen visas som förväntat.

Förpacka appen

Du kan också paketera WPF-appen i ett MSIX-paket för distribution. MSIX är den moderna apppaketeringstekniken för Windows och baseras på en kombination av installationstekniker för MSI, .appx, App-V och ClickOnce.

Följande instruktioner visar hur du paketerar alla komponenter i lösningen i ett MSIX-paket med hjälp av Windows Application Packaging Project i Visual Studio 2019. De här stegen är bara nödvändiga om du vill paketera WPF-appen i ett MSIX-paket.

Anmärkning

Om du väljer att inte paketera programmet i ett MSIX-paket för distribution måste datorer som kör appen ha Visual C++ Runtime installerat.

  1. Lägg till ett nytt Windows Application Packaging Project till din lösning. När du skapar projektet väljer du samma målversion och lägsta version som du valde för UWP-projektet.

  2. Högerklicka på noden Program i paketeringsprojektet och välj Lägg till referens. I listan över projekt väljer du WPF-projektet i din lösning och klickar på OK.

    Anmärkning

    Om du vill publicera din app i Microsoft Store måste du lägga till en referens till UWP-projektet i paketeringsprojektet.

  3. Konfigurera din lösning för att rikta in dig på en specifik plattform, till exempel x86 eller x64. Detta krävs för att skapa WPF-appen i ett MSIX-paket med hjälp av Windows Application Packaging Project.

    1. Högerklicka på lösningsnoden i Solution Explorer och välj Egenskaper ->Konfigurationsegenskaper ->Configuration Manager.
    2. Under Aktiv lösningsplattform väljer du x64 eller x86.
    3. På raden för ditt WPF-projekt väljer du Nytt i kolumnen Plattform.
    4. I dialogrutan Ny lösningsplattform väljer du x64 eller x86 (samma plattform som du valde för Aktiv lösningsplattform) och klickar på OK.
    5. Stäng de öppna dialogrutorna.

  4. Skapa och kör paketeringsprojektet. Bekräfta att WPF körs och att den anpassade UWP-kontrollen visas som förväntat.

  5. Information om hur du distribuerar paketet finns i Hantera msix-distributionen.

Lösa felet "Det går inte att hitta en resurs" när du är värd för en WinUI-kontroll

Om du är värd för en anpassad kontroll som innehåller en kontroll från WinUI-biblioteket kan det uppstå ett problem där kontrollen inte kan läsas in i en paketerad app och felsökning av koden visar följande fel.

Misslyckades med att köra WinUI-bibliotekskontroll

Lös det här felet genom att kopiera filen App.xbf från mappen build output i WPF-projektet till \AppX\<WPF-projekt> skapa utdatamappen för paketeringsprojektet.

Om WPF-projektet till exempel heter WPFXamlIslandsApp och riktar sig mot x86-plattformen kopierar du App.xbf från \WPFXamlIslandsApp\bin\x86\Release\netcoreapp3.1 till \WPFXamlIslandsApp.Pack\bin\x86\Release\AppX\WPFXamlIslandsAPP.

  • Last updated on