Share via

Guida alla distribuzione di Windows App SDK per le app dipendenti dal framework in pacchetto con percorso esterno o non in pacchetto

  • Articolo

Questo argomento fornisce indicazioni sulla distribuzione di app in pacchetto con posizione esterna o non in pacchetto e che usano Windows App SDK.

Panoramica

Gli sviluppatori di app in pacchetto con posizione esterna e di app non in pacchetto sono responsabili della distribuzione dei pacchetti di runtime necessari di Windows App SDK agli utenti finali. A tale scopo è possibile eseguire il programma di installazione o installare direttamente i pacchetti MSIX. Queste opzioni sono descritte in modo più dettagliato nella sezione Distribuzione del runtime Windows App SDK di seguito.

Le app in pacchetto con posizione esterna e le app non in pacchetto hanno anche altri requisiti di runtime. È necessario inizializzare l'accesso al runtime Windows App SDK usando l'API del API del caricatore di avvio. Inoltre, se l'app usa altri pacchetti framework oltre a Windows App SDK, si può utilizzare l'API delle dipendenze dinamiche. Questi requisiti sono descritti in modo più dettagliato nella sezione Requisiti di runtime per le app in pacchetto con posizione esterna o non in pacchetto di seguito.

Prerequisiti

Prerequisiti aggiuntivi

  • Le versioni sperimentali e di anteprima di Windows App SDK richiedono l'abilitazione del trasferimento locale per installare il runtime.

    • Il trasferimento locale è abilitato automaticamente in Windows 10, versione 2004 e successive.

    • Se il computer di sviluppo o il computer di distribuzione esegue Windows 11, verificare se il trasferimento locale è abilitato:

      • Impostazioni>Privacy & sicurezza>Per sviluppatori. Assicurarsi che la modalità sviluppatore sia attivata.

    • Se il computer di sviluppo o il computer di distribuzione esegue Windows 10, versione 1909 o una versione precedente, verificare se il trasferimento locale è abilitato:

      • Impostazioni>Aggiornamento & Sicurezza>Per sviluppatori>Usa le funzionalità per gli sviluppatori. Verificare che Sideload app o Modalità sviluppatore siano selezionate.

    • L'impostazione Modalità sviluppatore include il trasferimento locale e altre funzionalità.

      Nota

      Se il computer è gestito in un ambiente aziendale, potrebbe essere presente un criterio che impedisce la modifica di queste impostazioni. In tal caso, se si riceve un errore quando si tenta di installare il runtime di Windows App SDK, contattare il professionista IT per abilitare il trasferimento locale o la modalità sviluppatore.

Distribuzione del runtime di Windows App SDK

Le app in pacchetto con posizione esterno e le app non in pacchetto hanno due opzioni per distribuire il runtime di Windows App SDK:

Opzione 1: usare il programma di installazione

È possibile distribuire tutti i pacchetti di runtime di Windows App SDK eseguendo il programma di installazione. Il programma di installazione è disponibile in Download per Windows App SDK. Quando si esegue il programma di installazione (.exe), viene visualizzato un output simile al seguente:

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: MicrosoftCorporationII.WindowsAppRuntime.Main.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.Singleton_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x6_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x8_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

All install operations successful.

È possibile eseguire il programma di installazione senza interazione dell'utente e eliminare tutto l'output di testo con l'opzione --quiet:

WindowsAppRuntimeInstall.exe --quiet

È anche possibile scegliere di forzare l'aggiornamento dei pacchetti MSIX e arrestare qualsiasi processo di Windows App SDK attualmente in esecuzione usando l'opzione --force. Questa funzionalità è stata introdotta nella versione 1.1.

WindowsAppRuntimeInstall.exe --force

Per visualizzare tutte le opzioni della riga di comando del programma di installazione, eseguire WindowsAppRuntimeInstall --h.

Al termine dell'installazione, è possibile eseguire l'app in pacchetto con posizione esterna o non in pacchetto. Per un esempio di compilazione ed esecuzione di un'app in pacchetto con posizione esterna o non in pacchetto che usa Windows App SDK, vedere Esercitazione: usare l'API del programma di avvio automatico in un'app in pacchetto con posizione esterna o non in pacchetto che usa Windows App SDK.

Concatenare il programma di installazione di Windows App SDK alla configurazione dell'app

