Usare il runtime di SDK per app di Windows per le app in pacchetto con posizione esterna o non in pacchetto

  • Articolo

Nota

Se l'app è installata usando la tecnologia MSIX, vedere Windows App SDK: guida alla distribuzione per le app incluse nel 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 l'utilizzo prima di poter richiederne le funzionalità come WinUI 3, Ciclo di vita dell'app, MRT Core e DWriteCore. La propria app non inclusa nel pacchetto deve inizializzare il runtime di Windows App SDK prima di usare qualsiasi altra funzionalità di 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à del progetto <WindowsPackageType>None</WindowsPackageType>). Per una dimostrazione, vedere Creare il primo progetto WinUI 3.
  • 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 di Windows App SDK diversa dalla versione compilata con cui è stata costruita, 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 per accettare una dipendenza dinamica su 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 rinuncia all'inizializzazione automatica del modulo

Il codice generato dalla WindowsPackageType proprietà menzionata in precedenza sfrutta gli inizializzatori di modulo per richiedere l'API del programma di avvio automatico. Il programma di avvio automatico esegue il caricamento elevato per trovare Windows App SDK e abilitare il processo corrente per usarlo. Il codice generato gestisce sia l'inizializzazione che l'arresto. È possibile controllare il comportamento dell'inizializzazione con le proprietà del progetto 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>
    • Se si verifica un errore, eseguire un errore rapido.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • Richiedere all'utente di acquisire il runtime di Windows App SDK se non è possibile trovarne uno corrispondente.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • L'esito è positivo se viene chiamato in un processo con l'identità del pacchetto (in caso contrario ha esito negativo e viene restituito un errore).

Se si vuole che l'app abbia un controllo esplicito, è possibile chiamare direttamente l'API del programma di avvio automatico all'avvio dell'applicazione. In questo caso non è necessario WindowsPackageType nel file di progetto.

Nota

Oltre all'inizializzazione automatica e all'API del programma di avvio automatico, Windows App SDK fornisce anche un'implementazione dell'API di dipendenza dinamica. Questa API consente alle app non incluse nel pacchetto di accettare una dipendenza da qualsiasi pacchetto framework (non solo il pacchetto framework SDK per app di Windows) e viene usato internamente dall'API del programma di avvio automatico. 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.

Rifiuto esplicito dell'inizializzazione automatica dei moduli (o in)

La proprietà del progetto <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> disabilita l'inizializzazione automatica del modulo descritta 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 SDK per app di Windows (dal canale stabile), l'inizializzazione automatica del modulo si applica solo ai progetti che producono un eseguibile ( ovvero la proprietà del progetto OutputType è 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 programma di avvio automatico), è possibile abilitare in modo esplicito un inizializzatore automatico nel progetto con <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>.

Utilizzo dell'API del programma di avvio automatico

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 in Windows App SDK: MddBootstrapInitialize, MddBootstrapInitialize2, e MddBootstrapShutdown. Tali funzioni vengono fornite dalla libreria del programma di avvio automatico in 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 SDK per app di Windows 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 SDK per Windows App SDK. 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 Windows App SDK e aggiungere il riferimento di runtime al pacchetto framework.

L'API del programma di avvio automatico usa API di dipendenze dinamiche per aggiungere il pacchetto framework del runtime di Windows App SDK al grafico del pacchetto del processo corrente e in caso contrario 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 SDK per app di Windows 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 le API di Windows App SDK, inclusa l'API di 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.

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

Nonostante sia possibile chiamare l'API del programma di avvio automatico C/C++ direttamente dalle app .NET, ciò richiede l'uso di platform invoke per chiamare le funzioni. In Windows App SDK 1.0 e versioni successive, nell'assembly è disponibile un wrapper .NET per l'API del programma di avvio automatico Microsoft.WindowsAppRuntime.Bootstrap.Net.dll. Questo assembly offre un'API più semplice e naturale per gli sviluppatori .NET per accedere alle funzionalità del programma di avvio automatico. 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 l'API del programma di avvio automatico, vedere le istruzioni di C# in Tutorial: utilizzo dell'API del programma di avvio automatico in un'app inclusa nel pacchetto con percorso esterno o non inclusa nel pacchetto che utilizza 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 (OS) e per evitare il comportamento predefinito di Windows App SDK windows 8 (e potenziali arresti anomali), è possibile includere un manifesto dell'applicazione side-by-side con il pacchetto con la posizione esterna o l'app non inclusa nel pacchetto. 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 il supporto di Windows App SDK a un'app esistente, anziché crearne uno nuovo tramite un modello di progetto di Visual Studio.

Se non si dispone già di un manifesto dell'applicazione side-by-side nel progetto, aggiungere un nuovo file XML al progetto 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 si vuole che l'app venga eseguita su 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>