Distribuire un'app WinUI 3 senza pacchetti

La distribuzione senza pacchetti consente di distribuire un'app WinUI 3 senza MSIX, utile per scenari aziendali in cui la distribuzione MSIX non è disponibile o per gli sviluppatori che preferiscono un'installazione tradizionale basata su cartelle.

Importante

Esaminare queste limitazioni prima di iniziare. Le app WinUI 3 senza pacchetti hanno vincoli che influiscono sulla strategia di distribuzione:

  • EXE a file singolo: supporto PublishSingleFile di app WinUI 3 indipendenti senza pacchetti (SDK per app di Windows 1.5 e versioni successive). Questo produce un singolo EXE distribuibile; le dipendenze vengono estratte in una directory temporanea al primo avvio. Sono necessarie proprietà specifiche di MSBuild — vedere EXE a file singolo più sotto. Le app dipendenti dal framework e le app in pacchetto non supportano PublishSingleFile.
  • Dipendenza runtime - il runtime di SDK per app di Windows deve essere presente nel computer dell'utente. È necessario includere l'installer di runtime con l'app o utilizzare la distribuzione autonoma (che aumenta significativamente le dimensioni del file di output). Vedere Deploying the SDK per app di Windows runtime di seguito.
  • Nessuna identità del pacchetto - Senza un manifest del pacchetto, l'app non può usare funzionalità di Windows basate su manifest: nessun aggiornamento automatico tramite il programma di installazione app o lo Store, nessuna registrazione delle attività in background e nessuna associazione di tipi di file o personalizzazione dei riquadri del menu Start tramite manifest del pacchetto. I meccanismi Win32 tradizionali, ad esempio le voci del Registro di sistema scritte dal programma di installazione e i collegamenti, continuano a funzionare.
  • No MSIX/package-identity Store invio : questo modello di distribuzione non ha identità del pacchetto; non è idoneo come invio MSIX al Microsoft Store. È possibile inviare un programma di installazione tradizionale allo Store tramite il percorso di invio del programma di installazione MSI o EXE, ma si tratta di un flusso di lavoro separato da quello descritto in questo articolo.

Se questi vincoli rappresentano un problema, prendere in considerazione la creazione di pacchetti dell'app (consigliata per la maggior parte delle app) o la creazione di pacchetti con una posizione esterna per aggiungere l'identità del pacchetto senza una conversione MSIX completa.

Per informazioni dettagliate su tutte le opzioni di creazione di pacchetti, vedere Panoramica del pacchetto e della distribuzione di app Windows.

Se si sceglie di annullare il pacchetto di un'app WinUI nuova o esistente, seguire questa procedura:

Nel tuo .csproj file, trova il primo elemento PropertyGroup esistente, che contiene anche OutputType, TargetFramework, e altre proprietà.

  • Aggiungere la proprietà WindowsPackageType project a questo elemento PropertyGroup. Impostarne il valore su None.
<Project ...>
  ...
  <PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType><!-- add this -->
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    ...
  </PropertyGroup> 
  ...
</Project>

Per avviare l'app da Visual Studio (Debugging o Without Debugging> Selezionare il profilo di avvio Unpackaged dall'elenco a discesa Start. Se è selezionato il profilo Package, verrà visualizzato un errore di distribuzione in Visual Studio. Questo passaggio non è necessario se si avvia l'applicazione (.exe) dalla riga di comando o da Esplora file Windows.

Visual Studio - Menu a discesa di avvio con il profilo di avvio non impacchettato dell'applicazione C# evidenziato

API del programma di avvio automatico

L'impostazione della proprietà del progetto <WindowsPackageType>None</WindowsPackageType> fa sì che l'auto-initializer individui e carichi una versione del SDK per app di Windows più appropriata per la tua app.

Se sono necessarie esigenze avanzate, ad esempio la gestione degli errori personalizzata o il caricamento di una versione specifica del SDK per app di Windows, è possibile chiamare in modo esplicito l'API del programma di avvio automatico. Per ulteriori informazioni, vedi Usa il runtime del SDK per app di Windows per le app confezionate con ubicazione esterna o non confezionate, e Tutorial: Utilizza l'API bootstrapper in un'app confezionata con ubicazione esterna o non confezionata che usa il SDK per app di Windows.

Per altre informazioni sul programma di avvio automatico, vedi Architettura di distribuzione e panoramica per le app dipendenti dal framework.

Distribuzione del runtime di SDK per app di Windows

Le app WinUI 3 senza pacchetti dipendono dal runtime SDK per app di Windows installato nel computer dell'utente. Sono disponibili due opzioni per garantire che il runtime sia presente:

Opzione 1: programma di installazione del runtime di SDK per app di Windows (.exe) (scelta consigliata)

