Usando a CLI do winapp com o Tauri

Este guia demonstra como usar o winapp CLI com um aplicativo Tauri para depurar utilizando 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.

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

Pré-requisitos

1. Windows 11
2. Node.js - winget install OpenJS.NodeJS --source winget
3. Rust Toolchain – Instalar o Rust usando rustup ou winget install Rustlang.Rustup --source winget
4. CLI do winapp - winget install microsoft.winappcli --source winget

1. Criar um novo aplicativo Tauri

Comece criando uma nova aplicação Tauri usando a ferramenta oficial de criação:

npm create tauri-app@latest

Siga as instruções:

• Project name: tauri-app (ou seu nome preferido)
• Idioma de front-end: JavaScript
• Gerenciador de pacotes: npm
• Modelo de interface do usuário: Vanilla
• Sabor da interface do usuário: JavaScript

Navegue até o diretório do projeto e instale dependências.

cd tauri-app
npm install

Execute o aplicativo para verificar se tudo está funcionando:

npm run tauri dev

2. Atualizar código para verificar identidade

Atualizaremos o aplicativo para verificar se ele está em execução com a identidade do pacote. Usaremos o crate windows no back-end do Rust para acessar Windows APIs e expô-lo ao front-end.

Alterações de back-end (Rust)

1. Adicionar uma dependência: Abra src-tauri/Cargo.toml e adicione as seguintes linhas ao final do arquivo. Isso adiciona as associações de API Windows para que possamos verificar a identidade do pacote:

   [target.'cfg(windows)'.dependencies]
   windows = { version = "0.58", features = ["ApplicationModel"] }
   

2. Adicionar Comando: Abra src-tauri/src/lib.rs e adicione a get_package_family_name função. Coloque-o antes da pub fn run() função:

   #[tauri::command]
   fn get_package_family_name() -> String {
       #[cfg(target_os = "windows")]
       {
           use windows::ApplicationModel::Package;
           match Package::Current() {
               Ok(package) => {
                   match package.Id() {
                       Ok(id) => match id.FamilyName() {
                           Ok(name) => name.to_string(),
                           Err(_) => "Error retrieving Family Name".to_string(),
                       },
                       Err(_) => "Error retrieving Package ID".to_string(),
                   }
               }
               Err(_) => "No package identity".to_string(),
           }
       }
       #[cfg(not(target_os = "windows"))]
       {
           "Not running on Windows".to_string()
       }
   }
   

3. Registrar Comando: no mesmo arquivo (src-tauri/src/lib.rs), atualize a run função para registrar o novo comando:

   pub fn run() {
       tauri::Builder::default()
           .plugin(tauri_plugin_opener::init())
           .invoke_handler(tauri::generate_handler![greet, get_package_family_name]) // Add get_package_family_name here
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }
   

Alterações de front-end (JavaScript)

1. Atualizar HTML: abra src/index.html e adicione um parágrafo para exibir o resultado:

   <!-- ... inside <main> ... -->
   <p id="pfn-msg"></p>
   

2. Atualizar Lógica: abra src/main.js para invocar o comando e exibir o resultado:

   const { invoke } = window.__TAURI__.core;
   
   // ... existing code ...
   
   async function checkPackageIdentity() {
     const pfn = await invoke("get_package_family_name");
     const pfnMsgEl = document.querySelector("#pfn-msg");
   
     if (pfn !== "No package identity" && !pfn.startsWith("Error")) {
       pfnMsgEl.textContent = `Package family name: ${pfn}`;
     } else {
       pfnMsgEl.textContent = `Not running with package identity`;
     }
   }
   
   window.addEventListener("DOMContentLoaded", () => {
     // ... existing code ...
     checkPackageIdentity();
   });
   

3. Agora, execute o aplicativo como de costume:

   npm run tauri dev
   

   Você deve ver "Não está em execução com a identidade do pacote" na janela do aplicativo. Isso confirma que a compilação de desenvolvimento padrão está em execução sem identidade de pacote.

3. 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 (tauri-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
• Ponto de entrada: pressione Enter para aceitar o padrão (tauri-app.exe)
• Configurar SDKs: selecione "Não configurar SDKs" (o Tauri usa o crate do windows Rust, 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

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

4. Depuração usando Identidade

Para depurar utilizando identidade, precisamos compilar o backend em Rust e executá-lo com winapp run. Como npm run tauri dev gerencia o ciclo de vida do processo, é mais difícil injetar a identidade lá. Em vez disso, criaremos um script personalizado. Nenhum certificado ou assinatura é necessário para depuração.

1. Adicionar Script: Abra package.json e adicione um novo script tauri:dev:withidentity:

   "scripts": {
     "tauri": "tauri",
     "tauri:dev:withidentity": "cargo build --manifest-path src-tauri/Cargo.toml && (if not exist dist mkdir dist) && copy /Y src-tauri\\target\\debug\\tauri-app.exe dist\\ >nul && winapp run .\\dist"
   }
   

   O que este script faz:

   • cargo build ...: recompila o back-end do Rust.
   • copy ... dist\\: coloca apenas o exe em uma dist pasta (a target\debug pasta é muito grande e contém artefatos de build intermediários que não fazem parte do seu aplicativo).
   • winapp run .\\dist: registra um pacote de layout desestruturado (assim como uma instalação MSIX real) e executa o aplicativo.

2. Executar o Script:

   npm run tauri:dev:withidentity
   

Agora você deve ver o aplicativo aberto e exibir o "Nome de família do pacote", confirmando que ele está em execução com a identidade! Agora você pode começar a usar e depurar APIs que exigem a identidade do pacote, como Notificações ou as novas APIs de IA, como o Phi Silica.

5. Empacotar com MSIX

Quando estiver pronto para distribuir seu aplicativo, você poderá empacotá-lo como um MSIX que fornecerá a identidade do pacote ao seu aplicativo.

Primeiro, adicione um pack:msix script ao seu package.json:

"scripts": {
  "tauri": "tauri",
  "tauri:dev:withidentity": "...",
  "pack:msix": "npm run tauri -- build && (if not exist dist mkdir dist) && copy /Y src-tauri\\target\\release\\tauri-app.exe dist\\ >nul && winapp pack .\\dist --cert .\\devcert.pfx"
}

O que este script faz:

• npm run tauri -- build: Cria o backend do Rust no modo release.
• copy ... dist\\: coloca apenas o exe em uma dist pasta (a target\release pasta é muito grande e contém artefatos de build intermediários que não fazem parte do seu aplicativo).
• winapp pack .\\dist --cert .\\devcert.pfx: empacota e assina o aplicativo como MSIX.

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

Compilar, preparar e empacotar

npm run pack:msix

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

Instale o pacote clicando duas vezes no arquivo gerado .msix ou usando o PowerShell:

Add-AppxPackage .\tauri-app.msix

Depois de instalado, você pode iniciar seu aplicativo no menu Iniciar. Você deve ver o aplicativo em execução com autenticação.

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

• 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