CLI Belgeleri ve Kullanımı

Kabuk Tamamlama

Komutlar, seçenekler ve değerler için sekme tamamlamayı etkinleştirin. Kurulum yönergeleri için Kabuk Tamamlama kılavuzuna bakın.

# 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

başlat

Windows SDK'sı, Windows Uygulama SDK'sı ve modern Windows geliştirmesi için gerekli varlıklarla bir dizin başlatın.

winapp init [base-directory] [options]

Argümanlar:

base-directory - Uygulama/çalışma alanı için temel/kök dizin (varsayılan: geçerli dizin)

Seçenekler:

--config-dir <path> - Okuma/depolama yapılandırması dizini (varsayılan: geçerli dizin)
--setup-sdks - SDK yükleme modu: 'kararlı' (varsayılan), 'önizleme', 'deneysel' veya 'yok' (SDK yüklemesini atla)
--ignore-config, --no-config - Sürüm yönetimi için yapılandırma dosyasını kullanmayın
--no-gitignore - .gitignore dosyasını güncelleştirme
--use-defaults, --no-prompt - İstemi kullanmayın ve tüm istemlerin varsayılanını kullanın
--config-only - Yalnızca yapılandırma dosyası işlemlerini işleyin, paket yüklemesini atlayın
--add-js-bindings (yalnızca npm) - package.json ekleyin winapp.jsBindings ve sormadan JS/TypeScript bağlamaları oluşturun (ile --setup-sdks noneuyumsuz)

Ne yapar:

Yapılandırma dosyası oluşturur winapp.yaml (yalnızca SDK paketleri yönetildiğinde; ile --setup-sdks noneatlandığında)
Windows SDK'sı ve Windows Uygulama SDK'sı paketlerini indirir
C++/WinRT üst bilgileri ve ikili dosyaları oluşturur
Package.appxmanifest oluşturur
Derleme araçlarını ayarlar ve geliştirici modunu etkinleştirir
Oluşturulan dosyaları dışlamak için .gitignore güncelleştirmeleri
Paylaşılabilir dosyaları genel önbellek dizininde depolar
Etkinleştirildiğinde Windows Uygulama SDK'sı API'leri için JS bağlamaları oluşturur (yalnızca npm)

Otomatik proje algılama:

Dizin bağımsız değişkeni olmadan çalıştırıldığında init , uyumlu projeleri bulmak için geçerli dizin ağacının ilk genişliğine sahip bir arama yapar (en fazla 10). Desteklenen proje türleri:

Tauri — tauri.conf.json dizinin altında bir düzey bulundu
Electron — package.json bağımlılıklar veya devDependencies ile electron
Flutter — pubspec.yaml proje kökünde
.NET — .csproj proje kökünde
Rust — Cargo.toml proje kökünde
C++ — CMakeLists.txt proje kökünde

Arama yaygın olarak yoksayılan dizinleri (node_modules, bölme, obj, .git vb.) atlar. Uyumlu bir proje bulunduğunda, altındaki alt dizinlerde arama yapılmaz.

Bir dizin bağımsız değişkeni sağlanmışsa (ör. winapp init . veya winapp init path/to/project), arama atlanır ve init uyumlu bir proje için yalnızca bu dizini denetler
(veya --no-prompt) bir dizin bağımsız değişkeni olmadan ayarlanırsa --use-defaults , init aramayı atlar ve geçerli dizini etkileşimli olmayan bir şekilde başlatır; burada bilinen bir proje türü algılanmadıysa önce uyarır (örn. winapp init --use-defaults)
Etkileşimli olmayan ortamlarda (kanallı stdin, CI, yeniden yönlendirilen giriş), init davranışı otomatik olarak kullanır --use-defaults ve bir uyarı yayar: Non-interactive environment detected. Using default values.
Geçerli dizin uyumlu bir projeyse, init hemen devam eder
Başka bir yerde tam olarak bir proje bulunursa, bunu onaylamanız istenir
Birden çok proje bulunursa, hangisini başlatabileceğinizi seçebilirsiniz; geçerli dizin her zaman geri dönüş seçeneği olarak kullanılabilir
Proje bulunamazsa uyarılırsınız ve yine de devam edip etmeyeceğiniz sorulur
Arama 10 proje sınırına ulaşırsa, bir uyarı dizin bağımsız değişkeni sağlamayı önerir

Otomatik .NET proje akışı:

Hedef dizinde bir .csproj dosyası bulunduğunda, init kolaylaştırılmış .NET özgü bir akış kullanır:

TargetFramework Windows uyumlu bir TFM'ye doğrular ve güncelleştirir (örneğin, net10.0-windows10.0.26100.0)
Microsoft.WindowsAppSDK ve Microsoft.Windows.SDK.BuildTools girdilerini NuGet PackageReference girdisi olarak doğrudan .csproj'a ekler.
Package.appxmanifest, varlıkları ve geliştirme sertifikası oluşturur
C++ projeksiyonları oluşturmazwinapp.yaml veya indirmez (NuGet paketleri için kullanın dotnet restore )

Örnekler:

# 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

İpucu: İlk kurulumdan sonra SDK'ları yükleme

SDK yüklemesini init çalıştırdıysanız --setup-sdks none (veya atladıysanız) ve daha sonra SDK'lara ihtiyacınız varsa:

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

Önizleme/deneysel SDK sürümleri için veya --setup-sdks preview kullanın--setup-sdks experimental.

eski haline döndürmek

Paketleri geri yükleyin ve mevcut winapp.yaml yapılandırmaya göre dosyaları yeniden oluşturun.

winapp restore [options]

Seçenekler:

--config-dir <path> - winapp.yaml içeren dizin (varsayılan: geçerli dizin)

Ne yapar:

Mevcut winapp.yaml yapılandırmayı okur
SDK paketlerini belirtilen sürümlere indirir/güncelleştirir
C++/WinRT üst bilgilerini ve ikili dosyalarını yeniden oluşturur
Paylaşılabilir dosyaları genel önbellek dizininde depolar

Uyarı

winapp init ile başlatılan .NET projeleri için winapp.yaml yoktur. Bunun yerine NuGet paketlerini geri yüklemek için kullanın dotnet restore .

