Propriedades do Project e inicializadores automáticos

Este tópico descreve as propriedades project que pode definir no seu ficheiro Visual Studio project (como .csproj ou .vcxproj) para personalizar a forma como a sua aplicação é implementada, incluindo a configuração de inicializadores automáticos.

Auto-inicializadores no SDK de Aplicações Windows

No SDK de Aplicações Windows, existem várias rotinas cuja função é garantir que o Aplicação do Windows Runtime está devidamente inicializado. Essas rotinas são conhecidas como inicializadores automáticos, porque são executadas automaticamente antes do ponto de entrada do aplicativo e fazem o trabalho de inicialização para você.

Sugestão

Caso esteja curioso sobre detalhes técnicos. Em C++, um inicializador automático é implementado com um construtor de classe estática. Em C#, um autoinicializador é implementado com um inicializador de módulo .NET. Portanto, às vezes você pode ouvir o inicializador de módulo usado quando o termo adequado é inicializador automático.

Todos os inicializadores automáticos são habilitados condicionalmente por padrão, com base na configuração de empacotamento e implantação do seu aplicativo. Aqui estão detalhes sobre eles:

  • Inicializador automático do Bootstrapper (também conhecido como dependências dinâmicas). Este inicializador automático chama a API de bootstrapper automaticamente na inicialização do aplicativo. É necessário para aplicações não embaladas dependentes do framework, a fim de garantir que o Aplicação do Windows Runtime seja adicionado ao grafo de pacotes da aplicação. Para informações sobre aplicações dependentes do framework (e autónomas), veja SDK de Aplicações Windows deployment overview. Para obter informações sobre aplicativos não empacotados (e empacotados), consulte Aplicativos do Windows: empacotamento, implantação e processo.
    • Para uma aplicação empacotada, não é necessário o inicializador automático de dependências dinâmicas/bootstrapper porque o arquivo appxmanifest.xml expressa a dependência do framework. E para uma aplicação autónoma, não precisa do inicializador automático de dependências dinâmicas/bootstrapper porque essas aplicações não utilizam o framework.
    • Pode optar por não usar o inicializador automático de bootstrapper/dependências dinâmicas no seu arquivo .csproj ou .vcxproj via <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize>.
  • Inicializador automático do Deployment Manager. Isso é necessário para aplicativos empacotados que dependem de uma estrutura de software e que usam funcionalidades principais/singleton (por exemplo, notificações por push), porque essas dependências não podem ser expressas pelo arquivo appxmanifest.xml.
    • Para um aplicativo independente, você não precisa do inicializador automático do Deployment Manager porque esses aplicativos não suportam a funcionalidade principal/singleton.
    • Para obter informações mais importantes, consulte a seção O inicializador automático do Deployment Manager mais adiante neste tópico.
  • Inicializador automático de ativação sem necessidade de registo. Isto é obrigatório para que uma aplicação autónoma utilize ativação de Windows Runtime sem registo (WinRT) baseada em manifestos, sem dock (UndockedRegFreeWinRT), se a aplicação estiver a correr downlevel numa versão do sistema operativo anterior à atualização de maio de Windows 10 de 2019 (versão 1903; nome de código "19H1").
    • Para aplicações dependentes do framework, e para aplicações autónomas que têm como objetivo Windows 10, versão 1903 ou posterior, não precisa do inicializador automático de ativação sem registo. Essas aplicações podem desativar-se através de <WindowsAppSdkUndockedRegFreeWinRTInitialize>false</WindowsAppSdkUndockedRegFreeWinRTInitialize>.
  • Inicializador automático de compatibilidade. Isso é necessário para que uma aplicação use instalações de contenção A/B para controlar o comportamento de lançamento de atualizações de serviço. Para obter mais informações, consulte RuntimeCompatibilityOptions.
    • Para aplicativos que não usam contenção A/B (que é o padrão), você não precisa do inicializador automático de compatibilidade.

O inicializador automático do Deployment Manager

Quando uma aplicação que usa a SDK de Aplicações Windows 1.8 ou posterior arranca, o inicializador automático do Gestor de Implementação executa por defeito. Mas você pode optar por não que isso aconteça. Esta seção explica os benefícios e as advertências de permitir que o inicializador automático do Deployment Manager seja executado e ajuda você a decidir se deseja ou não desativar.

Para que seu aplicativo use a funcionalidade nos pacotes Main/Singleton (por exemplo, notificações por push): 1. Você deve usar a API de Implantação para garantir que esses pacotes sejam implantados (porque os pacotes Main/Singleton não são estruturas, mas pacotes "principais", como aplicativos; portanto, eles não podem ser registrados como dependências no manifesto appx do seu aplicativo. Em vez disso, a API de implantação fornece a funcionalidade para implantar esses pacotes). 2. Devido a 1), seu aplicativo precisa inicializar o Deployment Manager fazendo com que DeploymentManager.Initialize seja chamado. Seu aplicativo pode fazer isso automaticamente ou explicitamente, como veremos. 3. Seu aplicativo precisa ser um aplicativo empacotado dependente do framework, de modo a ter uma dependência dos pacotes Main/Singleton.

Uma forma de inicializar o Gestor de Implementação é permitir que o auto-inicializador do Gestor de Implantações seja executado (ver a secção Auto-inicializadores no SDK de Aplicações Windows anteriormente neste tópico). O inicializador automático do Deployment Manager chama DeploymentManager.Initialize para você. A outra maneira de inicializar o Deployment Manager é chamar explicitamente DeploymentManager.Initialize por si mesmo.

