Usando a CLI do Winapp com .NET

Este guia deve funcionar para a maioria dos tipos de projeto .NET. As etapas foram testadas com projetos baseados em console e interface do usuário, como WPF. Para obter exemplos de trabalho, confira os exemplos dotnet-app (console) e wpf-app (WPF) na pasta de exemplos.

Este guia demonstra como usar a CLI winapp com um aplicativo .NET para depurar usando a identidade do pacote e empacotar seu aplicativo como MSIX.

A identidade do pacote é um conceito básico no modelo de Windows app. Ele permite que seu aplicativo acesse APIs de Windows específicas (como Notificações, Segurança, APIs de IA etc.), ter uma experiência de instalação/desinstalação limpa e muito mais.

Um executável padrão (como um criado com dotnet build) não tem a identidade do pacote. Este guia mostra como adicionar para depuração e, em seguida, empacotar para distribuição.

Pré-requisitos

.NET SDK: instale o SDK do .NET (requer uma reinicialização após a instalação):
```
winget install Microsoft.DotNet.SDK.10 --source winget
```
CLI do winapp: instalar a winapp ferramenta por meio do winget (ou atualizar se já estiver instalado):
```
winget install Microsoft.winappcli --source winget
```

1. Criar um novo aplicativo .NET

Comece criando um aplicativo de console .NET simples:

dotnet new console -n dotnet-app
cd dotnet-app

Execute-o para verificar se tudo está funcionando:

dotnet run

A saída deve ser "Olá, Mundo!"

2. Atualizar código para verificar identidade

Atualizaremos o aplicativo para verificar se ele está em execução com a identidade do pacote. Usaremos a API Windows Runtime para acessar as APIs do Pacote.

Primeiro, atualize o arquivo project para direcionar uma versão específica do SDK do Windows. Abra dotnet-app.csproj e altere o TargetFramework para incluir a versão do SDK Windows:

  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

Isso lhe dá acesso a APIs de Windows Runtime sem precisar de pacotes adicionais.

Agora substitua o conteúdo de Program.cs pelo seguinte código. Esse código tenta recuperar a identidade do pacote atual usando a API Windows Runtime. Se for bem-sucedido, ele imprime o Nome da Família de Pacotes; caso contrário, ele imprime 'Não empacotado'.

using Windows.ApplicationModel;

try
{
    var package = Package.Current;
    var familyName = package.Id.FamilyName;
    Console.WriteLine($"Package Family Name: {familyName}");
}
catch (InvalidOperationException)
{
    // Thrown when app doesn't have package identity
    Console.WriteLine("Not packaged");
}

3. Executar sem identidade

Agora, execute o aplicativo como de costume:

dotnet run

Você deve ver a saída "Não empacotado". Isso confirma que o executável padrão está em execução sem nenhuma identidade de pacote.

4. Inicializar Project com a CLI do winapp

O comando winapp init detecta automaticamente arquivos .csproj e executa uma configuração específica .NET. Ele configura tudo o que você precisa de uma só vez: valida o seu TargetFramework, adiciona os pacotes NuGet necessários, gera o manifesto do aplicativo e os ativos.

Execute o seguinte comando e siga os prompts:

winapp init

Quando solicitado:

Nome do pacote: Pressione Enter para aceitar o padrão (dotnet-app)
Nome do publicador: pressione Enter para aceitar o valor padrão ou insira seu nome
Versão: Pressione Enter para aceitar 1.0.0.0
Description: Pressione Enter para aceitar o padrão (aplicativo Windows) ou insira uma descrição
SDK do Aplicativo Windows configuração: Selecione Estável, Visualização ou Experimental (determina qual versão SDK do Aplicativo Windows é adicionada)
TargetFramework update: se o TargetFramework não incluir uma versão do SDK Windows com suporte, você será solicitado a atualizá-la (por exemplo, para net10.0-windows10.0.26100.0)
Modo de Desenvolvedor: se você for solicitado sobre o "Modo de Desenvolvedor", poderá ativá-lo se desejar, mas esteja ciente de que ele requer privilégios administrativos

