Verwenden der winapp CLI mit Tauri

In diesem Handbuch wird veranschaulicht, wie Sie die winapp CLI mit einer Tauri-Anwendung zum Debuggen mit Paketidentität und zum Verpacken Ihrer Anwendung als MSIX verwenden.

Die Paketidentität ist ein Kernkonzept im Windows app-Modell. Sie ermöglicht Ihrer Anwendung den Zugriff auf bestimmte Windows-APIs (z. B. Benachrichtigungen, Sicherheit, AI-APIs usw.), eine Benutzeroberfläche für die Neuinstallation/Deinstallation und vieles mehr.

Ein vollständiges Arbeitsbeispiel finden Sie im Tauri-Beispiel in diesem Repository.

Voraussetzungen

1. Windows 11
2. Node.js - winget install OpenJS.NodeJS --source winget
3. Rust Toolchain - Rust installieren mit rustup oder winget install Rustlang.Rustup --source winget
4. winapp CLI - winget install microsoft.winappcli --source winget

1. Erstellen einer neuen Tauri-App

Erstellen Sie zunächst eine neue Tauri-Anwendung mit dem offiziellen Gerüsttool:

npm create tauri-app@latest

Folgen Sie den Anweisungen:

• Project Name: tauri-app (oder Ihr bevorzugter Name)
• Front-End-Sprache: JavaScript
• Paket-Manager: npm
• UI-Vorlage: Vanilla
• UI-Geschmack: JavaScript

Navigieren Sie zu Ihrem Projektverzeichnis und installieren Sie Abhängigkeiten.

cd tauri-app
npm install

Führen Sie die App aus, um sicherzustellen, dass alles funktioniert:

npm run tauri dev

2. Aktualisieren von Code zum Überprüfen der Identität

Wir aktualisieren die App, um zu überprüfen, ob sie mit Paketidentität ausgeführt wird. Wir verwenden die windows-Kiste im Rust-Back-End, um auf Windows APIs zuzugreifen und sie für das Frontend verfügbar zu machen.

Backend-Änderungen (Rust)

1. Abhängigkeit hinzufügen: Öffnen Sie src-tauri/Cargo.toml und fügen Sie die folgenden Zeilen am Ende der Datei hinzu. Dadurch werden die Windows-API-Bindungen hinzugefügt, damit wir die Paketidentität überprüfen können:

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

2. Befehl hinzufügen: Öffnen src-tauri/src/lib.rs und Hinzufügen der get_package_family_name Funktion. Platzieren Sie sie vor der pub fn run() Funktion:

   #[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. Befehl registrieren: Aktualisieren Sie in derselben Datei (src-tauri/src/lib.rs) die run Funktion, um den neuen Befehl zu registrieren:

   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");
   }
   

Frontend-Änderungen (JavaScript)

1. Aktualisieren Sie HTML: Öffnen Sie src/index.html und fügen Sie einen Absatz hinzu, um das Ergebnis anzuzeigen.

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

2. Updatelogik: Öffnen src/main.js , um den Befehl aufzurufen und das Ergebnis anzuzeigen:

   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. Führen Sie nun die App wie gewohnt aus:

   npm run tauri dev
   

   Im App-Fenster sollte "Nicht mit Paketidentität ausgeführt" angezeigt werden. Dadurch wird bestätigt, dass der Standardentwicklungsbuild ohne Paketidentität ausgeführt wird.

3. Initialisiere Projekt mit winapp CLI

Mit dem winapp init Befehl wird alles auf einmal eingerichtet, was Sie benötigen: App-Manifest und Assets. Das Manifest definiert die Identität Ihrer App (Name, Herausgeber, Version), die Windows verwendet, um API-Zugriff zu gewähren.

Führen Sie den folgenden Befehl aus, und folgen Sie den Eingabeaufforderungen:

winapp init

Wenn Sie dazu aufgefordert werden:

• Paketname: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu akzeptieren (tauri-app)
• Publisher Name: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu akzeptieren oder Ihren Namen einzugeben.
• Version: Drücken Sie die EINGABETASTE, um 1.0.0.0 zu akzeptieren.
• Einstiegspunkt: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu übernehmen (tauri-app.exe)
• Setup-SDKs: Wählen Sie "Keine SDKs einrichten" aus (Tauri verwendet Rosts windows Kasten, nicht die C++-SDK-Header)

Dieser Befehl bewirkt Folgendes:

• Erstellen Package.appxmanifest – das Manifest, das die Identität Ihrer App definiert
• Erstellen eines Ordners Assets – Symbole, die für die MSIX-Verpackung und die Store-Übermittlung erforderlich sind

