Winapp CLI használata .NET

Ennek az útmutatónak a legtöbb .NET projekttípus esetében működnie kell. A lépések tesztelése konzol- és felhasználói felületalapú projektekben is megtörtént, például WPF. Munkapéldákért tekintse meg a dotnet-app (konzol) és wpf-app (WPF) példákat a példamappában.

Ez az útmutató bemutatja, hogyan használhatja a winapp parancssori felületet egy .NET alkalmazással a csomagdentitás hibakereséséhez és az alkalmazás MSIX-ként való csomagolásához.

A csomagidentitás a Windows app modell alapvető fogalma. Lehetővé teszi, hogy az alkalmazás hozzáférjen bizonyos Windows API-khoz (például értesítések, biztonság, AI API-k stb.), tiszta telepítési/eltávolítási felülettel rendelkezik, és így tovább.

Egy standard végrehajtható fájl (mint amilyet a dotnet build-vel hoznak létre) nem rendelkezik csomagidentitással. Ez az útmutató bemutatja, hogyan lehet egy elemet hozzáadni hibakereséshez, majd hogyan csomagolhatja be terjesztés céljából.

Előfeltételek

  1. .NET SDK: Telepítse a .NET SDK-t (a telepítés után újra kell indítani):

    winget install Microsoft.DotNet.SDK.10 --source winget

  2. winapp CLI: Telepítse az eszközt a winapp wingettel (vagy frissítse, ha már telepítve van):

    winget install Microsoft.winappcli --source winget

1. Új .NET-alkalmazás létrehozása

Először hozzon létre egy egyszerű .NET konzolalkalmazást:

dotnet new console -n dotnet-app
cd dotnet-app

Futtassa le, hogy megbizonyosodjon arról, minden rendben működik:

dotnet run

A kimenetnek a következőnek kell lennie: "Hello, World!"

2. Kód frissítése az identitás ellenőrzéséhez

Frissítjük az alkalmazást, hogy ellenőrizze, a csomagazonossággal fut-e. A csomag API-k eléréséhez az Windows-futtatókörnyezet API-t fogjuk használni.

Először frissítse a project fájlt egy adott Windows SDK-verzióra. Nyissa meg a dotnet-app.csproj, és módosítsa a TargetFramework, hogy tartalmazza a Windows SDK-verziót.

  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

Így további csomagok nélkül is hozzáférhet Windows-futtatókörnyezet API-khoz.

Most cserélje le a Program.cs tartalmát a következő kóddal. Ez a kód a Windows-futtatókörnyezet API használatával próbálja lekérni az aktuális csomagidentitást. Ha sikerül, kinyomtatja a csomagcsalád nevét; ellenkező esetben a "Nincs csomagolva" felirat jelenik meg.

using Windows.ApplicationModel;

try
{
    var package = Package.Current;
    var familyName = package.Id.FamilyName;
    Console.WriteLine($"Package Family Name: {familyName}");
}
catch (InvalidOperationException)
{
    // Thrown when app doesn't have package identity
    Console.WriteLine("Not packaged");
}

3. Futtatás identitás nélkül

Most futtassa az alkalmazást a szokásos módon:

dotnet run

A "Nincs csomagolva" kimenetnek kell megjelennie. Ez megerősíti, hogy a standard végrehajtható fájl csomagidentitás nélkül fut.

4. A Project inicializálása winapp parancssori felülettel

A winapp init parancs automatikusan észleli .csproj fájlokat, és .NET-specifikus beállítást futtat. Egyetlen lépésben beállít mindent, amire szüksége van: ellenőrzi a TargetFramework, hozzáadja a szükséges NuGet-csomagokat, létrehozza az alkalmazásmanifestet és az alkalmazás-összetevőket.

Futtassa a következő parancsot, és kövesse az utasításokat:

winapp init

