Usando a CLI do winapp com aplicativos .NET baseados em arquivo

Para obter um exemplo funcional, consulte o exemplo dotnet-file-app. Para obter a referência completa, consulte o modo de arquivo único na referência da CLI.

.NET 10 pode executar um único arquivo .cs sem nenhum arquivo de projeto. Este guia mostra como executar esse arquivo com a identidade do pacote usando winapp run, para que APIs como Windows.ApplicationModel.Package.Current, notificações de aplicativo e IA no dispositivo funcionem. Você não cria um manifesto ou ativos de imagem: o winapp os gera para você.

A identidade do pacote é um conceito básico no modelo de Windows app. Ele permite que seu aplicativo acesse APIs Windows específicas, tenha uma experiência de instalação/desinstalação limpa e muito mais. Um aplicativo baseado em arquivo executado com dotnet run não tem identidade de pacote.

Prerequisites

1. .NET SDK 10.0.300 ou posterior: instale o SDK do .NET 10 (requer uma reinicialização após a instalação):

   winget install Microsoft.DotNet.SDK.10 --source winget
   

2. CLI do winapp: instalar a winapp ferramenta por meio do winget (ou atualizar se já estiver instalado):

   winget install Microsoft.winappcli --source winget
   

1. Crie um app baseado em arquivo

Crie uma pasta com um arquivo chamado hello.cs:

#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

using Windows.ApplicationModel;

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

As #:property linhas configuram o aplicativo da maneira que um .csproj faria. O Windows TargetFramework fornece ao código acesso a APIs de Windows Runtime, como Package.

Execute-o com dotnet run:

dotnet run hello.cs

A saída é Not packaged: o aplicativo é executado sem o identificador de pacote.

2. Executar com a identidade do pacote

Execute o mesmo arquivo com o winapp:

winapp run hello.cs

O winapp cria o aplicativo, gera um manifesto e ativos de imagem padrão na saída de build, registra o aplicativo como um pacote e o inicia. A saída agora mostra a identidade do pacote:

Package Family Name: hello-<hash>_<publisher-hash>

Sua pasta de origem ainda contém apenas hello.cs. Como este é um aplicativo de console (OutputType=Exe), o winapp o inicia por meio de um alias de execução, portanto, sua saída aparece no terminal.

O registro permanece após o aplicativo ser fechado, portanto, executar winapp run hello.cs novamente reutiliza a mesma identidade. Remova-o na etapa 5.

3. Nomeie seu pacote

Por padrão, o nome do pacote é o nome do arquivo mais um hash curto do caminho do arquivo. Para escolher seu próprio nome, cancele o registro do pacote atual primeiro, pois um novo nome registra um novo pacote:

winapp unregister hello.cs

Em seguida, adicione as diretivas #:property à parte superior de hello.cs:

#:property WinAppPackageName=com.contoso.hello
#:property WinAppDisplayName=Contoso Hello
#:property Version=1.0.0

Execute-o novamente:

winapp run hello.cs

A saída mostra o novo nome, por exemplo Package Family Name: com.contoso.hello_<publisher-hash>. O aplicativo também aparece no menu Iniciar como Contoso Hello.

Para cada propriedade de identidade e seu valor padrão, consulte as Propriedades do manifesto.

4. Executar com dotnet run

Para obter a mesma inicialização empacotada de dotnet run simples, faça referência ao pacote Microsoft.Windows.SDK.BuildTools.WinApp na parte superior de hello.cs:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*

dotnet run hello.cs

A saída mostra o mesmo identificador de pacote do que winapp run. Como dotnet run é compilado em uma pasta de saída diferente, ele avisa que está substituindo um registro existente instalado de um local diferente. Isso é esperado e você pode ignorá-lo.

O pacote também fornece ao aplicativo um ícone temporário para a janela, de forma que um aplicativo em modo janela mostra um ícone em sua barra de título. Para usar o seu, aponte ApplicationIcon para um arquivo .ico:

#:property ApplicationIcon=Assets\MyApp.ico

Para as propriedades que controlam esta inicialização, consulte Execução com dotnet run.

5. Limpar

Remova o registro passando o arquivo .cs para winapp unregister:

winapp unregister hello.cs

Adicionar recursos ou um manifesto personalizado

Algumas APIs precisam de uma capacidade declarada. Por exemplo, as APIs de IA Windows precisamsystemAIModels:

#:property WinAppCapabilities=systemAIModels

o winapp grava cada capacidade no elemento de manifesto correto. Consulte Capacidades para obter a lista completa e as regras de nomenclatura.

Manipuladores de protocolo, associações de arquivo e outras integrações de shell precisam de um manifesto criado. Coloque um hello.appxmanifest ao lado de hello.cs e o winapp o usa em vez de gerar um. Consulte Traga seu próprio manifesto.

Próximas etapas

• Pacote para distribuição: winapp run registra o aplicativo somente para desenvolvimento. Para produzir um MSIX que você pode distribuir, mova seu código para um projeto e siga o Pacote com MSIX no guia .NET.
• Explore Windows APIs: com a identidade do pacote, agora você pode usar Notificações, IA no dispositivo e outras APIs dependentes de identidade