Usando a linha de comando winapp com Tauri

Este guia demonstra como usar a CLI winapp com uma aplicação Tauri, para depurar utilizando a identidade do pacote e empacotar a sua aplicação como MSIX.

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.

Para um exemplo completo e funcional, consulte o exemplo Tauri deste repositório.

Pré-requisitos

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

1. Criar uma nova aplicação Tauri

Comece por criar uma nova aplicação Tauri usando a ferramenta oficial de andaime:

npm create tauri-app@latest

Siga as indicações:

• Nome do projeto: tauri-app (ou o seu nome preferido)
• Linguagem frontend: JavaScript
• Gestor de pacotes: npm
• Modelo de interface: Vanilla
• Estilo da interface de usuário: JavaScript

Navegue até o diretório do seu projeto e instale as dependências:

cd tauri-app
npm install

Executa a aplicação para garantir que tudo está a funcionar:

npm run tauri dev

2. Atualizar o código para verificar a identidade

Vamos atualizar a aplicação para verificar se está a correr com identidade de pacote. Vamos usar o crate windows no backend do Rust para aceder às APIs do Windows e expô-las no frontend.

Alterações no backend (Rust)

1. Adicionar Dependência: Abra src-tauri/Cargo.toml e adicione as seguintes linhas no final do ficheiro. Isto adiciona as ligações da API do Windows para que possamos verificar a identidade do pacote:

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

2. Adicionar Comando: Abre src-tauri/src/lib.rs e adiciona 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. Comando de Registo: No mesmo ficheiro (src-tauri/src/lib.rs), atualiza a run função para registar 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 na Frontend (JavaScript)

1. Atualize HTML: Abra src/index.html e adicione um parágrafo para mostrar o resultado:

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

2. Lógica de Atualização: Abrir src/main.js para invocar o comando e mostrar 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, executa a aplicação como de costume:

   npm run tauri dev
   

   Deverás ver "Não em execução com identidade de pacote" na janela da aplicação. Isto confirma que a compilação de desenvolvimento padrão está a funcionar sem identidade de pacote.

3. Inicializar o Project com a linha de comando winapp

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 (tauri-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
• Ponto de entrada: Pressione Enter para aceitar o padrão (tauri-app.exe)
• Configurar SDKs: Selecione "Não configurar SDKs" (o Tauri utiliza o crate do Rust, não os 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.

4. Depuração com Identidade

Para depurar com identidade, precisamos de construir o backend do Rust e executá-lo com winapp run. Como npm run tauri dev gere o ciclo de vida do processo, é mais difícil injetar a identidade aí. Em vez disso, vamos criar um script personalizado. Não é necessário nenhum certificado ou assinatura para a depuração.

1. Adicionar Script: Abrir package.json e adicionar 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 backend do Rust.
   • copy ... dist\\: Coloca apenas o exe numa dist pasta (a target\debug pasta é muito grande e contém artefactos intermédios de build que não fazem parte da tua aplicação).
   • winapp run .\\dist: Regista um pacote de layout solto (tal como numa instalação real do MSIX) e inicia a aplicação.

2. Corra o Script:

   npm run tauri:dev:withidentity
   

Agora deve ver a aplicação aberta a mostrar o "Nome da família do pacote", confirmando que está a executar com identidade! Agora pode começar a usar e a depurar APIs que exigem identidade de pacote, como as Notificações ou as novas APIs de IA como a Phi Silica.

5. Pacote com MSIX

Quando estiver pronto para distribuir a sua aplicação, pode empacotá-la como um MSIX, que fornecerá a identidade do pacote à sua aplicação.

Primeiro, adiciona um pack:msix script ao teu 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: Constrói o backend do Rust em modo de lançamento.
• copy ... dist\\: Coloca apenas o exe numa dist pasta (a target\release pasta é muito grande e contém artefactos intermédios de build que não fazem parte da tua aplicação).
• winapp pack .\\dist --cert .\\devcert.pfx: Empacota e assina a aplicação como MSIX.

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

Construir, Preparar e Empacotar

npm run pack:msix

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 fazendo duplo clique no ficheiro gerado .msix , ou usando o PowerShell:

Add-AppxPackage .\tauri-app.msix

Depois de instalado, pode iniciar a sua aplicação a partir do menu Iniciar. Deves ver a aplicação a executar com autenticação.

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 auto-assinado.
2. A Microsoft Store assina o MSIX por si, não precisa de assinar antes de submeter.
3. Pode ser necessário criar vários pacotes MSIX, um para cada arquitetura que suporta (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