Se si dispone di un programma di installazione personalizzato per l'app, è possibile concatenare il processo di installazione di Windows App SDK al processo di installazione dell'app. Il programma di installazione di Windows App SDK attualmente non fornisce un'interfaccia utente predefinita, quindi si dovrà procedere alla concatenazione usando l'interfaccia utente personalizzata della configurazione.

È possibile avviare e rilevare automaticamente l'installazione di Windows App SDK mentre viene visualizzato lo stato di avanzamento dell'installazione usando ShellExecute. Il programma di installazione di Windows App SDK decomprime automaticamente il bundle Windows App MSIX e chiama il metodo PackageManager.AddPackageAsync per completare l'installazione. Questa operazione è molto simile ad altri programmi di installazione di runtime usati, ad esempio .NET, Visual C++ o DirectX.

Per un esempio di codice che mostra come eseguire il programma di installazione di Windows App SDK dal programma di installazione, vedere la funzione RunInstaller nei test funzionali del programma di installazione.

Esempio di programma di installazione

Vedere l'esempio seguente per vedere come avviare il programma di installazione da un programma di installazione Win32 senza aprire una finestra della console durante l'installazione:

Esplorare l'esempio di programma di installazione

Risoluzione dei problemi

Codici restituiti

Nella tabella seguente sono elencati i codici restituiti più comuni per il programma di installazione di Windows App SDK .exe. I codici restituiti sono gli stessi per tutte le versioni del programma di installazione.

Codice restituito Descrizione
0x0 L'installazione o il provisioning del pacchetto è stato completato correttamente.
0x80073d06 Impossibile installare uno o più pacchetti.
0x80070005 L'installazione o il provisioning a livello di sistema non è stato possibile perché l'app non è in esecuzione con privilegi elevati o l'utente che esegue l'installazione non dispone di privilegi di amministratore.

Errori di installazione

Se il programma di installazione di Windows App SDK restituisce un errore durante l'installazione, restituirà un codice di errore che descrive il problema.

Opzione 2: distribuire direttamente i pacchetti di runtime di Windows App SDK

In alternativa all'uso del programma di installazione di Windows App SDK per la distribuzione agli utenti finali, è possibile distribuire manualmente i pacchetti MSIX tramite il programma o l'MSI dell'app. Questa opzione può essere ideale per gli sviluppatori che vogliono avere un maggiore controllo.

Per un esempio che mostra come il programma di installazione può installare i pacchetti MSIX, vedere install.cpp nel codice del programma di installazione di Windows App SDK.

Scenari di distribuzione

  • Installazione del runtime di Windows App SDK a livello di sistema: l'installazione a livello di sistema modifica il computer per tutti gli utenti, inclusi i nuovi utenti che verranno aggiunti in futuro. Se l'app è in esecuzione con privilegi elevati e l'utente che esegue l'installazione disponde di privilegi di amministratore, il programma di installazione registrerà i pacchetti MSIX a livello di sistema chiamando ProvisionPackageForAllUsersAsync. Se la registrazione a livello di sistema ha esito negativo, l'installazione verrà eseguita solo per l'utente corrente che esegue l'installazione. In un ambiente aziendale gestito, l'amministratore IT deve essere in grado di effettuare il provisioning per tutti come al solito.

  • Architetture ridistribuite dal programma di installazione di Windows App SDK: il programma di installazione di Windows App SDK è disponibile nelle architetture x86, x64 e Arm64. Ogni versione del programma di installazione include i pacchetti MSIX per quella specifica architettura. Ad esempio, se si esegue WindowsAppRuntimeInstall.exe x86 in un dispositivo x64 o Arm64, il programma di installazione distribuirà i pacchetti per quell'architettura di dispositivo.

  • Tutti i pacchetti MSIX di Windows App SDK sono già installati sul computer: i pacchetti MSIX vengono installati in una posizione a livello di sistema con una sola copia su disco. Se un'app tenta di installare Windows App SDK quando tutte le dipendenze del pacchetto MSIX sono già installate sul computer, l'installazione non viene eseguita.

  • Uno o più pacchetti MSIX di Windows App SDK non sono installati sul computer: quando si distribuisce Windows App SDK, tentare sempre di installare tutti i pacchetti MSIX (framework, main, singleton, DDLM) per assicurarsi che tutte le dipendenze siano installate e che non ci siano interruzioni dell'esperienza dell'utente finale.

