Použití rozhraní příkazového řádku winapp s .NET

Tato příručka by měla fungovat pro většinu typů projektů .NET. Tento postup jsme otestovali pomocí konzolových i uživatelských projektů, jako je WPF (Windows Presentation Foundation). Pro funkční příklady se podívejte na ukázky dotnet-app (konzola) a wpf-app (WPF (Windows Presentation Foundation)).

Tato příručka ukazuje, jak pomocí rozhraní příkazového řádku winapp s aplikací .NET ladit s identitou balíčku a zabalit aplikaci jako MSIX.

Identita balíčku je základním konceptem modelu Windows app. Umožňuje vaší aplikaci přistupovat ke konkrétním rozhraním API Windows (jako jsou oznámení, zabezpečení, rozhraní API AI atd.), mají čisté prostředí pro instalaci a odinstalaci a další.

Standardní spustitelný soubor (například vytvořený pomocí dotnet build) nemá identitu balíčku. Tento průvodce ukazuje, jak ho přidat pro ladění a pak ho zabalit pro distribuci.

Předpoklady

.NET SDK: Nainstalujte sadu .NET SDK (vyžaduje restartování po instalaci):
```
winget install Microsoft.DotNet.SDK.10 --source winget
```
winapp CLI: Nainstalujte nástroj prostřednictvím wingetu (nebo aktualizujte winapp , pokud už je nainstalovaný):
```
winget install Microsoft.winappcli --source winget
```

1. Vytvoření nové aplikace .NET

Začněte vytvořením jednoduché konzolové aplikace .NET:

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

Spusťte ho, abyste měli jistotu, že všechno funguje:

dotnet run

Výstup by měl být "Hello, World!"

2. Aktualizace kódu pro kontrolu identity

Aplikaci aktualizujeme a zkontrolujeme, jestli běží s identitou balíčku. Pro přístup k rozhraním API balíčků použijeme rozhraní API prostředí Windows Runtime.

Nejprve aktualizujte soubor project tak, aby cílil na konkrétní verzi sady Windows SDK. Otevřete dotnet-app.csproj a změňte TargetFramework tak, aby zahrnovala verzi sady WINDOWS SDK:

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

Získáte tak přístup k rozhraním API prostředí Windows Runtime, aniž byste potřebovali další balíčky.

Teď nahraďte obsah Program.cs následujícím kódem. Tento kód se pokusí načíst aktuální identitu balíčku pomocí rozhraní WINDOWS RUNTIME API. Pokud bude úspěšný, vytiskne název rodiny balíčků; jinak se vytiskne "Není zabaleno".

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");
}

Spusťte (program) bez přiřazené identity.

Teď spusťte aplikaci obvyklým způsobem:

dotnet run

Měl by se zobrazit výstup "Není zabaleno". Tím potvrdíte, že standardní spustitelný soubor běží bez jakékoli identity balíčku.

4. Inicializace Project pomocí rozhraní příkazového řádku winapp

Příkaz winapp init automaticky rozpozná soubory .csproj a spustí .NET konkrétní instalaci. Nastaví vše, co potřebujete jedním tahem: ověří TargetFramework, přidá požadované balíčky NuGet, vygeneruje manifest aplikace a prostředky.

Spusťte následující příkaz a postupujte podle pokynů:

winapp init

Po zobrazení výzvy:

Název balíčku: Stisknutím klávesy Enter přijměte výchozí hodnotu (dotnet-app).
Publisher název: Stisknutím klávesy Enter přijměte výchozí hodnotu nebo zadejte své jméno.
Verze: Stisknutím klávesy Enter přijměte verzi 1.0.0.0.
Description: Stisknutím klávesy Enter přijměte výchozí hodnotu (Windows Aplikace) nebo zadejte popis.
Windows App SDK nastavení: Vyberte stabilní verzi, verzi Preview nebo Experimentální (určuje, kterou verzi Windows App SDK se přidá)
Aktualizace TargetFramework: Pokud váš TargetFramework neobsahuje podporovanou verzi sady SDK Windows, zobrazí se výzva k její aktualizaci (například na net10.0-windows10.0.26100.0)
Vývojářský režim: Pokud se zobrazí výzva k "Vývojářskému režimu", můžete ho zapnout, pokud chcete, ale mějte na paměti, že vyžaduje oprávnění správce.

