Delen via

De Windows App SDK-runtime gebruiken voor apps die zijn verpakt met een externe locatie of uitgepakt

Opmerking

Als uw app is geïnstalleerd met behulp van MSIX-technologie, raadpleegt u de Implementatiehandleiding voor Windows App SDK voor frameworkafhankelijke verpakte apps.

Als uw app niet is geïnstalleerd met BEHULP van MSIX (dat wil gezegd, deze is verpakt met externe locatie of uitgepakt), moet u de Windows App SDK initialiseren voor gebruik voordat u Windows App SDK-functies zoals WinUI 3, App Lifecycle, MRT Core en DWriteCore kunt aanroepen. Uw app moet de Windows App SDK-runtime initialiseren voordat u een andere functie van de Windows App SDK gebruikt.

  • Vanaf Windows App SDK 1.0 kunt u deze automatisch uitvoeren wanneer uw app wordt gestart via automatische initialisatie (stel de projecteigenschap <WindowsPackageType>None</WindowsPackageType>in). Zie Uw eerste WinUI 3-project maken voor een demonstratie.
  • Maar als u geavanceerde behoeften hebt (zoals het afhandelen van fouten door uw eigen aangepaste gebruikersinterface of logboekregistratie weer te geven, of als u een versie van de Windows App SDK moet laden die verschilt van de versie waarmee u hebt gebouwd), leest u dit onderwerp verder. In deze scenario's kunt u in plaats van automatisch initialiseren de bootstrapper-API expliciet aanroepen.

Met een van de twee bovenstaande technieken kan een app die geen MSIX gebruikt, een dynamische afhankelijkheid van de Windows App SDK uitvoeren.

Zie MSIX-frameworkpakketten en dynamische afhankelijkheden voor achtergrondinformatie over dynamische afhankelijkheden.

Achter de schermen en afmelden voor automatische initialisatie

De code die door de WindowsPackageType bovenstaande eigenschap wordt gegenereerd, maakt gebruik van automatische initialisatieprogramma's om de bootstrapper-API aan te roepen. De bootstrapper doet het zware werk om de Windows App SDK te vinden en het huidige proces in te schakelen om het te gebruiken. De gegenereerde code verwerkt zowel initialisatie als afsluiten. U kunt het gedrag van initialisatie beheren met de volgende projecteigenschappen:

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • Gebruik standaardopties.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • Gebruik geen opties.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • Roep DebugBreak() aan als er alleen een fout optreedt als er een foutopsporingsprogramma aan het proces is gekoppeld.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • Voer een fail-fast uit als er een fout optreedt.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Vraag de gebruiker om de Windows App SDK-runtime te verkrijgen als er geen overeenkomende kan worden gevonden.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Succceed indien aangeroepen in een proces met pakketidentiteit (anders mislukt het en wordt er een fout geretourneerd).

Als u wilt dat uw app expliciete controle heeft, kunt u de boostrapper-API vroeg in het opstarten van uw toepassing aanroepen. In dat geval hebt u het projectbestand niet nodig WindowsPackageType .

Opmerking

Naast de automatische initialisatie en de bootstrapper-API biedt de Windows App SDK ook een implementatie van de dynamische afhankelijkheids-API. Met deze API kunnen uw uitgepakte apps afhankelijk zijn van elk frameworkpakket (niet alleen het Windows App SDK-frameworkpakket) en wordt deze intern gebruikt door de bootstrapper-API. Zie De API voor dynamische afhankelijkheden gebruiken om tijdens runtime te verwijzen naar MSIX-pakketten voor meer informatie over de API voor dynamische afhankelijkheden.

Automatische initialisatieprogramma's afmelden (of in)

Met de projecteigenschap <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> wordt de hierboven beschreven automatische initialisatiefunctie uitgeschakeld (de bootstrapper-API wordt niet aangeroepen). Hierdoor kan uw app verantwoordelijkheid nemen en de bootstrapper-API rechtstreeks aanroepen.

Vanaf versie 1.2 van de Windows App SDK (vanuit het stabiele kanaal) zijn auto-initializers alleen van toepassing op projecten die een uitvoerbaar bestand produceren (de eigenschap OutputType-project is ingesteld op Exe of WinExe). Dit is om te voorkomen dat automatisch initialisatieprogramma's worden toegevoegd aan klassebibliotheek-DLL's en andere niet-uitvoerbare bestanden. Als u een automatische initialisatiefunctie in een niet-uitvoerbaar bestand nodig hebt (bijvoorbeeld een test-DLL die is geladen door een uitvoerbaar hostproces dat de bootstrapper niet initialiseert), kunt u expliciet een automatische initialisatiefunctie inschakelen in uw project met <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

De bootstrapper-API gebruiken

Belangrijk

De hieronder genoemde mddBootstrapInitialize2-functie is beschikbaar vanaf versie 1.1.

De bootstrapper-API bestaat uit drie C/C++-functies die worden gedeclareerd in het headerbestand mddbootstrap.h in de Windows App SDK: MddBootstrapInitialize, MddBootstrapInitialize2 en MddBootstrapShutdown. Deze functies worden geleverd door de bootstrapper-bibliotheek in de Windows App SDK. Deze bibliotheek is een kleine DLL die u met uw app moet distribueren; het maakt geen deel uit van het frameworkpakket zelf.

