Verwenden der winapp CLI mit Rust

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

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

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.

Eine Standard-Ausführungsdatei (wie eine, die mit cargo build erstellt wurde) hat keine Paketidentität. In diesem Handbuch wird gezeigt, wie Sie es zum Debuggen hinzufügen und dann für die Verteilung verpacken.

Voraussetzungen

1. Rust Toolchain: Installieren Sie Rust mit Rost oder Winget (oder aktualisieren Sie, wenn bereits installiert):

   winget install Rustlang.Rustup --source winget
   

2. winapp CLI: Installieren Sie das winapp Tool über winget (oder aktualisieren Sie, falls bereits installiert):

   winget install microsoft.winappcli --source winget
   

1. Erstellen einer neuen Rust-App

Erstellen Sie zunächst eine einfache Rust-Anwendung:

cargo new rust-app
cd rust-app

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

cargo run

Die Ausgabe sollte "Hallo, Welt!" lauten.

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. Dadurch können wir überprüfen, ob die Identität in späteren Schritten ordnungsgemäß funktioniert. Wir nutzen den windows-Crate, um Zugriff auf die Windows-APIs zu erhalten.

Fügen Sie zunächst die windows Abhängigkeit zu Ihrem Cargo.toml Element hinzu, indem Sie Folgendes ausführen:

cargo add windows --features ApplicationModel

Dadurch werden die Windows-API-Bindungen mit dem Feature ApplicationModel hinzugefügt, das uns Zugriff auf die Package-API zum Überprüfen der Identität gewährt.

Ersetzen Sie als Nächstes den gesamten Inhalt von src/main.rs durch den folgenden Code. Dieser Code versucht, die aktuelle Paketidentität abzurufen. Wenn er erfolgreich ist, wird der Paketfamilienname gedruckt. andernfalls wird "Nicht verpackt" gedruckt.

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. Ohne Identität ausführen

Erstellen Sie nun die App wie gewohnt, und führen Sie sie aus:

cargo run

"Sie sollten die Ausgabe 'Nicht verpackt' angezeigt sehen." Dadurch wird bestätigt, dass die standardmäßige ausführbare Datei ohne Paketidentität ausgeführt wird.

4. Projekt mit winapp CLI initialisieren

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 den Standard (rust-app) zu akzeptieren.
• 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.
• Beschreibung: Drücken Sie die EINGABETASTE, um die Standardeinstellung zu akzeptieren oder eine Beschreibung einzugeben.
• Setup-SDKs: Wählen Sie "Keine SDKs einrichten" aus (Rust verwendet eine eigene windows Kiste, 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.

Ausführungsalias hinzufügen (für Konsolen-Apps)

Da cargo new eine Konsolen-App erstellt, müssen wir dem Manifest einen Ausführungsalias hinzufügen. Ohne diese Option wird winapp run die App über die AUMID-Aktivierung gestartet, wodurch ein neues Fenster geöffnet wird und das Fenster sofort geschlossen wird, wenn eine Konsolen-App beendet wird und dabei alle Ausgaben verschluckt.

Mit dem Alias können Benutzer Ihre App auch von einem beliebigen Terminal ausführen, nachdem sie die MSIX installiert haben. Das Manifest registriert einen Alias wie rust-app.exe (standardmäßig auf den Exe-Namen Ihres Projekts), den Benutzer als rust-app oder rust-app.exe aufrufen können.

Überspringen Sie diesen Schritt, wenn Sie eine UI-App erstellen (eine Rust-App , die ein eigenes Fenster rendert). Diese Apps funktionieren einwandfrei mit dem standardmäßigen AUMID-Start.

Fügen Sie den Alias hinzu:

winapp manifest add-alias

Dadurch wird ein uap5:ExecutionAlias Eintrag zu Package.appxmanifest.

5. Debuggen mit Identität

Um Features zu testen, die Identität erfordern (z. B. Benachrichtigungen), ohne die App vollständig zu verpacken, verwenden Sie winapp run. Dadurch wird der gesamte Buildausgabeordner als loses Layoutpaket registriert – genau wie eine echte MSIX-Installation – und startet die App. Für das Debuggen ist kein Zertifikat oder keine Signatur erforderlich.

1. Erstellen Sie die ausführbare Datei:

   cargo build
   

2. Ausführen mit Identität:

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

Das --with-alias-Flag startet die App über seinen Ausführungsalias, sodass die Konsolenausgabe im aktuellen Terminal bleibt. Dazu benötigen wir das uap5:ExecutionAlias, das wir in Schritt 4 hinzugefügt haben.

Nun sollte eine Ausgabe angezeigt werden, die ähnlich wie die folgende ist:

Package Family Name: rust-app_12345abcde

Dadurch wird bestätigt, dass Ihre App mit einer gültigen Paketidentität ausgeführt wird!

6. Paket mit MSIX

Sobald Sie bereit sind, Ihre App zu verteilen, können Sie sie mit demselben Manifest als MSIX verpacken. MSIX bietet saubere Installation/Deinstallation, automatische Updates und ein vertrauenswürdiges Installationserlebnis.

Vorbereiten des Paketverzeichnisses

Erstellen Sie zunächst Ihre Anwendung im Releasemodus, um eine optimale Leistung zu erzielen:

cargo build --release

Erstellen Sie dann ein Verzeichnis mit nur den dateien, die für die Verteilung erforderlich sind. Der target\release Ordner enthält Buildartefakte, die nicht Teil Ihrer App sind – wir benötigen nur die ausführbare Datei:

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

Generieren eines Entwicklungszertifikats

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

winapp cert generate --if-exists skip

Signieren und Packen

Jetzt können Sie in einem Schritt packen und signieren.

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

Hinweis: Der pack Befehl verwendet automatisch das Package.appxmanifest aus Ihrem aktuellen Verzeichnis und kopiert es vor dem Verpacken in den Zielordner. Die generierte MSIX-Datei befindet sich im aktuellen Verzeichnis.

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 oder über PowerShell doppelklicken:

Add-AppxPackage .\rust-app.msix

Jetzt können Sie Ihre App von praktisch überall im Terminal ausführen, indem Sie Folgendes eingeben:

rust-app

Die Ausgabe "Paketfamilienname" sollte angezeigt werden, wobei bestätigt wird, dass sie installiert ist und mit Identität ausgeführt wird.

Tipps

1. Nachdem 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.