Korzystanie z winapp CLI z platformą .NET

Ten przewodnik powinien działać w przypadku większości typów projektów .NET. Kroki zostały przetestowane w projektach konsolowych oraz projektach typu WPF opartych na interfejsie użytkownika. Aby zapoznać się z przykładami pracy, zapoznaj się z przykładami dotnet-app (konsola) i wpf-app (WPF) w folderze samples.

W tym przewodniku pokazano, jak używać interfejsu wiersza polecenia (CLI) winapp z aplikacją .NET do debugowania z wykorzystaniem tożsamości pakietu oraz zapakowania aplikacji w postaci pliku MSIX.

Tożsamość pakietu jest podstawową koncepcją w modelu Windows app. Umożliwia Twojej aplikacji dostęp do specyficznych interfejsów API Windows (takich jak powiadomienia, zabezpieczenia, interfejsy API sztucznej inteligencji itp.), zapewnia czyste środowisko instalacji i dezinstalacji oraz oferuje wiele innych funkcji.

Standardowy plik wykonywalny (taki jak utworzony za pomocą dotnet buildpolecenia ) nie ma tożsamości pakietu. W tym przewodniku pokazano, jak dodać go do debugowania, a następnie spakować go do dystrybucji.

Wymagania wstępne

.NET SDK: Zainstaluj zestaw SDK .NET (wymaga ponownego uruchomienia po instalacji):
```
winget install Microsoft.DotNet.SDK.10 --source winget
```
winapp CLI: Zainstaluj narzędzie winapp za pomocą pakietu winget (lub zaktualizuj, jeśli już zainstalowane):
```
winget install Microsoft.winappcli --source winget
```

1. Tworzenie nowej aplikacji .NET

Zacznij od utworzenia prostej aplikacji konsolowej .NET:

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

Uruchom go, aby upewnić się, że wszystko działa:

dotnet run

Dane wyjściowe powinny mieć wartość "Hello, World!"

2. Zaktualizuj kod, aby sprawdzić tożsamość

Zaktualizujemy aplikację, aby sprawdzić, czy jest ona uruchomiona przy użyciu tożsamości pakietu. Użyjemy interfejsu API środowisko wykonawcze systemu Windows, aby uzyskać dostęp do API pakietów.

Najpierw zaktualizuj plik project, aby był przeznaczony dla określonej wersji zestawu Windows SDK. Otwórz dotnet-app.csproj i zmień TargetFramework, aby uwzględnić wersję zestawu SDK Windows:

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

Zapewnia to dostęp do interfejsów API środowisko wykonawcze systemu Windows bez konieczności używania dodatkowych pakietów.

Teraz zastąp zawartość Program.cs pliku poniższym kodem. Ten kod próbuje pobrać bieżącą tożsamość pakietu przy użyciu interfejsu API środowisko wykonawcze systemu Windows. Jeśli to się powiedzie, wyświetla nazwę rodziny pakietów; w przeciwnym razie wyświetla tekst "Nie spakowane".

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. Uruchamianie bez tożsamości

Teraz uruchom aplikację w zwykły sposób:

dotnet run

Powinny zostać wyświetlone dane wyjściowe "Nie spakowane". Potwierdza to, że standardowy plik wykonywalny jest uruchomiony bez żadnej tożsamości pakietu.

4. Inicjowanie Projektu za pomocą CLI winapp

Polecenie winapp init automatycznie wykrywa pliki .csproj i uruchamia konfigurację specyficzną dla .NET. Konfiguruje wszystko, czego potrzebujesz w jednym miejscu: weryfikuje element TargetFramework, dodaje wymagane pakiety NuGet, generuje manifest aplikacji i zasoby.

Uruchom następujące polecenie i postępuj zgodnie z monitami:

winapp init

Po wyświetleniu monitu:

Nazwa pakietu: naciśnij klawisz Enter, aby zaakceptować wartość domyślną (dotnet-app)
Nazwa wydawcy: Naciśnij klawisz Enter, aby zaakceptować wartość domyślną lub wprowadź swoją nazwę
Wersja: Naciśnij klawisz Enter, aby zaakceptować 1.0.0.0
Description: Naciśnij klawisz Enter, aby zaakceptować wartość domyślną (Windows Aplikacja) lub wprowadź opis
Zestaw SDK do aplikacji systemu Windows setup: Select Stable, Preview lub Experimental (określa, która wersja Zestaw SDK do aplikacji systemu Windows jest dodawana)
TargetFramework update: Jeśli TargetFramework nie zawiera obsługiwanej wersji zestawu SDK Windows, zostanie wyświetlony monit o zaktualizowanie go (np. net10.0-windows10.0.26100.0)
Tryb dewelopera: jeśli zostanie wyświetlony monit o "Tryb dewelopera", możesz włączyć go, jeśli chcesz, ale pamiętaj, że wymaga uprawnień administracyjnych