Örnekler:

# Restore from winapp.yaml in current directory
winapp restore

güncelleştirmek

Paketleri en son sürümlerine güncelleştirin ve yapılandırma dosyasını güncelleştirin.

winapp update [options]

Seçenekler:

--setup-sdks <stable|preview|experimental|none> - SDK yükleme modu: stable (varsayılan), preview, experimentalveya none (SDK yüklemesini atla)

Ne yapar:

Geçerli dizindeki mevcut winapp.yaml yapılandırmayı okur
Tüm paketleri en son kullanılabilir sürümlerine güncelleştirir
winapp.yaml Dosyayı yeni sürüm numaralarıyla güncelleştirir
C++/WinRT üst bilgilerini ve ikili dosyalarını yeniden oluşturur

Örnekler:

# Update packages to latest versions
winapp update

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

pack

Hazırlanan uygulama dizinlerinden MSIX paketleri oluşturun. Hedef dizinde, geçerli dizinde bir bildirim dosyasının (Package.appxmanifest tercih edilir, appxmanifest.xml ayrıca desteklenir) mevcut olmasını veya seçeneğiyle geçirilmesini --manifest gerektirir. (bildirim oluşturmak için veya init komutunu çalıştırınmanifest generate)

Çok mimarili dağıtım için bir .msixbundle oluşturmak üzere birden çok giriş klasörü geçirin (aşağıdaki Çoklu mimari paketlerine bakın).

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

Argümanlar:

input-folder - Paketlendirecek uygulama dosyalarını içeren bir veya daha fazla dizin. BIR MSIX paketi oluşturmak için birden çok klasör (örn. ./publish/x64 ./publish/arm64) geçirin.

Seçenekler:

--output <filename> - Çıkış dosyası adı. Tek paketler için: <name>_<version>_<arch>.msix (, <name>_<arch>.msixveya <name>.msixöğesine <name>_<version>.msixgeri döner). Paketler için: <name>_<version>_<arch1>_<arch2>.msixbundle.
--name <name> - Paket adı (varsayılan: bildirimden)
--manifest <path> - Bildirim dosyasının yolu (Package.appxmanifest tercih edilen, appxmanifest.xml ayrıca desteklenir; varsayılan: otomatik algılama)
--cert <path> - İmzalama sertifikası yolu (otomatik imzalamayı etkinleştirir)
--cert-password <password> - Sertifika parolası (varsayılan: "parola")
--generate-cert - Yeni bir geliştirme sertifikası oluşturma
--install-cert - Makineye sertifika yükleme
--publisher <name>- Sertifika oluşturma için Publisher. Tam X.500 ayırt edici adını veya çıplak bir adı kabul eder (otomatik olarak olarak CN=<name>sarmalanır)
--self-contained - Paket Windows Uygulama SDK'sı çalışma zamanı
--skip-pri - PRI dosya oluşturmayı atlama
--executable <path> - Giriş klasörüne göre yürütülebilir dosyanın yolu (ayrıca --exe). Bildirimdeki $targetnametoken$ yer tutucularını çözümlemek için kullanılır.

Ne yapar:

Package.appxmanifest dosyalarını doğrular ve işler
Bildirimdeki belirteçleri $placeholder$ çözümler (aşağıdaki Bildirim yer tutucularına bakın)
Uygun çerçeve bağımlılıklarını sağlar
Yan yana bildirimleri kayıtlarla güncelleştirir
Bildirimde başvurulan görüntü olmayan dosyaları (appExtension manifest.json, yapılandırma dosyaları gibi) hazırlamada eksikse bildirim dizininden veya giriş klasöründen otomatik olarak bulur ve paketler
Üçüncü taraf WinRT bileşenlerini otomatik olarak bulur ve eyleme dönüştürebilir sınıflarını kaydeder (aşağıdaki WinRT bileşeni bulma bölümüne bakın)
Bağımsız WinAppSDK dağıtımını işler
Sertifika sağlandıysa paketi imzalar

WinRT bileşeni bulma

Paketleme sırasında, winapp pack üçüncü taraf WinRT bileşenlerinde (win2D gibi) veya winapp.yaml içinde *.csproj tanımlanan NuGet paketlerini otomatik olarak tarar. Dosyaları ayrıştırarak .winmd eyleme geçirilebilir sınıf adlarını ayıklar ve uygulama DLL'lerini bulur. Bulunan girdiler aşağıdaki gibi kaydedilir:

Çerçeveye bağımlı (varsayılan): Değiştirilebilir sınıflar <InProcessServer>Package.appxmanifest
Bağımsız (--self-contained): Çalıştırılabilir sınıflar yürütülebilir dosya içinde yan yana (SxS) bildirimlere eklenir

Paketleme sırasında yer tutucu çözünürlüğü:

Bildirim özniteliğinde $targetnametoken$ yer alırsaExecutable:

Sağlanırsa --executable (giriş klasörüne göre yol), yer tutucu belirtilen değerle değiştirilir
Aksi takdirde, winapp pack giriş klasörü kökünü dosyalar için .exe tarar; tam olarak bir tane bulunursa, otomatik olarak kullanılır
Sıfır veya birden çok .exe dosya bulunursa, belirtmenizi isteyen bir hata gösterilir --executable

Örnekler:

# 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

Çok mimarili paketler

Birden çok giriş klasörü geçirildiğinde, winapp pack mimari başına bir tane .msix içeren bir .msixbundle klasör oluşturur:

# 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

Komutu, birincil yürütülebilir dosyanın PE üst bilgisinden her klasörün mimarisini otomatik olarak algılar, dilimler (Kimlik, Yetenekler, Bağımlılıklar) arasında tutarlılığı doğrular ve bir <Name>_<Version>_<arch1>_<arch2>.msixbundleoluşturur.

Paketler için bildirim çözümlemesi:

Paketteki her dilimin bir bildirime ihtiyacı vardır. Komut bildirimleri şu sırayla çözümler:

--manifest <path> — Belirtilirse, bu tek bildirim tüm dilimler için kullanılır. ProcessorArchitecture, algılanan mimariyle eşleşecek şekilde dilim başına otomatik olarak güncelleştirilir.
Klasör başına bildirim — Her giriş klasörü bir Package.appxmanifest (veya appxmanifest.xml) içeriyorsa, dilim için bu klasörün bildirimi kullanılır.
Geçerli dizin geri dönüşü — Bir klasörün bildirimi yoksa, komut geçerli çalışma dizininde arar Package.appxmanifest ve bunu kullanır (mimari otomatik damgalı olarak).

Her durumda bildirim otomatik olarak güncelleştirilir: yer tutucular çözümlenir, bağımlılıklar eklenir ve ProcessorArchitecture algılanan mimariye zorla ayarlanır. Çözümden sonra, dilimler arası doğrulama, Kimlik (Ad, Sürüm, Publisher), Özellikler ve Bağımlılıklar'ın tüm dilimlerde tutarlı olmasını sağlar; yalnızca ProcessorArchitecture farklılık gösterebilir. Dilimlerde tanımlanan paket sürümü MSIX paket sürümüne atılır, ancak sürümü olması durumunda 0.0.0.0zaman damgası tabanlı bir sürüm otomatik olarak oluşturulur.

# 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

hata ayıklama kimliği oluştur

Seyrek paketleme kullanarak hata ayıklama için uygulama kimliği oluşturun. Exe özgün konumunda kalır; Windows kimliği Add-AppxPackage -ExternalLocation aracılığıyla ilişkilendirir.

Ne zaman kullanılır? winapp run: Exe create-debug-identity olduğunda (örneğin, içinde olduğu electron.exeElektron uygulamaları) veya seyrek paket davranışını özel olarak test ederken kullanınnode_modules. Exe dosyasının derleme çıkış klasörünüzde bulunduğu çoğu çerçeve için kullanın winapp run ; tam gevşek bir düzen paketi kaydeder ve uygulamayı başlatır. Tam karşılaştırma için Hata Ayıklama Kılavuzu'na bakın.

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

Argümanlar:

entrypoint - Kimlik gerektiren yürütülebilir dosya (.exe) veya betiğin yolu

Seçenekler:

--manifest <path> - Uygulama bildirim dosyasının yolu veya Package.appxmanifestappxmanifest.xml (varsayılan: otomatik algılama Package.appxmanifest veya appxmanifest.xml geçerli dizinde)
--no-install - Oluşturma işleminden sonra paketi yüklemeyin
--keep-identity - Paket adına ve uygulama kimliğine eklemeden .debug bildirim kimliğini as-istutun

Ne yapar:

Yürütülebilir dosyanın yan yana bildirimini değiştirir
Kimlik için hafif paketi kaydeder
Kimlik gerektiren API'lerde hata ayıklamayı etkinleştirir

Örnekler:

# 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

manifesto

Package.appxmanifest dosyalarını oluşturun ve yönetin.

bildirim oluşturma

Şablonlardan Package.appxmanifest oluşturun.

winapp manifest generate [directory] [options]

Argümanlar:

directory - Içinde bildirim oluşturulacak dizin (varsayılan: geçerli dizin)

Seçenekler:

--package-name <name> - Paket adı (varsayılan: klasör adı)
--publisher-name <name>- ayırt edici adı Publisher (varsayılan: CN=<geçerli kullanıcı>). Geçerli X.500 DN'leri kabul eder; çıplak adlar, CN=<name> olarak otomatik olarak sarmalanmıştır.
--version <version> - Sürüm (varsayılan: "1.0.0.0")
--description <text> - Açıklama (varsayılan: "Uygulamam")
--entrypoint <path> - Giriş noktası yürütülebilir dosyası veya betiği
--template <type> - Şablon türü: packaged (varsayılan) veya sparse
--logo-path <path> - Logo resim dosyasının yolu
--if-exists <Error|Overwrite|Skip> - Bildirim dosyası hedef yolda zaten mevcut olduğunda davranış (varsayılan: Error)

Şablon:

packaged - Standart paketlenmiş uygulama bildirimi
sparse - Seyrek/dış konum paketleme kullanan uygulama manifesti

Manifesto yer tutucuları

Paketleme zamanında otomatik olarak çözümlenen (dolar işareti ile sınırlandırılmış) $placeholder$ belirteçlerini kullanan oluşturulmuş bildirimler:

Yer tutucu	Çözümlenme:	Example
$targetnametoken$	Uzantısız yürütülebilir ad	`Executable="$targetnametoken$.exe"` → `Executable="MyApp.exe"`
$targetentrypoint$	`Windows.FullTrustApplication`	Her zaman otomatik olarak çözümlenir

Bu, Visual Studio proje şablonları tarafından kullanılan kuralın aynısını izler, bu nedenle bildirimler araçlar arasında taşınabilir.

Yer tutucular nasıl çözümlenir:

winapp pack — Paketleme sırasında, $targetnametoken$ seçeneği kullanılarak --executable veya giriş klasöründeki tekli .exe otomatik algılanarak çözümlenir. Birden çok (veya sıfır) .exe dosya bulunursa ve --executable belirtilmezse bir hata gösterilir.
winapp create-debug-identity — Bir giriş noktası bağımsız değişkeni sağlandığında, $targetnametoken$ bu bağımsız değişkenden çözümlenir. Giriş noktası olmadan yürütülebilir yer tutucu bildirimde zaten çözümlenmelidir.
winapp manifest generate --executable — Sağlandığında --executable , yürütülebilir dosyadan bildirim meta verileri (sürüm, açıklama) ve simgeler ayıklanır, ancak oluşturulan bildirim yine de kullanır $targetnametoken$.exe; bu yer tutucu daha sonra çözümlenir (örneğin winapp pack veya winapp create-debug-identity).

PS: İade edilmiş bildiriminizde $targetnametoken$ tutmak, yürütülebilir adların sabit olarak kodlanmasından kaçınır ve hem winapp pack hem de Visual Studio derlemeleriyle çalışır.

Örnekler:

# 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

bildirim ekleme diğer adı

Package.appxmanifest'e bir yürütme diğer adı (uap5:AppExecutionAlias) ekleyin. Bu, diğer adı yazarak paketlenmiş uygulamanın komut satırından başlatılmasına olanak tanır.

winapp manifest add-alias [options]

Seçenekler:

--name <alias> - Diğer ad (ör. myapp.exe). Varsayılan: bildirimdeki Executable özniteliğinden çıkarılır.
--manifest <path> - Package.appxmanifest yolu (varsayılan: geçerli dizini ara)
--app-id <id> - Diğer adın ekleneceği uygulama kimliği (varsayılan: ilk Uygulama öğesi)

Ne yapar:

Bildirimi okur ve diğer adı özniteliğinden Executable çıkarsar (gibi $targetnametoken$.exeyer tutucuları korur)
uap5 Henüz yoksa ad alanı bildirimini ekler
Hedef Application öğesinin içine ile <Extensions> bir <uap5:AppExecutionAlias> blok ekler
Diğer ad zaten varsa, bunu bildirir ve başarıyla çıkar

Örnekler:

# 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

manifesto varlıkları güncelle

Tüm gerekli MSIX görüntü varlıklarını tek bir kaynak görüntüden oluşturun.

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

Argümanlar:

image-path - Kaynak görüntü dosyasının yolu (PNG, JPG, SVG, ICO, GIF, BMP vb.)

Seçenekler:

--manifest <path> - Package.appxmanifest dosyasının yolu (varsayılan: geçerli dizinde ara)
--light-image <path> - Açık tema çeşitlemeleri için ayrı bir kaynak görüntünün yolu

Açıklama:

Tek bir kaynak görüntü alır ve bildirimin varlık başvurularını temel alan kapsamlı bir MSIX görüntü varlıkları kümesi oluşturur:

Bildirimde başvuruda bulunan her varlık için:

5 ölçek değişkeni — temel (sonek yok), .scale-125, .scale-150, .scale-200, , .scale-400

Uygulama simgesi için (Square44x44Logo / AppList, 44×44 tabanı):

14 kaplamalı targetsize varyantları — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
14 unplated targetsize variants — .targetsize-{size}_altform-unplated

Additionally:

app.ico — Kabuk tümleştirmesi için çok çözünürlüklü ICO dosyası (16, 24, 32, 48, 256). Var olan .ico bir dosya assets dizininde (örneğin AppIcon.ico , bir proje şablonundan) bulunursa, yineleme oluşturmak yerine yerinde değiştirilir

ile : --light-image

Açık tema, varyantları hedefleme — .targetsize-{size}_altform-lightunplated (uygulama simgesi)
Açık tema ölçek çeşitlemeleri — .scale-{factor}_altform-colorful_theme-light (kutucuklar, mağaza logosu)

SVG desteği: SVG dosyaları kaynak görüntü olarak tam olarak desteklenir. Bunlar her hedef boyutta doğrudan vektör olarak işlenir ve tüm çözünürlüklerde piksel mükemmel sonuçlar üretir.

Komut, görüntüleri orantılı olarak ölçeklendirir ve en boy oranını korur ve gerektiğinde saydam arka planlarla ortalar. Varlıklar, bildirim konumuna Assets göre dizine kaydedilir.

Örnekler:

# 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

run

Derleme çıktı klasöründen gevşek bir düzen paketi oluşturun, Windows.Management.Deployment.PackageManager API'sini kullanarak Windows kaydedin ve uygulamayı başlatın; hata ayıklama için tam MSIX yüklemesini benzetin. Hata ayıklayıcı eki için işlem kimliğini döndürür.

Bu, çoğu çerçevede (.NET, C++, Rust, Flutter, Tauri) paket kimliği ile hata ayıklama için tercih edilen komutdur. Tek bir exe için seyrek paket kaydedenlerden farklı create-debug-identity olarak, winapp run gerçek bir MSIX yüklemesi gibi klasörün tamamını gevşek bir düzen paketi olarak kaydeder. Yaygın hata ayıklama iş akışları için Hata Ayıklama Kılavuzu'na bakın.

winapp run <input-folder> [options]

Argümanlar:

input-folder - Çalıştırılacak uygulamayı içeren dizin (gerekli)

Seçenekler:

--manifest <path> - Package.appxmanifest yolu (varsayılan: giriş klasöründen veya geçerli dizinden otomatik algılama)
--output-appx-directory <path> - Gevşek düzen paketi için çıkış dizini (varsayılan: AppX giriş klasörü dizininin içinde)
--args <string> - Uygulamaya geçirmek için komut satırı bağımsız değişkenleri. Alternatif olarak, kaçıştan kaçınmak için bağımsız değişkenleri kullanın -- (örn. winapp run . -- --flag value).
--no-launch - Uygulamayı başlatmadan yalnızca hata ayıklama kimliğini oluşturun ve paketi kaydedin
--with-alias - AUMID etkinleştirmesi yerine yürütme diğer adını kullanarak uygulamayı başlatın. Uygulama geçerli terminalde devralınan stdin/stdout/stderr ile çalışır. Bildirimde bir uap5:ExecutionAlias gerektirir (eklemek için kullanın winapp manifest add-alias ). ile --no-launchbirleştirilemez. ile --jsonbirleştirilemez.
--debug-output - Başlatılan uygulamadan iletileri ve ilk şans özel durumlarını yakalayın OutputDebugString . Çerçeve gürültüsü (WinUI, COM, DirectX) konsol çıkışından filtrelenir; tüm günlük dosyası her şeyi yakalar. Uygulama kilitlenirse, otomatik olarak bir minidum yakalar ve özel durum türünü, iletiyi ve yığın izlemesini kaynak dosya:satır numaralarıyla gösterecek şekilde analiz eder (derleme çıktı klasöründeki PDB'lerden çözümlenir). Yönetilen (.NET) kilitlenmeler harici araçlar olmadan anında analiz edilir. Yerel (C++/WinRT) kilitlenmeleri modül adlarını ve uzaklıklarını gösterir. Kilitlenen uygulama bir WinUI 3 uygulamasıMicrosoft.UI.Xaml.dll (yüklenir) olduğunda, kaynak HRESULT, ErrorContext zinciri ve tam yerel XAML dağıtım yığınını ortaya çıkarması için ek bir özel durum önceliklendirme geçişi otomatik olarak çalıştırılır; gerekli hata ayıklayıcı bileşenleri ilk kullanımda indirilir (bkz. Hata ayıklama, ortam değişkeni aracılığıyla WINAPP_DBGTOOLS_DIR geçersiz kılınabilir). Aynı anda bir işleme yalnızca bir hata ayıklayıcısı eklenebilir, bu nedenle diğer hata ayıklayıcılar (Visual Studio, VS Code) aynı anda kullanılamaz. Bunun yerine, farklı bir hata ayıklayıcı eklemeniz gerekiyorsa kullanın --no-launch . ile --no-launchbirleştirilemez. ile --jsonbirleştirilemez.
--symbols - Çözümlenen işlev adlarıyla daha zengin yerel kilitlenme analizi için Microsoft Sembol Sunucusu'ndan PDB simgelerini indirin. Yalnızca ile --debug-outputkullanılır. Atlanırsa ve yerel kilitlenme oluşursa, çıkış bu bayrağın eklenmesini önerir. Bu bayrak, WinUI 3 uygulamaları için WinUI stowed-exception önceliklendirme yığınını da geliştirir. İlk çalıştırma simgeleri indirir ve yerel olarak önbelleğe alır; sonraki çalıştırmalarda önbellek kullanılır.
--unregister-on-exit - Uygulama çıktıktan sonra geliştirme paketinin kaydını kaldırın. Yalnızca geliştirme modunda kayıtlı paketleri kaldırır. ile --no-launchbirleştirilemez.
--detach - Uygulamayı başlatın ve çıkışını beklemeden hemen geri dönün. Başlatma sonrasında uygulamayla etkileşim kurmanız gereken CI/otomasyon için kullanışlıdır. PID'yi stdout'a (veya ile --jsonJSON'da) yazdırır. , , --no-launch--debug-outputveya --with-aliasile --unregister-on-exitbirleştirilemez.
--clean - Yeniden dağıtmadan önce mevcut paketin uygulama verilerini (LocalState, ayarlar vb.) kaldırın. Varsayılan olarak, uygulama verileri yeniden dağıtımlarda korunur.
--json - Programlı tüketim için çıkışı JSON olarak biçimlendirin (örn. CI/otomasyon). PID'yi yakalamak için ile --detach kullanışlıdır. veya --with-aliasile --debug-output birleştirilemez.

Uygulama verileri kalıcılığı:

Varsayılan olarak, winapp run yeniden dağıtım sırasında uygulamanızın verilerini (LocalState, RoamingState, Settingsvb.) korur. Uygulamanız paket bağlamı ApplicationData.Current.LocalFolder içinde veya Environment.GetFolderPath(SpecialFolder.LocalApplicationData) içine veri yazarsa, bu veriler çağrılar arasında winapp run kalır.

Yeni bir başlangıç yapmanız gerektiğinde kullanın --clean (örneğin, bozuk durumu sıfırlamak veya ilk çalıştırma davranışını test etmek için).

Ne yapar:

Package.appxmanifest dosyasını bulur veya oluşturur
Gevşek düzen paketi kullanarak hata ayıklama kimliği oluşturur ve kaydeder
Uygulama Kullanıcı Modeli Kimliğini (AUMID) hesaplar
Kayıtlı kimliği kullanarak uygulamayı başlatır (belirtilmediği sürece --no-launch )
Hata ayıklayıcı eki için işlem kimliğini (PID) yazdırır

Örnekler:

# 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

MSBuild özellikleri (NuGet paketi):

Microsoft.Windows.SDK.BuildTools.WinApp NuGet paketini kullanırken dotnet run otomatik olarak winapp run çağırır. Aşağıdaki MSBuild özellikleri, davranışı denetlemek için sizin içinde .csproj ayarlanabilir:

Mülkiyet	Varsayılan	Açıklama
`EnableWinAppRunSupport`	`true`	Çalıştırma desteği işlevselliğini etkinleştirme/devre dışı bırakma
`WinAppLaunchArgs`	(boş)	Başlatmada uygulamaya geçirecek bağımsız değişkenler
`WinAppRunUseExecutionAlias`	`false`	AUMID etkinleştirmesi yerine yürütme diğer adıyla başlatma
`WinAppRunNoLaunch`	`false`	Kimliği başlatmadan yalnızca kaydetme
`WinAppRunDebugOutput`	`false`	İletileri ve ilk şans özel durumlarını yakalayın `OutputDebugString` . Aynı anda yalnızca bir hata ayıklayıcısı eklenebilir (VS/VS Code'un engellenmesini önler). Bunun `WinAppRunNoLaunch` yerine farklı bir hata ayıklayıcı ekleyin.

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

kaydını kaldırma

Dışarıdan yüklenen geliştirme paketinin kaydını kaldırın. Yalnızca geliştirme modunda kayıtlı paketleri kaldırır (örneğin, veya winapp runaracılığıylacreate-debug-identity). Mağaza yüklü veya MSIX yüklü paketler hiçbir zaman kaldırılmaz.

winapp unregister [options]

Seçenekler:

--manifest <path> - Package.appxmanifest yolu (varsayılan: geçerli dizinden otomatik algılama)
--force - Yükleme konumu dizin denetimini atlayın ve paket farklı bir proje ağacından kaydedilmiş olsa bile kaydını kaldırın
--json - Çıktıyı JSON olarak biçimlendirme

Ne yapar:

Bildirimden paket adını okur
Hem {name} hem de {name}.debug paketleri arar (hata ayıklama değişkeni tarafından create-debug-identityoluşturulur)
Her paketin geliştirme modunda kayıtlı olduğunu doğrular (IsDevelopmentMode == true)
Paketin yükleme konumunun geçerli dizin ağacının altında olduğunu doğrular (sürece --force)
Eşleşen paketlerin kaydını kaldırma

Örnekler:

# 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

Geliştirme sertifikaları oluşturun, inceleyin ve yükleyin.

sertifika oluşturma

Paket imzalama için geliştirme sertifikaları oluşturun.

winapp cert generate [options]

Seçenekler:

--manifest <Package.appxmanifest> - Package.appxmanifest'ten yayımcı bilgilerini ayıklama
--publisher <name>- Sertifika için Publisher. Tam bir X.500 ayırt edici adı (ör. CN=Contoso, O=Contoso Ltd, C=US) veya otomatik olarak olarak sarmalanan çıplak bir adı kabul eder CN=<name>
--output <path> - Çıkış sertifikası dosya yolu (mutlak ve göreli yolları destekler)
--password <password> - Sertifika parolası (varsayılan: "parola")
--valid-days <valid-days> - Sertifikanın geçerli olduğu gün sayısı (varsayılan: 365)
--install - Sertifikayı oluşturma işleminden sonra yerel makine deposuna yükleyin
--if-exists <Error|Overwrite|Skip> - Sertifika dosyası zaten varsa davranışı ayarlayın (varsayılan: Hata)
--export-cer - Ile birlikte bir .cer dosyayı (yalnızca ortak anahtar) dışarı aktarın .pfx. Güven yüklemesi için ortak sertifikayı ayrı olarak dağıtmak için kullanışlıdır.
--json - Programlı tüketim için çıkışı JSON olarak biçimlendirin. Hatalar JSON ({"error": "..."} olarak da döndürülür.

sertifika bilgileri

PFX dosyasından sertifika ayrıntılarını görüntüleme. İmzalamadan önce bir sertifikanın bildiriminizle eşleştiğinden emin olmak için kullanışlıdır.

winapp cert info <cert-path> [options]

Argümanlar:

cert-path - Sertifika dosyasının yolu (PFX)

Seçenekler:

--password <password> - PFX dosyasının parolası (varsayılan: "parola")
--json - Çıktıyı JSON olarak biçimlendirme

sertifika yükleme

Sertifikayı makine sertifika deposuna yükleyin.

winapp cert install <cert-path> [options]

Argümanlar:

cert-path - Yüklenecek sertifika dosyasının yolu

Örnekler:

# 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

işaret

MSIX paketlerini ve yürütülebilir dosyaları sertifikalarla imzalayın.

winapp sign <file-path> [options]

Argümanlar:

file-path - İmzalayacak MSIX paketi veya yürütülebilir dosyası yolu

Seçenekler:

--cert <path> - İmzalama sertifikası yolu
--cert-password <password> - Sertifika parolası (varsayılan: "parola")

Örnekler:

# 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

Belirtilen dizinlerden yürütülebilir dosyaların karmalarını içeren bir CodeIntegrityExternal.cat katalog dosyası oluşturun. Bu katalog, paketin kendisine dahil olmayan dış dosyaların yürütülmesine izin vermek için MSIX seyrek paket bildirimlerinde (AllowExternalContent) TrustedLaunch bayrağıyla birlikte kullanılır.

Bu, MSIX paketini imzalarken oluşturma signtool.exe işlemine AppxMetadata\CodeIntegrity.cat benzer, ancak seyrek/dış konum paketlemesi ile kullanılmak üzere bir dış katalog oluşturur.

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

Argümanlar:

input-folder - İşlenmesi gereken yürütülebilir dosyaları içeren bir veya daha fazla dizin. Birden çok dizini noktalı virgülle ayırma (ör. "dir1;dir2")

Seçenekler:

--recursive, -r - Alt dizinlerden dosyaları dahil et
--use-page-hashes - Kataloğu oluştururken sayfa karmalarını ekleyin (sayfa başına karma verileriyle daha büyük bir katalog oluşturur)
--compute-flat-hashes - Kataloğu oluştururken düz dosya karmaları ekleme
--if-exists <Error|Overwrite|Skip> - Çıkış dosyası zaten mevcut olduğunda davranış (varsayılan: Error)
--output, -o - Çıktı kataloğu dosya yolu. Belirtilmezse, CodeIntegrityExternal.cat geçerli dizinde oluşturulur. Bir dizin belirtilirse, varsayılan dosya adı eklenir.

Ne yapar:

Yürütülebilir dosyalar için belirtilen dizinleri tarar (kod bölümleri içeren PE ikili dosyaları)
Bulunan tüm yürütülebilir dosyaları içeren bir Katalog Tanım Dosyası (CDF) oluşturur
.cat katalog dosyasını oluşturmak için Windows CryptoCAT API'lerini kullanır
Yürütülemeyen dosyalar (örneğin, .txt.dll kod bölümleri olmadan) otomatik olarak atlanır

Örnekler:

# 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

Ne zaman kullanılır:

Dış yürütülebilir dosyaları doğrulamak için TrustedLaunch kullanan seyrek bir MSIX paketi oluştururken bu komutu kullanın. Tipik iş akışı şu şekildedir:

winapp manifest generate --template sparse — ile seyrek bildirim oluşturma AllowExternalContent
winapp create-external-catalog ./bin — Uygulamanızın yürütülebilir dosyaları için kod bütünlüğü kataloğu oluşturma
winapp pack — Bildirimi, varlıkları ve kataloğu bir MSIX'te paketle

araç

Windows SDK araçlarına doğrudan erişin. Microsoft.Windows'da bulunan araçları kullanır. SDK. BuildTools

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

Kullanılabilir araçlar:

makeappx - Uygulama paketleri oluşturma ve işleme
signtool - Dosyaları imzalama ve imzaları doğrulama
mt - Yan yana derlemeler için manifest aracı
ayrıca Microsoft.Windows'dan diğer Windows SDK araçları. SDK. BuildTools

Örnekler:

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

store

Bir Microsoft Store Geliştirici CLI komutu çalıştırın. Bu komut, henüz indirilmemişse Microsoft Store Geliştirici CLI'sini indirir. Microsoft Store Developer CLI hakkında daha fazla bilgi edinin.

winapp store [args...]

Argümanlar:

args... – Doğrudan CLI'ya geçirmek için msstore bağımsız değişkenler. Kullanılabilir komutlar ve seçenekler için MSStore CLI belgelerine bakın.

Ne yapar:

Microsoft Store Geliştirici CLI'sinin (msstore) indirilmesini ve sisteminizde kullanılabilir olmasını sağlar.
Tüm bağımsız değişkenleri CLI'ya msstore iletir.
Çıkışı doğrudan terminalinizde gösteren komutu çalıştırır.

Örnekler:

# 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-win-uygulama-yolu

Yüklü Windows SDK bileşenlerinin yollarını alın.

winapp get-winapp-path [options]

Ne döndürür:

Çalışma alanı dizinine giden .winapp yollar
Paket yükleme dizinleri
Oluşturulan üst bilgi konumları

düğüm oluşturma bağlamaları

(Yalnızca NPM paketinde kullanılabilir) Windows Uygulama SDK'sı API'leri için JS bağlamaları oluşturun. Bağlamalar içinde package.json bir "winapp": { "jsBindings": {...} } ad alanı tarafından bildirilir ve öğesine .winapp/bindings/yazılır.

npx winapp node generate-bindings [options]

Seçenekler:

--verbose, -v - Dosya başına ayrıntılı kod oluşturma çıkışını etkinleştirme
--quiet, -q - İlerlemeyi ve bilgi çıkışını gizleme

Ne yapar:

bloğunu winapp.jsBindingspackage.json okur ve winmds.lock.json son winapp restoretarafından yazılan öğesini okur, ardından türü yazılan .js + .d.ts bağlamaları içine yayar .winapp/bindings/
package.json Değiştirmez, pasif bir yeniden üreticidir. winapp.jsBindings Blok ve çalışma zamanı bağımlılığının @microsoft/dynwinrt eklenmesi, JS bağlamaları etkinleştirildiğinde gerçekleşirwinapp init; blok yoksa bu komut hızlı başarısız olur
Bağımlılıklarınızda eksikse @microsoft/dynwinrt uyarır (ancak yazmaz), eklendikten sonra init çalıştırın npm install

Uyarı

Bağlamalar yalnızca npm'ye özgüdür; çağrıyı npx winapp ( @microsoft/winappcli npm paketi) gerektirir; tek başına winget CLI bunları ortaya çıkaramaz. Bağlamaları yeniden oluşturmak için bu komutu kullanmadan önce etkileşimli olarak çalıştırın winapp init ve kabul edin veya kullanın winapp init . --use-defaults --add-js-bindings. öğesini düzenlersenizwinapp.yaml, yeniden oluşturmadan önce Windows bağımlılıkları yenilemek için komutunu çalıştırınnpx winapp restore.

Örnekler:

# 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

Uçtan uca iş akışı ve yapılandırma seçenekleri için JS bağlamaları kılavuzunawinapp.jsBindings bakın.

node eklenti-oluştur

(Yalnızca NPM paketinde kullanılabilir) Windows SDK ve Windows Uygulama SDK'sı tümleştirmesi ile yerel C++ veya C# eklenti şablonları oluşturun.

npx winapp node create-addon [options]

Seçenekler:

--name <name> - Addon name (varsayılan: "nativeWindowsAddon")
--template - Eklenti türünü seçin. Seçenekler veya 'dır cs (varsayılan: cpp)cpp
--verbose - Ayrıntılı çıkışı etkinleştirme

Ne yapar:

Şablon dosyalarıyla addon dizini oluşturur
Windows SDK örnekleriyle binding.gyp ve addon.cc oluşturur
Gerekli npm bağımlılıklarını yükler (nan, node-addon-api, node-gyp)
package.json dosyasına derleme komut dosyası ekler

Örnekler:

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

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

node add-electron-debug-identity

(Yalnızca NPM paketinde kullanılabilir) Seyrek paketleme kullanarak Elektron geliştirme sürecine uygulama kimliği ekleyin. Package.appxmanifest gerektirir (veya yoksa bir winapp initwinapp manifest generate paket oluşturun).

Önemli

Seyrek paketleme Elektron uygulamalarında uygulamanın başlangıçta kilitlenmesine veya web içeriğini işlememesine neden olan bilinen bir sorun vardır. Sorun Windows düzeltildi ancak henüz dış Windows cihazlara yayılmadı. çağrısından add-electron-debug-identitysonra bu sorunu görüyorsanız, bayrağıyla hata ayıklama amacıyla --no-sandbox. Bu sorun tam MSIX paketlemesini etkilemez.

Elektron hata ayıklama kimliğini geriye almak için winapp node clear-electron-debug-identity kullanın.

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

Seçenekler:

Seçenek	Açıklama
`--manifest <path>`	Özel Package.appxmanifest yolu (varsayılan: Geçerli dizinde Package.appxmanifest)
`--no-install`	Bağımlılıkları yüklemeyin veya değiştirmeyin; yalnızca Elektron hata ayıklama kimliğini yapılandırma
`--keep-identity`	Paket adına ve uygulama kimliğine `.debug` eklemeden bildirim kimliğini olduğu gibi bırakın.
`--verbose`	Ayrıntılı çıktıyı etkinleştir

Ne yapar:

electron.exe işlemi için hata ayıklama kimliğini kaydeder
Elektron geliştirmesinde kimlik gerektiren API'lerin test edilmesine olanak tanır
Kimlik yapılandırması için mevcut Package.appxmanifest dosyasını kullanır

Örnekler:

# 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

node clear-electron-debug-identity

(Yalnızca NPM paketinde kullanılabilir) Özgün electron.exe yedekten geri yükleyerek Electron hata ayıklama işleminden paket kimliğini kaldırın.

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

Seçenekler:

Seçenek	Açıklama
`--verbose`	Ayrıntılı çıktıyı etkinleştir

Ne yapar:

tarafından oluşturulan yedeklemeden electron.exe geri yükler add-electron-debug-identity
Geri yüklemeden sonra yedekleme dosyalarını kaldırır
Electron'ı paket kimliği olmadan özgün durumuna döndürür

Örnekler:

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

Genel Seçenekler

Tüm komutlar şu genel seçenekleri destekler:

--verbose, -v - Ayrıntılı günlük kaydı için ayrıntılı çıkışı etkinleştirin
--quiet, -q - İlerleme iletilerini gizleme
--help, -h - Komut yardımlarını göster

Genel Önbellek Dizini

Winapp, birden çok proje arasında paylaşılabilen dosyaları önbelleğe almak için bir dizin oluşturur.

Varsayılan olarak, winapp genel önbellek dizini olarak konumunda $UserProfile/.winapp bir dizin oluşturur.

Farklı bir konum kullanmak için ortam değişkenini WINAPP_CLI_CACHE_DIRECTORY ayarlayın.

Cmd'de:

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

PowerShell ve pwsh'de:

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

veya initgibi restore komutları çalıştırdığınızda Winapp bu dizini otomatik olarak oluşturur.

Güncelleştirme Denetimleri

Winapp CLI düzenli aralıklarla yeni sürümleri denetler ve bir güncelleştirme kullanılabilir olduğunda tek satırlık bir bildirim görüntüler. Bu denetim arka planda çalışır ve komutlara gecikme süresi eklemez.

Güncelleştirme denetimleri CI ortamlarında (GitHub Actions, Azure Pipelines vb.) otomatik olarak devre dışı bırakılır.

Güncelleştirme denetimlerini el ile devre dışı bırakmak için ortam değişkenini WINAPP_CLI_UPDATE_CHECK olarak 0ayarlayın.

Cmd'de:

set WINAPP_CLI_UPDATE_CHECK=0

PowerShell ve pwsh'de:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Bunu kalıcı hale getirmek için:

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

Uı

UI Otomasyonu (UIA) kullanarak çalışan Windows uygulama URI'lerini inceleyin ve bunlarla etkileşime geçin.

winapp ui [command] [options]

Komut:

status - Uygulamaya bağlanın ve bilgileri gösterin
inspect - Öğe ağacını görüntüleme
search - Seçiciye göre öğeleri bulma
get-property - Öğe özelliklerini okuma
get-text / get-value - Öğeden değer/metin okuma (TextPattern, ValuePattern veya Name)
screenshot - Pencereyi/öğeyi PNG olarak yakala (iletişim kutularını ayrı ayrı otomatik yakalar)
record- Bir pencere/öğe bölgesini H.264 MP4 videosuna kaydetme (Grafik Yakalama + Media Foundation Windows)
invoke - Öğeyi etkinleştirme (tıklama, geçiş, genişletme)
click - Fare benzetimi aracılığıyla öğeye tıklayın (çağırmayı desteklemeyen denetimler için)
hover - Araç ipuçlarını, açılır öğeleri ve vurgulama durumlarını tetikleme amacıyla fareyi öğeye taşıma (varsayılan konut: 800ms)
drag - Fareyi öğe seçiciye veya ekran x,y koordinatlarına göre bir noktadan diğerine sürükleyin (yeniden sıralama, yeniden boyutlandırma, kaydırıcılar, sürükle ve bırak)
touch - Bir öğe merkezine veya ekran x,y koordinatlarına sentetik dokunma hareketleri (dokunma, iki kez dokunma, uzun basma, çekme, sıkıştırma, uzatma) ekleme
pen - Yapay kalem/ekran kalemi girişi ekleme — yapılandırılabilir basınç, eğme ve silgi modu ile dokunmalar ve mürekkep vuruşları
send-keys - Yapay klavye girişini (adlandırılmış tuşlar, birleşik girişler, ham vk=0xNN veya değişmez metin) pencereye gönderme
set-value - Düzenlenebilir öğede (metin, sayı) değer ayarlayın; TextPattern yalnızca zengin düzenleme denetimleri için LegacyIAccessible'a put_accValue geri döner
focus - Klavye odağını taşıma
scroll-into-view - Kaydırma öğesi görünür
wait-for - Öğe durumunu bekleme
list-windows - Bir uygulamanın tüm pencerelerini listeleme
get-focused - Şu anda odaklanmış öğeyi raporlama

Seçenekler:

-a, --app <app> - Hedef uygulama (ad, başlık veya PID)
-w, --window <hwnd> - HWND tarafından hedef pencere (kararlı)

ui kaydı

Hedef pencereyi (veya tek bir öğenin bölgesini) bir H.264 MP4 videosuna kaydedin. Çerçeveler, Windows Grafik Yakalama (PrintWindow geri dönüşü ile) aracılığıyla yakalanır ve Media Foundation ile artımlı olarak kodlanır, bu nedenle uzun kayıtlar hiçbir zaman bellekte arabelleğe almaz.

# 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

Kayıt seçenekleri:

--duration-sec <n> - Saniye cinsinden kayıt uzunluğu. 0 Ctrl+C (varsayılan 0) tuşlarına kadar kaydeder.
--fps <n> - Yakalamak için saniye başına kare sayısı (varsayılan 15).
--max-edge <px> - En uzun kenar en fazla şu kadar piksel olacak şekilde küçültülür (0 = azaltma yoktur).
--capture-screen - Yer paylaşımlarının/açılır pencerelerin dahil olması için ekrandan yakalayın (kaplayan pencereleri yakalayabilir).
-o, --output <path> - Çıkış .mp4 yolu (varsayılan olarak recording-<timestamp>-<guid>.mp4).

ile--json, çıkışı , , widthframes, height, fileSize, codec ("h264") ve mode — aslında kullanılan yakalama yolunu (wgc, printwindowveya screen) içeren pathbir UiRecordResult zarf yayar.

Bilinen sınırlama: Kendi üst düzey penceresinde (WinUI/XAML açılır öğesi, öğretim ipucu, araç ipucu) işlenen bir açılır pencere içinde belirli bir öğenin kaydedilmesi bunun yerine temel alınan ana pencereyi yakalayabilir. Pencerenin tamamını kaydedin veya açılır pencere stiller için kullanın ui screenshot --capture-screen . #646'da izlenir.

Tüm belgeler için bkz. docs/ui-automation.md.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-24

CLI Belgeleri ve Kullanımı

Kabuk Tamamlama

başlat

eski haline döndürmek

güncelleştirmek

pack

WinRT bileşeni bulma

Çok mimarili paketler

hata ayıklama kimliği oluştur

manifesto

bildirim oluşturma

Manifesto yer tutucuları

bildirim ekleme diğer adı

manifesto varlıkları güncelle

run

kaydını kaldırma

cert

sertifika oluşturma

sertifika bilgileri

sertifika yükleme

işaret

create-external-catalog

araç

store

get-win-uygulama-yolu

düğüm oluşturma bağlamaları

node eklenti-oluştur

node add-electron-debug-identity

node clear-electron-debug-identity

Genel Seçenekler

Genel Önbellek Dizini

Güncelleştirme Denetimleri

Uı

ui kaydı

Geri Bildirim

Ek kaynaklar