Este comando será:

Atualize o TargetFramework no seu .csproj para um TFM do Windows compatível (se necessário)
Adicione Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools e referências de pacote NuGet Microsoft.Windows.SDK.BuildTools.WinApp ao .csproj
Criar Package.appxmanifest e Assets pasta para a identidade do aplicativo

Observação

Ao contrário de projetos nativos/C++, o fluxo de .NET não cria um arquivo . Os pacotes NuGet são gerenciados diretamente por meio de sua .csproj. Use dotnet restore para restaurar pacotes após a clonagem.

Você pode abrir Package.appxmanifest para personalizar ainda mais as propriedades, como o nome de exibição, o editor e os recursos.

Para verificar se os pacotes foram adicionados ao seu projeto:

dotnet list package

Você deverá ver Microsoft.WindowsAppSDK e Microsoft.Windows.SDK.BuildTools na saída.

Adicionar alias de execução (para aplicativos de console)

Como estamos criando um aplicativo de console, precisamos garantir que dotnet run mantenha a saída do console no terminal atual. Por padrão, dotnet run inicia o aplicativo empacotado por meio da ativação AUMID, que abre uma nova janela e a janela é fechada imediatamente quando o aplicativo de console termina, engolindo qualquer saída.

Para corrigir isso, você adicionará um alias de execução ao manifesto e instruirá a integração de execução a iniciar através desse alias.

Pule esta etapa se você estiver criando um aplicativo de interface do usuário (WPF, WinForms, WinUI). Esses aplicativos renderizam sua própria janela, portanto, a inicialização padrão do AUMID é o que você deseja.

Adicione o alias de execução ao manifesto:
```
winapp manifest add-alias
```
Isso adiciona um uap5:ExecutionAlias ao Package.appxmanifest (padronizando para o nome exe do seu projeto) para que o aplicativo possa ser iniciado pelo nome a partir de um terminal.
Diga à integração dotnet run para usar o alias. Abra dotnet-app.csproj e adicione o seguinte dentro de qualquer <PropertyGroup> (ou crie um novo, <PropertyGroup> se necessário):
```
<WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
```
Com essa propriedade definida, dotnet run inicia o aplicativo através de seu nome de execução e herda as entradas/saídas stdin/stdout/stderr do terminal atual para que você veja a saída do console diretamente.

5. Depurar com Identidade

Como winapp init adicionou o pacote NuGet Microsoft.Windows.SDK.BuildTools.WinApp ao seu projeto, você pode simplesmente executar:

dotnet run

Isso invoca automaticamente winapp run nos bastidores – criando um pacote de layout flexível, registrando-o no Windows e iniciando seu aplicativo com a identidade completa do pacote.

Observação

Você pode ver avisos de vulnerabilidade do NuGet (NU1900) sobre fontes de pacotes. Elas são seguras de ignorar– elas não afetam seu build.

Você deverá ver uma saída semelhante a:

Package Family Name: dotnet-app_12345abcde

Isso confirma que seu aplicativo está em execução com uma identidade de pacote válida!

Alternativa: Manual `winapp run`

Se você não usou winapp init (ou removeu o pacote NuGet), poderá compilar e executar manualmente:

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Para adicionar o pacote NuGet de volta: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Dica

Para desabilitar a integração automática dotnet run , adicione <EnableWinAppRunSupport>false</EnableWinAppRunSupport> ao seu .csproj. Consulte a documentação de suporte do dotnet run para opções de personalização.

Alternativa: identidade de pacote esparso

Se você precisar de um comportamento de pacote esparso especificamente (identidade sem copiar arquivos), poderá usar create-debug-identity em vez disso. Isso registra um pacote esparso apontando para seu exe em vez de criar um layout flexível:

winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Em seguida, execute o executável diretamente (não use dotnet run , pois ele pode recompilar/substituir o arquivo):

.\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Alternativa: destino manual do MSBuild

Se preferir não usar o pacote NuGet, você poderá adicionar um destino personalizado do MSBuild que é executado create-debug-identity após compilações de Debug. Adicione isso ao seu arquivo .csproj no final, pouco antes da tag de fechamento </Project>:

  <!-- Automatically apply debug identity after Debug builds -->
  <Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Com esta configuração, dotnet build aplica a identidade de debug e você pode executar o executável diretamente. Note que dotnet run pode recompilar e substituir a identidade, portanto, execute o exe manualmente após a compilação.

Dica

Para obter fluxos de trabalho avançados de depuração (anexando depuradores, configuração de IDE, depuração de inicialização), consulte o Guia de Depuração.

Quando ignorar isso: se você preferir o controle explícito sobre quando a identidade é aplicada ou se você estiver trabalhando em um código que não precise de identidade para a maior parte do ciclo de desenvolvimento, a abordagem manual acima pode ser mais simples.

6. Usando SDK do Aplicativo Windows (opcional)

O SDK do Aplicativo Windows fornece acesso a APIs de Windows modernas além do que o SDK do Windows base fornece : coisas como o sistema de notificação, APIs de janela, gerenciamento do ciclo de vida do aplicativo e IA no dispositivo. Se seu aplicativo precisar de qualquer um desses recursos, essa etapa será para você. Se você precisar apenas da identidade do pacote para distribuição, poderá pular para a etapa 7.

Se você executou winapp init (Etapa 4), Microsoft.WindowsAppSDK já foi adicionado como uma referência de pacote NuGet ao seu .csproj. Você pode verificar com dotnet list package. Se você ignorou a instalação do SDK durante a inicialização ou precisa adicioná-la manualmente, execute:

dotnet add package Microsoft.WindowsAppSDK

Atualizar Program.cs

Substitua todo o conteúdo de Program.cs pelo código a seguir, que adiciona uma verificação de versão do aplicativo do Windows Runtime:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");
            
            // Get Windows App Runtime version using the API
            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            // Thrown when app doesn't have package identity
            Console.WriteLine("Not packaged");
        }
    }
}

Compilar e executar

Recompile e execute o aplicativo com SDK do Aplicativo Windows. Como adicionamos o WinAppSDK, precisamos registrar novamente com identidade para que winapp adicione a dependência de runtime. Se você adicionou o pacote NuGet do WinApp (recomendado), basta executar dotnet run. Caso contrário (substitua dotnet-app pelo nome do projeto):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Agora, você deve ver uma saída semelhante a:

Package Family Name: dotnet-app.debug_12345abcde
Windows App Runtime Version: 8000.770.947.0

O pacote NuGet SDK do Aplicativo Windows inclui todos os assemblies necessários para acessar APIs de Windows modernas, incluindo:

Notificações e azulejos dinâmicos
Ciclo de vida de janelas e aplicativos
Notificações por push
E muitos outros componentes do SDK do Aplicativo Windows

Para obter um uso mais avançado de SDK do Aplicativo Windows, confira a documentação SDK do Aplicativo Windows.

7. Empacotar com MSIX

Quando estiver pronto para distribuir seu aplicativo, você poderá empacotá-lo como um MSIX usando o mesmo manifesto.

Preparar para lançamento

Primeiro, crie seu aplicativo no modo de versão para um desempenho ideal:

dotnet build -c Release

Observação

Você pode ver avisos de vulnerabilidade do NuGet (NU1900). Seguras para serem ignoradas, elas não afetam o resultado da compilação.

Gerar um certificado de desenvolvimento

Antes de empacotar, você precisa de um certificado de desenvolvimento para assinatura. Gere um, se ainda não tiver feito isso.

winapp cert generate --if-exists skip

