Dela via

Använd Windows App SDK-runtime-miljön för appar paketerade med extern lagring eller utan paket

Anmärkning

Om din app installeras med hjälp av MSIX-teknik kan du läsa distributionsguiden för Windows App SDK för ramverksberoende paketerade appar.

Om din app inte installeras med MSIX (det vill säga den paketeras med extern plats eller packas upp) måste du initiera Windows App SDK för användning innan du kan anropa Windows App SDK-funktioner som WinUI 3, App Lifecycle, MRT Core och DWriteCore. Din app måste initiera Windows App SDK-körningen innan du använder någon annan funktion i Windows App SDK.

  • Från och med Windows App SDK 1.0 kan du göra det automatiskt när appen startar via automatisk initiering (ange projektegenskapen <WindowsPackageType>None</WindowsPackageType>). En demonstration finns i Skapa ditt första WinUI 3-projekt.
  • Men om du har avancerade behov (till exempel att hantera fel genom att visa ditt eget anpassade användargränssnitt eller loggning, eller om du behöver läsa in en version av Windows App SDK som skiljer sig från den version du skapade med), fortsätter du att läsa det här avsnittet. I dessa scenarier kan du i stället för automatisk initiering uttryckligen anropa bootstrapper-API:et.

Någon av de två teknikerna ovan tillåter en app som inte använder MSIX för att ta ett dynamiskt beroende av Windows App SDK vid körning.

Bakgrundsinformation om dynamiska beroenden finns i MSIX-ramverkspaket och dynamiska beroenden.

I bakgrunden och avaktivera automatiska initierare

Koden som genereras av egenskapen WindowsPackageType ovan använder automatiska initierare för att anropa bootstrapper-API:et. Bootstrapper utför tunga lyft för att hitta Windows App SDK och aktivera den aktuella processen för att använda den. Den genererade koden hanterar både initiering och avstängning. Du kan styra initieringens beteende med följande projektegenskaper:

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • Använd standardalternativ.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • Använd inga alternativ.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • Anropa DebugBreak() om ett fel endast inträffar om ett felsökningsprogram är kopplat till processen.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • Utför en felsnabb om ett fel inträffar.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Uppmana användaren att hämta Windows App SDK-körningen om det inte går att hitta en matchande.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Lyckades om den anropades i en process med paketidentitet (annars misslyckas den och ett fel returneras).

Om du vill att appen ska ha explicit kontroll kan du anropa boostrapper-API:et direkt tidigt i programmets start. I så fall behöver WindowsPackageType du inte i projektfilen.

Anmärkning

Förutom den automatiska initieringen och bootstrapper-API:et tillhandahåller Windows App SDK också en implementering av API: et för dynamiskt beroende. Med det här API:et kan dina uppackade appar vara beroende av alla ramverkspaket (inte bara Windows App SDK-ramverkspaketet), och det används internt av bootstrapper-API:et. Mer information om API:et för dynamiskt beroende finns i Använda API:et för dynamiskt beroende för att referera till MSIX-paket vid körning.

Välja bort (eller till) automatiska initiatorer

Projektegenskapen <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> inaktiverar den automatiska initiering som beskrivs ovan (bootstrapper-API:et anropas inte). Det gör att din app kan ta ansvar och anropa bootstrapper-API:et direkt.

Från och med version 1.2 av Windows App SDK (från den stabila kanalen) gäller automatiska initiatorer endast för projekt som skapar en körbar fil (dvs . OutputType-projektegenskapen är inställd på Exe eller WinExe). Det är för att förhindra att automatiska initiatorer läggs till i DLL:er för klassbibliotek och andra icke-körbara filer som standard. Om du behöver en automatisk initiering i en icke-körbar (till exempel en DLL-test som läses in av en körbar värdprocess som inte initierar bootstrappern), kan du uttryckligen aktivera en automatisk initierare i projektet med <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Använda bootstrapper-API:et

Viktigt!

Funktionen MddBootstrapInitialize2 som nämns nedan är tillgänglig från och med version 1.1.

Bootstrapper-API:et består av tre C/C++-funktioner som deklareras i huvudfilen mddbootstrap.h i Windows App SDK: MddBootstrapInitialize, MddBootstrapInitialize2 och MddBootstrapShutdown. Dessa funktioner tillhandahålls av bootstrapper-biblioteket i Windows App SDK. Biblioteket är en liten DLL som du måste distribuera med din app. det är inte en del av själva ramverkspaketet.

