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

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

Otomatik .NET proje tespiti:

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 --setup-sdks none çalıştırdıysanız init (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 experimental kullanın--setup-sdks preview.

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 manifest generate komutunu çalıştırıninit)

winapp pack <input-folder> [options]

Argümanlar:

input-folder - Paketlendirecek uygulama dosyalarını içeren dizin

Seçenekler:

--output <filename>- Çıkış MSIX dosya adı (varsayılan: <name>_<version>_<arch>.msix, , <name>_<arch>.msixöğesine <name>_<version>.msixgeri düşüyor veya <name>.msix sürüm/kemer belirlenemiyorsa)
--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 adı
--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
Üçü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 *.csproj içinde winapp.yaml 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 Executable yer alırsa $targetnametoken$ :

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

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 uygulama kodunuzdan ayrı olduğunda (örneğin, içinde olduğu electron.exenode_modulesElektron uygulamaları) veya seyrek paket davranışını özel olarak test ederken kullanıncreate-debug-identity. 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> - Publisher CN (varsayılan: CN=<geçerli kullanıcı>)
--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 <uap5:AppExecutionAlias> bir <Extensions> 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. 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. İ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. , , --debug-output--with-aliasveya --unregister-on-exitile --no-launchbirleş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 --debug-outputile --with-alias 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 create-debug-identityaracılığıylawinapp run). 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}.debug hem de {name} 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 adı
--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 AppxMetadata\CodeIntegrity.cat işlemine signtool.exe 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ı

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 --no-sandbox hata ayıklama amacıyla Electron uygulamanızda korumalı alanı devre dışı bırakabilirsiniz. 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 restoregibi init komutları çalıştırdığınızda Winapp bu dizini otomatik olarak oluşturur.

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)
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)
set-value - Düzenlenebilir öğede değeri ayarlama (metin, sayı)
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ı)

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-05-12

CLI Belgeleri ve Kullanımı

Kabuk Tamamlama

başlat

eski haline döndürmek

güncelleştirmek

pack

WinRT bileşeni bulma

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

node eklenti-oluştur

node add-electron-debug-identity

node clear-electron-debug-identity

Genel Seçenekler

Genel Önbellek Dizini

Uı

Geri Bildirim

Ek kaynaklar