Usando a CLI do winapp com o Rust

Este guia demonstra como usar a winapp CLI com um aplicativo Rust para depurar utilizando a identidade do pacote e empacotar seu aplicativo no formato MSIX.

Para obter um exemplo de trabalho completo, confira o exemplo do Rust neste repositório.

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

  1. Rust Toolchain: instalar o Rust usando rustup ou winget (ou atualizar se já estiver instalado):

    winget install Rustlang.Rustup --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. Criar um novo aplicativo Rust

Comece criando um aplicativo Rust simples:

cargo new rust-app
cd rust-app

Execute-o para verificar se tudo está funcionando:

cargo 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. Isso nos ajudará a verificar se a identidade está funcionando corretamente em etapas posteriores. Usaremos o windows crate para acessar APIs do Windows.

Primeiro, adicione a windows dependência à sua Cargo.toml executando:

cargo add windows --features ApplicationModel

Isso adiciona as associações de API Windows com o recurso ApplicationModel, que nos dá acesso à API Package para verificar a identidade.

Em seguida, substitua todo o conteúdo src/main.rs pelo código a seguir. Esse código tenta recuperar a identidade do pacote atual. Se for bem-sucedido, ele imprimirá o Nome da Família de Pacotes; senão, imprimirá "Não empacotado".

Note

O exemplo full também inclui código para mostrar uma notificação de Windows se a identidade estiver presente, mas, para este guia, nos concentraremos na verificação de identidade.

use windows::ApplicationModel::Package;

fn main() {
    match Package::Current() {
        Ok(package) => {
            match package.Id() {
                Ok(id) => match id.FamilyName() {
                    Ok(name) => println!("Package Family Name: {}", name),
                    Err(e) => println!("Error getting family name: {}", e),
                },
                Err(e) => println!("Error getting package ID: {}", e),
            }
        }
        Err(_) => println!("Not packaged"),
    }
}

3. Executar sem identidade

Agora, crie e execute o aplicativo como de costume:

cargo 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 winapp init comando configura tudo o que você precisa de uma só vez: manifesto do aplicativo e ativos. O manifesto define a identidade do aplicativo (nome, editor, versão) que Windows usa para conceder acesso à API.

Execute o seguinte comando e siga os prompts:

winapp init

Quando solicitado:

  • Nome do pacote: Pressione Enter para aceitar o padrão (rust-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
  • Descrição: pressione Enter para aceitar o padrão ou inserir uma descrição
  • Configurar SDKs: selecione "Não configurar SDKs" (o Rust usa seu próprio windows crate, não os cabeçalhos do SDK do C++)

Este comando será:

  • Criar Package.appxmanifest — o manifesto que define a identidade do aplicativo
  • Criar Assets pasta — ícones necessários para empacotamento MSIX e envio para a Loja

Note

Como nenhum pacote do SDK está sendo gerenciado, nenhum winapp.yaml é criado – o Rust usa o windows crate via Cargo, portanto, não há nada para winapp restore/update rastrear.

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

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

Como cargo new cria um aplicativo de console, precisamos adicionar um alias de execução ao manifesto. Sem esse elemento, winapp run inicia o aplicativo por meio da ativação AUMID, que abre uma nova janela — e essa janela se fecha imediatamente quando um aplicativo de console é concluído, suprimindo qualquer saída.

O alias também permite que os usuários executem seu aplicativo pelo nome de qualquer terminal depois que instalam o MSIX. O manifesto registra um alias como rust-app.exe (padrão para o nome exe do projeto), que os usuários podem invocar como rust-app ou rust-app.exe.

Ignore esta etapa se você estiver criando um aplicativo de interface do usuário (um aplicativo Rust que renderiza sua própria janela). Esses aplicativos funcionam bem com a inicialização AUMID padrão.

Adicione o alias:

winapp manifest add-alias

Isso adiciona uma uap5:ExecutionAlias entrada a Package.appxmanifest.

5. Depurar com Identidade

Para testar recursos que exigem identidade (como Notificações) sem empacotar totalmente o aplicativo, use winapp run. Isso registra toda a pasta de saída de compilação como um pacote de layout solto — exatamente como uma instalação MSIX real — e inicia o aplicativo. Nenhum certificado ou assinatura é necessário para depuração.

  1. Crie o executável:

    cargo build

  2. Executar com identidade:

    winapp run .\target\debug --with-alias

O --with-alias flag inicia o aplicativo através de seu alias de execução, com que a saída do console permaneça no terminal atual. Isso requer o uap5:ExecutionAlias que adicionamos na etapa 4.

Note

winapp run também registra o pacote em seu sistema. É por isso que o MSIX pode aparecer como "já instalado" quando você tentar instalá-lo posteriormente na etapa 6. Use winapp unregister para limpar pacotes de desenvolvimento quando terminar.

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

Package Family Name: rust-app_12345abcde

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

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.

6. Empacotar com MSIX

Quando estiver pronto para distribuir seu aplicativo, você poderá empacotá-lo como um MSIX usando o mesmo manifesto. O MSIX fornece instalação/desinstalação limpa, atualizações automáticas e uma experiência de instalação confiável.

Preparar o diretório do pacote

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

cargo build --release

Em seguida, crie um diretório apenas com os arquivos necessários para distribuição. A target\release pasta contém artefatos de build que não fazem parte do seu aplicativo. Só precisamos do executável:

mkdir dist
copy .\target\release\rust-app.exe .\dist\

Gerar um certificado de desenvolvimento

Os pacotes MSIX devem ser assinados. Para testes locais, gere um certificado de desenvolvimento autoassinado:

winapp cert generate --if-exists skip

Importante

O emissor do certificado deve corresponder ao Publisher em seu Package.appxmanifest. O cert generate comando lê isso automaticamente do manifesto.

Assinar e empacotar

Agora você pode empacotar e assinar em uma etapa:

winapp pack .\dist --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 confiar no certificado de desenvolvimento em seu computador. Execute este comando como administrador (você só precisa fazer isso uma vez por certificado):

winapp cert install .\devcert.pfx

Instalar e executar

Note

Se você usou winapp run na etapa 5, o pacote pode já estar registrado em seu sistema. Use winapp unregister primeiro para remover o registro de desenvolvimento e, em seguida, instale o pacote de lançamento.

Instale o pacote clicando duas vezes no arquivo gerado .msix ou por meio do PowerShell:

Add-AppxPackage .\rust-app.msix

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

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

  1. 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
  2. O Microsoft Store assinará o MSIX para você, não é necessário assinar antes do envio.
  3. Talvez seja necessário criar vários pacotes MSIX, um para cada arquitetura compatível (x64, Arm64)

Próximas etapas

  • Last updated on