Se a sua aplicação (usando o SDK de Aplicações Windows 1.8 ou posterior) não precisar dos pacotes Main/Singleton, então deve optar por não usar o auto-inicializador do Gestor de Implementação definindo a propriedade WindowsAppSdkDeploymentManagerInitialize para false no ficheiro de project da sua aplicação.

Se a sua aplicação (usando o SDK de Aplicações Windows 1.8 ou posterior) precisar dos pacotes Main/Singleton, então pode:

  • Permitir que o inicializador automático do Deployment Manager seja executado (o que ele faz por padrão),
  • ou optar por sair do autoinicializador do Gestor de Implementação definindo a propriedade WindowsAppSdkDeploymentManagerInitialize para false no ficheiro de project da sua aplicação. Em seguida, você deve chamar explicitamente DeploymentManager.Initialize você mesmo.

Importante

Para qualquer processo em execução no AppContainer, se você fizer com que DeploymentManager.Initialize seja chamado, seu aplicativo precisará declarar o packageManagement no manifesto do pacote.

Propriedades do Projeto

Na tabela abaixo estão as propriedades que pode definir no ficheiro de project da sua aplicação. Consulte a secção anterior (acima) para detalhes sobre os auto-inicializadores no SDK de Aplicações Windows.

Nome e descrição do imóvel Valores Para mais informações
AppxPackage. Especifica se uma aplicação WinUI está ou não incluída. false (para um aplicativo não empacotado) ou ausente (para um aplicativo empacotado) Desempacotar uma aplicação WinUI
EnableMsixTooling. Ativa a funcionalidade MSIX de projeto único para um projeto. true (para habilitar), ou ausente (para desabilitar) Empacote a sua aplicação utilizando MSIX de projeto único
UseCrtSDKReferenceStaticWarning. Suprime o aviso de compilação que dispara quando uma aplicação em C++ liga o CRT de forma estática (o que é necessário para implementação autónoma usando o CRT híbrido). Definido como falso nos projetos de aplicações empacotadas que optam pelo CRT híbrido. false (para suprimir o aviso em aplicações autónomas empacotadas), ou ausente (por defeito, aviso ativado) SDK de Aplicações Windows guia de implementação para aplicações autónomas
UseWinUI. Especifica se está a usar o framework de interface do WinUI na sua aplicação. verdadeiro, ou ausente (para falso) WinUI na SDK de Aplicações Windows (WinUI)
WindowsAppSDKSingleFileVerifyConfiguration. Controla se o SDK executa um alvo de validação em tempo de construção quando PublishSingleFile está definido. Quando ativado (o padrão), o alvo emite erros se as propriedades necessárias estiverem em falta (EnableMsixTooling, WindowsPackageType=None, IncludeAllContentForSelfExtract) e avisos se as definições autónomas estiverem ausentes (WindowsAppSDKSelfContained, SelfContained). Defina como false apenas para suprimir todas as verificações — por exemplo, em pipelines de integração contínua em que a conformidade foi verificada manualmente. true (por predefinição — a validação é executada), false (suprime todas as validações) Definido em Microsoft.WindowsAppSDK.SingleFile.targets (incluído automaticamente pelo pacote NuGet quando PublishSingleFile está definido)
WindowsAppSdkBootstrapInitialize. Determina se o SDK de Aplicações Windows utiliza ou não o inicializador automático de bootstrapper ou de dependências dinâmicas. true (o padrão para executáveis), false (o padrão para não executáveis) Optar por desativar (ou ativar) inicializadores automáticos
WindowsAppSdkDeploymentManagerInitialize. Determina se o SDK de Aplicações Windows utiliza ou não o autoinicializador do Gestor de Implementação. true (o padrão), false
WindowsAppSDKRuntimePatchLevel1, WindowsAppSDKRuntimePatchLevel2 e WindowsAppSDKDisabledChanges. Determina se o SDK de Aplicações Windows aproveita ou não o inicializador automático de compatibilidade e configura quaisquer opções de compatibilidade desejadas para o comportamento do Aplicação do Windows Runtime das alterações adicionadas nas atualizações de serviço. Vários, ou ausente (para desativar o inicializador automático) RuntimeCompatibilityOptions
WindowsAppSDKSelfContained. Determina se um aplicativo é implantado de forma autônoma ou não. verdadeiro, ou ausente (para falso) SDK de Aplicações Windows guia de implementação para aplicações autónomas
WindowsAppSdkUndockedRegFreeWinRTInitialize. Determina se o SDK de Aplicações Windows utiliza ou não o inicializador automático de ativação sem registo. true (o padrão para executáveis), false (o padrão para não executáveis) Optar por não receber (ou para) o suporte automático a UndockedRegFreeWinRT
WindowsPackageType. Definir <WindowsPackageType>None</WindowsPackageType> numa aplicação não empacotada faz com que o inicializador automático do bootstrapper/das dependências dinâmicas localize e carregue a versão do SDK de Aplicações Windows mais adequada à sua aplicação. Nenhum, ou ausente (para desativar o inicializador automático) Desempacotar uma aplicação WinUI

Nos bastidores e a opção de não usar inicializadores automáticos

Example

Aqui está um excerto de um ficheiro típico .csproj para um projeto C# WinUI 3, mostrando algumas das propriedades do projeto da tabela acima em utilização.

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