Condividi tramite

Usare il runtime di Windows App SDK per le app con pacchetti con posizione esterna o non impacchettate

Nota

Se l'app è installata usando la tecnologia MSIX, vedi Windows App SDK guida alla distribuzione per le app in pacchetto dipendenti dal framework.

Se l'app non è installata usando MSIX (ovvero viene inserita in un pacchetto con percorso esterno o senza pacchetti), è necessario inizializzare Windows App SDK per poter usare le funzionalità come WinUI 3, Ciclo di vita dell'app, MRT Core e DWriteCore. L'app deve inizializzare il runtime di Windows App SDK prima di usare qualsiasi altra funzionalità del Windows App SDK.

  • A partire da Windows App SDK 1.0, questa operazione può essere eseguita automaticamente all'avvio dell'app tramite l'inizializzazione automatica (impostare la proprietà project <WindowsPackageType>None</WindowsPackageType>). Per una dimostrazione, vedi Creare il tuo primo progetto WinUI.
  • Tuttavia, se si hanno esigenze avanzate ,ad esempio la gestione degli errori visualizzando l'interfaccia utente personalizzata o la registrazione o se è necessario caricare una versione del Windows App SDK diversa dalla versione compilata con), continuare a leggere questo argomento. In questi scenari, anziché l'inizializzazione automatica, è possibile richiedere l'API del programma di avvio automatico in modo esplicito.

Una delle due tecniche precedenti consente a un'app che non usa MSIX di accettare una dipendenza dinamica dal Windows App SDK in fase di esecuzione.

Per informazioni di base sulle dipendenze dinamiche, vedere Pacchetti del framework MSIX e dipendenze dinamiche.

Dietro le quinte e rifiutare esplicitamente gli inizializzatori automatici

Il codice generato dalla proprietà WindowsPackageType menzionata in precedenza sfrutta auto-initializers per chiamare l'API del programma di avvio automatico. Il bootstrapper gestisce il lavoro più complesso per trovare il Windows App SDK e consentire al processo corrente di utilizzarlo. Il codice generato gestisce sia l'inizializzazione che l'arresto. È possibile controllare il comportamento dell'inizializzazione con le proprietà project seguenti:

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • Utilizzo delle opzioni predefinite.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • Non utilizzare alcuna opzione.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • Richiedere DebugBreak() se si verifica un errore solo nel caso in cui un debugger è collegato al processo.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • Interrompere immediatamente in caso di errore.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Richiedere all'utente di acquisire il runtime di Windows App SDK se non è possibile trovarne una corrispondente.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Riesce se chiamato in un processo con identità del pacchetto; altrimenti fallisce e restituisce un errore.

Se si desidera che l'applicazione abbia un controllo esplicito, è possibile chiamare direttamente l'API di bootstrap all'inizio del processo di avvio dell'applicazione. In tal caso non è necessario WindowsPackageType nel file di project.

Nota

Oltre all'inizializzazione automatica e all'API del programma di avvio automatico, il Windows App SDK fornisce anche un'implementazione dell'API di dipendenza dynamic dependency API. Questa API consente alle app non in pacchetto di assumere una dipendenza da qualsiasi pacchetto framework (non solo dal pacchetto framework Windows App SDK) e viene usata internamente dall'API del bootstrapper. Per altre informazioni sull'API di dipendenza dinamica, vedere Utilizzo dell'API di dipendenza dinamica per fare riferimento ai pacchetti MSIX in fase di esecuzione.

Esclusione (o inclusione) degli inizializzatori automatici

La proprietà project <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> disabilita l'inizializzatore automatico descritto in precedenza (l'API del programma di avvio automatico non viene chiamata). Ciò consente all'app di assumere la responsabilità e chiamare direttamente l'API del programma di avvio automatico.

A partire dalla versione 1.2 del Windows App SDK (dal canale stabile), gli inizializzatori automatici si applicano solo ai progetti che producono un eseguibile (ovvero, La proprietà OutputType project è impostata su Exe o WinExe). Ciò impedisce l'aggiunta di inizializzatori automatici nelle DLL della libreria di classi e in altri file non eseguibili per impostazione predefinita. Se è necessario un inizializzatore automatico in un file non eseguibile (ad esempio, una DLL di test caricata da un eseguibile del processo host che non inizializza il bootstrapper), è possibile abilitare esplicitamente un inizializzatore automatico nel progetto con <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Utilizzo dell'API bootstrapper

Importante

La funzione MddBootstrapInitialize2 indicata di seguito è disponibile a partire dalla versione 1.1.

L'API del programma di avvio automatico è costituita da tre funzioni C/C++ dichiarate nel file di intestazione mddbootstrap.h nel file di intestazione Windows App SDK: MddBootstrapInitialize, MddBootstrapInitialize2 e MddBootstrapShutdown. Tali funzioni vengono fornite dalla libreria del programma di avvio automatico nella Windows App SDK. Questa libreria è una piccola DLL che è necessario distribuire con l'app; non fa parte del pacchetto framework stesso.