Assinar e empacotar

Agora você pode pacotar e assinar. Aponte o comando 'pack' para a pasta de saída de build (substitua dotnet-app e o caminho TFM pelos valores do projeto):

# package and sign the app with the generated certificate
winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --cert .\devcert.pfx

Observação: o pack comando usa automaticamente o Package.appxmanifest do diretório atual e copia-o para a pasta de destino antes do empacotamento. O arquivo .msix gerado estará no diretório atual.

Instalar o certificado

Antes de instalar o pacote MSIX, você precisa instalar o certificado de desenvolvimento. Execute este comando como administrador:

winapp cert install .\devcert.pfx

Instalar e executar

Instale o pacote clicando duas vezes no arquivo *.msix gerado.

Agora você pode executar seu aplicativo de qualquer lugar no terminal digitando:

dotnet-app

Você deverá visualizar a saída "Nome da Família de Pacotes", o que confirmará que o pacote está instalado e em execução com sua identidade.

Dica

Se você precisar reempacotar seu aplicativo (por exemplo, após alterações de código), incremente-o Version antes Package.appxmanifest de executar winapp pack novamente. Windows requer um número de versão mais alto para atualizar um pacote instalado.

Dicas

Quando estiver pronto para distribuição, você poderá assinar seu MSIX com um certificado de assinatura de código de uma Autoridade de Certificação para que os usuários não precisem instalar um certificado autoassinado.
O Microsoft Store assinará o MSIX para você, não é necessário assinar antes do envio.
Talvez seja necessário criar vários pacotes MSIX, um para cada arquitetura compatível (x64, Arm64). Use a -r flag com dotnet build para especificar arquiteturas específicas: dotnet build -c Release -r win-x64 ou dotnet build -c Release -r win-arm64.

Automatizando o empacotamento MSIX (opcional)

Para automatizar o empacotamento MSIX como parte das suas compilações de versão, adicione este alvo ao arquivo .csproj (você pode adicioná-lo ao lado do alvo de identidade de depuração).

  <!-- Automatically package as MSIX after Release builds -->
  <Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <!-- Package and sign directly from build output -->
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Com esta configuração:

Compilar no modo de versão (dotnet build -c Release) criará automaticamente o pacote MSIX
O MSIX é empacotado e assinado com seu certificado de desenvolvimento
O arquivo final .msix estará na raiz do projeto

Você também pode criar uma configuração personalizada (por exemplo, PackagedRelease) modificando a condição para '$(Configuration)' == 'PackagedRelease'.

Próximas etapas

Distribute via winget: envie seu MSIX para o repositório da comunidade Windows Gerenciador de Pacotes
Publicar na Microsoft Store: use winapp store para enviar seu pacote
Set up CI/CD: Use a Ação do setup-WinAppCli GitHub para automatizar o empacotamento em seu pipeline
Explore Windows APIs: com a identidade do pacote, agora você pode usar Notificações, IA no dispositivo e outras APIs dependentes de identidade

Comentários

Esta página foi útil?

Last updated on 2026-05-12

Usando a CLI do Winapp com .NET

Pré-requisitos

1. Criar um novo aplicativo .NET

2. Atualizar código para verificar identidade

3. Executar sem identidade

4. Inicializar Project com a CLI do winapp

Adicionar alias de execução (para aplicativos de console)

5. Depurar com Identidade

Alternativa: Manual winapp run

Alternativa: identidade de pacote esparso

Alternativa: destino manual do MSBuild

6. Usando SDK do Aplicativo Windows (opcional)

Atualizar Program.cs

Compilar e executar

7. Empacotar com MSIX

Preparar para lançamento

Gerar um certificado de desenvolvimento

Assinar e empacotar

Instalar o certificado

Instalar e executar

Dicas

Automatizando o empacotamento MSIX (opcional)

Próximas etapas

Comentários

Recursos adicionais

Alternativa: Manual `winapp run`