Proprietà di progetto e inizializzatori automatici

In questo argomento vengono descritte le proprietà project che è possibile impostare nel file di Visual Studio project (ad esempio .csproj o .vcxproj) per personalizzare la modalità di distribuzione dell'app, inclusa la configurazione degli inizializzatori automatici.

Inizializzatori automatici nel SDK per app di Windows

Nella SDK per app di Windows sono presenti diverse routine il cui processo consiste nel garantire che il runtime di app di Windows sia inizializzato correttamente. Queste routine sono note come inizializzatori automatici, perché vengono eseguite automaticamente prima del punto di ingresso dell'applicazione e funzionano automaticamente per l'inizializzazione.

Suggerimento

In caso di curiosità sui dettagli tecnici. In C++, un inizializzatore automatico viene implementato con un costruttore di classe statico. In C#, un inizializzatore automatico viene implementato con un inizializzatore di modulo .NET. È quindi possibile che a volte si senta l'inizializzatore di modulo usato quando il termine corretto è l'inizializzatore automatico.

Tutti gli inizializzatori automatici sono abilitati in modo condizionale per impostazione predefinita, in base alla configurazione di creazione di pacchetti e distribuzione dell'app. Ecco i dettagli su di essi:

  • Bootstrapper (noto anche come dipendenze dinamiche) inizializzatore automatico. Questo inizializzatore automatico chiama automaticamente l'API del programma di avvio automatico all'avvio dell'app. È necessario per le app non in pacchetto dipendenti dal framework, per assicurarsi che il runtime di app di Windows venga aggiunto al grafico del pacchetto dell'app. Per informazioni sulle app dipendenti dal framework e autonome, vedi panoramica della distribuzione SDK per app di Windows. Per informazioni sulle app senza pacchetto e con pacchetto, vedi App di Windows: creazione di pacchetti, distribuzione e processi.
    • Per un'applicazione confezionata, non è necessario l'auto-inizializzatore delle dipendenze dinamiche del bootstrapper perché il file appxmanifest.xml esprime la dipendenza del framework. E per un'app autonoma, non è necessario l'auto-initializzatore del bootstrapper/dipendenze dinamiche perché tali app non usano il framework.
    • È possibile disattivare l'inizializzatore automatico di bootstrapper/dipendenze dinamiche nel file .csproj o .vcxproj tramite <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize>.
  • Inizializzatore automatico di Deployment Manager. Questa operazione è necessaria per le app in pacchetto dipendenti dal framework che usano la funzionalità main/singleton (ad esempio, le notifiche push), perché il appxmanifest.xml file non può esprimere tali dipendenze.
    • Per un'app autonoma, non è necessario l'inizializzatore automatico di Deployment Manager perché tali app non supportano la funzionalità main/singleton.
    • Per informazioni più importanti, vedere la sezione Inizializzatore automatico di Deployment Manager più avanti in questo argomento.
  • Inizializzatore automatico di attivazione senza registrazione. Questa operazione è necessaria per un'applicazione autonoma per l'uso dell'attivazione di Windows Runtime basata su manifesto e senza registrazione (WinRT) (UndockedRegFreeWinRT), se l'applicazione è in esecuzione su una versione del sistema operativo precedente all'Aggiornamento di Windows 10 maggio 2019 (versione 1903; denominata "19H1").
    • Per le app dipendenti dal framework e per le app autonome destinate a Windows 10, versione 1903 o successiva, non è necessario l'inizializzatore automatico di attivazione senza registrazione. Queste app possono annullare l'iscrizione tramite <WindowsAppSdkUndockedRegFreeWinRTInitialize>false</WindowsAppSdkUndockedRegFreeWinRTInitialize>.
  • Inizializzatore automatico di compatibilità. Questo è necessario per consentire a un'app di utilizzare le strutture di contenimento A/B per controllare il comportamento di rilascio di assistenza. Per altre info, vedi RuntimeCompatibilityOptions.
    • Per le app che non usano il contenimento A/B (ovvero l'impostazione predefinita), non è necessario l'inizializzatore automatico di compatibilità.

Inizializzatore automatico di Deployment Manager

Quando un'app che usa il SDK per app di Windows 1.8 o versione successiva viene avviata, l'inizializzatore automatico di Deployment Manager viene eseguito by default. Ma puoi scegliere di non farlo accadere. Questa sezione illustra i vantaggi e le limitazioni di consentire l'esecuzione dell'inizializzatore automatico di Deployment Manager e aiuta a decidere se rinunciare.

Per consentire all'app di usare le funzionalità nei pacchetti Main/Singleton (ad esempio, notifiche push): 1. È necessario usare l'API di distribuzione per assicurarsi che tali pacchetti vengano distribuiti (perché i pacchetti Main/Singleton non sono framework, ma pacchetti "main", ad esempio le app, in modo che non possano essere registrati come dipendenze nel manifesto appx dell'app. L'API di distribuzione offre invece la funzionalità per distribuire tali pacchetti. 2. A causa di 1), l'app deve inizializzare Deployment Manager causando la chiamata di DeploymentManager.Initialize . L'app può eseguire questa operazione automaticamente o in modo esplicito, come vedremo. 3. L'app deve essere un'app in pacchetto dipendente dal framework in modo che richieda una dipendenza dai pacchetti Main/Singleton.

Un modo per inizializzare Deployment Manager consiste nell'consentire l'esecuzione dell'inizializzatore automatico di Deployment Manager (vedere la sezione Inizializzatoriauto nel SDK per app di Windows più indietro in questo argomento. L'inizializzatore automatico di Deployment Manager chiama DeploymentManager.Initialize automaticamente. L'altro modo per inizializzare Deployment Manager consiste nel chiamare in modo esplicito DeploymentManager.Initialize manualmente.

Se l'app (usando il SDK per app di Windows 1.8 o versione successiva) non richiede i pacchetti Main/Singleton, è quindi consigliabile rifiutare esplicitamente l'inizializzatore automatico di Deployment Manager impostando la proprietà WindowsAppSdkDeploymentManagerInitialize su false nel file di project dell'app.

Se l'app (usando il SDK per app di Windows 1.8 o versione successiva) does richiede i pacchetti Main/Singleton, è possibile:

  • Consentire l'esecuzione dell'inizializzatore automatico di Deployment Manager (operazione eseguita per impostazione predefinita)
  • o rifiutare esplicitamente l'inizializzatore automatico di Deployment Manager impostando la proprietà WindowsAppSdkDeploymentManagerInitialize su false nel file di project dell'app. È quindi necessario chiamare in modo esplicito DeploymentManager.Initialize manualmente.

Importante

Per qualsiasi processo in esecuzione in AppContainer, se si fa in modo che DeploymentManager.Initialize venga chiamato, l'app deve dichiarare la packageManagementfunzionalità con restrizioni nel manifesto del pacchetto.

proprietà del progetto

Nella tabella seguente sono riportate le proprietà che è possibile impostare nel file di project dell'app. Vedere la sezione precedente (sopra) per informazioni dettagliate sugli inizializzatori automatici nel SDK per app di Windows.

Nome e descrizione della proprietà Valori Per altre info
AppxPackage. Specifica se un'app WinUI è in pacchetto o meno. false (per un'app non in pacchetto) o assente (per un'app in pacchetto) Annullare il pacchetto di un'app WinUI
EnableMsixTooling. Abilita la funzionalità MSIX per un progetto singolo. true (per abilitare) o assente (per disabilitare) Confeziona l'app usando MSIX a singolo progetto
UseCrtSDKReferenceStaticWarning. Elimina l'avviso di compilazione che viene generato quando un'app in pacchetto C++ collega in modo statico il CRT (necessario per la distribuzione autonoma usando CRT ibrido). Impostare su false nei progetti di app in pacchetto che optano per CRT ibrido. false (per eliminare l'avviso nelle app autonome in pacchetto) o assente (impostazione predefinita, avviso abilitato) guida alla distribuzione di SDK per app di Windows per le app autonome
UseWinUI. Specifica se si usa il framework dell'interfaccia utente WinUI nell'app. true, o assente (per false) WinUI nel SDK per app di Windows (WinUI)
WindowsAppSDKSingleFileVerifyConfiguration. Determina se l’SDK esegue un target di convalida in fase di compilazione quando PublishSingleFile è impostato. Se abilitata (impostazione predefinita), la destinazione genera errori se mancano le proprietà necessarie (EnableMsixTooling, WindowsPackageType=None, IncludeAllContentForSelfExtract) e gli avvisi se le impostazioni autonome sono assenti (WindowsAppSDKSelfContained, SelfContained). Impostare su false solo per eliminare tutti i controlli, ad esempio nelle pipeline CI in cui è stata verificata la conformità manualmente. true (impostazione predefinita - esecuzioni di convalida), false (elimina tutti i controlli) Definito in Microsoft.WindowsAppSDK.SingleFile.targets (incluso automaticamente dal pacchetto NuGet quando PublishSingleFile è impostato)
WindowsAppSdkBootstrapInitialize. Determina se il SDK per app di Windows sfrutta il bootstrapper/l'inizializzatore automatico delle dipendenze dinamiche. true (impostazione predefinita per i file eseguibili), false (impostazione predefinita per i file non eseguibili) Esclusione (o inclusione) degli inizializzatori automatici
WindowsAppSdkDeploymentManagerInitialize. Determina se il SDK per app di Windows sfrutta l'inizializzatore automatico di Deployment Manager. true (impostazione predefinita), false
WindowsAppSDKRuntimePatchLevel1, WindowsAppSDKRuntimePatchLevel2 e WindowsAppSDKDisabledChanges. Verifica se il SDK per app di Windows utilizza l'auto-inizializzatore di compatibilità e configura le opzioni di compatibilità desiderate per il comportamento in fase di esecuzione del SDK per app di Windows delle modifiche aggiunte negli aggiornamenti di servizio. Vari o assenti (per disabilitare l'inizializzatore automatico) RuntimeCompatibilityOptions
WindowsAppSDKSelfContained. Determina se un'app viene distribuita autonomamente. true, o assente (per false) guida alla distribuzione di SDK per app di Windows per le app autonome
WindowsAppSdkUndockedRegFreeWinRTInitialize. Determina se il SDK per app di Windows sfrutta l'inizializzatore automatico di attivazione senza registrazione. true (impostazione predefinita per i file eseguibili), false (impostazione predefinita per i file non eseguibili) Scelta di rinunciare a (o aderire a) il supporto automatico per UndockedRegFreeWinRT
WindowsPackageType. L'impostazione di <WindowsPackageType>None</WindowsPackageType> per un'app senza pacchetto fa sì che il bootstrapper/inizializzatore automatico delle dipendenze dinamiche individui e carichi la versione di SDK per app di Windows più appropriata per l'app. Nessuno o assente (per disabilitare l'inizializzatore automatico) Annullare il pacchetto di un'app WinUI

Dietro le quinte e scegliere di non utilizzare gli inizializzatori automatici

Example

Ecco un estratto da un tipico file .csproj per un progetto WinUI 3 C#, che mostra alcune delle proprietà del progetto della tabella precedente in uso.

...
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
  </PropertyGroup>
...
  • Last updated on