MddBootstrapInitialize2

Met deze functie wordt het aanroepende proces geïnitialiseerd voor het gebruik van de versie van het Windows App SDK-frameworkpakket dat het beste overeenkomt met de criteria die u aan de functieparameters doorgeeft. Dit resulteert meestal in het verwijzen naar de versie van het frameworkpakket dat overeenkomt met het NuGet-pakket voor Windows App SDK dat is geïnstalleerd. Als meerdere pakketten aan de criteria voldoen, wordt de beste kandidaat geselecteerd. Deze functie moet een van de eerste aanroepen zijn in het opstarten van de app om ervoor te zorgen dat het bootstrapper-onderdeel de Windows App SDK correct kan initialiseren en de runtimeverwijzing aan het framework-pakket kan toevoegen.

De bootstrapper-API maakt gebruik van de Dynamic Dependencies-API om het frameworkpakket van de Windows App SDK-runtime toe te voegen aan de pakketgrafiek van het huidige proces en anders toegang tot het pakket in te schakelen.

Met deze functie wordt ook DDLM (Dynamic Dependency Lifetime Manager) geïnitialiseerd. Dit onderdeel biedt infrastructuur om te voorkomen dat het besturingssysteem het Framework-pakket van de Windows App SDK onderhoudt terwijl het wordt gebruikt door een uitgepakte app.

MddBootstrapShutdown

Met deze functie worden de wijzigingen in het huidige proces verwijderd die zijn aangebracht door een aanroep naar MddBootstrapInitialize. Nadat deze functie is aangeroepen, kan uw app geen API's van Windows App SDK meer aanroepen, inclusief de API voor dynamische afhankelijkheden.

Met deze functie wordt ook de Dynamic Dependency Lifetime Manager (DDLM) afgesloten, zodat Windows het frameworkpakket indien nodig kan onderhouden.

.NET wrapper voor de bootstrapper-API

Hoewel u de C/C++-bootstrapper-API rechtstreeks vanuit .NET-apps kunt aanroepen, moet u platform aanroepen om de functies aan te roepen. In Windows App SDK 1.0 en hoger is een .NET-wrapper voor de bootstrapper-API beschikbaar in de Microsoft.WindowsAppRuntime.Bootstrap.Net.dll assembly. Deze assembly biedt een eenvoudigere en natuurlijkere API voor .NET-ontwikkelaars om toegang te krijgen tot de functionaliteit van de bootstrapper. De Bootstrap-klasse biedt statische functies Initialize, TryInitialize en Shutdown waarmee aanroepen naar de mddBootstrapInitialize - en MddBootstrapShutdown-functies worden verpakt voor de meest voorkomende scenario's. Voor een voorbeeld dat laat zien hoe u de .NET-wrapper voor de bootstrapper-API gebruikt, raadpleegt u de C#-instructies in zelfstudie: De bootstrapper-API gebruiken in een app die is verpakt met externe locatie of uitgepakt die gebruikmaakt van de Windows App SDK.

Zie de volgende resources voor meer informatie over de .NET-wrapper voor de bootstrapper-API:

C++ wrapper voor de bootstrapper-API

Een C++-wrapper voor de bootstrapper-API is beschikbaar vanaf Windows App SDK 1.1.

Zie Bootstrapper C++ API.

Besturingssysteemcompatibiliteit declareren in uw toepassingsmanifest

Als u de compatibiliteit van het besturingssysteem (besturingssysteem) wilt declareren en om te voorkomen dat de Windows App SDK het standaardgedrag van Windows 8 gebruikt (en mogelijke crashes), kunt u een toepassingsmanifest naast elkaar opnemen met uw verpakte met externe locatie of uitgepakte app. Bekijk toepassingsmanifesten (het is het bestand dat dingen als DPI-bewustzijn declareert en is ingesloten in de app .exe tijdens de build). Dit kan een probleem zijn als u Windows App SDK-ondersteuning toevoegt aan een bestaande app in plaats van een nieuwe app te maken via een Visual Studio-projectsjabloon.

Als u nog geen toepassingsmanifest naast elkaar in uw project hebt, voegt u een nieuw XML-bestand toe aan uw project en geeft u dit de naam zoals aanbevolen in toepassingsmanifesten. Voeg aan het bestand het compatibiliteitselement en de onderliggende elementen toe die worden weergegeven in het volgende voorbeeld. Deze waarden bepalen het quirkniveau voor de onderdelen die worden uitgevoerd in het proces van uw app.

Vervang het id-kenmerk van het element maxversiontested door het versienummer van Windows dat u wilt gebruiken (moet 10.0.17763.0 of een latere release zijn). Houd er rekening mee dat het instellen van een hogere waarde betekent dat oudere versies van Windows uw app niet goed uitvoeren, omdat elke Windows-release alleen over versies weet voordat deze wordt uitgevoerd. Dus als u wilt dat uw app wordt uitgevoerd op Windows 10, versie 1809 (10.0; Build 17763), moet u de waarde 10.0.17763.0 ongewijzigd laten of meerdere maximaal geteste elementen toevoegen voor de verschillende waarden die door uw app worden ondersteund.

<?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>

Zie ook

  • Last updated on