To polecenie spowoduje:

Zaktualizuj TargetFramework w .csproj do TFM obsługiwanego przez Windows (w razie potrzeby)
Dodaj Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools i Microsoft.Windows.SDK.BuildTools.WinApp odwołania do pakietu NuGet do .csproj
Utwórz folder Package.appxmanifest i Assets dla tożsamości aplikacji

Uwaga / Notatka

W przeciwieństwie do projektów natywnych/C++ przepływ .NET nie tworzy pliku . Pakiety NuGet są zarządzane bezpośrednio za pośrednictwem elementu .csproj. Użyj dotnet restore, aby przywrócić pakiety po sklonowaniu.

Możesz otworzyć Package.appxmanifest aby jeszcze bardziej dostosować właściwości, takie jak nazwa wyświetlana, wydawca i funkcje.

Aby sprawdzić, czy pakiety zostały dodane do projektu:

dotnet list package

W danych wyjściowych powinny zostać wyświetlone Microsoft.WindowsAppSDK i Microsoft.Windows.SDK.BuildTools.

Dodawanie aliasu wykonywania (dla aplikacji konsolowych)

Ponieważ tworzymy aplikację konsolową, musimy upewnić się, że dotnet run nadal wyświetla dane wyjściowe na bieżącym terminalu. Domyślnie dotnet run uruchamia aplikację pakietową za pośrednictwem aktywacji AUMID, która otwiera nowe okno — a okno zamyka się natychmiast po zakończeniu pracy aplikacji konsolowej, przechwytując dane wyjściowe.

Aby rozwiązać ten problem, należy dodać alias wykonywania do manifestu i poinformować, że integracja uruchamiania zostanie uruchomiona za pośrednictwem tego aliasu.

Skip ten krok, jeśli tworzysz aplikację interfejsu użytkownika (WPF, WinForms, WinUI). Te aplikacje renderują własne okno, więc uruchomienie domyślnego identyfikatora AUMID jest odpowiednie.

Dodaj alias uruchomienia do manifestu:
```
winapp manifest add-alias
```
Spowoduje to dodanie uap5:ExecutionAlias elementu ( Package.appxmanifest domyślnie do nazwy exe projektu), aby aplikacja mogła zostać uruchomiona według nazwy z terminalu.
Powiedz integracji, aby użyła aliasu. Otwórz dotnet-app.csproj i dodaj następujące elementy wewnątrz dowolnego <PropertyGroup> (lub utwórz nowy <PropertyGroup> w razie potrzeby):
```
<WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
```
Gdy ta właściwość jest ustawiona, dotnet run uruchamia aplikację za pomocą aliasu uruchamiania i dzieli stdin/stdout/stderr z bieżącym terminalem, więc widzisz wynik konsoli w linii.

5. Debugowanie przy użyciu tożsamości

Ponieważ winapp init dodał pakiet Microsoft.Windows.SDK.BuildTools.WinApp NuGet do projektu, możesz po prostu uruchomić:

dotnet run

Spowoduje to automatyczne wywołanie winapp run pod maską — utworzenie luźnego pakietu układu, zarejestrowanie go w Windows i uruchomienie aplikacji z pełną tożsamością pakietu.

Uwaga / Notatka

Mogą pojawić się ostrzeżenia dotyczące luk w zabezpieczeniach NuGet (NU1900) dotyczące źródeł pakietów. Bez obaw można je zignorować — nie wpływają na kompilację.

Powinny zostać wyświetlone dane wyjściowe podobne do następujących:

Package Family Name: dotnet-app_12345abcde

Potwierdza to, że aplikacja jest uruchomiona z prawidłową tożsamością pakietu!

Alternatywa: Ręczne `winapp run`

Jeśli nie użyto winapp init (lub usunięto pakiet NuGet), możesz skompilować i uruchomić ręcznie:

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

Aby ponownie dodać pakiet NuGet: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Wskazówka

Aby wyłączyć automatyczną dotnet run integrację, dodaj <EnableWinAppRunSupport>false</EnableWinAppRunSupport> do .csproj. Aby uzyskać opcje dostosowywania, zobacz dotnet run support docs (Dokumentacja dotycząca obsługi uruchamiania dotnet ).

Alternatywna: tożsamość pakietu rozrzednego

