Winapp CLI gebruiken met Rust

Deze handleiding laat zien hoe u de winapp CLI gebruikt met een Rust-toepassing om fouten op te sporen met pakketidentiteit en uw toepassing als een MSIX-pakket te verpakken.

Bekijk het Rust-voorbeeld in deze opslagplaats voor een volledig werkvoorbeeld.

Pakketidentiteit is een kernconcept in het Windows app model. Hiermee heeft uw toepassing toegang tot specifieke Windows API's (zoals meldingen, beveiliging, AI-API's, enzovoort), een schone installatie-/verwijderingservaring en meer.

Een standaard uitvoerbaar bestand (zoals een bestand dat is gemaakt met cargo build) heeft geen pakketidentiteit. In deze handleiding ziet u hoe u deze toevoegt voor foutopsporing en deze vervolgens inpakt voor distributie.

Vereiste voorwaarden

1. Rust Toolchain: Rust installeren met behulp van rustup of winget (of update indien al geïnstalleerd):

   winget install Rustlang.Rustup --source winget
   

2. winapp CLI: installeer het winapp hulpprogramma via winget (of werk bij als dit al is geïnstalleerd):

   winget install microsoft.winappcli --source winget
   

1. Een nieuwe Rust-app maken

Begin met het maken van een eenvoudige Rust-toepassing:

cargo new rust-app
cd rust-app

Voer deze uit om te controleren of alles werkt:

cargo run

Uitvoer moet 'Hallo, wereld!' zijn

2. Code bijwerken om identiteit te controleren

We werken de app bij om te controleren of deze wordt uitgevoerd met pakketidentiteit. Dit helpt ons te controleren of de identiteit in latere stappen correct werkt. We gebruiken de windows krat om toegang te krijgen tot Windows API's.

Voeg eerst de windows afhankelijkheid toe aan uw Cargo.toml door het volgende uit te voeren:

cargo add windows --features ApplicationModel

Hiermee worden de Windows API-bindingen toegevoegd met de functie ApplicationModel, waarmee we toegang krijgen tot de Package-API voor het controleren van de identiteit.

Vervang vervolgens de volledige inhoud van src/main.rs door de volgende code. Met deze code wordt geprobeerd de huidige pakketidentiteit op te halen. Als het lukt, wordt de familienaam van het pakket afgedrukt; anders wordt 'Niet verpakt' afgedrukt.

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. Uitvoeren zonder identiteit

Bouw en voer de app nu zoals gewoonlijk uit:

cargo run

U zou de uitvoer 'Niet verpakt' moeten zien. Hiermee wordt bevestigd dat het standaard uitvoerbare bestand wordt uitgevoerd zonder pakketidentiteit.

4. Initialiseer Project met winapp CLI

Met de winapp init opdracht stelt u alles in dat u in één gebruik nodig hebt: app-manifest en -assets. Het manifest definieert de identiteit van uw app (naam, uitgever, versie) die Windows gebruikt om API-toegang te verlenen.

Voer de volgende opdracht uit en volg de aanwijzingen:

winapp init

Wanneer u hierom wordt gevraagd:

• Pakketnaam: druk op Enter om de standaardwaarde te accepteren (rust-app)
• Publisher naam: Druk op Enter om de standaardinstelling te accepteren of voer uw naam in
• Versie: Druk op Enter om 1.0.0.0 te accepteren
• Beschrijving: Druk op Enter om de standaardinstelling te accepteren of voer een beschrijving in
• Sdk's instellen: Selecteer 'SDK's niet instellen' (Rust maakt gebruik van een eigen windows krat, niet de C++ SDK-headers)

Met deze opdracht wordt het volgende uitgevoerd:

• Maken Package.appxmanifest : het manifest waarmee de identiteit van uw app wordt gedefinieerd
• Map maken Assets : pictogrammen die vereist zijn voor MSIX-pakketten en Store-inzending

U kunt openen Package.appxmanifest om eigenschappen zoals de weergavenaam, uitgever en mogelijkheden verder aan te passen.

Uitvoeringsalias toevoegen (voor console-apps)

Omdat cargo new er een console-app wordt gemaakt, moeten we een uitvoeringsalias toevoegen aan het manifest. Zonder dit lanceert winapp run de app via AUMID-activering, waardoor een nieuw venster wordt geopend — en dat venster sluit onmiddellijk zodra een console-app is voltooid, waardoor de uitvoer wordt onderdrukt.