Tento příkaz:

Aktualizujte TargetFramework ve .csproj na TFM podporovaný systémem Windows (v případě potřeby).
Přidejte odkazy na balíčky NuGet Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools a Microsoft.Windows.SDK.BuildTools.WinApp do svého .csproj
Vytvořte složky Package.appxmanifest a Assets pro identitu vaší aplikace

Poznámka:

Na rozdíl od nativních projektů nebo projektů C++ tok .NET nevytváří soubor winapp.yaml. Balíčky NuGet se spravují přímo prostřednictvím vašeho .csproj. Slouží dotnet restore k obnovení balíčků po klonování.

Můžete otevřít Package.appxmanifest a upravit vlastnosti, jako je zobrazovaný název, vydavatel a možnosti.

Ověření přidání balíčků do projektu:

dotnet list package

Ve výstupu byste měli vidět Microsoft.WindowsAppSDK a Microsoft.Windows.SDK.BuildTools.

Přidání spuštěcího aliasu (pro konzolové aplikace)

Vzhledem k tomu, že vytváříme konzolovou aplikaci, musíme zajistit dotnet run , aby výstup konzoly byl v aktuálním terminálu. Ve výchozím nastavení dotnet run spustí zabalenou aplikaci prostřednictvím aktivace AUMID, která otevře nové okno – a okno se hned po dokončení konzolové aplikace zavře a spolkne jakýkoli výstup.

Pokud chcete tento problém vyřešit, přidáte do manifestu alias pro spuštění a nastavíte integraci, aby se spustila přes tento alias.

Skip tento krok, pokud vytváříte aplikaci uživatelského rozhraní (WPF (Windows Presentation Foundation), WinForms, WinUI). Tyto aplikace vykreslují vlastní okno, takže výchozí spuštění AUMID je to, co potřebujete.

Přidejte výkonný alias do manifestu:
```
winapp manifest add-alias
```
Tím se přidá uap5:ExecutionAlias k Package.appxmanifest (který je ve výchozím nastavení názvem exe vašeho projektu), takže aplikace může být spuštěna podle názvu z terminálu.
dotnet run Řekněte integraci, aby používala alias. Otevřete dotnet-app.csproj a přidejte následující položky do libovolného <PropertyGroup> objektu (nebo v případě potřeby vytvořte nový <PropertyGroup> ):
```
<WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
```
S tímto nastavením vlastnosti dotnet run spustí aplikaci pomocí jejího aliasu spuštění a dědí stdin/stdout/stderr aktuálního terminálu, abyste viděli výstup z konzole přímo v textu.

5. Ladění pomocí identity

Vzhledem k tomu, že winapp init do projektu přidal balíček nuGet Microsoft.Windows.SDK.BuildTools.WinApp, můžete jednoduše spustit:

dotnet run

Tím se automaticky vyvolá winapp run pod kapotou – vytvoříte volný balíček rozložení, zaregistrujete ho v Windows a spustíte aplikaci s úplnou identitou balíčku.

Poznámka:

Může se zobrazit upozornění ohrožení zabezpečení NuGet (NU1900) o zdrojích balíčků. Ty lze bezpečně ignorovat – nemají vliv na vaši kompilaci.

Měl by se zobrazit výstup podobný následujícímu:

Package Family Name: dotnet-app_12345abcde

Tím potvrdíte, že vaše aplikace běží s platnou identitou balíčku.

Alternativní: Ruční `winapp run`

Pokud jste balíček NuGet nepoužíli winapp init (nebo jste ho odebrali), můžete sestavit a spustit ručně:

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

Postup přidání balíčku NuGet zpět: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Návod

Pokud chcete automatickou dotnet run integraci zakázat, přidejte <EnableWinAppRunSupport>false</EnableWinAppRunSupport> ji do souboru .csproj. Možnosti přizpůsobení najdete v dokumentaci podpory ke spuštění dotnetu .