Requisiti di runtime per le app in pacchetto con posizione esterna o non in pacchetto

Le app in pacchetto con posizione esterna o non in pacchetto hanno requisiti di runtime aggiuntivi per l'uso del runtime di Windows App SDK. Questo implica il riferimento e l'inizializzazione del pacchetto framework di Windows App SDK in fase di runtime. Inoltre, l'API delle dipendenze dinamiche può essere usata per fare riferimento ad altri pacchetti di framework all'esterno di Windows App SDK.

Usare il runtime di Windows App SDK

Le app in pacchetto con posizione esterna e non in pacchetto devono chiamare l'API del programma di avvio automatico per usare Windows App SDK in fase di runtime. Questa operazione è necessaria prima che l'app possa usare le funzionalità di Windows App SDK WinUI, Ciclo di vita dell'app, MRT Core e DWriteCore. Un componente del programma di avvio automatico consente alle app in pacchetto con posizione esterna e non in pacchetto per eseguire queste importanti attività:

  • Trovare e caricare il pacchetto framework di Windows App SDK nel grafico dei pacchetti dell'app.
  • Inizializzare il Dynamic Dependency Lifetime Manager (DDLM) per il pacchetto framework di Windows App SDK. Lo scopo del DDLM è impedire la manutenzione del pacchetto framework di Windows App SDK mentre è usato da un'app in pacchetto con percorso esterno o non in pacchetto.

Il modo più semplice per caricare il runtime di Windows App SDK per le app con in pacchetto con posizione esterna e non in pacchetto consiste nell'impostare la proprietà <WindowsPackageType>None</WindowsPackageType> nel file di progetto (con estensione csproj o .vcxproj). È anche possibile chiamare l'API del programma di avvio automatico direttamente nel codice di avvio dell'app per un maggiore controllo sull'inizializzazione. Per informazioni dettagliate, vedere Usare il runtime di Windows App SDK per le app in pacchetto con posizione esterna o non in pacchetto ed Esercitazione: usare l'API del programma di avvio automatico in un'app in pacchetto con posizione esterna o non in pacchetto che usa Windows App SDK.

Il supporto delle dipendenze dinamiche consente alle app in pacchetto con posizione esterna e non in pacchetto di mantenere il meccanismo di distribuzione esistente, ad esempio MSI o qualsiasi programma di installazione, oltre a poter sfruttare Windows App SDK nell'applicazione. Le dipendenze dinamiche possono essere usate nella app in pacchetto, nelle app in pacchetto con posizione esterna e nelle app non in pacchetto; anche se sono destinate principalmente a essere usato dalle app in pacchetto con posizione esterna e non in pacchetto.

È disponibile un DDLM per ogni versione e architettura del pacchetto framework di Windows App SDK. Ciò significa che in un x64 computer, è possibile che sia una versione x86 e una versione x64 del DDLM a supportare app di entrambe le architetture.

Fare riferimento ad altri pacchetti framework usando l'API delle dipendenze dinamiche

Se si vogliono usare funzionalità in altri pacchetti framework all'esterno di Windows App SDK (ad esempio, DirectX), le app in pacchetto con posizione esterna e non in pacchetto può chiamare l'API delle dipendenze dinamiche. Oltre al componente del programma di avvio automatico, Windows App SDK fornisce anche un set più ampio di funzioni C/C++ e classi WinRT che implementano l'API delle dipendenze dinamiche. Questa API è progettata per fare riferimento a qualsiasi pacchetto framework in modo dinamico in fase di runtime.

Per altre informazioni, vedere Usare pacchetti framework MSIX in modo dinamico dall'app desktop e l'esempio di dipendenze dinamiche

Distribuire file .winmd nel computer di destinazione

Insieme all'app, è consigliabile procedere e distribuire i file Windows Metadata (.winmd). I metadati possono essere usati da varie API e comportamenti in fase di runtime; la loro assenza può limitare o interromperne le funzionalità. Ad esempio, i metadati possono essere usati per effettuare il marshalling degli oggetti nei limiti degli apartment; e la necessità di effettuare il marshalling può essere una funzione delle prestazioni del computer. Poiché non esiste un modo deterministico per sapere se sono necessari metadati, è consigliabile distribuirli .winmd, a meno che non si sia estremamente preoccupati per le dimensioni.