Met de alias kunnen gebruikers uw app ook op naam uitvoeren vanuit elke terminal nadat ze de MSIX hebben geïnstalleerd. Het manifest registreert een alias zoals rust-app.exe (standaard ingesteld op de exe-naam van uw project), die gebruikers kunnen aanroepen als rust-app of rust-app.exe.

Sla deze stap over als u een UI-app bouwt (een Rust-app die een eigen venster weergeeft). Deze apps werken prima met de standaard-AUMID-start.

Voeg de alias toe:

winapp manifest add-alias

Hiermee voegt u een uap5:ExecutionAlias vermelding toe aan Package.appxmanifest.

5. Debuggen met identiteit

Als u functies wilt testen waarvoor identiteit (zoals meldingen) is vereist zonder de app volledig te verpakken, gebruikt u winapp run. Hiermee wordt de volledige build-uitvoermap geregistreerd als een los indelingspakket, net als bij een echte MSIX-installatie, en wordt de app gestart. Er is geen certificaat of ondertekening nodig voor foutopsporing.

1. Bouw het uitvoerbare bestand:

   cargo build
   

2. Uitvoeren met identiteit:

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

De --with-alias vlag start de app via de uitvoeringsalias, zodat de console-uitvoer in de huidige terminal blijft. Hiervoor is vereist dat we uap5:ExecutionAlias in stap 4 hebben toegevoegd.

U ziet nu uitvoer die vergelijkbaar is met:

Package Family Name: rust-app_12345abcde

Hiermee wordt bevestigd dat uw app wordt uitgevoerd met een geldige pakketidentiteit.

6. Pakket met MSIX

Zodra u klaar bent om uw app te distribueren, kunt u deze verpakken als een MSIX met hetzelfde manifest. MSIX biedt schone installatie/verwijdering, automatische updates en een vertrouwde installatie-ervaring.

De pakketmap voorbereiden

Bouw eerst uw toepassing in de releasemodus voor optimale prestaties:

cargo build --release

Maak vervolgens een map met alleen de bestanden die nodig zijn voor distributie. De target\release map bevat buildartefacten die geen deel uitmaken van uw app. We hebben alleen het uitvoerbare bestand nodig:

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

Een ontwikkelingscertificaat genereren

MSIX-pakketten moeten zijn ondertekend. Genereer voor lokaal testen een zelfondertekend ontwikkelingscertificaat:

winapp cert generate --if-exists skip

Ondertekenen en inpakken

Nu kunt u in één stap verpakken en ondertekenen.

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

Opmerking: De pack opdracht maakt automatisch gebruik van package.appxmanifest uit uw huidige map en kopieert deze naar de doelmap voordat de verpakking wordt verpakt. Het gegenereerde MSIX-bestand bevindt zich in de huidige map.

Het certificaat installeren

Voordat u het MSIX-pakket kunt installeren, moet u het ontwikkelingscertificaat op uw computer vertrouwen. Voer deze opdracht uit als beheerder (u hoeft dit slechts één keer per certificaat te doen):

winapp cert install .\devcert.pfx

Installeren en uitvoeren

Installeer het pakket door te dubbelklikken op het gegenereerde .msix bestand of via PowerShell:

Add-AppxPackage .\rust-app.msix

U kunt nu uw app vanaf elke locatie in de terminal uitvoeren door het volgende te typen:

rust-app

Als het goed is, ziet u de uitvoer "Package Family Name", waarin wordt bevestigd dat deze is geïnstalleerd en uitgevoerd met identiteit.

Tips

1. Zodra u klaar bent voor distributie, kunt u uw MSIX ondertekenen met een certificaat voor ondertekening van programmacode van een certificeringsinstantie, zodat uw gebruikers geen zelfondertekend certificaat hoeven te installeren
2. De Microsoft Store zal de MSIX voor u ondertekenen, u hoeft deze niet te ondertekenen voordat u hem indient.
3. Mogelijk moet u meerdere MSIX-pakketten maken, één voor elke architectuur die u ondersteunt (x64, Arm64)

Volgende stappen

• Distribute via winget: Dien uw MSIX in bij de Windows Pakketbeheer Community-opslagplaats
• Publiceren naar de Microsoft Store: gebruik winapp store om uw pakket in te dienen
• Set up CI/CD: Gebruik de GitHub Actie setup-WinAppCli om automatisering van het verpakken in uw pijplijn te realiseren.
• Explore Windows API's: Met pakketidentiteit kunt u nu meldingen, on-device AI en andere identiteitsafhankelijke API's gebruiken