Usar a linha de comando winapp com Rust

Este guia demonstra como usar a winapp CLI numa aplicação Rust para depurar utilizando a identidade do pacote e empacotar a sua aplicação como um MSIX.

Para um exemplo completo e funcional, consulte o exemplo de Rust neste repositório.

A identidade de pacote é um conceito central no modelo de Windows app. Permite que a sua aplicação aceda a APIs específicas do Windows (como Notificações, Segurança, APIs de IA, etc.), tenha uma experiência limpa de instalação/desinstalação e muito mais.

Um executável padrão (como um criado com cargo build) não tem identidade de pacote. Este guia mostra como adicioná-lo para depuração e depois empacotar para distribuição.

Pré-requisitos

1. Rust Toolchain: Instale Rust usando rustup ou winget (ou atualize se já estiver instalado):

   winget install Rustlang.Rustup --source winget
   

2. winapp CLI: Instale a winapp ferramenta via winget (ou atualize se já estiver instalado):

   winget install microsoft.winappcli --source winget
   

1. Criar uma nova aplicação Rust

Comece por criar uma aplicação simples de Rust:

cargo new rust-app
cd rust-app

Executa para garantir que tudo está a funcionar:

cargo run

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

2. Atualizar o código para verificar a identidade

Vamos atualizar a aplicação para verificar se está a correr com identidade de pacote. Isto vai ajudar-nos a verificar se a identidade está a funcionar corretamente nos passos seguintes. Vamos usar a caixa windows para aceder às APIs Windows.

Primeiro, adiciona a windows dependência ao Cargo.toml teu executando:

cargo add windows --features ApplicationModel

Isto adiciona as ligações Windows API com a funcionalidade ApplicationModel, que nos dá acesso à API Package para verificar identidade.

De seguida, substitua todo o conteúdo de src/main.rs pelo seguinte código. Este código tenta recuperar a identidade atual do pacote. Se tiver sucesso, imprime o Nome da Família do Pacote; caso contrário, imprime "Não embalado".

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. Correr sem identidade

Agora, construa e execute a aplicação como de costume:

cargo run

Deves ver a saída "Não empacotada". Isto confirma que o executável padrão está a correr sem qualquer identidade de pacote.

4. Inicializar o Project com o winapp CLI

O winapp init comando configura tudo o que precisas de uma só vez: manifesto da aplicação e assets. O manifesto define a identidade da sua aplicação (nome, publicador, versão) que o Windows usa para conceder acesso à API.

Execute o seguinte comando e siga as indicações:

winapp init

Quando solicitado:

• Nome do pacote: Pressione Enter para aceitar o padrão (rust-app)
• Nome do Publicador: Pressione Enter para aceitar o padrão ou inserir o 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
• Configuração de SDKs: Selecione "Não configurar SDKs" (o Rust utiliza o seu próprio windows crate, em vez dos cabeçalhos do SDK C++)

Este comando irá fazer:

• Criar Package.appxmanifest — o manifesto que define a identidade da sua aplicação
• Criar Assets pasta — ícones necessários para o empacotamento MSIX e envio para a loja

Pode abrir Package.appxmanifest para personalizar ainda mais propriedades como o nome de visualização, publicador e capacidades.

Adicionar Alias de Execução (para aplicações de consola)

Como cargo new cria uma aplicação de consola, precisamos de adicionar um alias de execução ao manifesto. Sem isso, a aplicação winapp run é lançada pela ativação do AUMID, que abre uma nova janela — e essa janela fecha imediatamente quando uma aplicação de linha de comando termina, suprimindo qualquer saída.

O alias também permite que os utilizadores executem a sua aplicação pelo nome a partir de qualquer terminal após instalarem o MSIX. O manifesto regista-se um alias como rust-app.exe (padrão com o nome do exe do seu projeto), que os utilizadores podem invocar como rust-app ou rust-app.exe.

Ignora este passo se estiveres a criar uma app UI (uma app Rust que renderiza a sua própria janela). Essas aplicações funcionam bem com o lançamento padrão do AUMID.

Adicione o pseudónimo:

winapp manifest add-alias

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

5. Depuração com Identidade

Para testar funcionalidades que exigem identidade (como Notificações) sem embalar totalmente a aplicação, use winapp run. Isto regista toda a pasta de saída da build como um pacote de layout solto — tal como numa instalação real do MSIX — e inicia a aplicação. Não é necessário nenhum certificado ou assinatura para a depuração.

1. Constrói o executável:

   cargo build
   

2. Executar com identidade:

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

A --with-alias flag lança a aplicação através do seu alias de execução para que a saída da consola permaneça no terminal atual. Isto requer o uap5:ExecutionAlias que adicionámos no passo 4.

Agora deverá ver uma saída semelhante a:

Package Family Name: rust-app_12345abcde

Isto confirma que a sua aplicação está a correr com uma identidade de pacote válida!

6. Pacote com MSIX

Quando estiver pronto para distribuir a sua aplicação, pode empacotá-la como MSIX usando o mesmo manifesto. O MSIX proporciona instalação/desinstalação limpa, atualizações automáticas e uma experiência de instalação confiável.

Preparar o Diretório de Pacotes

Primeiro, construa a sua aplicação em modo de lançamento para um desempenho ótimo:

cargo build --release

Depois, cria um diretório apenas com os ficheiros necessários para a distribuição. A target\release pasta contém artefactos de construção que não fazem parte da sua aplicação — só precisamos do executável:

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

Gerar um Certificado de Desenvolvimento

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

winapp cert generate --if-exists skip

Assinar e Embalar

Agora pode empacotar e assinar num só passo:

winapp pack .\dist --cert .\devcert.pfx 

Nota: O pack comando usa automaticamente o Package.appxmanifest do seu diretório atual e copia-o para a pasta de destino antes de o empacotar. O ficheiro .msix gerado estará no diretório atual.

Instalar o Certificado

Antes de poderes instalar o pacote MSIX, precisas de confiar no certificado de desenvolvimento da tua máquina. Executa este comando como administrador (só precisas de o fazer uma vez por certificado):

winapp cert install .\devcert.pfx

Instalar e Executar

Instale o pacote clicando duas vezes no ficheiro gerado .msix , ou através do PowerShell:

Add-AppxPackage .\rust-app.msix

Agora pode executar a sua aplicação a partir de qualquer ponto do terminal escrevendo:

rust-app

Deves ver o resultado "Nome da Família do Pacote", confirmando que está instalado e a funcionar com a identidade.

Tips

1. Quando estiver pronto para a distribuição, pode assinar o seu MSIX com um certificado de assinatura de código de uma Autoridade Certificadora, para que os seus utilizadores não tenham de instalar um certificado autoassinado
2. A Microsoft Store assina o MSIX por si, não precisa de assinar antes de submeter.
3. Poderás precisar de criar vários pacotes MSIX, um para cada arquitetura que suportas (x64, Arm64)

Próximas Etapas

• Distribua via winget: Submeta o seu MSIX ao Repositório Comunitário Windows Gestor de Pacotes
• Publicar no Microsoft Store: Use winapp store para submeter o seu pacote
• Configurar CI/CD: Use o GitHub Action para automatizar o empacotamento no seu pipeline
• Explore Windows APIs: Com a identidade do pacote, pode agora usar Notifications, on-device AI e outras APIs dependentes da identidade