MddBootstrapInitialize2

Den här funktionen initierar anropsprocessen för att använda versionen av Windows App SDK-ramverkspaketet som bäst matchar de kriterier som du skickar till funktionsparametrarna. Vanligtvis resulterar det i att referera till den version av ramverkspaketet som matchar Windows App SDK NuGet-paketet som är installerat. Om flera paket uppfyller kriterierna väljs den bästa kandidaten. Den här funktionen måste vara ett av de första anropen i appens start för att säkerställa att bootstrapper-komponenten kan initiera Windows App SDK korrekt och lägga till körningsreferensen till ramverkspaketet.

Bootstrapper-API:et använder API:et för dynamiska beroenden för att lägga till Windows App SDK-körningens ramverkspaket i den aktuella processens paketdiagram och på annat sätt aktivera åtkomst till paketet.

Den här funktionen initierar även DDLM (Dynamic Dependency Lifetime Manager). Komponenten tillhandahåller infrastruktur för att förhindra att operativsystemet underhåller Windows App SDK-ramverkspaketet medan det används av en uppackad app.

MddBootstrapShutdown

Den här funktionen tar bort ändringarna i den aktuella processen som gjordes av ett anrop till MddBootstrapInitialize. När den här funktionen har anropats kan din app inte längre anropa Windows App SDK-API:er, inklusive API:et för dynamiska beroenden.

Den här funktionen stänger också av DDLM (Dynamic Dependency Lifetime Manager) så att Windows kan hantera ramverkspaketet efter behov.

.NET-omslutning för bootstrapper-API:et

Även om du kan anropa C/C++-bootstrapper-API:et direkt från .NET-appar, kräver det att plattformsanrop används för att anropa funktionerna. I Windows App SDK 1.0 och senare versioner finns en .NET-omslutning för bootstrapper-API:et Microsoft.WindowsAppRuntime.Bootstrap.Net.dll i sammansättningen. Den här sammansättningen ger ett enklare och mer naturligt API för .NET-utvecklare att komma åt bootstrappers funktioner. Klassen Bootstrap innehåller statiska funktioner för initiering, TryInitialize och avstängning som omsluter anrop till funktionerna MddBootstrapInitialize och MddBootstrapShutdown för de vanligaste scenarierna. Ett exempel som visar hur du använder .NET-omslutningen för bootstrapper-API:et finns i C#-anvisningarna i Självstudie: Använda bootstrapper-API:et i en app som paketeras med extern plats eller packas upp som använder Windows App SDK.

Mer information om .NET-omslutningen för bootstrapper-API:et finns i följande resurser:

C++-omslutning för bootstrapper-API:et

En C++-omslutning för bootstrapper-API:et är tillgänglig från och med Windows App SDK 1.1.

Se Bootstrapper C++ API.

Deklarera OS-kompatibilitet i programmanifestet

Om du vill deklarera operativsystemskompatibilitet och för att undvika att Windows App SDK är standard för Windows 8-beteende (och potentiella krascher) kan du inkludera ett programmanifest sida vid sida med ditt paketerade med extern plats eller uppackad app. Se Programmanifest (det är filen som deklarerar saker som DPI-medvetenhet och är inbäddad i appens .exe under kompilering). Det här kan vara ett problem om du lägger till Stöd för Windows App SDK i en befintlig app i stället för att skapa en ny via en Visual Studio-projektmall.

Om du inte redan har ett programmanifest sida vid sida i projektet lägger du till en ny XML-fil i projektet och namnger den enligt rekommendationerna i Programmanifest. Lägg till kompatibilitetselementet och de underordnade element som visas i följande exempel i filen. Dessa värden styr egenhetsnivån för de komponenter som körs i appens process.

Ersätt ID-attributet för det maxversiontestade elementet med versionsnumret för Windows som du riktar in dig på (måste vara 10.0.17763.0 eller en senare version). Observera att inställningen av ett högre värde innebär att äldre versioner av Windows inte kör appen korrekt eftersom varje Windows-version bara känner till versioner före den. Så om du vill att din app ska köras på Windows 10 version 1809 (10.0; Skapa 17763) och lämna antingen värdet 10.0.17763.0 som det är, eller lägga till flera maxversionstestade element för de olika värden som appen stöder.

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>

Se även