Sie können Package.appxmanifest öffnen, um Eigenschaften wie den Anzeigenamen, den Herausgeber und die Funktionen weiter anzupassen.

4. Debuggen mit Identität

Zum Debuggen mit Identität müssen wir das Rust-Back-End erstellen und mit winapp rundiesen ausführen. Da npm run tauri dev den Prozesslebenszyklus verwaltet, ist es schwieriger, die Identität dort einzubinden. Stattdessen erstellen wir ein benutzerdefiniertes Skript. Für das Debuggen ist kein Zertifikat oder keine Signatur erforderlich.

1. Skript hinzufügen: Öffnen package.json und Hinzufügen eines neuen Skripts 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"
   }
   

   Funktionsweise dieses Skripts:

   • cargo build ...: Kompiliert das Rust-Back-End neu.
   • copy ... dist\\: Stellt nur die exe in einen dist Ordner (der target\debug Ordner ist sehr groß und enthält Zwischenbuildartefakte, die nicht zu Ihrer App gehören).
   • winapp run .\\dist: Registriert ein loses Layoutpaket (genau wie eine echte MSIX-Installation) und startet die App.

2. Führen Sie das Skript aus:

   npm run tauri:dev:withidentity
   

Nun sollte die App geöffnet sein und der "Paketfamilienname" angezeigt werden, was bestätigt, dass sie authentifiziert läuft! Sie können nun mit der Verwendung und dem Debuggen von APIs beginnen, die Paketidentität erfordern, z. B. Benachrichtigungen oder die neuen KI-APIs wie Phi Silica.

5. Paket mit MSIX

Sobald Sie bereit sind, Ihre App zu verteilen, können Sie sie als MSIX verpacken, die die Paketidentität für Ihre Anwendung bereitstellt.

Fügen Sie zunächst ein pack:msix-Skript zu Ihrem package.json hinzu.

"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"
}

Funktionsweise dieses Skripts:

• npm run tauri -- build: Erstellt das Rust-Backend im Veröffentlichungsmodus.
• copy ... dist\\: Stellt nur die exe in einen dist Ordner (der target\release Ordner ist sehr groß und enthält Zwischenbuildartefakte, die nicht zu Ihrer App gehören).
• winapp pack .\\dist --cert .\\devcert.pfx: Verpackt die App und signiert sie als MSIX.

Generieren eines Entwicklungszertifikats

MSIX-Pakete müssen signiert sein. Generieren Sie für lokale Tests ein selbstsigniertes Entwicklungszertifikat:

winapp cert generate --if-exists skip

Erstellen, Stufen und Packen

npm run pack:msix

Installieren des Zertifikats

Bevor Sie das MSIX-Paket installieren können, müssen Sie dem Entwicklungszertifikat auf Ihrem Computer vertrauen. Führen Sie diesen Befehl als Administrator aus (Sie müssen diesen Vorgang nur einmal pro Zertifikat ausführen):

winapp cert install .\devcert.pfx

Installieren und Ausführen

Installieren Sie das Paket, indem Sie auf die generierte .msix Datei doppelklicken oder PowerShell verwenden:

Add-AppxPackage .\tauri-app.msix

Nach der Installation können Sie Ihre App über das Startmenü starten. Sie sollten sehen, dass die App mit Authentifizierung ausgeführt wird.

Tipps

1. Sobald Sie bereit für die Verteilung sind, können Sie Ihr MSIX mit einem Codesignaturzertifikat von einer Zertifizierungsstelle signieren, damit Ihre Benutzer kein selbstsigniertes Zertifikat installieren müssen.
2. Der Microsoft Store signiert das MSIX für Sie, sodass Sie vor der Übermittlung nicht unterschreiben müssen.
3. Möglicherweise müssen Sie mehrere MSIX-Pakete erstellen, eine für jede architektur, die Sie unterstützen (x64, Arm64).

Nächste Schritte

• Distribute via winget: Übermitteln Sie Ihren MSIX an das Windows Paket-Manager Community-Repository
• Publish to the Microsoft Store: Verwenden Sie winapp store, um Ihr Paket zu übermitteln.
• Set up CI/CD: Verwenden Sie die setup-WinAppCli GitHub Action, um die Paketerstellung in Ihrer Pipeline zu automatisieren.
• Explore Windows-APIs: Mit Paketidentität können Sie jetzt Benachrichtigungen, gerätenahe KI und andere identitätsabhängige APIs verwenden.