Amikor a rendszer kéri:

  • Csomag neve: Nyomja le az Enter billentyűt az alapértelmezett (dotnet-app) elfogadásához
  • Publisher név: Az Enter billentyűt lenyomva fogadja el az alapértelmezett értéket, vagy adja meg a nevét
  • Verzió: Nyomja le az Enter billentyűt az 1.0.0.0 elfogadásához
  • Description: Nyomja le az Enter billentyűt az alapértelmezett (Windows alkalmazás) elfogadásához vagy leírás megadásához
  • Windows App SDK beállítás: Válassza a Stabil, az Előzetes verzió vagy a Kísérleti lehetőséget (meghatározza, hogy melyik Windows App SDK verzió van hozzáadva)
  • TargetFramework frissítés: Ha a TargetFramework nem tartalmaz támogatott Windows SDK-verziót, a rendszer kérni fogja a frissítését (például net10.0-windows10.0.26100.0)
  • Fejlesztői mód: Ha a rendszer a "Fejlesztői mód" kifejezésre kéri, bekapcsolhatja, ha szeretné, de vegye figyelembe, hogy rendszergazdai jogosultságokat igényel

Ez a parancs a következő lesz:

  • Frissítse a TargetFramework elemet a .csproj egy támogatott Windows TFM-re (ha szükséges)
  • Adja hozzá a Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools és Microsoft.Windows.SDK.BuildTools.WinApp NuGet-csomag hivatkozásokat a .csproj-hez.
  • Hozzon létre Package.appxmanifest és Assets mappát az alkalmazás identitásához

Megjegyzés:

A natív/C++ projektektől eltérően a .NET folyamat nem hoz létre winapp.yaml fájlt. A NuGet-csomagok közvetlenül az Ön .csproj-jén keresztül kerülnek kezelésre. Klónozás után futtassa a(z) dotnet restore vagy winapp restore parancsot.

Megnyithatja Package.appxmanifest az olyan tulajdonságok további testreszabásához, mint a megjelenítendő név, a közzétevő és a képességek.

Annak ellenőrzéséhez, hogy a csomagok hozzáadva lettek-e a projekthez:

dotnet list package

A kimenetben Microsoft.WindowsAppSDK és Microsoft.Windows.SDK.BuildTools kell megjelennie.

Konzolkimenet (nincs teendő)

Mivel konzolalkalmazást készítünk, a konzol kimenetének az aktuális terminálban kell maradnia. Az AUMID aktiválással a csomagolt alkalmazások nem kapnak konzolt, így a konzolalkalmazások megfelelően futnak, és semmit sem nyomtatnak ki.

A winapp ezt kezeli Ön helyett: a(z) OutputType=Exe használó alkalmazás ehelyett egy végrehajtási aliason keresztül indul el, amely örökli a terminál stdin/stdout/stderr csatornáit. Hozzáadja a szükséges uap5:ExecutionAlias elemet az előkészített jegyzékfájlhoz, ezért nincs mit konfigurálni.

A felhasználói felületi alkalmazások (WPF, WinForms, WinUI) saját ablakot jelenítenek meg, így megtartják az AUMID aktiválását.

Ha mégis kényszeríteni szeretné az AUMID beállítását egy konzolalkalmazásnál, állítsa be a következőt bármely <PropertyGroup> elemben a dotnet-app.csproj fájlban — az alkalmazás ezután konzol nélkül fut, és nem ír ki semmit a terminálra:

<WinAppRunUseExecutionAlias>false</WinAppRunUseExecutionAlias>

Ha inkább ön választja ki a parancs nevét, futtassa a(z) winapp manifest add-alias parancsot a(z) Package.appxmanifest fájlban való deklarálásához; az ön által megadott alias pontosan úgy lesz használva, ahogy van.

5. Hibakeresés identitással

Mivel winapp init hozzáadta a Microsoft.Windows.SDK.BuildTools.WinApp NuGet-csomagot a projekthez, egyszerűen futtathatja:

dotnet run

Ez automatikusan meghívja a winapp run a háttérben – létrehoz egy laza elrendezési csomagot, regisztrálja azt a Windows rendszerrel, és elindítja az alkalmazást teljes csomagazonosítóval.

A után írt argumentumok az dotnet run lesznek átadva, pontosan ugyanúgy, mintha a projekt nem hivatkozna erre a csomagra:

dotnet run --devtools          # your app receives --devtools
dotnet run -- --devtools       # identical: the SDK consumes the -- before forwarding

Használja a(z) -- elemet, amikor az alkalmazás kapcsolója egyben dotnet run opció is (--configuration, --framework, --project, -c, -f, -r, ...) — enélkül az SDK lefoglalja a token-t, és az alkalmazás soha nem kapja meg:

dotnet run -- --configuration Release   # your app receives --configuration Release

Konfigurálja magát a WinApp-indítót az WinAppRun* MSBuild tulajdonsággal. Az MSBuild ezeket használja, így soha nem érik el az alkalmazást:

dotnet run -p:WinAppRunDebugOutput=true --devtools

Itt ez a tulajdonság a WinAppot konfigurálja, míg a(z) --devtools átadásra kerül az alkalmazásnak. Tekintse meg dotnet run a teljes tulajdonságlista támogatását, beleértve azt is, hogy mely tulajdonságok nem kombinálhatók.

Megjegyzés:

Előfordulhat, hogy NuGet biztonsági résekre vonatkozó figyelmeztetések (NU1900) jelennek meg a csomagforrásokkal kapcsolatban. Ezeket nyugodtan figyelmen kívül hagyhatja – ezek nem befolyásolják a buildet.

A következőhöz hasonló kimenetnek kell megjelennie:

Package Family Name: dotnet-app_12345abcde

Ez megerősíti, hogy az alkalmazás érvényes csomagazonosítóval fut!

Alternatív: Kézi winapp run

Ha nem használta winapp init (vagy eltávolította a NuGet-csomagot), manuálisan is létrehozhat és futtathat. winapp run közvetlenül kezeli a projektet (projektmódban) – létrehozza a(z) .csproj-t, és elindítja, így nem kell a build kimeneti mappáját megadnia, és külön buildelnie sem:

# Build and run the project in one step (project mode)
winapp run .

# ...or run a specific project / configuration / architecture
winapp run .\dotnet-app.csproj -c Debug --arch x64

A projekt natív AOT-konfigurációjának futtatásához engedélyezze az AOT-t a projektben , és futtassa a következőt:

winapp run . --aot
winapp run . --aot -c Release

X64 vagy ARM64 használata. Egyszeri felülbíráláshoz adja hozzá a(z) -p PublishAot=true elemet.

Ha szeretné, a winapp run elemet továbbra is egy előre létrehozott kimeneti mappára irányíthatja (mappamód):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

A projektmód a csomagolt és a csomagolatlan WinUI-alkalmazásokat is támogatja — a projekt WindowsPackageType alapján felismeri, melyikről van szó, és automatikusan telepíti a megfelelő architektúrájú Windows-alkalmazás Runtime-ot. Ha egy csomagolt projektet csomagolatlanul szeretne futtatni, adja hozzá a következőt: -p WindowsPackageType=None

A többprojektes alkalmazások (az osztálykódtárakra hivatkozó alkalmazások) megfelelően épülnek fel: a winapp ahelyett, hogy az alkalmazás architektúráját a gráfra kényszeríti, a kompatibilis platformon tartja AnyCPU/netstandard2.0 a hivatkozásokat. A csak RID-alapú beállítás marad az alapértelmezett; amikor a tényleges konfiguráció önálló profilt igényel (például egy levágott Release-build esetén), a winapp automatikusan kiválasztja a megfelelő profilt a hivatkozott könyvtárak platformjának módosítása nélkül.

A dotnet build kimenete valós időben jelenik meg, és először a pontos parancshívás kerül kiírásra. Adja hozzá a(z) --verbose elemet a winapp saját builddöntési nyomkövetéseihez. .NET SDK 8.0.100 vagy újabb verziót igényel. Lásd winapp run a teljes beállításlista használati referenciájában .

Nincs telepítve Windows SDK? A C#/WinRT-projektek létrehozásához általában regisztrált Windows SDK-ra van szükség. Ha a projektmód nem észlel egyiket sem (tiszta CI, tárolók, SDK nélküli fejlesztői gépek), a cswinrt-t az automatikusan visszaállított Microsoft.Windows.SDK.NET.Ref csomagból származó winmd-fájlokra irányítja, így a build továbbra is sikeresen lefut — nincs szükség beavatkozásra. Nem történik semmi, ha telepítve van egy SDK, vagy ha Ön állítja be a(z) -p CsWinRTWindowsMetadata=… elemet.

A NuGet-csomag visszaadása: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Jótanács

Az automatikus dotnet run integráció letiltásához adja hozzá a <EnableWinAppRunSupport>false</EnableWinAppRunSupport> a saját .csproj-hez. A testreszabási lehetőségeket a dotnet futtatási támogatási dokumentumai között találhatja meg.

Alternatíva: Ritka csomag azonosítója

Ha kifejezetten a csomag ritkán használt viselkedésére van szüksége (fájlok másolása nélküli identitásra), használhatja create-debug-identity helyette. Ez egy ritka csomagot regisztrál, amely az exe-re mutat, nem pedig laza elrendezést hoz létre:

winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Ezután futtassa közvetlenül a végrehajtható fájlt (ne használja dotnet run , mert újraépítheti/felülírhatja a fájlt):

.\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Alternatív: Manuális MSBuild célkitűzés

Ha nem szeretné használni a NuGet csomagot, hozzáadhat egy egyéni célt az MSBuildhez, amely a hibakeresési buildek után fut create-debug-identity. Adja hozzá a .csproj fájlhoz a záró </Project> címke előtt:

  <!-- Automatically apply debug identity after Debug builds -->
  <Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

dotnet build ezzel a konfigurációval alkalmazza a hibakeresési identitást, és közvetlenül futtathatja a végrehajtható fájlt. Vegye figyelembe, hogy dotnet run újraépítheti és felülírhatja az identitást, ezért az építés után futtassa manuálisan az exe-t.

Jótanács

A speciális hibakeresési munkafolyamatokat (hibakeresők csatolása, IDE-beállítás, indítási hibakeresés) a hibakeresési útmutatóban találja.

Mikor érdemes kihagyni ezt: Ha az identitás alkalmazásakor a explicit vezérlést részesíti előnyben, vagy ha olyan kódon dolgozik, amely a fejlesztési ciklus nagy részében nem igényel identitást, a fenti manuális megközelítés egyszerűbb lehet.

6. A Windows App SDK használata (nem kötelező)

A Windows App SDK hozzáférést biztosít a modern Windows API-khoz azon túl, amit az SDK alap Windows biztosít – ilyen például az értesítési rendszer, az ablakos API-k, az alkalmazás életciklus-kezelése és az eszközön futó AI. Ha az alkalmazásnak szüksége van ezekre a képességekre, ezt a lépést Önnek kell tennie. Ha csak csomagidentitásra van szüksége a terjesztéshez, ugorjon a 7. lépésre.

Ha a winapp init futott (4. lépés), a Microsoft.WindowsAppSDK már NuGet-csomaghivatkozásként lett hozzáadva a .csproj-hez. Ellenőrizhet a dotnet list package segítségével. Ha kihagyta az SDK beállítását az init során, vagy manuálisan kell hozzáadnia, futtassa a következőt:

dotnet add package Microsoft.WindowsAppSDK

Program.cs frissítése

Cserélje le a Program.cs teljes tartalmát a következő kódra, amely hozzáad egy Windows-alkalmazás futtatókörnyezeti verzióellenőrzést:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");
            
            // Get Windows App Runtime version using the API
            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            // Thrown when app doesn't have package identity
            Console.WriteLine("Not packaged");
        }
    }
}

Építés és futtatás

Építse újra és futtassa az alkalmazást a Windows App SDK használatával. Mivel hozzáadtuk a WinAppSDK-t, identitással újra kell regisztrálnunk, hogy winapp hozzáadja a futtatókörnyezet függőségét. Ha hozzáadta a WinApp NuGet-csomagot (ajánlott), egyszerűen futtassa.dotnet run Ellenkező esetben (cserélje ki dotnet-app a projekt nevével):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Most a következő kimenetnek kell megjelennie:

Package Family Name: dotnet-app.debug_12345abcde
Windows App Runtime Version: 8000.770.947.0

A Windows App SDK NuGet csomag tartalmazza a modern Windows API-k eléréséhez szükséges összes szerelvényt, beleértve a következőket:

  • Értesítések és élő csempék
  • Ablakozás és alkalmazás életciklusa
  • Push értesítések
  • És még sok más Windows App SDK összetevő

A fejlettebb Windows App SDK használatért tekintse meg a Windows App SDK dokumentációját.

7. MSIX csomagolás

Miután készen áll az alkalmazás terjesztésére, ugyanazzal a jegyzékfájllal MSIX-ként csomagolhatja be.

Kiadásra kész build készítése

Először hozza létre az alkalmazást kiadási módban az optimális teljesítmény érdekében:

dotnet build -c Release

Megjegyzés:

A NuGet biztonsági résekre vonatkozó figyelmeztetései (NU1900) megjelenhetnek. Ezek nyugodtan figyelmen kívül hagyhatóak, és nem befolyásolják a build kimenetét.

Fejlesztési tanúsítvány létrehozása

A csomagolás előtt fejlesztési tanúsítványra van szüksége az aláíráshoz. Hozzon létre egyet, ha még nem tette meg:

winapp cert generate --if-exists skip

Aláírás és csomagolás

Most már csomagolhat és aláírhat. Irányítsa a csomagparancsot a build kimeneti mappájára (cserélje le dotnet-app-t és a TFM elérési utat a projekt értékeire):

# package and sign the app with the generated certificate
winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --cert .\devcert.pfx

Megjegyzés: A pack parancs automatikusan a Package.appxmanifestet használja az aktuális könyvtárból, és a csomagolás előtt átmásolja a célmappába. A létrehozott .msix fájl az aktuális könyvtárban lesz.

Tipp: Azt is kihagyhatja, hogy a build-output mappát keresse, és közvetlenül a projektből csomagoljon – winapp package .\dotnet-app.csproj --cert .\devcert.pfx egy lépésben teszi közzé és csomagolja a kimenetet (a projektmód alapértelmezés szerint a kiadási konfigurációra vonatkozik). A projektmód támogatja a következő buildbeállításokat: -c, --arch, -f, --no-build, --no-restore, -p; adja hozzá a(z) --no-build elemet egy meglévő build újraépítés nélküli becsomagolásához.

A tanúsítvány telepítése

Az MSIX-csomag telepítése előtt telepítenie kell a fejlesztési tanúsítványt. Futtassa ezt a parancsot rendszergazdaként:

winapp cert install .\devcert.pfx

Telepítés és futtatás

Telepítse a csomagot a létrehozott *.msix fájlra duplán kattintva.

Mostantól a terminál bármely pontjáról futtathatja az alkalmazást a következő beírással:

dotnet-app

Látnia kell a "Csomagcsalád neve" kimenetet, amely megerősíti, hogy telepítve van, és identitással fut.

Jótanács

Ha újra kell csomagolnia az alkalmazást (például a kódmódosítások után), növelje a verziószámot a VersionPackage.appxmanifest futtatása előtt. Windows egy telepített csomag frissítéséhez magasabb verziószám szükséges.

Tips

  1. Miután készen áll a terjesztésre, aláírhatja az MSIX-et egy hitelesítésszolgáltató kódaláíró tanúsítványával, hogy a felhasználóknak ne kelljen önaláírt tanúsítványt telepíteniük.
  2. A Microsoft Store aláírja Önnek az MSIX-et, a beküldés előtt nem kell aláírnia.
  3. Előfordulhat, hogy több MSIX-csomagot kell létrehoznia, egyet minden támogatott architektúrához (x64, Arm64). -r A jelzővel dotnet build meghatározott architektúrákat célozhat meg: dotnet build -c Release -r win-x64 vagydotnet build -c Release -r win-arm64.

MSIX-csomagolás automatizálása (nem kötelező)

Ha automatizálni szeretné az MSIX-csomagolást a kiadási buildek részeként, adja hozzá ezt a célt a .csproj fájlhoz (a hibakeresési identitás célhelyével együtt hozzáadhatja):

  <!-- Automatically package as MSIX after Release builds -->
  <Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <!-- Package and sign directly from build output -->
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Ezzel a konfigurációval:

  • A kiadási módban történő létrehozás (dotnet build -c Release) automatikusan létrehozza az MSIX-csomagot
  • Az MSIX a fejlesztési tanúsítvánnyal van csomagolva és aláírva
  • A végső .msix fájl a projekt gyökerében lesz

Egyéni konfigurációt is létrehozhat (például PackagedRelease), ha a feltételt a következőre módosítja: '$(Configuration)' == 'PackagedRelease'.

Következő lépések

  • Last updated on