Jeśli potrzebujesz rzadkiego zachowania pakietów (identyczność bez kopiowania plików), możesz użyć zamiast tego create-debug-identity. Spowoduje to zarejestrowanie rzadkiego pakietu wskazującego na plik exe zamiast tworzenia luźnego rozmieszczenia.

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

Następnie uruchom plik wykonywalny bezpośrednio (nie używaj dotnet run, ponieważ może on ponownie skompilować lub zastąpić plik):

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

Alternatywa: Ręczny cel MSBuild

Jeśli nie chcesz używać pakietu NuGet, możesz dodać niestandardowy element docelowy programu MSBuild uruchamiany create-debug-identity po kompilacjach debugowania. Dodaj to do pliku .csproj na końcu, tuż przed zamykającym tagiem </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>

W przypadku tej konfiguracji dotnet build stosuje identyfikator debugowania i umożliwia bezpośrednie uruchomienie pliku wykonywalnego. Pamiętaj, że dotnet run może to spowodować ponowne skompilowanie i zastąpienie tożsamości, dlatego uruchom plik exe ręcznie po utworzeniu.

Wskazówka

Aby uzyskać zaawansowane scenariusze debugowania (dołączanie debugerów, konfigurowanie środowiska IDE, debugowanie uruchamiania), zobacz Przewodnik debugowania.

Kiedy pominąć to: Jeśli wolisz jawną kontrolę nad zastosowaniem tożsamości lub jeśli pracujesz nad kodem, który nie potrzebuje tożsamości w większości cyklu programowania, powyższe podejście ręczne może być prostsze.

6. Używanie Zestaw SDK do aplikacji systemu Windows (opcjonalnie)

Zestaw SDK do aplikacji systemu Windows zapewnia dostęp do nowoczesnych interfejsów API Windows poza podstawowym zestawem SDK Windows — takich jak system powiadomień, interfejsy API okien, zarządzanie cyklem życia aplikacji i sztuczna inteligencja na urządzeniu. Jeśli Twoja aplikacja potrzebuje dowolnej z tych możliwości, ten krok jest dla Ciebie. Jeśli potrzebujesz tożsamości pakietu do dystrybucji, możesz przejść do kroku 7.

Jeśli uruchomiłeś winapp init (krok 4), Microsoft.WindowsAppSDK został już dodany jako odwołanie pakietu NuGet do .csproj. Możesz zweryfikować za pomocą polecenia dotnet list package. Jeśli podczas inicjowania pominięto konfigurację zestawu SDK lub musisz dodać ją ręcznie, uruchom polecenie:

dotnet add package Microsoft.WindowsAppSDK

Zaktualizuj Program.cs

Zastąp całą zawartość Program.cs następującym kodem, który dodaje sprawdzanie wersji środowiska uruchomieniowego aplikacja dla systemu Windows:

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

Budowanie i uruchamianie

Skompiluj i uruchom aplikację przy użyciu Zestaw SDK do aplikacji systemu Windows. Ponieważ dodaliśmy zestaw WinAppSDK, musimy ponownie zarejestrować się przy użyciu tożsamości, aby winapp dodać zależność środowiska uruchomieniowego. Jeśli dodano pakiet NuGet WinApp (zalecane), po prostu uruchom dotnet run. W przeciwnym razie (zastąp dotnet-app nazwą projektu):

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

Powinny zostać wyświetlone dane wyjściowe, takie jak:

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

Pakiet Zestaw SDK do aplikacji systemu Windows NuGet zawiera wszystkie zestawy niezbędne do uzyskiwania dostępu do nowoczesnych interfejsów API Windows, w tym:

Powiadomienia i dynamiczne kafelki
Cykl życia okien i aplikacji
Powiadomienia push
I wiele innych składników Zestaw SDK do aplikacji systemu Windows

Aby uzyskać bardziej zaawansowane użycie Zestaw SDK do aplikacji systemu Windows, zapoznaj się z dokumentacją Zestaw SDK do aplikacji systemu Windows.

7. Pakiet z plikiem MSIX

Gdy wszystko będzie gotowe do dystrybucji aplikacji, możesz spakować ją jako plik MSIX przy użyciu tego samego manifestu.

Kompilacja dla wydania

Najpierw skompiluj aplikację w trybie wydania, aby uzyskać optymalną wydajność:

dotnet build -c Release

Uwaga / Notatka

Mogą zostać wyświetlone ostrzeżenia dotyczące luk w zabezpieczeniach NuGet (NU1900). Są one bezpieczne do ignorowania i nie mają wpływu na dane wyjściowe kompilacji.

Generowanie certyfikatu programistycznego

Przed pakowaniem potrzebny jest certyfikat dewelopera do podpisywania. Wygeneruj go, jeśli jeszcze tego nie zrobiono:

winapp cert generate --if-exists skip

Podpisywanie i pakowanie

Teraz możesz spakować i podpisać. Skieruj polecenie pack do folderu wyjściowego kompilacji, zastępując dotnet-app i ścieżkę TFM wartościami 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

Uwaga: polecenie pack automatycznie używa pliku Package.appxmanifest z bieżącego katalogu i kopiuje go do folderu docelowego przed opakowaniem. Wygenerowany plik msix będzie znajdować się w bieżącym katalogu.

Instalowanie certyfikatu

Przed zainstalowaniem pakietu MSIX należy zainstalować certyfikat dewelopera. Uruchom to polecenie jako administrator:

winapp cert install .\devcert.pfx

Instalowanie i uruchamianie

Zainstaluj pakiet, klikając dwukrotnie wygenerowany plik *.msix.

Teraz możesz uruchomić aplikację z dowolnego miejsca w terminalu, wpisując:

dotnet-app

Powinny zostać wyświetlone dane wyjściowe "Nazwa rodziny pakietów", potwierdzające, że pakiet został zainstalowany i działa z unikalnym identyfikatorem.

Wskazówka

Jeśli musisz ponownie spakować aplikację (np. po zmianie kodu), zwiększ Version wartość w Package.appxmanifest przed ponownym uruchomieniem winapp pack . Windows wymaga wyższego numeru wersji w celu zaktualizowania zainstalowanego pakietu.

Porady

Gdy wszystko będzie gotowe do dystrybucji, możesz podpisać plik MSIX przy użyciu certyfikatu podpisywania kodu z urzędu certyfikacji, aby użytkownicy nie musieli instalować certyfikatu z podpisem własnym.
Microsoft Store podpisze plik MSIX bez konieczności podpisywania przed przesłaniem.
Może być konieczne utworzenie wielu pakietów MSIX — po jednym dla każdej obsługiwanej architektury (x64, Arm64). Użyj flagi -r z dotnet build , aby kierować do określonych architektur: dotnet build -c Release -r win-x64 lub dotnet build -c Release -r win-arm64.

Automatyzowanie pakowania MSIX (opcjonalnie)

Aby zautomatyzować pakowanie MSIX w ramach kompilacji wydawniczych, dodaj ten cel do pliku .csproj (możesz dodać go wraz z celem do debugowania).

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

W tej konfiguracji:

Kompilowanie w trybie wydania (dotnet build -c Release) spowoduje automatyczne utworzenie pakietu MSIX
Plik MSIX jest spakowany i podpisany przy użyciu certyfikatu dewelopera
Plik ostateczny .msix znajdzie się w katalogu głównym projektu

Można również utworzyć konfigurację niestandardową (np. PackagedRelease), modyfikując warunek na '$(Configuration)' == 'PackagedRelease'.

Dalsze kroki

Rozprowadź za pomocą narzędzia winget: Prześlij swój plik MSIX do Windows Menedżer pakietów Community Repository
Publikuj w Microsoft Store: Użyj winapp store aby przesłać pakiet
Konfigurowanie CI/CD: Użyj akcji setup-WinAppCli GitHub, aby zautomatyzować tworzenie pakietów w potoku
Zapoznaj się z interfejsami API Windows: z tożsamością pakietu możesz teraz użyć Powiadomień, AI na urządzeniu oraz innych interfejsów API zależnych od tożsamości

Opinia

Czy ta strona była pomocna?

Last updated on 2026-05-12

Korzystanie z winapp CLI z platformą .NET

Wymagania wstępne

1. Tworzenie nowej aplikacji .NET

2. Zaktualizuj kod, aby sprawdzić tożsamość

3. Uruchamianie bez tożsamości

4. Inicjowanie Projektu za pomocą CLI winapp

Dodawanie aliasu wykonywania (dla aplikacji konsolowych)

5. Debugowanie przy użyciu tożsamości

Alternatywa: Ręczne winapp run

Alternatywna: tożsamość pakietu rozrzednego

Alternatywa: Ręczny cel MSBuild

6. Używanie Zestaw SDK do aplikacji systemu Windows (opcjonalnie)

Zaktualizuj Program.cs

Budowanie i uruchamianie

7. Pakiet z plikiem MSIX

Kompilacja dla wydania

Generowanie certyfikatu programistycznego

Podpisywanie i pakowanie

Instalowanie certyfikatu

Instalowanie i uruchamianie

Porady

Automatyzowanie pakowania MSIX (opcjonalnie)

Dalsze kroki

Opinia

Dodatkowe zasoby

Alternatywa: Ręczne `winapp run`