Dokumentacja interfejsu wiersza polecenia i użycie

Wersja

Wydrukuj zainstalowaną wersję aplikacji winapp z lub jego krótką formą --version-V:

winapp -V

Małe litery -v to krótka forma --verbose poleceń (na przykład winapp restore -v).

Uzupełnianie powłoki

Włącz uzupełnianie kart dla poleceń, opcji i wartości. Aby uzyskać instrukcje dotyczące konfiguracji, zobacz Przewodnik po uzupełnianiu powłoki .

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

inicjacja

Zainicjuj katalog przy użyciu zestawu Windows SDK, Zestaw SDK do aplikacji systemu Windows i wymaganych zasobów na potrzeby nowoczesnego programowania w systemie Windows.

winapp init [base-directory] [options]

argumenty:

base-directory - Katalog podstawowy/główny dla aplikacji/obszaru roboczego (ustawienie domyślne: bieżący katalog)

Opcje:

--config-dir <path> - Katalog do odczytu/przechowywania konfiguracji (ustawienie domyślne: wybrany katalog projektu lub bieżący katalog, jeśli nie zostanie wykryty żaden projekt)
--setup-sdks - Tryb instalacji zestawu SDK: "stable" (ustawienie domyślne), "preview", "experimental" lub "none" (pomiń instalację zestawu SDK)
--ignore-config, --no-config — nie używaj pliku konfiguracji do zarządzania wersjami
--no-gitignore - Nie aktualizuj pliku .gitignore
--use-defaults, --no-prompt — nie monituj i użyj wartości domyślnej wszystkich monitów
--config-only — Obsługa tylko operacji na plikach konfiguracji, pomijanie instalacji pakietu
--exe <path> — Ścieżka do pliku wykonywalnego aplikacji. Wymaga --sparse. Generuje manifest tylko do obsługi tożsamości dla pliku exe zamiast pełnej konfiguracji pakietu/zestawu SDK.
--sparse — Generuj rozrzedny manifest tożsamości (appxmanifest.xml) dla istniejącego pliku exe pulpitu. Pomija instalację zestawu SDK/pakietu. Użyj z --exe.
--name <name> — Zastąp nazwę pakietu (tylko rozrzedzony; wartość domyślna: wywnioskowana z pliku exe)
--publisher <CN> — Zastąp nazwę CN wydawcy (tylko rozrzedzony; wartość domyślna: wywnioskowana z nazwy firmy exe)
--output-dir <path> - Katalog do zapisywania rozrzednego manifestu i Assets/ (tylko rozrzedzęt; ustawienie domyślne: sparse/ folder w bieżącym katalogu)
--force - Zastąp istniejący appxmanifest.xml w katalogu docelowym (tylko rozrzedłe). Bez niego inicjowanie kończy się niepowodzeniem zamiast zastępowania istniejącego manifestu/zasobów.
--add-js-bindings (tylko narzędzie npm) — dodaj winapp.jsBindings do package.json i wygeneruj powiązania JS/TypeScript bez monitowania (niezgodne z --setup-sdks none)

Co to robi:

Tworzy winapp.yaml plik konfiguracji (tylko wtedy, gdy pakiety zestawu SDK są zarządzane; pomijane za pomocą polecenia --setup-sdks none)
Pobieranie zestawów Windows SDK i pakietów Zestaw SDK do aplikacji systemu Windows
Używa najnowszej wersji Zestaw SDK do aplikacji systemu Windows w wybranym --setup-sdks kanale. Jeśli ta wersja jest nadal publikowana, a niektóre z jego pakietów nie są jeszcze dostępne, init zamiast tego używa poprzedniej wersji i drukuje notatkę, mówiąc tak. Aby przejść do nowej wersji później, uruchom polecenie winapp updatelub dla projektu .NET, dotnet add package Microsoft.WindowsAppSDK --version <new version>.
Generuje nagłówki i pliki binarne języka C++/WinRT
Tworzy plik Package.appxmanifest
Konfiguruje narzędzia kompilacji i włącza tryb dewelopera
Aktualizuje plik gitignore w celu wykluczenia wygenerowanych plików
Przechowuje pliki do udostępniania w katalogu globalnej pamięci podręcznej
Generuje powiązania JS dla interfejsów API Zestaw SDK do aplikacji systemu Windows po włączeniu (tylko narzędzie npm)

Automatyczne wykrywanie projektów:

Po init uruchomieniu bez argumentu katalogu wykonuje wyszukiwanie według zakresu bieżącego drzewa katalogów w celu znalezienia zgodnych projektów (do 10). Obsługiwane typy projektów:

Tauri — tauri.conf.json znaleziono jeden poziom poniżej katalogu
Elektron — package.json z zależnościami electron lub devDependencies
Trzecie — pubspec.yaml w katalogu głównym projektu
.NET — .csproj w katalogu głównym projektu
Rust — Cargo.toml w katalogu głównym projektu
C++ — CMakeLists.txt w katalogu głównym projektu

Wyszukiwanie pomija często ignorowane katalogi (node_modules, bin, obj, .git itp.). Po znalezieniu zgodnego projektu podkatalogi poniżej nie są przeszukiwane.

Jeśli zostanie podany argument katalogu (np winapp init . . lub winapp init path/to/project), wyszukiwanie zostanie pominięte i init sprawdza tylko ten katalog dla zgodnego projektu
Jeśli --use-defaults parametr (lub --no-prompt) jest ustawiony bez argumentu katalogu, init pomija wyszukiwanie i inicjuje bieżący katalog nieinterakcyjny, najpierw ostrzeżenie, jeśli nie wykryto tam znanego typu projektu (np. winapp init --use-defaults)
W środowiskach nieinterakcyjnych (potokowe stdin, CI, przekierowane dane wejściowe) init automatycznie używa --use-defaults zachowania i emituje ostrzeżenie: Non-interactive environment detected. Using default values.
Jeśli bieżący katalog jest zgodnym projektem, init następuje natychmiast
Jeśli dokładnie jeden projekt zostanie znaleziony w innym miejscu, zostanie wyświetlony monit o potwierdzenie
Jeśli znaleziono wiele projektów, możesz wybrać, który z nich ma być inicjowany — bieżący katalog jest zawsze dostępny jako opcja rezerwowa
Jeśli nie znaleziono żadnych projektów, zostanie wyświetlone ostrzeżenie i pytanie, czy mimo to kontynuować
Jeśli wyszukiwanie osiągnie limit 10 projektów, ostrzeżenie sugeruje podanie argumentu katalogu

Przepływ projektu automatycznego .NET:

Gdy plik .csproj zostanie znaleziony w katalogu docelowym, init używa usprawnionego przepływu specyficznego dla .NET:

Weryfikuje i aktualizuje TargetFramework do Windows zgodnego z programem TFM (np. net10.0-windows10.0.26100.0)
Dodaje Microsoft.WindowsAppSDK i Microsoft.Windows.SDK.BuildTools jako wpisy NuGet dla PackageReference bezpośrednio w obiekcie .csproj.
Package.appxmanifestGeneruje, zasoby i certyfikat deweloperski
Nie tworzy ani nie pobiera projekcji języka C++ (użyj dla pakietów NuGet)

Tryb tożsamości rozrzedzania (--exe + --sparse):

Generuje manifest pakietu tylko dla tożsamości dla istniejącego pliku wykonywalnego pulpitu — pierwszy krok przepływu pracy pakowania rozrzednego. W przeciwieństwie do pełnego init przepływu pomija to całą instalację zestawu SDK/pakietu (rozrzedkowane pakiety tożsamości nie mają zależności zestawu SDK) i generuje tylko zasoby manifestu i symboli zastępczych.

Wywnioskuje nazwę pakietu, wydawcę, opis i wersję z pliku exe za pośrednictwem metody FileVersionInfo (zastąpić element , --name--publisherlub interaktywnie)
appxmanifest.xml Zapisuje (z nazwą exe podstawioną do Executable) oraz Assets/ folderem do sparse/ folderu w bieżącym katalogu (lub --output-dir)
Używa --use-defaults/--no-prompt metody do pomijania interakcyjnych monitów przesłonięcia (przyjazny dla ciągłej integracji)
--exe bez --sparse błędu

Zasoby są zewnętrzne. Rozrzedzonych .msix jest tylko tożsamość: wygenerowane Assets/ są rozpoznawane z katalogu instalacyjnego aplikacji (lokalizacji zawartości zewnętrznej) w czasie wykonywania, a nie powiązane z .msixprogramem . Wdróż je obok aplikacji.

Następne kroki po : winapp init --exe <exe> --sparsewinapp pack <appxmanifest.xml> w celu skompilowania tożsamości .msix, a następnie winapp embed-identity <exe>. Aby zapoznać się z pełnym przewodnikiem, zobacz Przewodnik po pakietach rozrzednych .

Przykłady:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

# Generate a sparse identity manifest for an existing exe (no SDK install)
winapp init --exe ./bin/Release/net8.0-windows/MyApp.exe --sparse --use-defaults

Porada: Instalowanie zestawów SDK po początkowej konfiguracji

Jeśli uruchomiono init--setup-sdks none polecenie (lub pominięto instalację zestawu SDK), a później potrzebne są zestawy SDK:

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init . --use-defaults --setup-sdks stable

Użyj --setup-sdks preview lub --setup-sdks experimental dla wersji zapoznawczej/eksperymentalnego zestawu SDK.

nowy

Utwórz nową aplikację WinUI na podstawie oficjalnego szablonu Zestaw SDK do aplikacji systemu Windowsdotnet new. Interakcyjne domyślnie; automatycznie używa wartości domyślnych w środowiskach nieinterakcyjnych.

winapp new [options]

Opcje:

-t, --template <short-name> - Krótka nazwa szablonu (np. winui, winui-navview, winui-mvvm, winui-lib, winui-unittestlub eksperymentalny szablon Reactor, taki jak reactor lub reactor-mvu). Zweryfikowane względem zainstalowanego pakietu w czasie wykonywania; uruchom polecenie winapp new --list , aby wyświetlić wszystko. Ustawienie domyślne: winui (pusta aplikacja XAML).
-n, --name <name> - Nazwa nowej aplikacji/projektu (wartość domyślna: pochodzi z --output, else WinUIApp)
-o, --output <path> - Katalog do utworzenia aplikacji w programie (ustawienie domyślne: ./<name>)
--use-defaults, --no-prompt — nie monituj; użyj wartości domyślnych (pusty szablon, nazwa z --output/--name, i zachowaj zainstalowany pakiet szablonu zamiast aktualizować go)
--force — Szkielet, nawet jeśli katalog wyjściowy zawiera już pliki
--template-version <latest|installed|version> - Wersja pakietu szablonów WinUI: latest aktualizacje najnowszego opublikowanego pakietu bez monitowania (zainstalowany pakiet, który jest już nowszy, taki jak lokalna kompilacja w wersji wstępnej, jest zachowywany; kończy się niepowodzeniem, jeśli nie można sprawdzić kanału informacyjnego), installed przechowuje wszystko, co zostało już pobrane (bez sieci) lub przypnij jawną wersję, taką jak 1.2.3. Ustawienie domyślne: zainstaluj najnowszą wersję, jeśli pakiet nie jest obecny, w przeciwnym razie wyświetl monit o zaktualizowanie nieaktualnego pakietu (przechowywanego as-is w obszarze --use-defaults).
--list — Wyświetl listę dostępnych szablonów WinUI i zakończ (najpierw instaluje najnowszy pakiet, jeśli żaden z nich nie jest zainstalowany)
--json - Formatuj dane wyjściowe jako dane JSON

Szablony:

Pakiet dostarcza dwa style aplikacji WinUI. Szablony XAML definiują interfejs użytkownika w adiustacji za pomocą kodu w języku C#. Szablony reaktorów to czysty kod C# bez kodu XAML, używając wzorca MVU (Model-View-Update). Lista szablonów jest odczytywana na żywo z zainstalowanego pakietu, więc zawsze odzwierciedla zainstalowaną wersję — uruchom winapp new --list polecenie , aby wyświetlić bieżący zestaw. Selektor interaktywny i --list najpierw pokaż szablony WinUI, a następnie wszystkie inne grupy w kolejności alfabetycznej. Typowe szablony:

Krótka nazwa	Opis
`winui`	Minimalna pusta aplikacja XAML (pakowanie MSIX)
`winui-navview`	Aplikacja startowa XAML NavigationView
`winui-tabview`	Aplikacja startowa TabView XAML
`winui-mvvm`	Aplikacja XAML MVVM (CommunityToolkit.Mvvm)
`winui-lib`	Biblioteka klas WinUI 3
`winui-unittest`	Spakowana aplikacja MSTest; testy są uruchamiane po uruchomieniu
`reactor`	Eksperymentalny. Pusta aplikacja Reactor — czysty kod C#, bez XAML
`reactor-mvu`	Eksperymentalny. Aplikacja Reactor przedstawiająca wzorzec MVU
`reactor-navview`	Eksperymentalny. Aplikacja startowa Reactor NavigationView
`reactor-tabview`	Eksperymentalny. Aplikacja startowa Reactor TabView

Szablony reaktorów są eksperymentalne. Odwołują się do pakietów wstępnych Microsoft.UI.Reactor , których interfejsy API mogą ulec zmianie lub zostać usunięte w przyszłej wersji. winapp new oznacza je (eksperymentalne) w --list i w selektorze interaktywnym, ustawia "Experimental": true w --jsonelemecie i wyświetla ostrzeżenie po utworzeniu szkieletu. Nigdy nie są wybierane jako szablon domyślny. Reactor wymaga również zestawu SDK .NET 10 lub nowszego. W przypadku starszego zestawu SDK winapp new kończy się niepowodzeniem z wersją, której potrzebuje, a nie szkieletem projektu, którego nie można skompilować.

Każda kanoniczna krótka nazwa szablonu jest pierwszą listą aliasów dotnet new . Wszystkie aliasy wymienione na liście (np. winui3, wasdk-single, winui-reactor) również są akceptowane. Jeśli inny zainstalowany pakiet szablonów rejestruje tę samą krótką nazwę (na przykład reactor z Microsoft.UI.Reactor.Templates), winapp new nadal tworzy szablon pakietu WinUI przy użyciu jednego z innych aliasów. Jeśli inny pakiet rejestruje każdy alias, który ma szablon, winapp new zatrzymuje i nazywa ten pakiet. Usuń go z poleceniem dotnet new uninstall <package> i uruchom ponownie. Po uruchomieniu wewnątrz istniejącego projektu WinUI również są wyświetlane szablony elementów (np. pusta strona), która winapp new dodaje do bieżącego projektu dotnet new zamiast tworzyć nowe.

Przechowywanie wersji pakietu szablonu:

winapp new Nie przypina już określonej wersji pakietu szablonu. Jeśli pakiet nie zostanie zainstalowany, zainstaluje najnowszą wersję. Jeśli starszy pakiet jest już zainstalowany, sprawdza kanał informacyjny i, gdy istnieje nowszy, monituje o aktualizację — z wyjątkiem nieinterakcyjnych/--use-defaults uruchomień, które zachowają zainstalowany pakiet. Użyj --template-version latest polecenia , aby zawsze pobierać najnowsze bez monitowania (nigdy nie zastępuje zainstalowanego pakietu starszym i kończy się niepowodzeniem, jeśli nie można sprawdzić kanału informacyjnego) lub --template-version installed zawsze używa pobranego pakietu bez sprawdzania sieci. Przekazywanie jawnej wersji (np. --template-version 1.2.3) zawsze instaluje dokładnie tę wersję — ponowne instalowanie nawet wtedy, gdy nowszy pakiet jest już obecny — dlatego tworzenie szkieletów można odtworzyć na różnych maszynach.

Pierwsze uruchomienie może trwać dłużej: Zainstalowanie lub zaktualizowanie pakietu szablonu lub przywrócenie brakujących pakietów NuGet Zestaw SDK do aplikacji systemu Windows używanych przez wybrany szablon może wymagać dodatkowych pobrań. Może się to zdarzyć również po opublikowaniu nowej wersji Zestaw SDK do aplikacji systemu Windows. Jeśli tworzenie szkieletu jest nadal uruchomione po 10 sekundach, aktualizuje komunikat o stanie, aby wskazać, winapp new że pakiety mogą być pobierane lub przywracane.

Co to robi:

Sprawdza, czy zestaw SDK .NET jest zainstalowany (kończy się niepowodzeniem z wskazówkami, jeśli brakuje — winapp nie instaluje łańcuchów narzędzi)
Instaluje lub aktualizuje oficjalny pakiet szablonów WinUI (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) na żądanie
Wylicza dostępne szablony z zainstalowanego pakietu i deleguje szkielet do dotnet new <short-name>

Szablony aplikacji WinUI zawierają już Windows pakowanie i tożsamość (Package.appxmanifest), więc nie jest wymagany żaden oddzielny winapp init krok. W przypadku szablonów aplikacji użyj polecenia winapp run , aby skompilować i uruchomić aplikację. Szablon winui-lib tworzy bibliotekę klas do odwołania z projektu aplikacji (nie ma manifestu aplikacji). Szablon winui-unittest to spakowana aplikacja MSTest, której testy są uruchamiane po uruchomieniu aplikacji () —winapp run a nie za pośrednictwem metody dotnet test. winapp newSzkielety dla zainstalowanej platformy docelowej zestawu SDK .NET i wyświetla odpowiedni następny krok dla wybranego szablonu.

Przekaż flagę globalną --verbose (-v), aby powtórzyć każde wywołanie bazowe dotnet (zapytanie dotyczące pakietu, sprawdzanie aktualizacji, instalowanie, dotnet new listszkielet) wraz z pełnymi danymi wyjściowymi — przydatne do diagnozowania problemów z pakietem szablonu lub szkieletem.

Przykłady:

# Interactive: pick a template, then a name (output defaults to ./<name>)
winapp new

# List the available templates without scaffolding
winapp new --list

# One-shot with a specific template
winapp new --name MyApp --template winui-navview

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

przywracać

Przywracanie pakietów i ponowne generowanie plików na podstawie istniejącej winapp.yaml konfiguracji.

winapp restore [base-directory] [options]

argumenty:

base-directory - Katalog do przywrócenia (ustawienie domyślne: bieżący katalog). Ponadto wybiera lokalizację winapp.yaml i nuget.config odczyt z, chyba że --config-dir je zastąpi.

Opcje:

--config-dir <path> - Katalog zawierający winapp.yaml (ustawienie domyślne: base-directory)

Co to robi:

Odczytuje istniejącą winapp.yaml konfigurację
Pobiera/aktualizuje pakiety zestawu SDK do określonych wersji
Ponowne generowanie nagłówków i plików binarnych C++/WinRT
Przechowuje pliki do udostępniania w katalogu globalnej pamięci podręcznej

Uwaga / Notatka

W przypadku projektów .NET nie winapp.yaml ma — wersje zestawu SDK działają jako PackageReference wpisy w pliku .csproj — dlatego winapp restore są uruchamiane dotnet restore dla Ciebie.

Przykłady:

# Restore from winapp.yaml in current directory
winapp restore

# Restore a specific project directory (reads ./my-project/winapp.yaml)
winapp restore ./my-project

Niestandardowe i prywatne kanały informacyjne NuGet:

winapp init, restorei update pobierz pakiety Windows SDK i Zestaw SDK do aplikacji systemu Windows za pomocą narzędzia NuGet, honorując hierarchię standardowąnuget.config. Prywatne kanały informacyjne i dublowania, poświadczenia kanału informacyjnego (w tym dostawcy poświadczeń) i niestandardowe globalPackagesFolder wszystkie działają tak jak w przypadku dotnet restoreprogramu . Aby przywrócić wyłącznie z własnego dublowania, <clear /> dziedziczone źródła i dodać tylko Twoje:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

Uwaga / Notatka

W przypadku projektów natywnych winapp rozpoznaje z nuget.config katalogu, na którym działa:restoreinit/argument katalogu, --config-dir jeśli zostanie podany, w przeciwnym razie bieżący katalog. W przypadku projektów .NET źródła pochodzą z własnej nuget.config hierarchii projektu, ponieważ jest to co dotnet add package i dotnet restore używane, dlatego umieść konfigurację prywatnego źródła danych w katalogu projektu lub modułu nadrzędnego. Poza tym hierarchią --config-dir jest zgłaszana i ignorowana zamiast dyskretnie wybierać wersji, których projekt nie może przywrócić. Uruchom te polecenia tylko w przypadku zaufanych katalogów— ta sama ostrożność, która ma zastosowanie do dotnet restoreprogramu . Po skonfigurowaniu kilku źródeł użyj mapowania źródła pakietów, aby przypiąć każdy pakiet do źródła danych.

aktualizacja

Zaktualizuj pakiety do najnowszych wersji i zaktualizuj plik konfiguracji.

winapp update [options]

Opcje:

--setup-sdks <stable|preview|experimental|none> - Tryb instalacji zestawu SDK: stable (ustawienie domyślne), preview, experimentallub none (pomiń instalację zestawu SDK)

Co to robi:

Odczytuje istniejącą winapp.yaml konfigurację w bieżącym katalogu
Aktualizuje wszystkie pakiety do najnowszych dostępnych wersji. Wydanie Zestaw SDK do aplikacji systemu Windows, które jest nadal publikowane, jest pomijane do momentu udostępnienia wszystkich jego pakietów i update drukuje notatkę nazewnictwa używanej wersji. Uruchom winapp update ponownie później, aby przejść do nowej wersji.
winapp.yaml Aktualizuje plik przy użyciu nowych numerów wersji
Ponowne generowanie nagłówków i plików binarnych C++/WinRT

Przykłady:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

pack

Utwórz pakiety MSIX na podstawie projektu lub przygotowanych katalogów aplikacji. Wymaga, aby plik manifestu (Package.appxmanifest preferowany, appxmanifest.xml obsługiwany również) był obecny w katalogu docelowym, w bieżącym katalogu lub przekazany z opcją --manifest . (uruchom init polecenie lub manifest generate aby utworzyć manifest)

Przekaż pojedynczy element .csproj , aby skompilować projekt i spakować jego dane wyjściowe w jednym kroku (tryb projektu, zobacz Tworzenie pakietów projektu bezpośrednio poniżej). Przekaż wiele folderów wejściowych, aby utworzyć dla .msixbundle dystrybucji z wieloma architekturami (zobacz pakiety z wieloma architekturami poniżej).

winapp pack <input-folder> [input-folder...] [options]

argumenty:

input-folder — Pojedynczy element .csproj do kompilowania i tworzenia pakietu (tryb projektu) lub co najmniej jednego katalogu zawierającego pliki aplikacji do pakietu. Przekaż wiele folderów (np. ./publish/x64 ./publish/arm64) w celu utworzenia pakietu MSIX. W przypadku rozrzednych pakietów tożsamości przekaż plik rozrzedzny appxmanifest.xml bezpośrednio zamiast folderu (zobacz Sparse identity packages below).

Opcje:

--output <filename> - Nazwa pliku wyjściowego. W przypadku pojedynczych pakietów: <name>_<version>_<arch>.msix (powrót do <name>_<version>.msix, <name>_<arch>.msixlub <name>.msix). W przypadku pakietów: <name>_<version>_<arch1>_<arch2>.msixbundle.
--name <name> - Nazwa pakietu (wartość domyślna: z manifestu)
--manifest <path> - Ścieżka do pliku manifestu (Package.appxmanifest preferowana, appxmanifest.xml obsługiwana również; domyślna: automatyczne wykrywanie)
--cert <path> — Ścieżka do certyfikatu podpisywania (umożliwia automatyczne podpisywanie)
--cert-password <password> - Hasło certyfikatu (domyślne: "hasło")
--generate-cert — Generowanie nowego certyfikatu programistycznego
--no-sign — Dostarczaj pakiet bez znaku, przesłaniając dowolną konfigurację podpisywania projektu (np. w przypadku przesyłania magazynu lub zewnętrznego potoku podpisywania). Nie można połączyć z programem --cert lub --generate-cert.
--install-cert - Instalowanie certyfikatu na maszynie
--publisher <name>- Publisher generowania certyfikatów. Akceptuje pełną nazwę wyróżniającą X.500 lub nagą nazwę (automatycznie opakowaną jako CN=<name>)
--self-contained — środowisko uruchomieniowe Zestaw SDK do aplikacji systemu Windows pakietu
--skip-pri - Pomiń generowanie plików PRI
--executable <path> - Ścieżka do pliku wykonywalnego względem folderu wejściowego (również --exe). Służy do rozpoznawania $targetnametoken$ symboli zastępczych w manifeście.

opcje trybu Project (wymagają .csproj danych wejściowych; odrzucone dla danych wejściowych folderu/pakietu/manifestu):

--configuration <name> (-c) — Konfiguracja kompilacji (ustawienie domyślne: Release)
--arch <arch> - Architektura docelowa: x64, arm64lub x86 (wartość domyślna: bieżąca architektura procesu)
--framework <tfm> (-f) — nazwa platformy docelowej dla projektów wielokierunkowych
--no-build — Pakowanie istniejących danych wyjściowych kompilacji bez ponownego kompilowania
--no-restore - Pomiń przywracanie projektu przed kompilacją
--property <name=value> (-p) — właściwość MSBuild przekazana do kompilacji i oceny (powtarzalna)

Uwaga: W przypadku trybu projektu WinUI/ EnableMsixTooling.csproj (msiX-tooling) Zestaw SDK do aplikacji systemu Windows jest właścicielem manifestu, punktu wejścia i generowania PRI, więc --manifest, --executablei --skip-pri są odrzucane — skonfiguruj <AppxManifest>punkt wejścia projektu i jego kompilację zasobów w samym projekcie. Te trzy opcje nadal mają zastosowanie do danych wejściowych folderów i do trybu projektu ogólnego (innego niż MSIX-tooling). .csproj

Co to robi:

Weryfikuje i przetwarza pliki Package.appxmanifest
Rozwiązuje tokeny $placeholder$ w manifeście (zobacz symbole zastępcze manifestu poniżej)
Zapewnia prawidłowe zależności struktury
Aktualizuje manifesty równoczesne z rejestracjami
Automatycznie odnajduje i dołącza wszystkie pliki inne niż obrazy, do których odwołuje się manifest (np. AppExtension manifest.json, pliki konfiguracji) z katalogu manifestu lub folderu wejściowego, jeśli brakuje ich w środowisku przejściowym
Automatycznie odnajduje składniki WinRT innych firm i rejestruje ich klasy aktywowalne (zobacz odnajdywanie składników WinRT poniżej)
Obsługuje samodzielne wdrożenie winAppSDK
Podpisuje pakiet w przypadku podania certyfikatu

Bezpośrednie pakowanie projektu

Gdy dane wejściowe są pojedynczym .csprojelementem , winapp pack kompiluje projekt (przy użyciu powyższych opcji) i pakuje wynikowe dane wyjściowe — nie trzeba kompilować oddzielnie ani najpierw lokalizować folder wyjściowy. To dubluje winapp runtryb projektu.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

Architektura docelowa pochodzi z --archelementu lub z samotnego -p RuntimeIdentifier=<rid> , gdy nie przekazujesz --arch (dokładne identyfikatory RID są zachowywane i napędzają kompilację). Przekazywanie zarówno, jak --arch i -p RuntimeIdentifier jest konfliktem i jest odrzucane.

Projekt musi być kompilowany jako spakowana aplikacja (EnableMsixTooling=true z elementem Package.appxmanifest); projekt, który kompiluje się jako niepakowana aplikacja (WindowsPackageType=None) nie ma manifestu MSIX w celu spakowania i winapp pack raportowania błędu możliwego do wykonania akcji. Dane wejściowe folderu, pakietu i manifestu rozrzedzonych są niezmienione.

Project tryb tworzy pojedynczy .msix lub tylko .msixbundle architekturę (zobacz Pakiety z wieloma architekturami). Nie generuje archiwów przekazywania magazynu ani pakietów podzielonych na zasoby (język/skala): jawne -p UapAppxPackageBuildMode=StoreUpload lub -p AppxBundleAutoResourcePackageQualifiers=... odrzucone za pomocą notatki w celu uruchomienia natywnego polecenia pakowania zestawu SDK bezpośrednio dla tych przepływów.

Pakiety tożsamości rozrzednia

Gdy dane wejściowe są plikiem rozrzedłym appxmanifest.xml (deklarowanym <uap10:AllowExternalContent>true</uap10:AllowExternalContent> w folderze <Properties>), a nie folderem, winapp pack tworzy tylko.msix tożsamość — pakuje tylko manifest bez plików binarnych aplikacji ani zasobów. Jest to krok 2 przepływu pracy rozrzednia pakietów.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx

Wartość domyślna danych wyjściowych <PackageName>.identity.msix w bieżącym katalogu (zastąp element ).--output
Podpisywanie odbywa się tylko wtedy, gdy --cert (lub --generate-cert) jest udostępniany.
Jeśli zamiast tego przekażesz folder, którego manifest deklaruje AllowExternalContent, istniejące zachowanie tworzenia pakietów folderów ma zastosowanie, ale winapp pack ostrzega, czy znajdzie zasoby (/.ico.png/.jpg) lub pliki binarne (.exe.dll//.so) — w przypadku rozrzednych pakietów należą one do lokalizacji zewnętrznej.msix, a nie wewnątrz .

Po spakowaniu uruchom winapp embed-identity <exe> i zarejestruj pakiet w instalatorze przy użyciu polecenia Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Zobacz Przewodnik po pakowaniu rozrzedowym.

Odnajdywanie składników WinRT

Podczas tworzenia pakietów winapp pack automatycznie skanuje pakiety NuGet zdefiniowane w składnikach winapp.yaml*.csproj WinRT innych firm (np. Win2D). .winmd Analizuje pliki w celu wyodrębnienia aktywowanych nazw klas i lokalizowania ich bibliotek DLL implementacji. Odnalezione wpisy są rejestrowane w następujący sposób:

Zależne od struktury (ustawienie domyślne): klasy możliwe do aktywowania są dodawane jako <InProcessServer> wpisy w obiekcie Package.appxmanifest
Self-contained (--self-contained): Klasy umożliwiające aktywację są osadzone w manifestach równoległych (SxS) w pliku wykonywalnym

Rozpoznawanie symboli zastępczych podczas pakowania:

Jeśli manifest zawiera $targetnametoken$ w atrybucie Executable :

Jeśli --executable zostanie podana (ścieżka względem folderu wejściowego), symbol zastępczy zostanie zastąpiony określoną wartością
winapp pack W przeciwnym razie skanuje katalog główny folderu wejściowego dla .exe plików — jeśli zostanie znaleziony dokładnie taki folder, zostanie on użyty automatycznie
Jeśli znaleziono zero lub wiele .exe plików, zostanie wyświetlony błąd z prośbą o określenie --executable

Przykłady:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

Pakiety z wieloma architekturami

Po przekazaniu winapp pack wielu folderów wejściowych tworzy jeden .msixbundle dla .msix każdej architektury:

# Create unsigned bundle for Microsoft Store submission
winapp pack ./publish/x64 ./publish/arm64

# Create signed bundle for sideloading
winapp pack ./publish/x64 ./publish/arm64 --cert ./devcert.pfx

# Self-contained bundle
winapp pack ./publish/x64 ./publish/arm64 --self-contained --generate-cert

Polecenie automatycznie wykrywa architekturę każdego folderu z nagłówka PE podstawowego pliku wykonywalnego, weryfikuje spójność we fragmentach (tożsamość, możliwości, zależności) i tworzy element <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Rozpoznawanie manifestu dla pakietów:

Każdy wycinek w pakiecie wymaga manifestu. Polecenie rozpoznaje manifesty w następującej kolejności:

--manifest <path> — Jeśli zostanie określony, ten pojedynczy manifest jest używany dla wszystkich wycinków. Element ProcessorArchitecture jest automatycznie aktualizowany według wycinka w celu dopasowania do wykrytej architektury.
Manifest dla folderu — jeśli każdy folder wejściowy zawiera Package.appxmanifest element (lub appxmanifest.xml), manifest tego folderu jest używany do jego wycinka.
Bieżący rezerwowy katalog — jeśli folder nie ma manifestu, polecenie szuka Package.appxmanifest w bieżącym katalogu roboczym i używa go (z automatycznym sygnaturą architektury).

We wszystkich przypadkach manifest jest automatycznie aktualizowany: symbole zastępcze są rozpoznawane, zależności są wstrzykiwane, a ProcessorArchitecture właściwość jest ustawiana na wykrytą architekturę. Po rozwiązaniu weryfikacja krzyżowa gwarantuje, że tożsamość (nazwa, wersja, Publisher), możliwości i zależności są spójne we wszystkich fragmentach — mogą się różnić.ProcessorArchitecture Wersja pakietu zdefiniowana w wycinkach jest przypisywana do wersji pakietu MSIX, z wyjątkiem sytuacji, w której jest 0.0.0.0to , w którym przypadku jest automatycznie generowana wersja oparta na znaczniku czasu.

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

create-debug-identity

Utwórz tożsamość aplikacji na potrzeby debugowania przy użyciu rozrzedanych pakietów. Plik exe pozostaje w oryginalnej lokalizacji — Windows kojarzy tożsamość z nim za pośrednictwem Add-AppxPackage -ExternalLocation.

Kiedy używać tego elementu vs winapp run: Użyj create-debug-identity polecenia , gdy plik exe jest oddzielony od kodu aplikacji (np. aplikacji Electron, gdzie electron.exe znajduje się w node_moduleselemecie ), lub podczas testowania zachowania rozrzedzania pakietu. W przypadku większości struktur, w których plik exe znajduje się w folderze danych wyjściowych kompilacji, użyj go winapp run — rejestruje pełny luźny pakiet układu i uruchamia aplikację. Aby uzyskać pełne porównanie, zobacz Przewodnik debugowania .

winapp create-debug-identity [entrypoint] [options]

argumenty:

entrypoint - Ścieżka do pliku wykonywalnego (.exe) lub skrypt, który wymaga tożsamości

Opcje:

--manifest <path> — Ścieżka do pliku manifestu aplikacji lub Package.appxmanifestappxmanifest.xml (ustawienie domyślne: automatyczne wykrywanie Package.appxmanifest lub appxmanifest.xml w bieżącym katalogu)
--no-install — Nie instaluj pakietu po utworzeniu
--keep-identity — Zachowaj tożsamość manifestu as-is, bez dołączania .debug do nazwy pakietu i identyfikatora aplikacji

Co to robi:

Modyfikuje manifest równoległy pliku wykonywalnego
Rejestruje rozrzedny pakiet dla tożsamości
Umożliwia debugowanie interfejsów API wymagających tożsamości

Przykłady:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

osadzanie tożsamości

Połącz aplikację klasyczną z rozrzedzony pakiet tożsamości , osadzając <msix> element w manifeście równoległym (fusion) aplikacji. Jest to krok 3 przepływu pracy rozrzednia pakietów — informuje Windows, do którego pakietu tożsamości należy uruchomiony plik exe.

winapp embed-identity <target> [options]

argumenty:

target - Plik do aktualizacji. Automatycznie wykrywane przez rozszerzenie:
- .exe (Tryb EXE) — osadza <msix> element bezpośrednio w manifeście równoległym exe przy użyciu polecenia mt.exe.
- .xml / .manifest (tryb XML) — wstawia lub zastępuje <msix> element w zewnętrznym pliku manifestu SxS (utworzony, jeśli nie istnieje). Ponownie skompiluj aplikację, aby zaktualizowany manifest był osadzony w pliku binarnym.

Opcje:

--manifest <path> - Ścieżka do rozrzednicy appxmanifest.xml do odczytu tożsamości (packageName, publisher, applicationId) z. Po pominięciu polecenie wyszukuje sparse/ folder obok obiektu docelowego, a następnie w bieżącym katalogu, a następnie katalog docelowy i bieżący katalog dla appxmanifest.xml.

Przykłady:

# EXE mode — embed identity straight into the built exe
winapp embed-identity ./bin/Release/net8.0-windows/MyApp.exe

# XML mode — update a checked-in side-by-side manifest, then rebuild
winapp embed-identity ./app.manifest --manifest ./appxmanifest.xml

To polecenie jest idempotentne: ponowne uruchomienie zastępuje dowolny istniejący <msix> element, a nie duplikowanie go.

manifest

Generowanie plików Package.appxmanifest i zarządzanie nimi.

generowanie manifestu

Wygeneruj plik Package.appxmanifest na podstawie szablonów.

winapp manifest generate [directory] [options]

argumenty:

directory - Katalog do generowania manifestu w (ustawienie domyślne: bieżący katalog)

Opcje:

--package-name <name> - Nazwa pakietu (domyślna: nazwa folderu)
--publisher-name <name>- Publisher nazwa wyróżniająca (wartość domyślna: CN=<current user>). Akceptuje dn X.500 z jednowartych, rozdzielonych przecinkami składników (wielowartych + RDN i ukośników odwrotnych nie są obsługiwane); nazwy na pasku są automatycznie opakowane jako CN=<name>.
--version <version> — Wersja (domyślna: "1.0.0.0")
--description <text> - Opis (wartość domyślna: "Moja aplikacja")
--entrypoint <path> - Punkt wejścia wykonywalny lub skrypt
--template <type> - Typ szablonu: packaged (wartość domyślna) lub sparse
--logo-path <path> - Ścieżka do pliku obrazu logo
--if-exists <Error|Overwrite|Skip> - Zachowanie, gdy plik manifestu już istnieje w ścieżce docelowej (domyślnie: Error)

Szablony:

packaged — Standardowy manifest spakowanej aplikacji
sparse - Manifest aplikacji przy użyciu pakowania rzadkiego/zewnętrznego

Symbole zastępcze manifestu

Wygenerowane manifesty używają $placeholder$ tokenów (oddzielonych znakiem dolara), które są rozwiązywane automatycznie podczas pakowania.

Placeholder	Rozwiązano problem	Przykład
$targetnametoken$	Nazwa pliku wykonywalnego bez rozszerzenia	`Executable="$targetnametoken$.exe"` → `Executable="MyApp.exe"`
$targetentrypoint$	`Windows.FullTrustApplication`	Zawsze rozwiązywane automatycznie

Jest to zgodne z tą samą konwencją używaną przez szablony projektów Visual Studio, więc manifesty są przenośne między narzędziami.

Jak rozwiązywać pola zastępcze:

winapp pack — Podczas tworzenia pakietów $targetnametoken$ rozwiązanie jest rozwiązywane przy użyciu --executable opcji lub przez automatyczne wykrywanie pojedynczego .exe elementu w folderze wejściowym. Jeśli znaleziono wiele (lub zero) .exe plików i --executable nie zostanie określonych, zostanie wyświetlony błąd.
winapp create-debug-identity — po podaniu $targetnametoken$ argumentu punktu wejścia jest rozpoznawany z niego. Bez punktu wejścia symbol zastępczy pliku wykonywalnego musi być już rozpoznany w manifeście.
winapp manifest generate --executable — Po --executable podaniu metadane manifestu (wersja, opis) i ikony są wyodrębniane z pliku wykonywalnego, ale wygenerowany manifest nadal używa $targetnametoken$.exewartości ; ten symbol zastępczy zostanie rozpoznany później (np. winapp pack lub winapp create-debug-identity).

PS: Keeping $targetnametoken$ w manifeście zaewidencjonowany pozwala uniknąć twardych nazw plików wykonywalnych i działa z kompilacjami winapp pack i Visual Studio.

Przykłady:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

manifest add-alias

Dodaj alias wykonywania (uap5:AppExecutionAlias) do pliku Package.appxmanifest. Umożliwia to uruchomienie spakowanej aplikacji z wiersza polecenia przez wpisanie nazwy aliasu.

winapp manifest add-alias [options]

Opcje:

--name <alias> - Nazwa aliasu (np. myapp.exe). Ustawienie domyślne: wnioskowane z atrybutu Executable w manifeście.
--manifest <path> — Ścieżka do pliku Package.appxmanifest (ustawienie domyślne: wyszukaj bieżący katalog)
--app-id <id> - Identyfikator aplikacji, aby dodać alias do (ustawienie domyślne: pierwszy element aplikacji)

Co to robi:

Odczytuje manifest i wywnioskuje alias z atrybutu Executable (zachowując symbole zastępcze, takie jak $targetnametoken$.exe)
Dodaje deklarację uap5 przestrzeni nazw, jeśli jeszcze nie istnieje
<Extensions> Dodaje blok z <uap5:AppExecutionAlias> elementem aplikacji docelowej
Jeśli alias już istnieje, zgłasza go i kończy pomyślnie

Przykłady:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

manifest aktualizuj-zasoby

Wygeneruj wszystkie wymagane zasoby obrazów MSIX na podstawie pojedynczego obrazu źródłowego.

winapp manifest update-assets <image-path> [options]

argumenty:

image-path - Ścieżka do pliku obrazu źródłowego (PNG, JPG, SVG, ICO, GIF, BMP itp.)

Opcje:

--manifest <path> - Ścieżka do pliku Package.appxmanifest (domyślnie: wyszukaj bieżący katalog)
--light-image <path> - Ścieżka do oddzielnego obrazu źródłowego dla wariantów motywu lekkiego

Description:

Pobiera pojedynczy obraz źródłowy i generuje kompleksowy zestaw zasobów obrazów MSIX na podstawie odwołań do zasobów manifestu:

Dla każdego zasobu, do których odwołuje się manifest:

5 wariantów skalowania — podstawowy (bez sufiksu), .scale-125, .scale-150, , .scale-200.scale-400

Dla ikony aplikacji (Square44x44Logo / AppList, 44×44 base):

14 płytowanych wariantów rozmiaru docelowego — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
14 nieplatowanych wariantów rozmiaru docelowego — .targetsize-{size}_altform-unplated

Additionally:

app.ico — plik ICO o wielu rozdzielczościach (16, 24, 32, 48, 256) na potrzeby integracji powłoki. Jeśli istniejący .ico plik zostanie znaleziony w katalogu zasobów (np. AppIcon.ico z szablonu projektu), zostanie zastąpiony w miejscu zamiast tworzenia duplikatu

Z użyciem --light-image:

Warianty rozmiaru docelowego motywu jasnego — .targetsize-{size}_altform-lightunplated (ikona aplikacji)
Warianty skalowania motywu lekkiego — .scale-{factor}_altform-colorful_theme-light (kafelki, logo sklepu)

Obsługa svG: Pliki SVG są w pełni obsługiwane jako obrazy źródłowe. Są one renderowane jako wektory bezpośrednio w każdym rozmiarze docelowym, generując doskonałe wyniki w pikselach we wszystkich rozdzielczościach. Plik musi zadeklarować własny rozmiar za pomocą viewBox atrybutów bezwzględnych lub bezwzględnych widthheight ; szerokość procentowa bez viewBox żadnego określonego rozmiaru. Źródło, które deklaruje, że żadna z nich nie jest odrzucana, SVG image has no usable dimensions zamiast produkować puste zasoby.

Polecenie skaluje obrazy proporcjonalnie przy zachowaniu współczynnika proporcji, wyśrodkując je z przezroczystymi tłami w razie potrzeby. Zasoby są zapisywane w Assets katalogu w odniesieniu do lokalizacji manifestu.

Przykłady:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

przebieg

Utwórz luźny pakiet układu z folderu wyjściowego kompilacji, zarejestruj go w Windows przy użyciu interfejsu API Windows.Management.Deployment.PackageManager i uruchom aplikację — symulując pełną instalację MSIX na potrzeby debugowania. Zwraca identyfikator procesu dla załącznika debugera.

winapp run działa w jednym z trzech trybów, wybierane automatycznie z danych wejściowych:

Tryb folderu — dane wejściowe to folder danych wyjściowych kompilacji (zawiera Package.appxmanifest/AppxManifest.xmlelement ).
Project tryb — dane wejściowe to .csproj, C++ .vcxproj, .sln/.slnx rozwiązanie lub katalog zawierający jeden. winapp run kompiluje projekt i uruchamia go, obsługując zarówno spakowane , jak i rozpakowane aplikacje. Zobacz poniżej Project tryb i projekty języka C++.
Tryb pojedynczego pliku — dane wejściowe są aplikacją opartą.cs na plikach .NET. winapp run tworzy go, generuje manifest na podstawie swoich #:property dyrektyw i uruchamia go przy użyciu tożsamości pakietu.

Wskazówka

Wybór trybu jest domyślnie dyskretny. Jeśli katalog był traktowany jako folder danych wyjściowych kompilacji, gdy spodziewano się, że zostanie on skompilowany jako projekt, uruchom go ponownie za pomocą --verbose polecenia — w trybie folderu zgłasza, dlaczego został wybrany (No .csproj/.vcxproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Katalog jest kompilowany tylko jako projekt, gdy .csproj.sln///.vcxproj.slnx aplikacja z możliwością uruchamiania znajduje się na najwyższym poziomie; nie jest przeszukiwana rekursywnie.

This jest preferowanym poleceniem debugowania przy użyciu tożsamości pakietu dla większości struktur (.NET, C++, Rust, Flutter, Tauri). W przeciwieństwie do create-debug-identity tego, który rejestruje rozrzedny pakiet dla pojedynczego pliku exe, winapp run rejestruje cały folder jako luźny pakiet układu, podobnie jak prawdziwa instalacja MSIX. Zobacz Przewodnik debugowania , aby zapoznać się z typowymi przepływami pracy debugowania.

winapp run [<input>] [options]

argumenty:

input- Aplikacja do uruchomienia: folder danych wyjściowych kompilacji (tryb folderu), .cs .NET aplikacji opartej na plikach (tryb pojedynczego pliku), .csproj projektu lub C++.vcxproj, .sln/.slnx rozwiązania lub katalogu zawierającego jeden z nich na najwyższym poziomie (tryb projektu; katalog nie jest przeszukiwany rekursywnie). Użyj . polecenia , aby skompilować/uruchomić projekt w bieżącym katalogu. Opcjonalnie — domyślnie jest to bieżący katalog po pominięciu (dopasowujedotnet runwartość ).

Opcje:

--manifest <path> — Ścieżka do pliku Package.appxmanifest (ustawienie domyślne: automatyczne wykrywanie z folderu wejściowego lub bieżącego katalogu)
--output-appx-directory <path> - Katalog wyjściowy luźnego układu (wartość domyślna: AppX wewnątrz folderu wejściowego). Układ domyślny usuwa pliki już nie w kompilacji; katalog niestandardowy przechowuje dodatkowe pliki. Użyj nowego katalogu niestandardowego, jeśli potrzebujesz czystego układu.
--args <string> - Argumenty wiersza polecenia do przekazania do aplikacji. Alternatywnie należy użyć -- argumentów, aby uniknąć ucieczki (np. winapp run . -- --flag value).
--no-launch — Utwórz tożsamość debugowania i zarejestruj pakiet bez uruchamiania aplikacji
--with-alias — Uruchom aplikację przy użyciu aliasu wykonywania zamiast aktywacji identyfikatora AUMID. Aplikacja działa w bieżącym terminalu z dziedziczony stdin/stdout/stderr. Rzadko potrzebne: aplikacja z OutputType=Exe już uruchamia się w ten sposób domyślnie. Aplikacja winapp dodaje wymagane uap5:ExecutionAlias do manifestu etapy w układzie AppX, więc nie jest wymagana żadna zmiana manifestu zaewidencjonowania; alias zadeklarowany przez aplikację jest używany as-is. Nie można połączyć z --no-launch, , --detach--without-aliaslub --json.
--without-alias — Wymuś aktywację identyfikatora AUMID dla aplikacji, która w przeciwnym razie zostanie uruchomiona za pośrednictwem aliasu wykonywania. Następnie aplikacja konsolowa działa bez konsoli i nie drukuje nic do tego terminalu. Nie można połączyć z --with-alias.
--debug-output — Przechwytywanie OutputDebugString komunikatów i wyjątków pierwszej szansy z uruchomionej aplikacji. Szum struktury (WinUI, COM, DirectX) jest filtrowany z danych wyjściowych konsoli; pełny plik dziennika przechwytuje wszystko. Jeśli aplikacja ulegnie awarii, automatycznie przechwytuje minidump i analizuje ją, aby pokazać typ wyjątku, komunikat i ślad stosu za pomocą pliku źródłowego:numery wierszy (rozwiązane z plików PDB w folderze danych wyjściowych kompilacji). Awarie zarządzane (.NET) są analizowane natychmiast bez narzędzi zewnętrznych. Awarie natywne (C++/WinRT) pokazują nazwy modułów i przesunięcia. Gdy aplikacja, która uległa awarii, jest aplikacją WinUI 3 (Microsoft.UI.Xaml.dll jest ładowana), jest automatycznie uruchamiana dodatkowa klasyfikacja wyjątków stowed-exception, aby wyświetlić źródłowy hrESULT, jego łańcuch ErrorContext i pełny natywny stos wysyłania XAML; wymagane składniki debugera są pobierane podczas pierwszego użycia (zobacz Debugowanie, zastępowanie za pośrednictwem WINAPP_DBGTOOLS_DIR zmiennej środowiskowej). Tylko jeden debuger może dołączać do procesu w danym momencie, więc inne debugery (Visual Studio, VS Code) nie mogą być używane jednocześnie. Zamiast tego użyj --no-launch polecenia , jeśli musisz dołączyć inny debuger. Nie można połączyć z --no-launch. Nie można połączyć z --json. Jeśli bez niego zostanie uruchomiona, a aplikacja zakończy działanie z kodem niezerowym, aplikacja winapp wyświetli wskazówkę, aby ponownie uruchomić polecenie .--debug-output
--symbols — pobierz symbole PDB z serwera symboli Microsoft, aby uzyskać bogatszą analizę awarii natywnej z rozpoznanymi nazwami funkcji. Używane tylko z --debug-output. Jeśli pominięto i wystąpi awaria natywna, dane wyjściowe będą sugerować dodanie tej flagi. Ta flaga usprawnia również stos klasyfikacji wyjątków winUI dla aplikacji WinUI 3. Najpierw uruchom symbole pobierania i buforuje je lokalnie; kolejne uruchomienia używają pamięci podręcznej.
--unregister-on-exit — Wyrejestrowywanie pakietu programistycznego po zakończeniu działania aplikacji. Usuwa tylko pakiety zarejestrowane w trybie programowania. Nie można połączyć z --no-launch.
--detach — Uruchom aplikację i wróć natychmiast bez oczekiwania na jej zakończenie. Przydatne w przypadku ciągłej integracji/automatyzacji, w której należy korzystać z aplikacji po uruchomieniu. Lokalne przebiegi drukują identyfikator PID; przebiegi docelowe wyświetlają docelowy interfejs użytkownika o określonym zakresie. Kod JSON zawiera identyfikator PID i zakres docelowy. Nie można połączyć z --no-launch, , --debug-output--with-aliaslub --unregister-on-exit.
--clean — Przed ponownym wdrożeniem usuń dane aplikacji istniejącego pakietu (LocalState, ustawienia itp.). Domyślnie dane aplikacji są zachowywane w ramach ponownych wdrożeń.
--json - Formatuj dane wyjściowe jako dane JSON na potrzeby użycia programowego (np. ciągła integracja/automatyzacja). Przydatne w --detach celu przechwycenia identyfikatora PID. Nie można połączyć z programem --with-alias lub --debug-output.
--on <target> - Skompiluj na hoście, a następnie zarejestruj i uruchom polecenie w obiekcie docelowym. Obecnie obsługuje program sandboxbez powrotu do lokalnego wykonywania. Przed --detach wykonaniem kolejnych poleceń interfejsu użytkownika użyj polecenia. Piaskownica --debug-output wymaga spakowanej aplikacji. Zobacz Windows Wykonywanie piaskownicy, aby uzyskać informacje na temat instalacji, obsługi środowiska uruchomieniowego i okresu istnienia odłączonej aplikacji.

Trwałość danych aplikacji:

Domyślnie winapp run dane aplikacji (LocalState, RoamingState, Settingsitp.) są zachowywane podczas ponownego wdrażania. Jeśli aplikacja zapisuje dane w ApplicationData.Current.LocalFolder kontekście pakietu lub Environment.GetFolderPath(SpecialFolder.LocalApplicationData) w kontekście pakietu, te dane będą przetrwać w winapp run wywołaniach.

Użyj --clean polecenia , gdy potrzebujesz nowego uruchomienia (np. aby zresetować uszkodzony stan lub przetestować zachowanie pierwszego uruchomienia).

Co to robi:

Lokalizuje lub generuje plik Package.appxmanifest
Tworzy i rejestruje tożsamość debugowania przy użyciu luźnego pakietu układu
Oblicza identyfikator modelu użytkownika aplikacji (AUMID)
Uruchamia aplikację przy użyciu zarejestrowanej tożsamości (chyba że --no-launch określono)
Drukuje identyfikator procesu (PID) dla załącznika debugera

Przykłady:

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

tryb Project (projekty zestawu SDK .NET)

Gdy dane wejściowe to .csproj,.slnx/.sln rozwiązanie lub katalog zawierający jeden (w tym .),winapp run kompiluje projekt za pomocą dotnet build polecenia , a następnie uruchamia go. Obsługuje zarówno spakowane, jak i rozpakowane aplikacje WinUI oraz instaluje zgodne architektury aplikacja dla systemu Windows Runtime, których potrzebuje aplikacja przed uruchomieniem.

Dane wejściowe rozwiązania: wskaż winapp run/.slnx.slnelement (lub katalog zawierający jeden — rozwiązanie jest preferowane w przypadku luźnych .csproj plików) i rozwiązuje projekt aplikacji z możliwością uruchamiania, a następnie kompiluje go za pomocą zdefiniowanych właściwości elementów równorzędnychSolution*, więc projekty, które zależą od nich, są kompilowane zgodnie z $(SolutionDir) Visual Studio. Reguły rozwiązywania:

Projekty testowe są pomijane podczas automatycznego wybierania, więc rozwiązanie zawierające aplikację oraz jej testy są rozpoznawane dla aplikacji bez --project potrzeby. (Projekt testowy WinUI jest samą aplikacją spakowana, więc sam typ danych wyjściowych nie może go odróżnić).
Jeśli jedynym uruchomionym projektem jest projekt testowy, zostanie uruchomiony.
Jeśli istnieje więcej niż jeden projekt aplikacji z możliwością uruchamiania, winapp run nie odgadnie projektu startowego — błędy podczas wyświetlania listy kandydatów. Użyj --project <name> polecenia , aby wybrać, który jest zawsze honorowany, w tym do wybierania projektu testowego.

Spakowane a rozpakowane są wykrywane automatycznie z obowiązującej WindowsPackageType właściwości MSBuild projektu (nigdy z obecności manifestu):

Spakowany (WindowsPackageType=MSIXspakowany domyślny pakiet WinUI) — kompilacje, a następnie rejestruje dane wyjściowe kompilacji jako pakiet luźnego układu i uruchamia za pośrednictwem identyfikatora AUMID (tego samego potoku co tryb folderu).
Rozpakowane (WindowsPackageType=None) — kompilacje zapewniają zainstalowanie środowiska uruchomieniowego zależnego od platformy aplikacja dla systemu Windows, a następnie uruchomienie skompilowanego .exe bezpośrednio. Wymuś to dla spakowanego projektu za pomocą polecenia -p WindowsPackageType=None.

tryb Project wymaga zestawu SDK .NET w wersji 8.0.100 lub nowszej (w przypadku programu MSBuild--getProperty).

Natywna funkcja AOT: dodaj tę grupę właściwości wewnątrz elementu pliku <Project> project, a następnie dodaj polecenie --aot:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

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

--aotobsługuje projekty x64 i ARM64 i wymagają zestawu .NET SDK 8.0.300 lub nowszego. Jest on uruchamiany dotnet publish z konfiguracją AOT projektu, a następnie uruchamia te dane wyjściowe; użyj jednorazowego -p PublishAot=true zastąpienia. Nie wykonuje oddzielnej certyfikacji środowiska uruchomieniowego i nie można jej połączyć z --no-build programem lub --manifest.

W przypadku aplikacji korzystających z tożsamości pakietu bez wygenerowanego układu MSIX dołącz Package.appxmanifest dane wyjściowe publikowania lub appxmanifest.xml w danych wyjściowych publikowania projektu. Aplikacja Winapp inscenuje opublikowane pliki za pomocą tego manifestu. Jeśli obie nazwy są obecne, winapp zatrzymuje się zamiast wybierać jedno; usuń nieaktualny manifest i skonfiguruj projekt tak, aby publikował tylko zamierzony manifest.

opcje trybu Project (ignorowane w trybie folderu, chyba że jest to zaznaczone):

-c, --configuration <name> — Konfiguracja kompilacji. Wartość domyślna: Debug. (Również honorowane w trybie pojedynczego pliku).
--arch <x64|arm64|x86> - Architektura docelowa. Ustawienie domyślne: bieżąca architektura procesu. Określa identyfikator RID kompilacji i architekturę środowiska uruchomieniowego aplikacja dla systemu Windows oraz wybiera zgodny profil publikowania zależnego od platformy, jeśli jest to wymagane przez efektywną kompilację. (Również honorowane w trybie pojedynczego pliku).
-r, --runtime <rid>— Docelowy identyfikator środowiska uruchomieniowego .NET (np. win-x64). Project tryb używa tylko architektury identyfikatora RID, zawsze kompiluje canonical win-<arch>i odrzuca identyfikatory ZAREZERWOWANE inne niż Windows (np. linux-x64). Jej architektura zastępuje --arch i może wybrać wymagany profil publikowania. (Również honorowane w trybie pojedynczego pliku, gdzie zastępuje zadeklarowany #:property RuntimeIdentifier przez plik).
-f, --framework <tfm> - Target framework moniker for multi-target projects (np. net10.0-windows10.0.26100.0). (Odrzucone w trybie pojedynczego pliku — użyj . #:property TargetFramework=...)
--project <name-or-path> — Jeśli dane wejściowe są rozwiązaniem (.sln/.slnx) lub katalogiem z wieloma projektami aplikacji z możliwością uruchamiania, wybiera projekt do uruchomienia (według nazwy projektu lub ścieżki). (Odrzucone w trybie pojedynczego pliku — .cs sama aplikacja oparta na plikach jest projektem).
--no-build — Pomiń kompilowanie i uruchamianie istniejących danych wyjściowych kompilacji (nadal ocenia właściwości danych wyjściowych). (Również honorowane w trybie pojedynczego pliku).
--no-restore — Pomiń przywracanie przed kompilacją lub publikowaniem natywnej usługi AOT. (Również honorowane w trybie pojedynczego pliku).
--aot— Uruchom skonfigurowaną .NET natywną publikację AOT projektu. Wymaga skutecznego PublishAot=true. Odrzucone w trybach folderów i jednego pliku.
-p, --property <Name=Value> - Właściwość MSBuild przekazana do kompilacji i oceny właściwości. Powtórz dla -p wielu właściwości; użyj %3B lub %2C dla średnika literału lub przecinka w wartości. (Również honorowane w trybie pojedynczego pliku, gdzie jest to jedyny sposób ustawiania TargetFramework.)

Kompiluj dane wyjściowe i szczegółowość: zwykły przebieg projektu używa dotnet buildmetody , a następnie oblicza skompilowane dane wyjściowe. Przywracanie i kompilowanie strumienia wyjściowego na żywo przy użyciu poświadczeń z uwierzytelnionych adresów URL kanału informacyjnego zostało zredagowane. W programie --aotwinapp używa polecenia dotnet publish; --verbose pokazuje polecenie publikowania i rozwiązane ścieżki. Użyj poniższych opcji szczegółowości, aby kontrolować, co jest wyświetlane:

Flaga	dotnet verbosity	Dodaje
(domyślnie)	`minimal`	—
`--verbose`	`minimal`	Ślady podejmowania decyzji dotyczących kompilacji aplikacji winapp
`--quiet`	`quiet`	—

Natywna usługa AOT publikuje strumienie wyjściowe w miarę ich nadejścia. W obszarze --jsonpolecenie przywróć/skompiluj wywołania i dane wyjściowe podrzędne przejdź do stderr, więc stdout pozostaje czysty kod JSON. W obszarze --quietwywołania są pomijane, a ciche dane wyjściowe przywracania/kompilacji dotnet są kierowane do stderr, więc stdout pozostaje czysty. Natywne dane wyjściowe publikowania AOT również przechodzą do narzędzia stderr w ramach jednej z opcji.

Możliwość stosowania opcji: opcje tożsamości/luźnego układu (--manifest, --output-appx-directory, , --no-launch--with-alias, --unregister-on-exit, --clean), --executablemają zastosowanie tylko do spakowanych aplikacji. Są one odrzucane z wyraźnym błędem dla niepakowanych aplikacji (które nie mają pakietu MSIX). Opcje uruchamiania/debugowania (--args/--, --detach, , --debug-output--symbols, --json) działają w obu tych przypadkach.

przykłady trybu Project:

# Build and run the project in the current directory (input defaults to ".")
winapp run

# Run a specific project
winapp run ./src/MyApp/MyApp.csproj

# Build and run from a solution (resolves the runnable app project, defines $(SolutionDir))
winapp run ./MyApp.sln

# Pick a startup project when the solution has more than one runnable app
winapp run ./MyApp.sln --project MyApp

# Release build for arm64
winapp run . -c Release --arch arm64

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

Projekty języka C++ (.vcxproj)

Wskaż winapp run element — lub w folderze lub rozwiązaniu, którego jedyną .vcxproj aplikacją do uruchomienia jest jedna — i kompiluje projekt za pomocą programu MSBuild Visual Studio, a następnie uruchamia go w taki sam sposób, jak projekt .NET:

winapp run .\MyApp.vcxproj
winapp run . -c Release --arch arm64
winapp run . --no-build --detach --json

Aplikacja WinUI 3 C++/WinRT z szablonu Visual Studio WinUI Blank App (Spakowane) jest uruchamiana w pakiecie. Inne projekty aplikacji, takie jak aplikacja konsolowa lub aplikacja WinUI skompilowana za pomocą -p WindowsPackageType=Nonepolecenia , uruchamiają rozpakowywanie z poziomu skompilowanego .exeelementu .
Kompilacje Debug dla bieżącej architektury domyślnie. --arch x64|arm64|x86 lub -p Platform=x64|ARM64|Win32 wybiera architekturę (przekazywanie obu z różnymi architekturami jest błędem); nazwa niestandardowa -p Platform jest przekazywana.
packages.config Przywraca najpierw pakiety NuGet (pomiń --no-restoreza pomocą polecenia ) i instaluje przypiętą wersję środowiska uruchomieniowego aplikacja dla systemu Windows. Spakowane aplikacje pobierają również pakiety struktury odwołania do kompilacji, takie jak środowisko uruchomieniowe debugowania VC++, zainstalowane w przypadku braku.
--frameworki --aot mają zastosowanie tylko do projektów .NET.
Dane wyjściowe kompilacji pokazują tylko ostrzeżenia i błędy programu MSBuild z pokrętło podczas kompilacji; --verbose Wyświetla pełne dane wyjściowe programu MSBuild i dokładne polecenie.
W folderze lub rozwiązaniu, który ma również aplikację języka C# z możliwością uruchamiania, wybrano aplikację języka C#; użyj --project <name> polecenia , aby uruchomić aplikację języka C++. Biblioteki języka C# i projekty testowe obok aplikacji języka C++ nie są w ten sposób.
Nie można skompilować aplikacji języka C#, która odwołuje się do projektu C++ (na przykład natywnej biblioteki DLL) za pomocą polecenia dotnet. Skompiluj go przy użyciu Visual Studio lub MSBuild.exe, a następnie uruchom polecenie lub spakuj winapp run <app>.csproj --no-buildfolder wyjściowy za pomocą polecenia winapp package <folder>.

Wymagania wstępne: Visual Studio lub Build Tools for Visual Studio 2022 w wersji 17.8 lub nowszej z narzędziami kompilacji MSVC C++ dla architektury docelowej (programowanie aplikacji klasycznych z obciążeniem C++) i zestawem SDK Windows przeznaczonym dla projektu. Aplikacje WinUI 3 również potrzebują narzędzi deweloperskich aplikacji WinUI języka C++; w przypadku kilku instalacji winapp używa najnowszej, która może skompilować projekt. Zestaw .NET SDK nie jest wymagany. Gdy brakuje narzędzi kompilacji, zestawu narzędzi platformy (MSB8020) lub zestawu Windows SDK (MSB8036), mówi, winapp run co należy zainstalować, w tym winget polecenie.

Zobacz przykład cpp-winui-app.

Tryb pojedynczego pliku (.NET aplikacje oparte na plikach)

.NET 10 umożliwia uruchomienie pojedynczego .cs pliku bez pliku projektu, skonfigurowanie go z dyrektywami #: u góry. Wskaż winapp run ten plik i skompiluje aplikację, wygeneruje dla niej plik appxmanifest i uruchomi go przy użyciu tożsamości pakietu — dlatego Windows.ApplicationModel.Package.Current aplikacja pobiera prawdziwy identyfikator AUMID i wpis menu Start oraz interfejsy API, które po prostu wymagają tożsamości (powiadomienia aplikacji, ApplicationData, sztuczna inteligencja na urządzeniu).

Integracje powłoki, takie jak programy obsługi protokołów, skojarzenia plików, obiekty docelowe udziału i zadania uruchamiania, wymagają zadeklarowanego <Extensions> wpisu, który wygenerowany manifest nie zawiera. Aby go dodać, utwórz własny manifest — zobacz Bring your own manifest poniżej.

winapp run counter.cs

Możesz też uruchomić go w zwykły sposób dotnet run — zobacz Uruchamianie z poniższymi instrukcjami dotnet run .

Nie tworzysz manifestu. Zamiast tego opisz pakiet z dyrektywami #:property :

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

Właściwości manifestu. Wszystkie są opcjonalne; każda z nich wraca do rozsądnej wartości domyślnej:

Majątek	Zestawy	Wartość domyślna
`WinAppPackageName`	`Identity/@Name` (tożsamość pakietu)	nazwa pliku, oczyszczona do `[-.A-Za-z0-9]`, oraz krótki skrót ścieżki pliku (`counter.cs` → `counter-a1b2c3d4`)
`WinAppDisplayName`	Nazwa wyświetlana w obszarze Start i Ustawienia	nazwa pliku bez jego rozszerzenia
`WinAppPublisher`	`Identity/@Publisher`	`CN=<your Windows user name>`. Nazwa nagie jest opakowana jako `CN=<name>`.
`WinAppVersion`	`Identity/@Version`	`$(Version)`, znormalizowane (patrz poniżej)
`WinAppDescription`	Opis wyświetlany podczas instalacji i w ustawieniach	nazwa wyświetlana
`WinAppCapabilities`	Możliwości deklarowania, rozdzielone przez `;` lub `,`	Brak

Version. Wersja pakietu musi zawierać dokładnie cztery cyfry, z których każda to 0–65535. WinAppVersion (lub, jeśli go nie ustawisz, właściwość standardowa Version ) jest znormalizowana do dopasowania: -preview/-rc sufiks jest porzucony, a brakujące składniki są wypełnione zerami, więc #:property Version=1.2.3-preview.4 staje się 1.2.3.0 i ustawia wersję zestawu i wersję pakietu razem. Wartość, która nie może być dopasowana — składnik powyżej 65535 lub więcej niż czterech składników — jest odrzucana z błędem , a nie dyskretnie zmieniana.

Capabilities

Aplikacja uruchamia pełne zaufanie z tożsamością, która spełnia wymagania interfejsów API, które wymagają tylko spakowanej aplikacji. Jednak niektóre interfejsy API są bramowane w zadeklarowanej możliwości niezależnie od tego , Windows interfejsy API sztucznej inteligencji są typowym przypadkiem. (Integracje powłoki, takie jak programy obsługi protokołów i skojarzenia plików, są trzecim przypadkiem: te wymagają wpisów utworzonych <Extensions> , a nie możliwości, więc użyj własnego manifestu dla nich).

#:property WinAppCapabilities=systemAIModels

To wszystko Phi Silica i inne interfejsy API modelu urządzenia muszą pochodzić z manifestu. Zadeklaruj kilka, oddzielając je:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

Aplikacja winapp zapisuje każdy z nich w elemecie i przestrzeni nazw XML, której faktycznie wymaga, deklaruje tę przestrzeń nazw i zgłasza MaxVersionTested , gdy funkcja wymaga nowszego. Ma to większe znaczenie niż brzmi: możliwości są rozłożone na kilka różnych elementów, a ta sama lista powyżej staje się trzema różnymi kształtami —

<systemai:Capability Name="systemAIModels" />
<Capability Name="internetClient" />
<DeviceCapability Name="microphone" />

Nazwy winapp wie są napisane dla Ciebie. W przypadku czegokolwiek innego — zestaw ograniczony rośnie wraz z upływem czasu — kwalifikuje się go do prefiksu przestrzeni nazw:

prefiks	Emituje
`rescap:`	`<rescap:Capability>` — możliwości z ograniczeniami
`uap:`, , `uap6:`, , `uap7:uap11:`	`<uap*:Capability>`
`systemai:`	`<systemai:Capability>`
`device:`	`<DeviceCapability>`
`app:`	`<Capability>` w domyślnej przestrzeni nazw

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Nierozpoznana nazwa nagie jest odrzucana z błędem nazewnictwa tych prefiksów, a nie odgadnięcia na — możliwość emitowana w niewłaściwej przestrzeni nazw generuje manifest, Windows albo odmawia rejestrowania lub akceptowania, podczas gdy dyskretnie nie przyznaje.

Korzystanie z własnego manifestu

Jeśli potrzebujesz właściwości, które nie obejmują — procedury obsługi protokołu, skojarzenia pliku, aliasu wykonywania — utwórz manifest i winapp run użyje go dosłownego zamiast generowania. Jest on pobierany z, w kolejności:

--manifest <path> w wierszu polecenia.
#:property WinAppManifestPath=<path> .cs w pliku .
Manifest siedzi obok .cs pliku o nazwie <filename>.appxmanifest (na przykład counter.appxmanifest obok counter.cs).

Tylko ta nazwa dla pliku jest pobierana automatycznie. Obiekt Package.appxmanifest lub appxmanifest.xml w tym samym folderze jest celowo ignorowany — kilka .cs plików może współużytkować folder, a przyjęcie nazwy udostępnionej spowoduje dyskretne uruchomienie jednej aplikacji w ramach tożsamości innej. Aby użyć jednego manifestu dla kilku plików, nadaj mu jawną --manifest nazwę lub WinAppManifestPath.

Package.appxmanifest W przeciwnym razie element zostanie wygenerowany w danych wyjściowych kompilacji wraz z domyślnymi elementami zawartości obrazu i odświeżony przy każdym uruchomieniu.

Options. Każda opcja trybu folderu działa: --no-launch, , --without-alias--output-appx-directory--with-alias--args--unregister-on-exit/--symbols----debug-output--json--executable--clean--detach-c/--configuration--no-build--manifest--no-restorei .-p/--property

Wskazówka

Aplikacja konsolowa domyślnie drukuje do terminalu. Spakowana aplikacja uruchomiona za pośrednictwem identyfikatora AUMID nie ma konsoli, więc aplikacja tylko do konsoli będzie działać poprawnie i nic nie wydrukować. Aplikacja winapp unika tego: aplikacja z OutputType=Exe systemem jest uruchamiana za pośrednictwem aliasu wykonywania, który dziedziczy stdin/stdout/stderr tego terminalu. Nadal uzyskujesz tożsamość pakietu i nie musisz go prosić:

winapp run counter.cs

Przekaż --without-alias , aby wymusić aktywację identyfikatora AUMID — aplikacja jest uruchamiana bez konsoli i nie drukuje nic tutaj. W aplikacji z oknem (WinExe) jest wyświetlane okno, dzięki czemu zachowuje aktywację AUMID. Mimo to przekaż ją --with-alias , jeśli chcesz ją w tym terminalu. Aby naprawić wybór w pliku, a nie w każdym wierszu polecenia, ustaw tę samą właściwość używa:.csproj

#:property WinAppRunUseExecutionAlias=false

Alias winapp deklaruje nazwę po nazwie rodziny pakietów z prefiksem winapp- — tak com.contoso.counter opublikowanym przez CN=You polecenie pobiera winapp-com.contoso.counter_gspb8g6x97k2t.exe. Ta końcowa część to skrót wydawcy, Windows pochodzi, więc dwie aplikacje współużytkujące nazwę w różnych wydawcach nadal uzyskują różne aliasy. Prefiks zachowuje nazwę bez rzeczywistych poleceń: aplikacja w python.cs programie pobiera winapp-… alias, nigdy .python.exe Jeśli tworzysz własny manifest, alias zadeklarowany jest używany as-is i winapp nie dodaje niczego.

Dotyczy to tylko aliasu. Sama rejestracja jest kluczem w nazwie pakietu, więc uruchomienie drugiej aplikacji, która deklaruje to samo WinAppPackageName w ramach innego wydawcy zastępuje pierwszą rejestrację, a nie siedząc obok niej. Nadaj każdej aplikacji własną nazwę, jeśli chcesz, aby obie zostały zarejestrowane jednocześnie.

winapp run Wyświetla zarejestrowany alias, więc nie trzeba obliczać skrótu, aby go znaleźć.

Alias to polecenie w ścieżce, które trwa tak długo, jak pakiet pozostaje zarejestrowany. Jeśli jakiś inny pakiet jest już właścicielem nazwy, winapp mówi tak. Gdy wywnioskowany alias zostanie uruchomiony za pośrednictwem identyfikatora AUMID, zamiast uruchamiać niewłaściwą aplikację; po wyświetleniu monitu o jawne — z elementem --with-alias lub #:property WinAppRunUseExecutionAlias=true — kończy się niepowodzeniem zamiast po cichu robić coś innego.

Nie mają zastosowania dwie opcje trybu projektu, ponieważ aplikacja oparta na plikach konfiguruje się. Są one odrzucane z komunikatem nazewnictwa dyrektywy, aby zamiast tego użyć:

Option	Użyj zamiast tego
`-f/--framework`	`#:property TargetFramework=net10.0-windows10.0.22621.0`
`--project`	nic — `.cs` plik jest projektem

--arch i -r/--runtime działają tak jak w trybie projektu. Jeśli nie przejdziesz albo, kompilacje winapp dla architektury maszyny — co jest tym, czego potrzebuje samodzielna aplikacja Zestaw SDK do aplikacji systemu Windows, ponieważ bez niej zestaw SDK kompiluje AnyCPU i kończy się niepowodzeniem z .WindowsAppSDKSelfContained requires a supported Windows architecture Element #:property RuntimeIdentifier=win-arm64 w pliku jest przestrzegany; jawne --arch/--runtime zastępuje go.

Spakowane i rozpakowane działają, wykryte z skutecznego WindowsPackageType dokładnie tak jak w trybie projektu: ustawienie domyślne rejestruje luźny układ i uruchamia ją z tożsamością, podczas gdy #:property WindowsPackageType=None kompiluje aplikację, instaluje pasujące aplikacja dla systemu Windows Runtime i uruchamia .exe bezpośrednio. (Spakowana aplikacja jest uruchamiana za pośrednictwem aliasu wykonywania lub za pośrednictwem aktywacji AUMID — zobacz notatkę konsoli powyżej; wybór ten jest oddzielony od tego, czy jest spakowany). Opcje tożsamości (--no-launch, --with-alias, , --without-alias--clean, --unregister-on-exit, --manifest, --output-appx-directory) dotyczą tylko spakowanych aplikacji.

Uruchamianie za pomocą polecenia `dotnet run`

Nie musisz w ogóle wpisywać winapp . Odwołanie do Microsoft.Windows.SDK.BuildTools.WinApp pakietu z pliku i zwykły dotnet run zapewnia to samo spakowane uruchomienie:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

Docelowy program MSBuild pakietu przekierowuje przebieg do aplikacji winapp, która pakuje, rejestruje i uruchamia utworzoną właśnie aplikację dotnet run — nie została ona ponownie skompilowana. Obsługa manifestu jest niezmieniona: aplikacja winapp rozwiązuje go dokładnie tak samo jak w przypadku winapp run, więc #:property WinAppManifestPath=…<filename>.appxmanifest obok .cs obu elementów (zobacz Bring your own manifest), katalog Package.appxmanifest jest nadal ignorowany, a w przeciwnym razie jeden jest generowany na podstawie #:property dyrektyw i odświeżany każdy przebieg.

Aby przekierowanie miało miejsce, muszą zostać wstrzymane dwa warunki:

Dyrektywa	Dlaczego
`#:package Microsoft.Windows.SDK.BuildTools.WinApp@*`	miejsca docelowe wykonujące przekierowanie wysyłki w tym pakiecie
`#:property TargetFramework=net10.0-windows…`	`net10.0` zwykły plik jest pozostawiony sam, więc jest uruchamiany rozpakowany

Dodanie #:property WindowsPackageType=None pozostawia również sam plik: dotnet run następnie uruchamia .exe bezpośrednio bez tożsamości. Użyj winapp run dla ścieżki rozpakowanej, jeśli chcesz najpierw zainstalować pasujące środowisko uruchomieniowe aplikacja dla systemu Windows Runtime.

Ustaw #:property EnableWinAppRunSupport=false opcję całkowitego rezygnacji z przekierowania, a WinAppRun* właściwości opisane w sekcji Konfiguracja umożliwiają kształtowanie uruchamiania — na przykład:

#:property WinAppRunUnregisterOnExit=true

Jeśli dotnet run aplikacja jest rozpakowana po oczekiwanej tożsamości, zapytaj program MSBuild dlaczego. Użyj polecenia dotnet build, a nie dotnet msbuild — zsyntetyzuje tylko dotnet build projekt wirtualny, za pomocą którego jest kompilowana aplikacja oparta na plikach:

dotnet build counter.cs -t:WinAppRunSupportInfo

Tryb pojedynczego pliku wymaga zestawu .NET SDK 10.0.300 lub nowszego.

Rejestracja przeżywa przebieg. winapp run counter.cs pozostawia pakiet zarejestrowany po zakończeniu pracy aplikacji, dokładnie tak jak folder i tryb projektu — więc LocalState przetrwa i ponownie uruchomi ten sam plik ponownie używa tej samej tożsamości, a nie stosowania rejestracji. Winapp mówi, że po raz pierwszy rejestruje aplikację i winapp unregister bierze się za .cs :

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs nie wymaga ścieżki manifestu: oblicza wartości pliku #:property w taki sam sposób run i usuwa tylko pakiet zarejestrowany z danych wyjściowych kompilacji tego pliku. Aplikacja o tej samej nazwie zarejestrowana w innym folderze jest odrzucana, chyba że przekażesz polecenie --force. Jeśli przebieg użył opcji, która kształtuje tożsamość lub układ, przekaż tę samą opcję do unregister:

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-pzastępuje własne dyrektywy pliku i Directory.Build.props obok .cs klawisza może $(Configuration)WinAppPackageName wyłączyć lub $(RuntimeIdentifier) — dzięki czemu każdy z nich może zmienić, który pakiet zostanie zarejestrowany.

Po wyczyszczeniu danych wyjściowych zestawu SDK nie można już potwierdzić, winapp unregister counter.cs że rejestracja pochodzi z tego pliku i pominie go — użyj winapp unregister --prune polecenia , aby wyczyścić rejestracje, których pliki zostały usunięte, lub --force usunąć konkretną. Jeśli używany --output-appx-directoryprzebieg , przekaż ten sam katalog do , aby unregister mógł rozpoznać układ.

To samo dotyczy niestandardowej ścieżki wyjściowej: własność jest potwierdzana ze standardowego <root>\bin\<configuration> układu zestawu SDK, więc nie można dopasować przebiegu skompilowanego z plikiem -p OutputPath=<somewhere-else> źródłowym. unregister Pomija go zamiast odgadywać w szerszym katalogu — nadaj układowi nazwę , --output-appx-directorylub użyj polecenia --force.

Przykłady pojedynczego pliku:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

Uwaga / Notatka

Tożsamość domyślna zawiera krótki skrót ścieżki pliku — counter.cs staje się podobny counter-a1b2c3d4 do następującego — więc dwa counter.cs pliki w różnych folderach są różnymi aplikacjami i zachowują własne ustawienia i LocalState. Skrót pochodzi ze ścieżki, więc przetrwa edycje i ponownie uruchamia i zmienia się tylko po przeniesieniu pliku. Ustaw #:property WinAppPackageName=<name> opcję samodzielnego wybierania stabilnej tożsamości. Jest ona znormalizowana do tego, co Identity/@Name zezwala — znaki na zewnątrz [-.A-Za-z0-9] są porzucane, nazwy krótsze niż 3 znaki są dopełniane znakiem 1, a wynik jest ograniczony do 50 znaków, więc My App rejestruje się jako MyApp. Tak czy inaczej menu Start i Ustawienia pokazują wartość WinAppDisplayName (domyślną: nazwę pliku), a nie tożsamość. Tożsamość jest zawsze ograniczona do konta użytkownika, więc nigdy nie zderza się z innym użytkownikiem na tym samym komputerze.

Właściwości programu MSBuild (pakiet NuGet):

W przypadku korzystania z pakietu Microsoft.Windows.SDK.BuildTools.WinApp NuGet dotnet run automatycznie wywołuje winapp run.

Wszystko zapisane po dotnet run przekazaniu do aplikacji dokładnie tak, jak byłoby bez pakietu. Skonfiguruj moduł uruchamiania przy użyciu poniższych właściwości programu MSBuild:

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

Następujące właściwości programu MSBuild można ustawić w .csproj celu kontrolowania zachowania:

Majątek	Wartość domyślna	Opis
`EnableWinAppRunSupport`	`true`	Włączanie/wyłączanie funkcji obsługi przebiegu
`WinAppLaunchArgs`	(puste)	Argumenty przekazywane do aplikacji podczas uruchamiania
`WinAppRunUseExecutionAlias`	wnioskowane z aplikacji	Uruchom za pomocą aliasu wykonywania zamiast aktywacji identyfikatora AUMID. Pozostawiony bez ustawienia, aplikacja winapp wywnioskuje ją: aplikacja konsolowa używa aliasu, aby jego dane wyjściowe dotarły do terminalu, aplikacja okienna używa identyfikatora AUMID. Ustaw `true` lub `false` decydujesz o tym samodzielnie.
`WinAppRunNoLaunch`	`false`	Zarejestruj tożsamość tylko bez uruchamiania
`WinAppRunDebugOutput`	`false`	Przechwytywanie `OutputDebugString` komunikatów i wyjątków pierwszej szansy. Tylko jeden debuger może dołączać jednocześnie (uniemożliwia programOWI VS/VS Code). Zamiast tego użyj `WinAppRunNoLaunch` polecenia , aby dołączyć inny debuger.
`WinAppRunDetach`	`false`	Wróć natychmiast po uruchomieniu zamiast czekać na zakończenie działania aplikacji. Drukuje identyfikator PID.
`WinAppRunUnregisterOnExit`	`false`	Wyrejestrowywanie pakietu programistycznego po zakończeniu działania aplikacji
`WinAppRunClean`	`false`	Przed ponownym wdrożeniem usuń dane aplikacji istniejącego pakietu (LocalState, settings)
`WinAppRunSymbols`	`false`	Pobierz symbole z serwera symboli Microsoft, aby uzyskać bogatszą analizę awarii natywnej. Ma wpływ tylko na `WinAppRunDebugOutput`.
`WinAppRunExecutable`	(puste)	Ścieżka pliku wykonywalnego względem folderu build-output. Użyj polecenia , gdy manifest zawiera $targetnametoken$ i folder wyjściowy ma więcej niż jeden `.exe`element .
`WinAppRunArgs`	(puste)	Nieprzetworzone argumenty dołączone do `winapp run` wiersza polecenia dla opcji bez dedykowanej właściwości (na przykład `--verbose`). Dołączono po każdej powyższej właściwości.

Wzajemnie wykluczające się ustawienia. WinAppRunNoLaunch każda WinAppRunDetach z nich opisuje inne zachowanie uruchamiania, dlatego powodują konflikt z innymi właściwościami uruchamiania i ze sobą. Ustawianie pary powodującej konflikt kończy się niepowodzeniem podczas uruchamiania za pomocą polecenia --X and --Y cannot be used together:

Majątek	Nie można połączyć z
`WinAppRunNoLaunch`	`WinAppRunDetach`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`
`WinAppRunDetach`	`WinAppRunNoLaunch`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`

WinAppRunUseExecutionAlias celowo nie znajduje się na tej liście, w obu kierunkach. false prosi o aktywację identyfikatora AUMID, która nie jest już uruchamiana i odłączana; true program nie jest po prostu stosowany, gdy jest ustawiony, ponieważ alias wykonywania wymaga śledzonego, uruchomionego procesu. W związku z tym projekt, który nadal jest sprawdzany <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> w dotnet run -p:WinAppRunDetach=trueobszarze , uruchamia się za pośrednictwem identyfikatora AUMID, a nie kończy się niepowodzeniem.

WinAppRunUseExecutionAlias, WinAppRunDebugOutputi WinAppRunUnregisterOnExit można łączyć ze sobą. WinAppRunClean, , WinAppRunSymbolsWinAppRunExecutablei WinAppLaunchArgs nie mają żadnych ograniczeń. WinAppRunArgs dodaje żadnych ograniczeń, ale przełącznik przekazywany przez nie jest sprawdzany jak każdy inny, więc WinAppRunArgs="--detach" nadal powoduje konflikt z WinAppRunNoLaunch.

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

Wyrejestrować

Wyrejestrowywanie ładowanego bezpośrednio pakietu programistycznego. Usuwa tylko pakiety zarejestrowane w trybie programowania (np. za pośrednictwem winapp run lub create-debug-identity). Pakiety zainstalowane w magazynie lub zainstalowane przez plik MSIX nigdy nie są usuwane.

winapp unregister [input] [options]

argumenty:

input— Ścieżka do .NET aplikacji opartej na plikach (pojedynczej .cs), której pakiet powinien być wyrejestrowany. Jego tożsamość jest rozpoznawana w taki sam sposób, jak winapp run jest rozpoznawana — z manifestu utworzonego, jeśli aplikacja ma ją, w przeciwnym razie z jej #:property wartości — więc nie jest wymagana żadna ścieżka manifestu. Pomiń użycie --manifest lub automatyczne wykrywanie manifestu w bieżącym katalogu. Nie można połączyć z elementem --manifest, który nadaje pakietowi inną nazwę i może rozpoznać inny.

Opcje:

--manifest <path> — Ścieżka do pliku Package.appxmanifest (ustawienie domyślne: automatyczne wykrywanie z bieżącego katalogu)
--force — Tylko w przypadku wyrejestrowania lokalnego pomiń sprawdzanie katalogu lokalizacji instalacji i wyrejestrowywanie, nawet jeśli pakiet został zarejestrowany z innego drzewa projektu. Jest on odrzucany z --on; nie można pominąć kontroli własności docelowej.
--on <target> — Usuń zgodną rejestrację sandboxdeweloperów winapp z programu , a nie z tej maszyny. Wymaga manifestu i nie obsługuje --force. Zobacz Oczyszczanie aplikacji piaskownicy.
--prune — Usuń każdą rejestrację w trybie programowania, której pliki zniknęły. Nie można połączyć z danymi wejściowymi, --manifest, --property, --configuration, --arch, --runtimelub --output-appx-directory.
-p, --property <Name=Value> - Właściwość MSBuild używana podczas rozpoznawania tożsamości aplikacji opartej .cs na plikach. Powtarzalne. Przekaż te same właściwości wpływające na tożsamość używanego przebiegu (np. -p WinAppPackageName=...), ponieważ właściwość wiersza polecenia zastępuje własne #:property dyrektywy pliku. Dotyczy tylko danych wejściowych .cs .
-c, --configuration <name> — Konfiguracja kompilacji używana podczas rozpoznawania tożsamości aplikacji opartej .cs na plikach. Wartość domyślna: Debug. Przekaż tę samą konfigurację używaną przez przebieg: Directory.Build.props obok parametru .cs można ustawić WinAppPackageName lub WinAppManifestPath warunkowo na .$(Configuration) Dotyczy tylko danych wejściowych .cs .
--arch <x64|arm64|x86> — Architektura docelowa używana podczas rozpoznawania tożsamości aplikacji opartej .cs na plikach. Ustawienie domyślne: bieżąca architektura procesu. Przekaż tę samą architekturę używaną przez przebieg, ponieważ tożsamość może być również wyłączona $(RuntimeIdentifier). Dotyczy tylko danych wejściowych .cs .
-r, --runtime <rid>— Docelowy identyfikator środowiska uruchomieniowego .NET (np. win-x64) używany podczas rozpoznawania tożsamości aplikacji opartej .cs na plikach. Używana jest tylko jego architektura i zastępuje --archwartość . Dotyczy tylko danych wejściowych .cs .
--output-appx-directory <path> — Katalog układu AppX, z którego został zarejestrowany pakiet. Potrzebne tylko wtedy, gdy przebieg był używany --output-appx-directory, ponieważ nic na rekordach pakietu, które opcja uruchamiania wygenerowała jego układ.
--json - Formatuj dane wyjściowe jako dane JSON

Co to robi:

Określa nazwę pakietu — z .cs rozpoznanej tożsamości pliku lub odczytując manifest
Wyszukuje zarówno pakiety, jak {name} i {name}.debug (wariant debugowania jest tworzony przez create-debug-identityprogram )
Sprawdza, czy każdy pakiet został zarejestrowany w trybie programowania (IsDevelopmentMode == true)
Sprawdza, czy pakiet należy do aplikacji o nazwie (chyba że --force) — jego lokalizacja instalacji musi znajdować się w określonym katalogu: .cs własne dane wyjściowe kompilacji pliku, katalog manifestu, bieżący katalog lub jawne --output-appx-directory. Pakiet, którego nie można rozpoznać lokalizacji instalacji (jego pliki zostały usunięte), jest pomijany, ponieważ tożsamość nie jest dowodem własności: dwie aplikacje, które ustawiają #:property WinAppPackageName=counter tę samą tożsamość z różnych folderów. Użyj --prune polecenia , aby wyczyścić rejestracje, których pliki zniknęły.
Wyrejestrowywanie pasujących pakietów

Czyszczenie utraconych rejestracji (--prune):

Rejestracja przeżywa swoje pliki. Usuń dane wyjściowe kompilacji, drzewo projektu lub (w przypadku aplikacji opartej na plikach) pozwól Windows czyszczenie %LOCALAPPDATA%\Temp, a pakiet pozostaje zarejestrowany: Windows zachowuje tożsamość i jego wpis menu Start, ale aktywacja dyskretnie nic nie robi. Te kumulują się w sposób niewidoczny.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

Uwzględniane są tylko rejestracje w trybie programowania, a każda z nich jest usuwana przy użyciu pełnej nazwy pakietu, więc pakiet o tej samej nazwie nadal jest instalowany z lokalizacji na żywo. Monit istnieje, ponieważ brakująca lokalizacja instalacji jest zwykle folderem usuniętym, ale także opisuje pakiet zarejestrowany w odłączonym udziale sieciowym lub dysku wymiennym — przejrzyj listę przed potwierdzeniem.

Przykłady:

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# Remove every dev registration whose files are gone
winapp unregister --prune

# JSON output for scripting
winapp unregister --json

cert

Generowanie, sprawdzanie i instalowanie certyfikatów programistycznych.

Generowanie certyfikatu

Generowanie certyfikatów programistycznych na potrzeby podpisywania pakietów.

winapp cert generate [options]

Opcje:

--manifest <Package.appxmanifest>— Wyodrębnij publisher certyfikatu z manifestu Identity/@Publisher. Tylko wydawca jest wymagany, więc częściowo kompletny manifest nadal działa. Jeśli manifest nie ma użytecznego wydawcy, polecenie kończy się niepowodzeniem zamiast podstawiania domyślnego, więc certyfikat nigdy nie może dyskretnie niezgodnie manifestu.
--publisher <name>- Publisher dla certyfikatu. Podczas generowania certyfikatu ta opcja ma pierwszeństwo --manifestprzed ; jawnie pusta wartość kończy się niepowodzeniem zamiast używania wydawcy manifestu. Akceptuje pełną nazwę wyróżniającą X.500 (np CN=Contoso, O=Contoso Ltd, C=US. ) lub nagą nazwę, która jest automatycznie opakowana jako CN=<name>. Składniki muszą być rozdzielone przecinkami i jednowarte; Wielowartych rdN (CN=Foo+OU=Bar) i ukośników odwrotnych nie są obsługiwane, ponieważ wydawca manifestu MSIX nie może ich reprezentować. Źle sformułowana nazwa wyróżniająca (np. CN= lub CN=A,,O=B) jest odrzucana z wyjściem bez zera i błędem nazewnictwa problemu, zamiast produkować certyfikat, który nigdy nie może być zgodny z wydawcą manifestu.
--output <path> — Ścieżka pliku certyfikatu wyjściowego (obsługuje ścieżki bezwzględne i względne)
--password <password> - Hasło certyfikatu (domyślnie: password, który jest publicznie znany — zobacz dane wyjściowe JSON i zabezpieczenia)
--valid-days <valid-days> - Liczba dni ważności certyfikatu (wartość domyślna: 365)
--install - Zainstaluj certyfikat w magazynie komputera lokalnego po wygenerowaniu
--if-exists <Error|Overwrite|Skip> - Ustaw zachowanie, jeśli plik certyfikatu już istnieje (wartość domyślna: Błąd)
--export-cer — Wyeksportuj .cer plik (tylko klucz publiczny) obok elementu .pfx. Przydatne do dystrybucji certyfikatu publicznego oddzielnie na potrzeby instalacji zaufania.
--json - Formatuj dane wyjściowe jako dane JSON w celu programowania użycia. Błędy są również zwracane jako dane JSON ({"error": "..."}).

Dane wyjściowe JSON:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ],
  "skipped": false
}

publisher to nazwa wyświetlana i subjectName pełna nazwa wyróżniająca, do którego wystawiono certyfikat. defaultPasswordIsPublic jest zawsze obecny podczas generowania certyfikatu. Gdy jest trueto , .pfx element jest chroniony hasłem, które każdy może odgadnąć, więc certyfikat musi podpisywać tylko kompilacje, które pozostają na własnych maszynach — sprawdź je, zanim skrypt przekazuje certyfikat do czegokolwiek innego. warnings prowadzi takie samo ujawnienie jak tekst i jest pomijane, gdy nie ma nic do zgłoszenia. publicCertificatePath jest wyświetlany tylko z --export-cer.

Gdy --if-exists skipplik certyfikatu już istnieje, polecenie pozostawia go nietknięte i zwraca tylko jego ścieżkę:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "skipped": true
}

Sprawdź skipped przed odczytaniem innych pól. Aby sprawdzić istniejący certyfikat, uruchom polecenie winapp cert info.

informacje o certyfikatach

Wyświetl szczegóły certyfikatu z pliku PFX lub CER. Przydatne do weryfikowania certyfikatu zgodnego z manifestem przed podpisaniem.

winapp cert info <cert-path> [options]

argumenty:

cert-path - Ścieżka do pliku certyfikatu (PFX lub CER)

Opcje:

--password <password> - Hasło do pliku PFX, ignorowane dla publicznego CER (ustawienie domyślne: "hasło")
--json - Formatuj dane wyjściowe jako dane JSON

Instalacja certyfikatu

Zainstaluj certyfikat w sklepie certyfikatów komputera.

winapp cert install <cert-path> [options]

argumenty:

cert-path - Ścieżka do pliku certyfikatu do zainstalowania

Przykłady:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

znak

Podpisywanie pakietów MSIX i plików wykonywalnych przy użyciu certyfikatów.

winapp sign <file-path> <cert-path> [options]

argumenty:

file-path - Ścieżka do pakietu MSIX lub pliku wykonywalnego do podpisania
cert-path - Ścieżka do certyfikatu podpisywania (pfx)

Opcje:

--password <password> - Hasło certyfikatu (domyślne: "hasło")
--timestamp <url> - Adres URL serwera sygnatury czasowej RFC 3161

Przykłady:

# Sign MSIX package
winapp sign MyApp.msix ./mycert.pfx

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --password mypassword

az-sign

Podpisywanie kodu pliku (exe, MSIX lub MSIX) przy użyciu Azure Trusted Signing — tożsamości podpisywania zarządzanego przez chmurę, więc żaden klucz prywatny (PFX) nigdy nie istnieje na komputerze lokalnym.

winapp az-sign <file-path> [options]

argumenty:

file-path - Ścieżka do pliku do podpisania (exe, msix lub msixbundle)

Opcje:

--subscription, -s — Azure identyfikator subskrypcji do użycia. Jeśli nie podano i istnieje wiele subskrypcji, zostanie wyświetlony monit
--resource-group, -r — grupa zasobów w celu zawężenia kont podpisywania
--account — Nazwa konta podpisywania. Należy używać z --resource-group
--profile, -p — nazwa profilu certyfikatu. Należy używać z --account
--metadata-file, -m — ścieżka do istniejącego metadata.jsonelementu . Pomija odnajdywanie zasobów i monity wyboru konta/profilu i podpisuje je bezpośrednio. Poświadczenie nieinterakcyjne Azure powinno być już dostępne. W przeciwnym razie interfejs wiersza polecenia może wrócić do interakcyjnego monitu dzierżawy lub az login, ale interfejs API programu npm jest zawsze nieinterakcyjny i kończy się niepowodzeniem zamiast monitowania

Authentication (Uwierzytelnianie):

az-signużywa standardowego łańcucha poświadczeń Azure (DefaultAzureCredential). W przypadku ciągłej integracji/ciągłego wdrażania ustaw AZURE_TENANT_IDwartości , AZURE_CLIENT_IDi AZURE_CLIENT_SECRET (lub użyj GitHub Actions OIDC / tożsamości zarządzanej). Istniejąca sesja Azure CLI (az loginw tym azure/login akcja GitHub) jest również honorowana w dowolnym środowisku. Tylko wtedy, gdy nie znaleziono poświadczeń , a sesja zostanie az-sign uruchomiona az login interaktywnie.

Wymagania wstępne:

Konto podpisywania kodu Azure i profil certyfikatu (utworzony w portalu Azure po weryfikacji tożsamości) oraz przypisana do tożsamości rola podpisywania certyfikatu podpisywania kodu. Aby uzyskać więcej wskazówek, zapoznaj się z dokumentacją przewodnika Szybki start dotyczącą podpisywania artefaktów Azure.
Zainstalowano środowisko uruchomieniowe x64 x64 .NET 8 (lub nowsze). Biblioteka klienta podpisywania Azure jest zestawem zarządzanym, który signtool.exe ładuje się w osobnym procesie; własne środowisko uruchomieniowe winapp nie spełnia wymagań. Zainstaluj go z https://dotnet.microsoft.com/download programu , jeśli podpisywanie zakończy się niepowodzeniem z powodu błędu ładowania w czasie wykonywania.
Microsoft redystrybucyjny Visual C++ (x64). Biblioteka klienta podpisywania Azure zależy od środowiska uruchomieniowego VC++, a ponieważ aplikacja winapp pobiera nieprzetworzony pakiet NuGet, a nie od oficjalnego instalatora narzędzi klienckich, ta zależność nie jest instalowana automatycznie. Czysta maszyna może ładować się nawet w przypadku .NET i narzędzia SignTool. Zainstaluj najnowszy pakiet redystrybucyjny x64, https://aka.ms/vs/17/release/vc_redist.x64.exe jeśli podpisywanie kończy się niepowodzeniem z komunikatem 0xc000007b"Aplikacja nie mogła uruchomić poprawnie" lub błąd brakującej biblioteki DLL z biblioteki dlib.

Ciągła integracja z najmniejszymi uprawnieniami: Automatyczne odnajdywanie (wyświetlanie subskrypcji, grup zasobów, kont i profilów) wymaga dostępu do odczytu w zakresie nadrzędnym. Aby uniknąć każdego wywołania listy kolekcji, przekaż wszystkie cztery wartości --subscription, --resource-groupi --account--profile:az-sign, a następnie weryfikuje konto i profil przy użyciu bezpośrednich odczytów zasobów (GET dla każdego nazwanego zasobu) zamiast wyliczać kolekcję nadrzędną, więc podmiot zabezpieczeń o określonym zakresie tylko dla tego konta i profilu jest wystarczający. Pominięcie jednego z nich powoduje ponowne wprowadzenie wywołania listy — na przykład pomija wyświetlanie --subscription listy powoduje az-sign , że lista subskrypcji, do których może uzyskiwać dostęp tożsamość — której może nie zezwalać podmiot zabezpieczeń o wąskim zakresie. Podmiot zabezpieczeń o określonym zakresie tylko dla pojedynczego profilu certyfikatu może całkowicie pominąć walidację, przekazując wstępnie wygenerowany --metadata-file element (który określa bezpośrednio punkt końcowy konta i profil).

Przykłady:

# Interactive — discover/select subscription, account, and profile
winapp az-sign ./app.msix

# Fully specified — no prompting (ideal for CI/CD)
winapp az-sign ./app.msix --subscription <sub-id> --resource-group <rg> --account <account> --profile <profile>

# Reuse an existing metadata.json (skips resource discovery and selection; authentication may still prompt)
winapp az-sign ./app.msix --metadata-file ./metadata.json

create-external-catalog

Wygeneruj CodeIntegrityExternal.cat plik wykazu zawierający skróty plików wykonywalnych z określonych katalogów. Ten wykaz jest używany z flagą TrustedLaunch w manifestach pakietów rozrzedzanych MSIX (AllowExternalContent), aby umożliwić wykonywanie plików zewnętrznych, które nie są uwzględnione w samym pakiecie.

Jest to podobne do sposobu signtool.exe tworzenia AppxMetadata\CodeIntegrity.cat podczas podpisywania pakietu MSIX, ale generuje wykaz zewnętrzny do użycia z rozrzedniami/zewnętrznymi pakietami lokalizacji.

winapp create-external-catalog <input-folder> [options]

argumenty:

input-folder - Co najmniej jeden katalog zawierający pliki wykonywalne do przetworzenia. Rozdziel wiele katalogów średnikami (np. "dir1;dir2")

Opcje:

--recursive, -r — dołączanie plików z podkatalogów
--use-page-hashes — Dołączanie skrótów stron podczas generowania wykazu (tworzy większy wykaz z danymi skrótu na stronie)
--compute-flat-hashes — Dołączanie skrótów plików prostych podczas generowania katalogu
--if-exists <Error|Overwrite|Skip> - Zachowanie, gdy plik wyjściowy już istnieje (wartość domyślna: Error)
--output, -o — ścieżka pliku wykazu danych wyjściowych. Jeśli nie zostanie określony, CodeIntegrityExternal.cat zostanie utworzony w bieżącym katalogu. Jeśli zostanie określony katalog, zostanie dołączona domyślna nazwa pliku.

Co to robi:

Skanuje określone katalogi dla plików wykonywalnych (pliki binarne PE z sekcjami kodu)
Generuje plik definicji katalogu (CDF) z skrótami wszystkich znalezionych plików wykonywalnych
Używa interfejsów API Windows CryptoCAT do tworzenia pliku katalogu .cat
Pliki nie .txtwykonywalne (np. , .dll bez sekcji kodu) są automatycznie pomijane

Przykłady:

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

Kiedy należy użyć:

Użyj tego polecenia podczas kompilowania rozrzedliwego pakietu MSIX, który używa trustedLaunch do weryfikowania zewnętrznych plików wykonywalnych. Typowy przepływ pracy to:

winapp manifest generate --template sparse — Tworzenie rozrzednego manifestu za pomocą polecenia AllowExternalContent
winapp create-external-catalog ./bin — Generowanie katalogu integralności kodu dla plików wykonywalnych aplikacji
winapp pack — Pakowanie manifestu, zasobów i wykazu do pliku MSIX

narzędzie

Uzyskaj dostęp do narzędzi Windows SDK bezpośrednio. Używa narzędzi dostępnych w Microsoft.Windows. SDK. BuildTools

winapp tool <tool-name> [tool-arguments]

Dostępne narzędzia:

makeappx - Tworzenie pakietów aplikacji i manipulowanie nimi
signtool - Podpisywanie plików i weryfikowanie podpisów
mt - Narzędzie do tworzenia manifestów dla zbiorów równoległych
Inne narzędzia zestawu SDK Windows z Microsoft.Windows. SDK. BuildTools

Przykłady:

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

Weryfikacja podpisu

Narzędzia kompilacji są pobierane z narzędzia NuGet, a następnie wykonywane, dlatego aplikacja Winapp sprawdza każdy z nich pod kątem prawidłowego podpisu Microsoft Authenticode bezpośrednio przed uruchomieniem. Certyfikat musi nazwać Microsoft Corporation jako organizację podpisywania. Dotyczy to każdego polecenia, które powłoki są wyświetlane w narzędziu zestawu SDK, w tym tool, packagei sign. Narzędzie, które kończy się niepowodzeniem sprawdzania, nie jest uruchamiane:

'mt.exe' is not validly signed by Microsoft, so it was not run (C:\...\mt.exe).

Błąd oznacza, że plik na dysku nie jest tym, co Microsoft opublikowane — najczęściej jest to uszkodzone lub częściowe pobieranie. Usuń pakiet z pamięci podręcznej NuGet i uruchom polecenie ponownie, aby aplikacja winapp ponownie ją pobrała.

Aplikacja winapp przechowuje narzędzie otwarte tak długo, jak działa, więc plik, który został sprawdzony, jest plikiem, Windows ładuje. Jeśli nie może on trzymać narzędzia na miejscu, nie jest uruchamiany albo:

'mt.exe' could not be held open for verification, so it was not run (C:\...\mt.exe).

Zamknij wszystko, co używa pliku — skanowanie antywirusowe lub otwarty edytor jest zwykle przyczyną — i ponownie uruchom polecenie. Jeśli narzędzie nie jest używane, usuń pakiet z pamięci podręcznej NuGet, aby aplikacja WinApp ponownie ją pobrała.

przechowywać

Uruchom polecenie Microsoft Store Developer CLI. To polecenie spowoduje pobranie interfejsu wiersza polecenia dewelopera Microsoft Store, jeśli nie został jeszcze pobrany. Dowiedz się więcej o interfejsie wiersza polecenia dewelopera Microsoft Store.

winapp store [args...]

argumenty:

args... — Argumenty przekazywane bezpośrednio do interfejsu msstore wiersza polecenia. Zobacz dokumentację interfejsu wiersza polecenia programu MSStore , aby uzyskać dostępne polecenia i opcje.

Co to robi:

Gwarantuje, że interfejs wiersza polecenia dewelopera Microsoft Store (msstore) jest pobierany i dostępny w systemie.
Przekazuje wszystkie argumenty do interfejsu msstore wiersza polecenia.
Uruchamia polecenie z danymi wyjściowymi bezpośrednio w terminalu.

Przykłady:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

get-winapp-path

Pobierz ścieżki do zainstalowanych składników zestawu Windows SDK.

winapp get-winapp-path [options]

Co zwraca:

Ścieżki do .winapp katalogu obszaru roboczego
Katalogi instalacji pakietów
Wygenerowane lokalizacje nagłówków

miejsce docelowe

Uruchom polecenia, skopiuj pliki, sprawdź stan lub przechwyć cały pulpit gościa.

Każde zlecenie przyjmuje sandbox jako pierwszy argument. Z wyjątkiem poleceń snapshotmożna przygotować lub uruchomić piaskownicę. Zobacz Windows Wykonywanie piaskownicy, aby zapoznać się z wymaganiami wstępnymi, uprawnieniami, cyklem życia i odzyskiwaniem.

target exec

Uruchom polecenie jako użytkownik-gość.

winapp target exec <target> [--cwd <path>] [--json] -- <executable> [arguments...]
winapp target exec sandbox -- dotnet --info

Argumenty po -- zachowaniu granic. Strumienie standardowe i kod zakończenia procesu gościa są przekazywane; nie jest to pełny terminal. --json formatuje błędy winapp na stderr bez zmiany stdout polecenia podrzędnego. Użyj struktury error.code , aby odróżnić błąd docelowy od własnego stanu zakończenia aplikacji.

Jawne WINAPP_UI_WORKFLOW_ID grupuje również wywołania interfejsu użytkownika gościa wykonywane przez polecenie. Zobacz Koordynacja interfejsu użytkownika piaskownicy.

ciąg wypychania docelowego i ściągnięcia docelowego

Skopiuj plik lub katalog w kierunku nazwanym przez czasownik.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

Ścieżki docelowe są względne względem zarządzanego obszaru roboczego obiektu docelowego; ścieżki bezwzględne, rooted i UNC są odrzucane. Miejsce docelowe pliku zawiera jego nazwę pliku. Zobacz Uruchamianie poleceń i kopiowanie plików dla układu katalogu, obsługi linków i uruchamiania skopiowanego skryptu.

migawka docelowa

Gotowość raportu, wdrożenia i okna gościa bez uruchamiania piaskownicy.

winapp target snapshot <target> [--json]
winapp target snapshot sandbox

Nie łączy ponownie klienta ani nie naprawia agenta. Brak uruchomionej piaskownicy jest wynikiem pomyślnym, a nie błędem. Zobacz Inspekcja piaskownicy, aby interpretować gotowość i identyfikatory procesów.

docelowy zrzut ekranu

Przechwyć pulpit gościa w natywnym rozmiarze pikseli jako host PNG bez selektora aplikacji lub obramowania okien hosta. --json raportuje źródło współrzędnych gościa.

winapp target screenshot <target> [-o <host-path>] [--json]
winapp target screenshot sandbox -o .\sandbox.png

Zamiast tego użyj ui screenshot --on sandbox -a <app> polecenia dla okna aplikacji. Zobacz Zrzuty ekranu i nagrania , aby zapoznać się z wymaganiami klienta, ograniczeniami fokusu i obsługą danych wyjściowych.

rekord docelowy

Zarejestruj pulpit gościa w formacie H.264 MP4. Hostowanie plików wideo i ramek przybywa po zakończeniu nagrywania; Kod JSON i manifest ramki opisują dowolne skalowanie lub dopełnienie.

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

Używa opcji ui recordczasu trwania, ramki, zastąpienia i wyniku elementu , ale przechwytuje pulpit, a nie jedną aplikację. Preferuj dodatnie --duration-sec użycie nienadzorowanego interfejsu wiersza polecenia; pomocnik npm wymaga elementu durationSec. Zobacz Przechwytywanie piaskownicy , aby uzyskać częściowe dowody i niepowodzenia gotowości do przechwytywania.

find-ui

Najpierw agent. find-ui jest tworzony głównie dla agentów kodowania sztucznej inteligencji — umożliwia agentowi ściąganie rzeczywistych, kompilowanie znaczników WinUI z galerii wysyłki zamiast ich tworzenia i --json sprawia, że każdy wynik (i każdy błąd) jest czytelny dla komputera. Działa tak dobrze, jak dobrze wpisany ręcznie.

Wyszukaj kontrolki WinUI i przykłady dla działającego przykładu kodu. Tylko winUI: corpus to Galeria WinUI 3 i Windows Community Toolkit (plus kilka wyselekcjonowanych wzorców rdzeni) — nie obejmuje WPF, WinForms lub innych struktur interfejsu użytkownika. Trzecie źródło, microsoft-ui-reactor ReactorGallery, jest opt-in: jest wykluczone z normalnego wyszukiwania i wyszukiwane tylko po przekazaniu --source reactor (jego próbki deklaratywne tylko w języku C#nie wklejają się do standardowej aplikacji XAML, więc skontaktuj się z nią tylko podczas tworzenia projektu Reactor/MVU).

winapp find-ui "<query>" [options]

Corpora Gallery, Toolkit i Reactor wewnątrz interfejsu wiersza polecenia działa więc find-ui bez dostępu do sieci — w tym w pierwszym uruchomieniu w piaskownicy agenta lub za firmowym serwerem proxy, który blokuje raw.githubusercontent.comprogram . Gdy GitHub jest osiągalny interfejs wiersza polecenia odświeża się z niego i buforuje wynik dla poszczególnych użytkowników w obszarze <global .winapp>/cache/find-ui; wbudowany korpus jest tylko podłogą, nigdy sufitem. Buforowane dane są odświeżane co najwyżej co 24 godziny lub na żądanie za pomocą polecenia --refresh.

Wbudowane elementy corpus są ponownie pobierane z GitHub za każdym razem, gdy skompilowana jest stabilna wersja, a odświeżanie, które kończy się niepowodzeniem, zatrzymuje kompilację wydania, a nie po cichu wysyłkę starszych danych — piekarze pobiera te same zastosowania ścieżki --refresh kodu, więc awaria oznacza, że odświeżanie na żywo również zostało przerwane i warto zbadać przed wysyłką. Wydanie może być nadal wycinane względem wcześniej zatwierdzonego korpusu, ale tylko jako jawne przesłonięcia. Gdy wyniki są obsługiwane z wbudowanej kopii corpora Gallery/Toolkit/Reactor, find-ui mówi tak na stderr i --json dane wyjściowe prowadzi "corpus": "embedded" (inne wartości: "network" dla nowego pobierania, "cache" dla lokalnej pamięci podręcznej). Żądanie tylko do rdzenia — --source corelub --id zestaw, który jest wszystkimi podstawowymi wzorcami — raportuje "embedded" również, ponieważ wyselekcjonowane wzorce rdzeni są kompilowane w interfejsie wiersza polecenia i nigdy nie są pobierane; nie wyświetla żadnych powiadomień o nieaktualności, ponieważ --refresh nie można ich zmienić. Pole corpus jest zgłaszane za każdym razem, gdy zostały obsłużone wyniki; jest nieobecne tylko wtedy, gdy w ogóle nie można załadować żadnego korpusu.

Opcje:

--id <id> - Pobierz kod (Galeria/Zestaw narzędzi zwraca XAML i/lub C#; Reactor to C#-only) oraz uwagi dotyczące wymagań wstępnych dla co najmniej jednego identyfikatora scenariusza z poprzedniego wyszukiwania (np. gallery-tabview-1). Powtarzalne. Identyfikatory są bez uwzględniania wielkości liter — GALLERY-TABVIEW-1 rozwiązuje to samo, co gallery-tabview-1.
--list — Wyświetl listę wszystkich wykrywalnych identyfikatorów kontroli/przykładów zamiast wyszukiwania (Galeria + Zestaw narzędzi + rdzeń; źródło reaktora jest wykluczone).
--source <gallery|toolkit|reactor|core> — Ogranicz wyniki wyszukiwania do jednego źródła. (Tylko wyszukiwanie — nieprawidłowe z --list/--id.) Reaktor jest opt-in — jest wykluczony z normalnego wyszukiwania, więc --source reactor jest jedynym sposobem wyszukiwania.
--max <N> - Maksymalna liczba dopasowanych kontrolek do zwrócenia (wartość domyślna: 3). Dotyczy tylko wyszukiwania; ignorowane za pomocą polecenia --list/--id.
--refresh— Pomiń lokalną pamięć podręczną i ponownie pobierz jednostki WinUI z GitHub.
--json - Emituj ustrukturyzowany kod JSON (przyjazny dla agenta). W przypadku wyszukiwania każde dopasowanie niesie ze sobą source, , controlscore, descriptioni tablicę, której wpisy przechowują scenarios poszczególne scenariusze i header; dla --id, id pełny kod. W przypadku --jsonkażdego błędu — w tym błędów argumentu/analizatora, takich jak --max liczba całkowita — jest emitowany jako obiekt płaski {"error": "..."} na stdout z kodem zakończenia bez zera, więc dane wyjściowe pozostają czytelne dla maszyny.

Przepływ pracy: wyszukiwanie kompaktowo w celu znalezienia odpowiedniej kontrolki i identyfikatorów scenariusza, a następnie pobierz pełny kod, aby uzyskać najlepsze dopasowanie do --idelementu .

Przykłady:

# Find a control by intent (compact results with scenario ids)
winapp find-ui "tabbed layout"

# Restrict to the Windows Community Toolkit
winapp find-ui "settings card" --source toolkit

# Restrict to Reactor (opt-in; C#-only declarative WinUI — Reactor projects only)
winapp find-ui "flex layout" --source reactor

# Fetch the full XAML + C# for a specific scenario
winapp find-ui --id gallery-tabview-1

# Agent-friendly structured output
winapp find-ui "color picker" --json

# Browse everything, or force a corpus refresh
winapp find-ui --list
winapp find-ui "navigation view" --refresh

Powiązane:find-ui wyszukuje przykłady winUI; Służy find-api do przeszukiwania powierzchni interfejsu API (typów, elementów członkowskich, wyliczenia) odwołań do projektu i winapp ui search wyszukiwania drzewa interfejsu użytkownika uruchomionej aplikacji .

find-api

Najpierw agent. find-api jest tworzony głównie dla agentów kodowania sztucznej inteligencji — jest on oparty na wygenerowanym kodzie w interfejsie API, w rzeczywistości odwołuje się do projektu zamiast wspomnieć o nim modelu, a --json także kodów zakończenia innych niż zero na brakujących symbolach, aby umożliwić generowanie kodu bramy agenta na odpowiedź. Działa tak dobrze, jak dobrze wpisany ręcznie.

Wyszukaj i sprawdź powierzchnię interfejsu API Windows/WinRT (typy, elementy członkowskie, wyliczenia, przestrzenie nazw) dostępne dla projektu, rozpoznane na podstawie odwołanych .winmd/.dll metadanych. Nagi formularz wyszukuje; podrzędne czasowniki przejdź do określonego typu, przestrzeni nazw lub samego indeksu.

winapp find-api "<query>" [options]
winapp find-api [command] [options]

Indeks jest tworzony na podstawie przywróconych pakietów NuGet/SDK projektu (za pośrednictwem project.assets.json) podczas pierwszego użycia i odświeżane automatycznie po przywróceniu projektu. Znajduje się on w globalnej .winapp pamięci podręcznej (cache/find-api/) i jest współużytkowany w projektach. Przywróć projekt najpierw (winapp restore lub dotnet restore).

Każde dopasowanie jest wyświetlane w swojej przestrzeni nazw z pakietem dostarczanym do niego i jednowierszowym podsumowaniem tego, co robi, więc wynik jest dostępny bez drugiego members wywołania:

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

Dodaj --verbose , aby również wydrukować plik pamięci podręcznej na dysku z kopią zapasową każdej przestrzeni nazw, co jest przydatne podczas diagnozowania nieaktualnego lub nieoczekiwanego indeksu.

Uruchomienie winapp find-api bez kwerendy powoduje wyświetlenie krótkiego podsumowania użycia i zakończenia 0 — jest to prośba o pomoc, a nie wyszukiwanie, które nie znalazło niczego.

Zakresów. Każda odpowiedź pochodzi z dokładnie jednego zakresu, zgłoszonego jako scope i --json jako notatki w danych wyjściowych tekstu:

project — projekt w bieżącym katalogu (lub --project / --project-dir). Obejmuje zestaw SDK Windows, Zestaw SDK do aplikacji systemu Windows i własne pakiety NuGet projektu. Metadane Zestaw SDK do aplikacji systemu Windows to wydanie, do którego odwołuje się projekt: jeśli maszyna ma zainstalowane nowsze środowisko uruchomieniowe aplikacja dla systemu Windows, ostrzega i pomija je zamiast potwierdzać, find-api że typy projektu nie mogą zostać skompilowane.
sdk— zestaw SDK Windows dla całej maszyny i metadane Zestaw SDK do aplikacji systemu Windows, używane automatycznie, gdy bieżący katalog nie zawiera żadnego projektu i nie ma rozwiązania. find-api Dzięki temu można eksplorować interfejsy API, zanim jakikolwiek projekt istnieje i nie potrzebuje dostępu do sieci. Celowo nie obejmuje pakietów NuGet innych firm, więc typ z (powiedzmy) zestawu narzędzi Community Toolkit nie zostanie znaleziony w tym zakresie.

Zapytanie z katalogu bez projektu i żadne rozwiązanie nie jest zawsze odpowiadane przez sdk zakres — nigdy w zależności od tego, który projekt ma być indeksowany w udostępnionej pamięci podręcznej , więc wyniki nigdy nie zależą od niepowiązanego stanu globalnego. Przekaż--project sdk, aby jawnie wybrać zakres zestawu SDK w projekcie i winapp find-api refresh --project sdk ponownie skompilować go po zainstalowaniu nowego zestawu SDK Windows.

Katalogi rozwiązań. Z katalogu zawierającego .sln/.slnx plik bez pliku projektu obok niego projekty kompilują odpowiedź zamiast sdk zakresu — są indeksowane na żądanie, więc są uwzględniane ich pakiety NuGet. Gdy rozwiązanie kompiluje więcej niż jeden indeksowany projekt, zapytanie wyświetla je i pyta --project <name> , a nie wybiera go.

Polecenia:

(gołe)find-api "<query>" ["<query>"...] — Typ wyszukiwania i nazwy elementów członkowskich, wracając do udokumentowanych podsumowań, pogrupowane według przestrzeni nazw
members <type> [<type>...] [--filter <text>] — Wyświetlanie listy właściwości, zdarzeń i metod typu (zadeklarowanych elementów członkowskich z podpisami, dziedziczonych składowych podsumowanych przez deklarowanie typu)
check-property <type> <property> [<property>...] — Sprawdź, czy właściwości istnieją w typie (kończy działanie inne niż zero, jeśli brakuje). Właściwość tylko do odczytu jest zgłaszana za pomocą ⚠polecenia ✔ i "tylko do odczytu, nie można jej przypisać" zamiast zwykłego ✅elementu , więc właściwość taka jak ActualWidth nie jest mylona z czymś, co można ustawić. W nazwach właściwości jest rozróżniana wielkość liter, ponieważ język C# i XAML to: check-property Button background kończy działanie inne niż zero i oferuje Background jako niemal zgodne, a nie zgłasza nazwy, której nie można faktycznie napisać.
enums <type> [<type>...] [--filter <text>] — Wyświetlanie listy wartości wyliczenia (kończy się od zera, gdy typ nie jest wyliczeniem)
packages — Wyświetlanie listy indeksowanych pakietów metadanych z liczbami poszczególnych typów pakietów/składowych
stats — Pokaż zagregowane statystyki indeksu (pakiety, przestrzenie nazw, typy, elementy członkowskie, .winmd pliki)
refresh [--scan] - Ponownie skompiluj indeks dla projektu (--scan indeksuje każdy projekt w katalogu). W przypadku --project <name>elementu nazwa zgodna z żadnym pojedynczym indeksowanym projektem kończy się niepowodzeniem zamiast indeksowania bieżącego katalogu.

Batching.search, members, enumsi check-property akceptuj wiele tematów w jednym wywołaniu. W przypadku agenta sztucznej inteligencji jest to jedna największa dźwignia kosztowa: marginalny koszt wyszukiwania jest zdominowany przez rundę (każde wywołanie ponownie wysyła całą konwersację), a nie przez rozmiar ładunku, więc jedna rozmowa odpowiadająca dziesięć pytań jest znacznie tańsza niż dziesięć wywołań.

Pojedynczy temat zwraca dokładnie kształt ładunku, który zawsze zawiera, zarówno w tekście, jak i --json.
Co najmniej dwa tematy zwracają kopertę — { "count": N, "results": [ ... ] } w elemecie --jsonkażdy element jest normalnym ładunkiem pojedynczego tematu; check-property dodaje element missingCount. Dane wyjściowe tekstu renderuje każdy temat w sekwencji w jednym nagłówku zakresu.
check-property batches właściwości na jednym typie: pierwszy argument jest typem, każdy argument po nim jest właściwością. W trybie wsadowym właściwość, która istnieje, drukuje pojedynczy ✅ wiersz. Pełne szczegóły niemal pominięte są drukowane tylko dla tych, które nie.
Partia kończy działanie 0 tylko wtedy, gdy każdy temat został rozwiązany i został znaleziony — więc partia jest nadal bezpieczna dla modułu codegen bramy.

Ranking wyszukiwania. Zapytanie, które dokładnie pasuje do nazwy typu, jest klasyfikowane przed częściowymi dopasowaniami, a gdy krótka nazwa jest współużytkowana przez kilka przestrzeni nazw, są wyświetlane tylko jako niejednoznaczne — zapytanie, takie jak NavigationView raportuje kilka przestrzeni nazw, które definiują ten dokładny typ, a nie każdą przestrzeń nazw zawierającą podobnie nazwany symbol. Lista niejednoznaczności przestrzega --max, a normalne wyniki są nadal drukowane pod nim.

Nazwy typów,members, check-propertyi enums akceptują krótką nazwę (NavigationView) lub w pełni kwalifikowaną (Microsoft.UI.Xaml.Controls.NavigationView). Gdy krótka nazwa jest udostępniana przez nowoczesny Microsoft.* typ i starszą Windows.* reprezentację platformy UWP, Microsoft.* odpowiedzi typu — czyli projekcja używana przez aplikację Zestaw SDK do aplikacji systemu Windows — i rozpoznawana w pełni kwalifikowana nazwa jest zawsze wyświetlana. Każda inna kolizja kończy się bez zera i wymienia kandydatów zamiast zgadywać.

Podpisy metod. Podpis jest drukowany w sposób, w jaki należy napisać wywołanie: metoda wywoływana dla typu, a nie w wystąpieniu, jest wyświetlana za pomocą staticelementu , a parametr by-reference jest wyświetlany ze słowem kluczowym, którego faktycznie potrzebuje — out, lub inref. Odczytuje Boolean TryGetValue(String key, out String value)więc TryGetValue wartość , która kompiluje się jako zapisana.

Opcje:

--max <n> — Maksymalna liczba wyników wyszukiwania pogrupowanych w przestrzeni nazw (wartość domyślna 5; tylko wyszukiwanie). Ponadto limituje listę niejednoznaczności, więc krótkie zapytanie, które koliduje między wieloma przestrzeniami nazw, pozostaje czytelne.
--filter <text> - Zawęź listę na members i enums: dopasowanie podciągów bez uwzględniania wielkości liter w nazwie elementu członkowskiego/wartości. Najlepiej używać w typach z setkami elementów członkowskich. Większość wyliczeniowych jest wystarczająco mała, aby zrzucić całość (nawet Symbol, największa w przypadku winui na 197 wartości), więc filtrowanie ich zwykle kosztuje więcej niż oszczędza, gdy uwzględnisz drugie odgadnięcie. Nigdy nie uruchom ponownie tego samego polecenia z innym tekstem filtru — zrzuć go raz i odczytać.
--all - Na membersliście na liście kompletnej powierzchni: pełne podpisy dla dziedziczonych elementów członkowskich oraz statyczne identyfikatory właściwości zależności i opisy poszczególnych składowych, z których wszystkie niefiltrowane listy pomijają (zobacz Rozmiar listy poniżej). --verboseimplikuje; użyj polecenia , jeśli chcesz --jsonrównież użyć polecenia --all , którego nie można połączyć z parametrem --verbose.
--scan - Rekursywnie odnajdywanie i indeksowanie każdego projektu w katalogu (refresh tylko)
--project <name>— Project do wykonywania zapytań (pasuje .csproj/.vcxproj do nazwy) lub sdk wykonywania zapytań dotyczących zakresu zestawu SDK Windows dla całej maszyny
--project-dir <path>- Project katalogu do zapytania (domyślnie do bieżącego katalogu). Ścieżka, która nie istnieje, jest błędem — nigdy nie odpowiada w trybie dyskretnym sdk z zakresu.
--json - Emituj ładunek czytelny dla maszyny w stdout (obsługiwany przez każde zlecenie). Ładunki zapytań identyfikują indeks, na który udzielono odpowiedzi za pośrednictwem scope (project lub sdk), projectNamei projectDir (nieobecne w zakresie zestawu SDK) — nazwy projektów nie są unikatowe w katalogach, więc projectDir jest to niezawodna tożsamość. W przypadku --jsonkażdego błędu — w tym błędów argumentu/analizatora, takich jak --max liczba całkowita — jest emitowany jako obiekt płaski {"error": "..."} na stdout z kodem zakończenia bez zera, więc dane wyjściowe pozostają czytelne dla maszyny.

Przykłady:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

Po --filter zastosowaniu dane wyjściowe nadal zgłasza niefiltrowaną sumę (totalValueslubtotalEvents//totalPropertiestotalMethods w ), --jsonwięc wąski widok nigdy nie jest mylony z małym interfejsem API. Filtr, który nie pasuje do niczego, nadal kończy działanie 0 i mówi tak jawnie — to "nic nie pasuje do filtru", a nie "nie ma takiego typu".

Rozmiar listy. Niefiltrowana members lista to jeden kosztowny kształt — members Button obejmuje 288 elementów członkowskich, z których 280 jest dziedziczonych z 6 typów bazowych. Niefiltrowane wywołanie jest zapytaniem orientacji ("co to jest ten typ, w przybliżeniu co może zrobić?), więc odpowiada na to i pomija części, z których nic nie zostało napisane:

Dziedziczone podpisy składowe — dziedziczone elementy członkowskie są grupowane przez deklarowanie typu i wyświetlane tylko według nazwy, więc kształt dziedziczonej powierzchni jest nadal widoczny bez 280 pełnych podpisów.
Statyczne identyfikatory właściwości zależności (BackgroundProperty) — 28% typowych właściwości kontrolki WinUI. Istnieją, aby zostały przekazane do GetValue/SetValueelementu , które nie zostały przypisane.
Opisy poszczególnych składowych — prozy XML-doc, około 16% ładunku.
Pola implikowane przez otoczenie w obiekcie --json: kind (implikowane przez tablicę zawierającą/eventspropertiesmethods/), returnType (wiodący token signature) iinherited, gdy wartość false (implikowane przez ).declaringType

Pominięto to, co zostało pominięte, jest zawsze zgłaszane (hiddenDependencyProperties, descriptionsOmitted, i hint in --json; wiersz "Pominięty:" w tekście) i sumy nadal opisują cały typ. Zarówno --filter , jak i --all zobaczyć pełną powierzchnię z pełnymi podpisami i opisami, więc members Button --filter BackgroundProperty nadal znajduje identyfikator i members Button --filter Click nadal zwraca Clickdziedziczony podpis. Mierzona w obiekcie samples/winui-appprzyjmuje members Button --json od 91 91 954 do 10 567 znaków (−88,5%) podczas opuszczania --filter i --all bajtów identycznych.

Dopasowanie zapytania. winapp find-api "language model" klasyfikuje powyżej dopasowania, których wyrazy LanguageModel są rozpraszane między przestrzeniami nazw i elementami członkowskimi, w tym poza projektem, gdy typ jest indeksowany. Wyszukiwanie jest leksykalne, a nie semantyczne: pasuje do całych wyrazów identyfikatora, a nie dowolnego uruchomienia liter, więc llm znajduje IImageLLMAdapterSession się, ale nie ScrollMode. Gdy zapytanie nie pasuje do żadnej nazwy, jest sprawdzane względem udokumentowanych podsumowań typów i elementów członkowskich, co pozwala "random-access stream" znaleźć IRandomAccessStreamelement . Opisy klasyfikują poniżej każdego dopasowania nazwy, a tylko podsumowania, które faktycznie wysyłają pakiety, można przeszukiwać — pakiet bez dokumentacji XML nie przyczynia się do żadnego tekstu opisu.

Projekty bez pliku projektu MSBuild. Aplikacja Electron (lub dowolna inna aplikacja inna niż .NET sterowana przez winapp.yamlprogram ) nie .csproj ma i dlatego nie ma project.assets.json. find-api indeksuje go z .winapp/winmds.lock.json zapisu winapp restore , który rejestruje to samo: każdy rozpoznany pakiet, jego wersję i .winmd pliki, które współtworzy. Taki projekt ma nazwę po katalogu, a jego indeks jest nieaktualny po ponownym zapisaniu pliku lockfile. Katalog zawierający element .csproj i winapp.yaml jest indeksowany z .csprojobiektu , który jest bardziej dokładnym opisem kompilacji projektu.

Odpowiedzi negatywne są kwalifikowane, gdy indeks jest niekompletny. Jeśli nie można odczytać metadanych pakietu, "nie ma takiego typu" i "ten pakiet nigdy nie został indeksowany" wygląda identycznie — i działa na pierwszym, gdy jest to naprawdę drugi generuje kod względem interfejsu API, który został poinformowany, nie istnieje. Więc każda negatywna odpowiedź, w tym search , która zwraca zero wyników, niesie ze sobą uwagę, że indeks jest częściowy i wskazuje na winapp find-api refreshwartość . Nie ma to wpływu na pozytywne odpowiedzi.

Nazwy typów ogólnych. Metadane przechowują typy ogólne z sufiksem arity (IAsyncOperation`1), który nie jest sposobem ich zapisu. members, enumsi check-property zaakceptuj każdy formularz: IAsyncOperation, IAsyncOperation<StorageFile>i IAsyncOperation`1 wszystkie rozpoznawane jako ten sam typ. Nazwa nagie jest zgodna z dowolną arity; określona wartość arity (w obu notacjach) musi być zgodna, więc Holder<A, B> nie zostanie rozpoznana jako pojedynczy parametr Holder<T>.

--json ładunki pomijają diagnostykę. Ścieżki plików pamięci podręcznej są wyświetlane tylko w obszarze --verbose (pasujące dane wyjściowe tekstu, w których były już pełne), a puste tablice sugestii są pomijane, a nie serializowane jako [].

Kody zakończenia:search bez trafień, check-property na brakującej właściwości i enums na typie innej niż wyliczeniowa wszystkie zakończ bez zera — generowanie kodu bramy i sprawdzanie ciągłej integracji na nich. Wywołanie wsadowe kończy się bez zera, jeśli którykolwiek temat zakończy się niepowodzeniem. Właściwość tylko do odczytu nie jest błędem — istnieje, więc check-property kończy działanie i flaguje 0 ją w danych wyjściowych (writable: false w --jsonpliku ). Raport init właściwości writable: false z tego samego powodu: można go ustawić w inicjatorze obiektu, a jego podpis mówi { get; init; }, ale przypisywanie go później nie kompiluje.

Powiązane:find-api odpowiedzi "czy ten interfejs API istnieje i jakie są jego elementy członkowskie?"; użyj find-ui polecenia , aby znaleźć działający przykład WinUI dla kontrolki.

node generate-bindings (powiązania generowania węzłów)

(Dostępne tylko w pakiecie NPM) Generowanie powiązań JS dla interfejsów API Zestaw SDK do aplikacji systemu Windows. Powiązania są deklarowane przez "winapp": { "jsBindings": {...} } przestrzeń nazw w pliku package.json i zapisywane w pliku .winapp/bindings/.

npx winapp node generate-bindings [options]

Opcje:

--verbose, -v — włączanie pełnych danych wyjściowych gen kodu dla pliku
--quiet, -q — pomijanie postępu i danych wyjściowych informacyjnych

Co to robi:

Odczytuje winapp.jsBindings blok z package.json i winmds.lock.json zapisany przez ostatni winapp restoreelement , a następnie emituje wpisane .js + .d.ts powiązania do .winapp/bindings/
Nie modyfikuje package.json — jest to pasywny regenerujący. winapp.jsBindings Dodanie bloku i @microsoft/dynwinrt zależności środowiska uruchomieniowego odbywa się podczas winapp init włączania powiązań JS; to polecenie kończy się niepowodzeniem, jeśli blok jest nieobecny
Ostrzega (ale nie zapisuje), jeśli @microsoft/dynwinrt brakuje zależności — uruchom npm install polecenie po init dodaniu go

Uwaga / Notatka

Powiązania są tylko narzędziem npm — wymagają wywołania za pośrednictwem npx winapp ( @microsoft/winappcli pakietu npm); autonomiczny interfejs wiersza polecenia zestawu winget nie wyświetla ich. Uruchom winapp init interaktywnie i zrezygnuj z polecenia lub użyj winapp init . --use-defaults --add-js-bindingspolecenia , aby ponownie wygenerować powiązania. Jeśli edytujesz winapp.yamlpolecenie , uruchom polecenie npx winapp restore , aby odświeżyć Windows zależności przed ponownego wygenerowania.

Przykłady:

# Regenerate JS bindings in the current project
npx winapp node generate-bindings

# Regenerate after editing winapp.jsBindings, with verbose output
npx winapp node generate-bindings --verbose

Zapoznaj się z przewodnikiem powiązań JS , aby zapoznać się z przepływem pracy kompleksowego winapp.jsBindings i opcjami konfiguracji.

node utwórz-dodatek

(Dostępne tylko w pakiecie NPM) Generowanie natywnych szablonów dodatków języka C++ lub C# przy użyciu zestawu SDK Windows i integracji Zestaw SDK do aplikacji systemu Windows.

npx winapp node create-addon [options]

Opcje:

--name <name> - Nazwa dodatku (wartość domyślna: "nativeWindowsAddon")
--template - Wybierz typ dodatku. Opcje to cs lub cpp (wartość domyślna: cpp)
--verbose - Włączanie pełnych danych wyjściowych

Co to robi:

Tworzy katalog dodatku z plikami szablonów
Generuje plik binding.gyp i addon.cc przy użyciu przykładów zestawu SDK Windows
Instaluje wymagane zależności npm (nan, node-addon-api, node-gyp)
Dodaje skrypt kompilacji do package.json

Przykłady:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

węzeł add-electron-debug-identity

(Dostępne tylko w pakiecie NPM) Dodaj tożsamość aplikacji do procesu opracowywania elektronów przy użyciu rozrzedliwego pakowania. Wymaga pliku Package.appxmanifest (utwórz go z elementem winapp init lub winapp manifest generate jeśli go nie masz).

Ważna

Istnieje znany problem z rozrzednymi aplikacjami Electron, co powoduje awarię aplikacji podczas uruchamiania lub nie renderowania zawartości internetowej. Problem został rozwiązany w Windows, ale nie został jeszcze rozpropagowany na urządzeniach Windows zewnętrznych. Jeśli ten problem występuje po wywołaniu add-electron-debug-identitymetody , możesz wyłączyć piaskownicę w aplikacji Electron na potrzeby debugowania z flagą --no-sandbox . Ten problem nie ma wpływu na pełne pakowanie MSIX.

Aby cofnąć identyfikator debugowania Electron, użyj polecenia winapp node clear-electron-debug-identity.

npx winapp node add-electron-debug-identity [options]

Opcje:

Option	Opis
`--manifest <path>`	Ścieżka do niestandardowego pliku Package.appxmanifest (ustawienie domyślne: Package.appxmanifest w bieżącym katalogu)
`--no-install`	Nie instaluj ani nie modyfikuj zależności; skonfiguruj tylko tożsamość debugowania Electron.
`--keep-identity`	Zachowaj tożsamość manifestu as-is, bez dołączania `.debug` do nazwy pakietu i identyfikatora aplikacji
`--verbose`	Włączanie pełnych danych wyjściowych

Co to robi:

Rejestruje tożsamość debugowania dla procesu electron.exe
Umożliwia testowanie interfejsów API wymagających tożsamości w rozwoju elektronów
Używa istniejącego pliku Package.appxmanifest na potrzeby konfiguracji tożsamości

Przykłady:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

węzeł clear-electron-debug-identity

(Dostępne tylko w pakiecie NPM) Usuń tożsamość pakietu z procesu debugowania Elektron, przywracając oryginalne electron.exe z kopii zapasowej.

npx winapp node clear-electron-debug-identity [options]

Opcje:

Option	Opis
`--verbose`	Włączanie pełnych danych wyjściowych

Co to robi:

Przywraca electron.exe z kopii zapasowej utworzonej przez program add-electron-debug-identity
Usuwa pliki kopii zapasowej po przywróceniu
Zwraca elektron do pierwotnego stanu bez tożsamości pakietu

Przykłady:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

Opcje globalne

Wszystkie polecenia obsługują następujące opcje globalne:

--verbose, -v — Włączanie pełnych danych wyjściowych na potrzeby szczegółowego rejestrowania
--quiet, -q — Pomijanie komunikatów o postępie
--help, -h — Pokaż pomoc polecenia

Katalog globalnej pamięci podręcznej

Aplikacja Winapp tworzy katalog do buforowania plików, które mogą być współużytkowane przez wiele projektów.

Domyślnie aplikacja winapp tworzy katalog jako $UserProfile/.winapp katalog globalnej pamięci podręcznej.

Aby użyć innej lokalizacji, ustaw zmienną WINAPP_CLI_CACHE_DIRECTORY środowiskową.

W cmd:

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

W programie PowerShell i programie pwsh:

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

Aplikacja Winapp tworzy ten katalog, gdy polecenie najpierw go potrzebuje.

Gdy aplikacja winapp nie może zapisać w katalogu globalnej pamięci podręcznej

Niektóre środowiska, takie jak piaskownice agentów, które zezwalają tylko na zapisy w bieżącym projekcie, blokują dostęp do %USERPROFILE%\.winappelementu . Większość poleceń nadal tam działa, a sprawdzanie aktualizacji jest pomijane. Jeśli aplikacja winapp nie ukończyła pierwszego uruchomienia w tym katalogu, każde uruchomienie wyświetla również jednowierszowe powiadomienie telemetryczne do narzędzia stderr.

Te polecenia muszą zapisywać w katalogu pamięci podręcznej i zatrzymywać się z powodu błędu, który nazywa ścieżkę:

Command	Co pisze
`find-api`	Indeks interfejsu API, gdy trzeba go skompilować lub odświeżyć. Istniejący up-toindeks daty jest nadal odczytywany.
`store`	Interfejs wiersza polecenia dewelopera Microsoft Store po raz pierwszy jest zainstalowany.

Aby rozwiązać ten problem, ustaw WINAPP_CLI_CACHE_DIRECTORY na winapp folder może zapisywać dane (na przykład jeden wewnątrz projektu), a następnie ponów próbę.

winapp ui polecenia zachowują stan podejmowania obrotu w systemie %USERPROFILE%\.winapp\state\ui. Jeśli nie mogą uzyskać dostępu do niego, nadal działają, ale bez oczekiwania na inne winapp ui polecenia na tym samym pulpicie i wyświetl jedno ostrzeżenie (pominięte za pomocą --json polecenia lub --quiet). Unikaj uruchamiania innych winapp ui poleceń na tym pulpicie w tym samym czasie.

Windows polecenia piaskownicy zachowują stan .%USERPROFILE%\.winapp\state Jeśli ten folder nie jest zapisywalny, zatrzymają się sandbox_state_unavailable na zmiennej i nadają jej nazwę, aby ustawić.

Testy aktualizacji

Interfejs wiersza polecenia winapp okresowo sprawdza dostępność nowych wersji i wyświetla jednowierszowe powiadomienie, gdy aktualizacja jest dostępna. To sprawdzanie jest uruchamiane w tle i nie dodaje żadnych opóźnień do poleceń.

Testy aktualizacji są automatycznie wyłączone w środowiskach ciągłej integracji (GitHub Actions, Azure Pipelines itp.).

Aby ręcznie wyłączyć sprawdzanie aktualizacji, ustaw zmienną WINAPP_CLI_UPDATE_CHECK środowiskową na 0wartość .

W cmd:

set WINAPP_CLI_UPDATE_CHECK=0

W programie PowerShell i programie pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Aby uczynić to stałym:

[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')

Tożsamość przepływu pracy interfejsu użytkownika

winapp ui polecenia, które napędzają komputer fizyczny zawsze działają w trybie kooperacyjnie, więc dwa przepływy pracy działające jednocześnie nie mogą ukraść fokusu lub odrzucić menu siebie nawzajem. Ten arbitraż nie wymaga konfiguracji i nie można go wyłączyć.

Co jest opcjonalne, to ciągłość. Domyślnie każde polecenie jest samodzielnym jednym strzałem, który zwalnia pulpit natychmiast po zakończeniu. Aby zachować pulpit w kilku poleceniach, nadaj im wszystkie te same identyfikatory przepływu pracy:

$env:WINAPP_UI_WORKFLOW_ID = [guid]::NewGuid().ToString()

Użyj tej samej wartości dla współpracujących procesów (na przykład nagrania i kliknięć, które powinny przechwycić) i różnych wartości dla niezależnych przepływów pracy. Każde polecenie bez identyfikatora jest własnym przepływem pracy jednorazowego, nawet jeśli kilka jest uruchamianych z jednej powłoki, dlatego hosty, które uruchamiają nową powłokę na polecenie, muszą wstrzyknąć tę samą jawną wartość do każdej z nich. Wartość jest nieprzezroczysta, nigdy nie jest traktowana jako poświadczenie i jest utrwalana tylko w postaci skrótu SHA-256. Zobacz automatyzacja interfejsu użytkownika → Koordynowanie współbieżnych przepływów pracy interfejsu użytkownika.

Interfejsu użytkownika

Sprawdzanie i interakcja z uruchomionymi interfejsami użytkownika aplikacji Windows przy użyciu automatyzacja interfejsu użytkownika interfejsu użytkownika (UIA). Uruchom polecenie winapp ui --help dla podstawowego przepływu pracy. Zobacz Automatyzacja interfejsu użytkownika , aby zapoznać się z pełnym przewodnikiem.

winapp ui [command] [options]

Polecenia:

status - Nawiązywanie połączenia z aplikacją i wyświetlanie informacji
inspect - Wyświetlanie drzewa elementów
search - Znajdowanie elementów według selektora
get-property - Odczyt właściwości elementu
get-text / get-value - Odczytaj wartość/tekst z elementu (TextPattern, ValuePattern lub Name)
screenshot - Przechwyć okno/element jako PNG (wiele okien formularza jeden złożony PNG; zobacz zakres przechwytywania)
record- Rejestrowanie obszaru okna/elementu w wideo H.264 MP4 (Windows Graphics Capture + Media Foundation)
invoke - Aktywuj element (kliknij, przełącz, rozwiń); --action wybiera dokładną operację (zobacz wywołanie)
click - Kliknięcie elementu za pomocą symulacji myszy (w przypadku kontrolek, które nie obsługują wywołania)
hover - Przenieś wskaźnik myszy do elementu, aby wyzwolić etykietki narzędzi, wysuwane i stany aktywowania (domyślne zamieszkanie: 800 ms)
drag - Przeciągnij mysz z jednego punktu do innego, wybierając selektor elementów lub współrzędne ekranu x,y (zmień kolejność, rozmiar, suwaki, przeciąganie i upuszczanie)
touch- Wstrzykiwanie syntetycznych gestów dotykowych (naciśnięcie, dwukrotne naciśnięcie, długie naciśnięcie, przesunięcie, szczypnięcie, rozciągnięcie) na środku elementu lub współrzędnych ekranu x,y
pen - Wstrzykiwanie syntetycznych danych wejściowych pióra/rysika — naciśnięcia i pociągnięcia pisma odręcznego z konfigurowalnym ciśnieniem, przechylaniem i gumką
send-keys - Wysyłanie syntetycznych danych wejściowych klawiatury (nazwanych klawiszy, kombi, nieprzetworzonych vk=0xNN lub tekstu literału) do okna
set-value - Ustaw wartość na edytowalny element (tekst, liczba); powraca do elementu LegacyIAccessible put_accValue dla kontrolek edycji sformatowanej tylko dla funkcji TextPattern
focus - Przenieś fokus klawiatury
scroll-into-view - Przewijaj element widoczny
wait-for - Oczekiwanie na stan elementu
list-windows — Wyświetlanie listy wszystkich okien dla aplikacji
get-focused — Zgłaszanie aktualnie ukierunkowanego elementu
yield — Zwolnij zwrot interfejsu użytkownika bieżącego przepływu pracy; wymaga WINAPP_UI_WORKFLOW_ID

Opcje:

-a, --app <app> - Aplikacja docelowa (nazwa, tytuł lub PID)
-w, --window <hwnd> - Okno docelowe przez HWND (stabilne)
--on <target> - Uruchom dowolne ui zlecenie w ; sandboxnazwy, identyfikatory PID i uchwyty okien odwołują się do gościa. Dane wyjściowe są dostarczane do hosta. Zobacz Automatyzacja interfejsu użytkownika piaskownicy , aby uzyskać informacje na temat konfiguracji, koordynacji przepływu pracy i wymagań klienta.
--type, --root--class-name — zawęża selektor poleceń wymienionych w zapytaniach o określonym zakresie i wpisanych zapytaniach

Rekord interfejsu użytkownika

Zarejestruj okno lub region elementu w formacie H.264 MP4.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o evidence.mp4

Opcje rekordu:

--duration-sec <n> - Długość nagrywania w sekundach. 0 rekordy do ctrl+C (wartość domyślna 0).
--fps <n> - Ramki na sekundę do przechwycenia (wartość domyślna 15).
--max-edge <px> - Skalowanie w dół tak, aby najdłuższa krawędź wynosi co najwyżej tyle pikseli (0 = brak skalowania w dół).
--capture-screen - Przechwyć z ekranu tak nakładki/wyskakujące okienka są uwzględnione (może przechwytywać okludium okien).
-o, --output <path> - Ścieżka wyjściowa .mp4 (wartość domyślna to recording-<timestamp>-<guid>.mp4).
--overwrite - Zastąp istniejące dane wyjściowe nagrywania po zakończeniu nowego wykonania; istniejące dane wyjściowe są domyślnie odrzucane. Poprzednie pakiety ramek są zachowywane. Zobacz Rejestrowanie odzyskiwania danych wyjściowych.
--frames — Zapisz znaczniki czasu plików JPEGs, frames.ndjsoni manifest.json do <output-name>.frames. Obsługuje 1-30 klatek na sekundę i --max-edge 64-4096 (domyślnie 1280), z 1 ramką GiB cap.

W przypadku --jsonelementu wynik końcowy zawiera ścieżkę wyjściową, wymiary, kodek, tryb przechwytywania, cykle, przyczynę zatrzymania, opcjonalne frameArtifactsi ostrzeżenia.

Aby uzyskać pełną dokumentację, zobacz docs/ui-automation.md.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-10-08

Dokumentacja interfejsu wiersza polecenia i użycie

Wersja

Uzupełnianie powłoki

inicjacja

nowy

przywracać

aktualizacja

pack

Bezpośrednie pakowanie projektu

Pakiety tożsamości rozrzednia

Odnajdywanie składników WinRT

Pakiety z wieloma architekturami

create-debug-identity

osadzanie tożsamości

manifest

generowanie manifestu

Symbole zastępcze manifestu

manifest add-alias

manifest aktualizuj-zasoby

przebieg

tryb Project (projekty zestawu SDK .NET)

Projekty języka C++ (.vcxproj)

Tryb pojedynczego pliku (.NET aplikacje oparte na plikach)

Capabilities

Korzystanie z własnego manifestu

Uruchamianie za pomocą polecenia dotnet run

Wyrejestrować

cert

Generowanie certyfikatu

informacje o certyfikatach

Instalacja certyfikatu

znak

az-sign

create-external-catalog

narzędzie

przechowywać

get-winapp-path

miejsce docelowe

target exec

ciąg wypychania docelowego i ściągnięcia docelowego

migawka docelowa

docelowy zrzut ekranu

rekord docelowy

find-ui

find-api

node generate-bindings (powiązania generowania węzłów)

node utwórz-dodatek

węzeł add-electron-debug-identity

węzeł clear-electron-debug-identity

Opcje globalne

Katalog globalnej pamięci podręcznej

Gdy aplikacja winapp nie może zapisać w katalogu globalnej pamięci podręcznej

Testy aktualizacji

Tożsamość przepływu pracy interfejsu użytkownika

Interfejsu użytkownika

Rekord interfejsu użytkownika

Opinia

Dodatkowe zasoby

Uruchamianie za pomocą polecenia `dotnet run`