Alternativa: Neúplná identita balíčku

Pokud potřebujete konkrétně řídké chování balíčku (identita bez kopírování souborů), můžete místo toho použít create-debug-identity . Tím se zaregistruje řídký balíček odkazující na váš exe místo vytvoření volného rozložení:

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

Potom spusťte spustitelný soubor přímo (nepoužívejte dotnet run ho, protože by mohl znovu sestavit nebo přepsat soubor):

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

Alternativa: Ručně vytvořený cíl MSBuild

Pokud nechcete používat balíček NuGet, můžete přidat vlastní cíl MSBuild, který se spustí po sestaveních v režimu ladění. Přidejte toto na konec souboru .csproj těsně před uzavírací značkou </Project>:

  <!-- 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>

V této konfiguraci dotnet build použijete identitu ladění a spustitelný soubor můžete spustit přímo. Všimněte si, že dotnet run může znovu sestavit a přepsat identitu systému, takže po sestavení spusťte exe ručně.

Návod

Pokročilé ladicí pracovní postupy (připojení ladicích programů, nastavení integrovaného vývojového prostředí, ladění po spuštění) najdete v průvodci laděním.

Kdy tuto možnost přeskočit: Pokud dáváte přednost explicitní kontrole nad tím, kdy se identita použije, nebo pokud pracujete na kódu, který pro většinu vývojového cyklu nepotřebuje identitu, může být výše uvedený ruční přístup jednodušší.

6. Použití Windows App SDK (volitelné)

Windows App SDK poskytuje přístup k moderním rozhraním API Windows nad rámec toho, co poskytuje základní sada WINDOWS SDK – například systém oznámení, rozhraní API pro okna, správa životního cyklu aplikací a AI na zařízení. Pokud vaše aplikace potřebuje některou z těchto funkcí, je tento krok určený pro vás. Pokud potřebujete jenom identitu balíčku pro distribuci, můžete přeskočit ke kroku 7.

Pokud jste spustili winapp init (krok 4), Microsoft.WindowsAppSDK byl již přidán jako odkaz na balíček NuGet na váš .csproj. Můžete to ověřit pomocí dotnet list packagepříkazu . Pokud jste během inicializaci přeskočili nastavení sady SDK nebo ho potřebujete přidat ručně, spusťte:

dotnet add package Microsoft.WindowsAppSDK

Aktualizace Program.cs

Celý obsah souboru Program.cs nahraďte následujícím kódem, který přidá kontrolu verze modulu aplikace pro Windows Runtime:

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");
        }
    }
}

Sestavení a spuštění

Znovu sestavte a spusťte aplikaci pomocí Windows App SDK. Vzhledem k tomu, že jsme přidali WinAppSDK, musíme se znovu zaregistrovat pomocí identity, aby se winapp přidala závislost na modulu runtime. Pokud jste přidali balíček NuGet WinApp (doporučeno), jednoduše spusťte dotnet run. Jinak (nahraďte dotnet-app názvem projektu):

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

Teď by se měl zobrazit výstup jako:

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

Balíček NuGet Windows App SDK obsahuje všechna potřebná sestavení pro přístup k moderním rozhraním API Windows, včetně:

Oznámení a živé dlaždice
Životní cyklus oken a aplikace
Oznámení push
A mnoho dalších komponent Windows App SDK

Pokud chcete pokročilejší Windows App SDK využití, přečtěte si dokumentaci k Windows App SDK.

7. Balíček s MSIX

Jakmile budete připraveni distribuovat aplikaci, můžete ji zabalit jako MSIX pomocí stejného manifestu.

Sestavení pro vydání

Nejprve sestavte aplikaci v režimu vydávání, abyste mohli dosáhnout optimálního výkonu:

dotnet build -c Release

Poznámka:

Může se zobrazit upozornění ohrožení zabezpečení NuGet (NU1900). Je bezpečné to ignorovat a nemá to vliv na výstup sestavení.

Vygenerování vývojového certifikátu

Před balením potřebujete vývojový certifikát pro podepisování. Vygenerujte ho, pokud jste to ještě neudělali:

winapp cert generate --if-exists skip

Podepsání a balení

Teď můžete zabalit a podepsat. Nasměrujte příkaz balíčku na výstupní složku sestavení (nahraďte dotnet-app cestu TFM hodnotami projektu):

# 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

Poznámka: Příkaz pack před zabalení automaticky použije Package.appxmanifest z aktuálního adresáře a zkopíruje ho do cílové složky. Vygenerovaný soubor .msix bude v aktuálním adresáři.

Instalace certifikátu

Než budete moct nainstalovat balíček MSIX, musíte nainstalovat vývojový certifikát. Spusťte tento příkaz jako správce:

winapp cert install .\devcert.pfx

Instalace a spuštění

Nainstalujte balíček poklikáním na vygenerovaný soubor *.msix.

Teď můžete aplikaci spustit odkudkoli v terminálu zadáním:

dotnet-app

Měl by se zobrazit výstup "Název rodiny balíčků", čímž se potvrdí jeho instalace a spuštění pod danou identitou.

Návod

Pokud potřebujete aplikaci znovu přebalit (např. po změně kódu), před dalším spuštěním Package.appxmanifest zvyšte hodnotu Version. Windows k aktualizaci nainstalovaného balíčku vyžaduje vyšší číslo verze.

Tips

Jakmile budete připraveni k distribuci, můžete podepisovat MSIX certifikátem pro podepisování kódu od certifikační autority, aby uživatelé nemuseli instalovat certifikát podepsaný svým držitelem.
Microsoft Store za vás podepíše MSIX, před odesláním se nemusíte podepisovat.
Možná budete muset vytvořit několik balíčků MSIX, jeden pro každou architekturu, kterou podporujete (x64, Arm64). Příznak -r použijte s dotnet build k cílení na konkrétní architektury: dotnet build -c Release -r win-x64 nebo dotnet build -c Release -r win-arm64.

Automatizace balení MSIX (volitelné)

Pokud chcete balíček MSIX automatizovat jako součást sestavení vydaných verzí, přidejte tento cíl do .csproj souboru (můžete ho přidat společně s cílem ladění identity):

  <!-- 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>

S touto konfigurací:

Sestavení v režimu vydání (dotnet build -c Release) automaticky vytvoří balíček MSIX.
MSIX je zabalený a podepsaný pomocí vývojového certifikátu.
Konečný .msix soubor bude v kořenovém adresáři projektu.

Můžete také vytvořit vlastní konfiguraci (např. PackagedRelease) úpravou podmínky na '$(Configuration)' == 'PackagedRelease'.

Další kroky

Distribuujte pomocí winget: Odešlete svůj MSIX do repizitáře Windows Správce balíčků Community
Publish do Microsoft Store: Odešlete balíček pomocí winapp store
Nastavte CI/CD: Použijte akci setup-WinAppCli GitHub ke zautomatizování balení v pipeline
prozkoumat rozhraní Windows API: S identitou balíčku teď můžete používat oznámení, AI na zařízení a další rozhraní API závislé na identitě

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-12

Použití rozhraní příkazového řádku winapp s .NET

Předpoklady

1. Vytvoření nové aplikace .NET

2. Aktualizace kódu pro kontrolu identity

Spusťte (program) bez přiřazené identity.

4. Inicializace Project pomocí rozhraní příkazového řádku winapp

Přidání spuštěcího aliasu (pro konzolové aplikace)

5. Ladění pomocí identity

Alternativní: Ruční winapp run

Alternativa: Neúplná identita balíčku

Alternativa: Ručně vytvořený cíl MSBuild

6. Použití Windows App SDK (volitelné)

Aktualizace Program.cs

Sestavení a spuštění

7. Balíček s MSIX

Sestavení pro vydání

Vygenerování vývojového certifikátu

Podepsání a balení

Instalace certifikátu

Instalace a spuštění

Tips

Automatizace balení MSIX (volitelné)

Další kroky

Váš názor

Další materiály

Alternativní: Ruční `winapp run`