Använda winapp CLI med Rust

Den här guiden visar hur du använder winapp CLI med ett Rust-program för att felsöka med paketidentitet och paketera ditt program som en MSIX.

Ett fullständigt arbetsexempel finns i Rust-exemplet på den här lagringsplatsen.

Paketidentitet är ett grundläggande begrepp i Windows app modellen. Det gör att ditt program kan komma åt specifika Windows API:er (t.ex. meddelanden, säkerhet, AI-API:er osv.), har en ren installations-/avinstallationsupplevelse med mera.

En körbar standard (som en som skapats med cargo build) har inte paketidentitet. Den här guiden visar hur du lägger till den för felsökning och sedan paketera den för distribution.

Förutsättningar

1. Rust Toolchain: Installera Rust med rustup eller winget (eller uppdatera om det redan är installerat):

   winget install Rustlang.Rustup --source winget
   

2. winapp CLI: Installera winapp verktyget via winget (eller uppdatera om det redan är installerat):

   winget install microsoft.winappcli --source winget
   

1. Skapa en ny Rust-app

Börja med att skapa ett enkelt Rust-program:

cargo new rust-app
cd rust-app

Kör den för att kontrollera att allt fungerar:

cargo run

Utdata ska vara "Hello, world!"

2. Uppdatera koden för att kontrollera identiteten

Vi uppdaterar appen för att kontrollera om den körs med paketidentitet. Detta hjälper oss att kontrollera att identiteten fungerar korrekt i senare steg. Vi använder windows-lådan för att komma åt Windows API:er.

Lägg först till beroendet windows i ditt Cargo.toml genom att köra:

cargo add windows --features ApplicationModel

Detta lägger till Windows API-bindningar med funktionen ApplicationModel, vilket ger oss åtkomst till api:et Package för att kontrollera identiteten.

Ersätt sedan hela innehållet i src/main.rs med följande kod. Den här koden försöker hämta den aktuella paketidentiteten. Om det lyckas skrivs paketfamiljenamnet ut. annars skrivs "Inte paketerad".

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. Kör utan identitet

Nu skapar och kör du appen som vanligt:

cargo run

Du bör se utdata "Inte paketerad". Detta bekräftar att den körbara standarden körs utan paketidentitet.

4. Initiera Project med winapp CLI

Kommandot winapp init konfigurerar allt du behöver i ett svep: appmanifest och resurser. Manifestet definierar appens identitet (namn, utgivare, version) som Windows använder för att bevilja API-åtkomst.

Kör följande kommando och följ anvisningarna:

winapp init

När du uppmanas att göra det:

• Paketnamn: Tryck på Retur för att acceptera standardvärdet (rust-app)
• Utgivarens namn: Tryck på Enter för att acceptera standardvärdet eller ange ditt namn
• Version: Tryck på Retur för att acceptera 1.0.0.0
• Beskrivning: Tryck på Retur för att acceptera standardvärdet eller ange en beskrivning
• Installations-SDK:er: Välj "Konfigurera inte SDK:er" (Rust använder sin egen windows låda, inte C++ SDK-huvudena)

Det här kommandot kommer att:

• Skapa Package.appxmanifest – manifestet som definierar appens identitet
• Skapa Assets mapp – ikoner som krävs för MSIX-paketering och Lagringsöverföring

Du kan öppna Package.appxmanifest för att ytterligare anpassa egenskaper som visningsnamn, utgivare och funktioner.

Lägg till köralias (för konsolappar)

Eftersom cargo new skapar en konsolapp måste vi lägga till ett körningsalias i manifestet. Utan den winapp run startar appen via AUMID-aktivering, vilket öppnar ett nytt fönster – och det fönstret stängs omedelbart när en konsolapp är klar och sväljer eventuella utdata.

Med aliaset kan användarna också köra appen med namn från valfri terminal när de har installerat MSIX. Manifestet registrerar ett alias som rust-app.exe (som standard till projektets exe-namn), som användarna kan anropa som rust-app eller rust-app.exe.

Hoppa över det här steget om du skapar en användargränssnittsapp (en Rust-app som renderar ett eget fönster). Dessa appar fungerar bra med standardstarten för AUMID.

Lägg till aliaset:

winapp manifest add-alias

Detta lägger till en uap5:ExecutionAlias post i Package.appxmanifest.

5. Felsöka med identitet

Om du vill testa funktioner som kräver identitet (t.ex. meddelanden) utan att helt paketera appen använder du winapp run. Detta registrerar hela utmatningsmappen från bygget som ett osammanhängande layoutpaket, precis som en verklig MSIX-installation, och startar appen. Inget certifikat eller signering krävs för felsökning.

1. Skapa den körbara filen:

   cargo build
   

2. Kör med identitet:

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

Flaggan --with-alias startar appen via dess körningsalias så att konsolutdata finns kvar i den aktuella terminalen. Detta kräver uap5:ExecutionAlias, vilket vi lade till i steg 4.

Nu bör du se utdata som liknar:

Package Family Name: rust-app_12345abcde

Detta bekräftar att din app körs med en giltig paketidentitet!

6. Paket med MSIX

När du är redo att distribuera din app kan du paketera den som en MSIX med samma manifest. MSIX tillhandahåller ren installation/avinstallation, automatiska uppdateringar och en betrodd installationsupplevelse.

Förbereda paketkatalogen

Börja med att skapa ditt program i versionsläge för optimala prestanda:

cargo build --release

Skapa sedan en katalog med bara de filer som behövs för distribution. Mappen target\release innehåller byggartefakter som inte ingår i din app – vi behöver bara den körbara filen:

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

Generera ett utvecklingscertifikat

MSIX-paket måste signeras. För lokal testning genererar du ett självsignerat utvecklingscertifikat:

winapp cert generate --if-exists skip

Signera och packa

Nu kan du paketera och logga in i ett steg:

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

Obs! Kommandot pack använder automatiskt Package.appxmanifest från din aktuella katalog och kopierar den till målmappen före paketering. Den genererade .msix-filen finns i den aktuella katalogen.

Installera certifikatet

Innan du kan installera MSIX-paketet måste du lita på utvecklingscertifikatet på datorn. Kör det här kommandot som administratör (du behöver bara göra det en gång per certifikat):

winapp cert install .\devcert.pfx

Installera och kör

Installera paketet genom att dubbelklicka på den genererade .msix filen eller via PowerShell:

Add-AppxPackage .\rust-app.msix

Nu kan du köra appen var som helst i terminalen genom att skriva:

rust-app

Du bör se utdata för "Package Family Name" som bekräftar att det är installerat och körs med rätt identitet.

Tips

1. När du är redo för distribution kan du signera din MSIX med ett kodsigneringscertifikat från en certifikatutfärdare så att användarna inte behöver installera ett självsignerat certifikat
2. Microsoft Store signerar MSIX åt dig, du behöver inte signera innan det skickas in.
3. Du kan behöva skapa flera MSIX-paket, ett för varje arkitektur som du stöder (x64, Arm64)

Nästa steg

• Distribute via winget: Skicka din MSIX till Windows Správca balíkov Community Repository
• Publicera till Microsoft Store: Skicka paketet med winapp store
• Set up CI/CD: Använd setup-WinAppCli GitHub Action för att automatisera paketeringen i din pipeline
• Explore Windows API:er: Med paketidentitet kan du nu använda notiser, AI på enheten och andra identitetsberoende API:er