MddBootstrapInitialize2

Questa funzione inizializza il processo chiamante per usare la versione del pacchetto framework Windows App SDK che meglio corrisponde ai criteri passati ai parametri della funzione. In genere, ciò comporta il riferimento alla versione del pacchetto framework che corrisponde al pacchetto NuGet Windows App SDK installato. Se più pacchetti soddisfano i criteri, viene selezionato il candidato migliore. Questa funzione deve essere una delle prime chiamate all'avvio dell'app per assicurarsi che il componente del programma di avvio automatico possa inizializzare correttamente il Windows App SDK e aggiungere il riferimento di runtime al pacchetto framework.

L'API del bootstrapper usa l'API Dynamic Dependencies per aggiungere il pacchetto framework del runtime di Windows App SDK al grafico dei pacchetti del processo corrente e altrimenti abilitare l'accesso al pacchetto.

Questa funzione inizializza anche Dynamic Dependency Lifetime Manager (DDLM). Tale componente fornisce l'infrastruttura per impedire al sistema operativo di gestire il pacchetto framework Windows App SDK mentre viene usato da un'app non in pacchetto.

MddBootstrapShutdown

Questa funzione rimuove le modifiche apportate al processo corrente apportate da una chiamata a MddBootstrapInitialize. Dopo aver chiamato questa funzione, l'app non può più chiamare api Windows App SDK, inclusa l'API delle dipendenze dinamiche.

Questa funzione arresta anche Dynamic Dependency Lifetime Manager (DDLM) in modo che Windows possa eseguire il servizio del pacchetto framework in base alle esigenze.

.NET wrapper per l'API del programma di avvio automatico

Sebbene sia possibile chiamare l'API del programma di avvio automatico C/C++ direttamente dalle app .NET, è necessario usare platform invoke per chiamare le funzioni. In Windows App SDK 1.0 e versioni successive, nell'assembly Microsoft.WindowsAppRuntime.Bootstrap.Net.dll è disponibile un wrapper .NET per l'API del programma di avvio automatico. Tale assembly offre un'API più semplice e più naturale per gli sviluppatori .NET per accedere alle funzionalità del bootstrapper. La classe Bootstrap fornisce funzioni statiche Initialize, TryInitialize, e Shutdown che eseguano il wrapping delle chiamate alle funzioni MddBootstrapInitialize e MddBootstrapShutdown per gli scenari più comuni. Per un esempio che illustra come usare il wrapper .NET per la bootstrapper API, vedere le istruzioni C# in Tutorial: Usare la bootstrapper API in un'app con pacchetto a percorso esterno o non impacchettata che utilizza il Windows App SDK.

Per altre informazioni sul wrapper .NET per l'API del programma di avvio automatico, vedere queste risorse:

Wrapper C++ per l'API del programma di avvio automatico

A partire da Windows App SDK 1.1 è disponibile un wrapper C++ per l'API del programma di avvio automatico.

Vedere API C++ del programma di avvio automatico.

Dichiarare la compatibilità del sistema operativo nel manifesto dell'applicazione

Per dichiarare la compatibilità del sistema operativo e per evitare che il comportamento predefinito di Windows App SDK sia quello di Windows 8 (e potenziali arresti anomali), è possibile includere un manifesto dell'applicazione side-by-side con l'applicazione pacchettizzata nella posizione esterna o con l'app non confezionata. Vedere Manifesto dell'applicazione, ovvero un file che dichiara elementi come la riconoscimento DPI e viene incorporato nell'applicazione .exe durante la compilazione. Questo potrebbe essere un problema se si aggiunge Windows App SDK supporto a un'app esistente, anziché crearne uno nuovo tramite un modello di Visual Studio project.

Se nel project non è già presente un manifesto dell'applicazione side-by-side, aggiungere un nuovo file XML al project e denominarlo come consigliato in Manifesti dell'applicazione. Aggiungere al file l'elemento di compatibilità e gli elementi figlio illustrati nell'esempio seguente. Questi valori controllano il livello di comportamenti anomali per i componenti in esecuzione nel processo dell'app.

Sostituire l'attributo Id dell'elemento maxversiontested con il numero della versione di Windows a cui si indirizza (deve essere 10.0.17763.0 o una versione successiva). Tenere presente che l'impostazione di un valore superiore implica che le versioni precedenti di Windows non eseguiranno correttamente l'app perché ogni versione di Windows conosce solo le versioni che la precedono. Quindi, se vuoi che l'app venga eseguita in Windows 10 versione 1809 (10.0; Build 17763), è necessario lasciare invariato il valore 10.0.17763.0 oppure aggiungere più elementi maxversiontested per i diversi valori supportati dall'app.

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

Vedi anche

  • Last updated on