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

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)

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 — Co najmniej jeden katalog zawierający pliki aplikacji do spakowania. Przekaż wiele folderów (np. ./publish/x64 ./publish/arm64) w celu utworzenia pakietu MSIX.

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

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

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 :

  1. Jeśli --executable zostanie podana (ścieżka względem folderu wejściowego), symbol zastępczy zostanie zastąpiony określoną wartością
  2. 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
  3. 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 .msix dla .msixbundle 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:

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

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

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

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 dowolną prawidłową wartość DN X.500; nazwy bez pasych 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:

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. 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.
  • --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. Drukuje identyfikator PID na stdout (lub w formacie JSON za pomocą polecenia --json). 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.

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>- Publisher dla certyfikatu. 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>
  • --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:

  1. winapp manifest generate --template sparse — Tworzenie rozrzednego manifestu za pomocą polecenia AllowExternalContent
  2. winapp create-external-catalog ./bin — Generowanie katalogu integralności kodu dla plików wykonywalnych aplikacji
  3. 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:

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

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

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)
  • record- Rejestrowanie obszaru okna/elementu w wideo H.264 MP4 (Windows Graphics Capture + Media Foundation)
  • 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)
  • 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

Opcje:

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

Rekord interfejsu użytkownika

Zarejestruj okno docelowe — lub region pojedynczego elementu — do wideo H.264 MP4. Ramki są przechwytywane za pośrednictwem funkcji przechwytywania grafiki Windows (z rezerwowym elementem PrintWindow) i kodowane przyrostowo za pomocą programu Media Foundation, więc długie nagrania nigdy nie buforują się w pamięci.

# 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

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

Za pomocą --jsonpolecenia emituje kopertęUiRecordResult, w tym dane wyjściowe path, , frames, heightwidth, fileSize, codec ("h264") i mode — ścieżkę przechwytywania faktycznie użytą (wgc, printwindowlub screen).

Znane ograniczenie: rejestrowanie określonego elementu w wyskakującym okienku renderującym we własnym oknie najwyższego poziomu (wysuwane WinUI/XAML, porada dydaktyczna, etykietka narzędzia) może przechwytywać bazowe okno główne. Zarejestruj całe okno lub użyj ui screenshot --capture-screen polecenia w celu wyświetlania wyskakujących okienek. Śledzone w 646.

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

  • Last updated on