Includere il programma di installazione del runtime di SDK per app di Windows insieme alla tua app. Il programma di installazione del runtime è un .exe ridistribuibile che installa i pacchetti di runtime SDK per app di Windows necessari. Scaricalo dalla pagina delle release di SDK per app di Windows e includilo nel tuo programma di installazione o script di configurazione. Per indicazioni complete, vedere Usare il runtime di SDK per app di Windows per app confezionate con ubicazione esterna o non confezionate.

Gli utenti devono eseguire il programma di installazione di runtime una sola volta. Gli aggiornamenti successivi dell'app non richiedono la reinstallazione del runtime, a meno che non venga modificata la versione SDK per app di Windows richiesta.

Opzione 2: Distribuzione autonoma

Impostare <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained> nel file di progetto per aggregare il runtime di SDK per app di Windows direttamente nella cartella di output dell'app. In questo modo viene rimossa la dipendenza di runtime. Gli utenti non devono installare alcun elemento separatamente.

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

Il compromesso: la cartella di output è notevolmente più grande (il runtime completo è incluso) e ogni aggiornamento dell'applicazione include l'intero runtime. Usare questa opzione per scenari di distribuzione semplici o quando non è possibile controllare gli elementi installati nel computer di destinazione.

Distribuisci app non confezionate che utilizzano SDK per app di Windows per il riferimento completo alla distribuzione di runtime.

EXE a file singolo

A partire da SDK per app di Windows 1.5, le app WinUI 3 senza pacchetto e autonome supportano il modello di distribuzione di .NETPublishSingleFile. Questo produce un singolo file EXE distribuibile: tutte le dipendenze vengono raggruppate nell'exe ed estratte in una directory temporanea al primo avvio.

Importante

PublishSingleFile non è supportato per le app in pacchetto (MSIX o in pacchetto con posizione esterna) o per le app dipendenti dal framework. Entrambe le condizioni — senza pacchetto e autonome — sono necessarie.

Proprietà di MSBuild necessarie

Il SDK per app di Windows include una destinazione di convalida in fase di compilazione (WindowsAppSDKSingleFileVerifyConfiguration) che controlla la configurazione del progetto quando PublishSingleFile è impostata. Le seguenti proprietà sono richieste:

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
  <SelfContained>true</SelfContained>
  <EnableMsixTooling>true</EnableMsixTooling>
  <IncludeAllContentForSelfExtract>true</IncludeAllContentForSelfExtract>
  <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>

La compilazione genera errori se EnableMsixTooling, WindowsPackageType=Noneo IncludeAllContentForSelfExtract sono mancanti e gli avvisi se WindowsAppSDKSelfContained o SelfContained sono assenti.

Note

Comportamento di estrazione:IncludeAllContentForSelfExtract=true significa che le dipendenze vengono estratte in una directory temporanea nel computer dell'utente al primo avvio, ovvero l'app non è un file binario di estrazione zero. Il singolo exe è pratico da distribuire, ma i file estratti devono essere presenti per l'esecuzione. L'inizializzatore WindowsAppSdkUndockedRegFreeWinRTInitialize automatico gestisce l'individuazione del runtime estratto. Se si rifiuta esplicitamente, è necessario impostare la variabile di ambiente su AppContext.BaseDirectory prima dell'immissione MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY del programma.

Alternative se l'estrazione di file singoli non è accettabile

Se hai bisogno di un unico file binario che non richieda estrazione, oppure se il comportamento di estrazione non è accettabile nel tuo ambiente di distribuzione, considera:

  • Usare il packaging MSIX — gli utenti ottengono un'unica esperienza di installazione (App Installer gestisce tutti i file) e si ottengono l'idoneità dello Store, l'identità del pacchetto e gli aggiornamenti predefiniti.
  • Usare un programma di installazione tradizionale (WiX, Installazione di Inno): eseguire il wrapping della cartella di output in un singolo programma di installazione EXE che estrae e installa tutti i file necessari in modo trasparente
  • Usare un framework diverso: macchine virtuali Windows e le app WinForms supportano PublishSingleFile un set più ampio di configurazioni

Considerazioni sulla distribuzione per le app non in pacchetto

Le app WinUI 3 non in pacchetto non dispongono dell'identità del pacchetto, il che significa che non possono accedere a determinate funzionalità di Windows:

  • Nessun aggiornamento automatico tramite il programma di installazione app o Microsoft Store
  • Nessuna registrazione dell'attività in background tramite il manifest del pacchetto
  • Nessuna associazione di tipi di file o gestori di protocollo tramite il manifesto del pacchetto
  • Nessuna personalizzazione del riquadro del menu Start tramite il manifesto del pacchetto

Se sono necessarie queste funzionalità, prendere in considerazione la creazione di pacchetti con una posizione esterna come percorso intermedio che aggiunge l'identità del pacchetto senza richiedere la conversione MSIX completa.

→ Pubblica la prima app Windows per una panoramica completa delle opzioni di distribuzione per WinUI 3 e altri framework app Windows.

  • Ultimo aggiornamento: