Dokumentacja interfejsu wiersza polecenia i użycie

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 (domyślnie: bieżący katalog)
--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

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

Automatyczne wykrywanie projektów .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)

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

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.

przywracać

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

winapp restore [options]

Opcje:

--config-dir <path> - Katalog zawierający winapp.yaml (wartość domyślna: bieżący katalog)

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 zainicjowanych przy użyciu winapp init nie ma winapp.yaml. Użyj polecenia dotnet restore , aby przywrócić pakiety NuGet.

Przykłady:

# Restore from winapp.yaml in current directory
winapp restore

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

winapp pack <input-folder> [options]

argumenty:

input-folder - Katalog zawierający pliki aplikacji do spakowania

Opcje:

--output <filename> - Nazwa pliku MSIX wyjściowego (wartość domyślna: <name>_<version>_<arch>.msix, powrót do <name>_<version>.msix, <name>_<arch>.msixlub <name>.msix gdy nie można określić wersji/archu)
--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
--install-cert - Instalowanie certyfikatu na maszynie
--publisher <name> — nazwa Publisher generowania certyfikatów
--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.

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

Odnajdywanie składników WinRT

Podczas tworzenia pakietów winapp pack automatycznie skanuje pakiety NuGet zdefiniowane w składnikach *.csprojwinapp.yaml 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

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

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 CN (wartość domyślna: CN=<current użytkownik>)
--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.

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.

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-folder> [options]

argumenty:

input-folder — Katalog zawierający aplikację do uruchomienia (wymagane)

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 dla luźnego pakietu układu (wartość domyślna: AppX wewnątrz katalogu folderów wejściowych)
--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. uap5:ExecutionAlias Wymaga elementu w manifeście (użyj polecenia winapp manifest add-alias , aby go dodać). Nie można połączyć z --no-launch. Nie można połączyć z --json.
--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. 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.
--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. 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. Drukuje identyfikator PID na stdout (lub w formacie JSON za pomocą polecenia --json). Nie można połączyć z --no-launch, , --with-alias--debug-outputlub --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.

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

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. 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`	`false`	Uruchamianie za pośrednictwem aliasu wykonywania zamiast aktywacji identyfikatora AUMID
`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.

<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 [options]

Opcje:

--manifest <path> — Ścieżka do pliku Package.appxmanifest (ustawienie domyślne: automatyczne wykrywanie z bieżącego katalogu)
--force — Pomiń sprawdzanie katalogu install-location i wyrejestrowywanie, nawet jeśli pakiet został zarejestrowany z innego drzewa projektu
--json - Formatuj dane wyjściowe jako dane JSON

Co to robi:

Odczytuje nazwę pakietu z manifestu
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 lokalizacja instalacji pakietu znajduje się w bieżącym drzewie katalogu (chyba że --force)
Wyrejestrowywanie pasujących pakietów

Przykłady:

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

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

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

# 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ębnianie informacji o wydawcy z pliku Package.appxmanifest
--publisher <name> — nazwa Publisher certyfikatu
--output <path> — Ścieżka pliku certyfikatu wyjściowego (obsługuje ścieżki bezwzględne i względne)
--password <password> - Hasło certyfikatu (domyślne: "hasło")
--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": "..."}).

informacje o certyfikatach

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

winapp cert info <cert-path> [options]

argumenty:

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

Opcje:

--password <password> - Hasło do pliku PFX (domyślnie: "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> [options]

argumenty:

file-path - Ścieżka do pakietu MSIX lub pliku wykonywalnego do podpisania

Opcje:

--cert <path> — Ścieżka do certyfikatu podpisywania
--cert-password <password> - Hasło certyfikatu (domyślne: "hasło")

Przykłady:

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

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

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

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

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 automatycznie utworzy ten katalog po uruchomieniu poleceń takich jak init lub restore.

Interfejsu użytkownika

Sprawdzanie i interakcja z uruchomionymi interfejsami użytkownika aplikacji Windows przy użyciu automatyzacja interfejsu użytkownika interfejsu użytkownika (UIA).

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 (automatycznie przechwytuje okna dialogowe oddzielnie)
invoke - Aktywuj element (kliknij, przełącz, rozwiń)
click - Kliknięcie elementu za pomocą symulacji myszy (w przypadku kontrolek, które nie obsługują wywołania)
set-value - Ustaw wartość na edytowalny element (tekst, liczba)
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

Opcje:

-a, --app <app> - Aplikacja docelowa (nazwa, tytuł lub PID)
-w, --window <hwnd> - Okno docelowe przez HWND (stabilne)

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

Opinia

Czy ta strona była pomocna?

Last updated on 2026-05-12

Dokumentacja interfejsu wiersza polecenia i użycie

Uzupełnianie powłoki

inicjacja

przywracać

aktualizacja

pack

Odnajdywanie składników WinRT

create-debug-identity

manifest

generowanie manifestu

Symbole zastępcze manifestu

manifest add-alias

manifest aktualizuj-zasoby

przebieg

Wyrejestrować

cert

Generowanie certyfikatu

informacje o certyfikatach

Instalacja certyfikatu

znak

create-external-catalog

narzędzie

przechowywać

get-winapp-path

node utwórz-dodatek

węzeł add-electron-debug-identity

węzeł clear-electron-debug-identity

Opcje globalne

Katalog globalnej pamięci podręcznej

Interfejsu użytkownika

Opinia

Dodatkowe zasoby