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

.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
```
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 .csproj elemet a TargetFramework 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. A csomagok klónozás utáni visszaállítására használható dotnet restore .

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.

Végrehajtási alias hozzáadása (konzolalkalmazásokhoz)

Mivel konzolalkalmazást készítünk, meg kell győződnünk arról, hogy dotnet run a konzol kimenete az aktuális terminálban marad. Alapértelmezés szerint dotnet run elindítja a csomagolt alkalmazást az AUMID aktiválással, amely új ablakot nyit meg – és az ablak azonnal bezárul, amikor a konzolalkalmazás befejeződik, és lenyeli a kimenetet.

A probléma megoldásához hozzá kell adnia egy végrehajtási aliast a jegyzékhez, és meg kell mondania a futtatási integrációnak, hogy az aliason keresztül induljon el.

Ha felhasználói felületi alkalmazást készít (WPF, WinForms, WinUI), hagyja ki ezt a lépést. Ezek az alkalmazások a saját ablakukat jelenítik meg, ezért az alapértelmezett AUMID-indítás az, amit szeretne.

Adja hozzá a végrehajtási aliast a jegyzékhez:
```
winapp manifest add-alias
```
Ez hozzáad egy uap5:ExecutionAlias elemet Package.appxmanifest-hez, ami alapértelmezés szerint a projekt exe nevére állítódik, így az alkalmazás a név megadásával indítható el egy terminálból.
Állítsa be az dotnet run integrációt az alias használatához. Nyissa meg dotnet-app.csproj és adja hozzá a következőket bármelyikbe <PropertyGroup> (vagy hozzon létre egy újat <PropertyGroup> , ha szükséges):
```
<WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
```
Ezzel a tulajdonságkészlettel dotnet run elindítja az alkalmazást annak végrehajtási álneve segítségével, és az aktuális terminál stdin/stdout/stderr azonosítóját örökli, így a konzol kimenete közvetlenül jelenik meg.

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.

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:

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

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.

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

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.
A Microsoft Store aláírja Önnek az MSIX-et, a beküldés előtt nem kell aláírnia.
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

Distribute via winget: Küldje el MSIX-ét a Windows Csomagkezelő közösségi adattárba
Tegye közzé a Microsoft Store-ban: Küldje be a csomagot a winapp store segítségével
Set up CI/CD: A setup-WinAppCli GitHub Művelettel automatizálhatja a csomagolást a folyamatban
Explore Windows API-k: Csomagidentitással mostantól használhatja az Értesítések, a helyi eszközi AI, és egyéb identitásfüggő API-kat

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-05-12

Winapp CLI használata .NET

Előfeltételek

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

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

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

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

Végrehajtási alias hozzáadása (konzolalkalmazásokhoz)

5. Hibakeresés identitással

Alternatív: Kézi winapp run

Alternatíva: Ritka csomag azonosítója

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

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

Program.cs frissítése

Építés és futtatás

7. MSIX csomagolás

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

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

Aláírás és csomagolás

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

Telepítés és futtatás

Tips

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

Következő lépések

Visszajelzés

További források

Alternatív: Kézi `winapp run`