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
  • --exe <path> - Uygulama yürütülebilir dosyasının yolu. gerektirir --sparse. Tam paket/SDK kurulumu yerine exe için yalnızca kimlik seyrek bildirim oluşturur.
  • --sparse - Mevcut bir masaüstü exe dosyası için seyrek kimlik bildirimi (appxmanifest.xml) oluşturun. SDK/paket yüklemesini atlar. --exe ile kullanın.
  • --name <name> - Paket adını geçersiz kılma (yalnızca seyrek; varsayılan: exe'den çıkarılır)
  • --publisher <CN> - Yayımcı CN'sini geçersiz kılma (yalnızca seyrek; varsayılan: exe'nin şirket adından çıkarılır)
  • --output-dir <path> - Seyrek bildirimi yazmak için dizin ve Assets/ (yalnızca seyrek; varsayılan: geçerli dizindeki bir sparse/ klasör)
  • --force - Hedef dizinde var olan appxmanifest.xml bir dizinin üzerine yazın (yalnızca seyrek). Bu olmadan, mevcut bir bildirimi/varlıkları değiştirmek yerine init başarısız olur.
  • --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 --use-defaults) bir dizin bağımsız değişkeni olmadan ayarlanırsa --no-prompt , 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 )

Seyrek kimlik modu (--exe + --sparse):

Seyrek paketleme iş akışının ilk adımı olan mevcut masaüstü yürütülebilir dosyası için yalnızca kimlikli seyrek paket bildirimi oluşturur. Tam init akışın aksine, bu tüm SDK/paket yüklemesini atlar (seyrek kimlik paketlerinin SDK bağımlılıkları yoktur) ve yalnızca bildirim ve yer tutucu varlıklar oluşturur.

  • aracılığıyla exe'den paket adını, yayımcıyı, açıklamayı ve sürümü çıkartır FileVersionInfo (, --publisherveya etkileşimli olarak geçersiz kıl--name)
  • appxmanifest.xml Geçerli dizindeki (veya --output-dir) bir klasöre yazar (yerine exe adı Executableile ) ve bir Assets/sparse/ klasör ekler
  • Etkileşimli geçersiz kılma istemlerini atlamak için kullanır --use-defaults/--no-prompt (CI kullanımı kolay)
  • --exe olmadan --sparse bir hatadır

Varlıklar haricidir. Seyrek .msix yalnızca kimliktir: oluşturulanAssets/, çalışma zamanında uygulamanın yükleme dizininden (dış içerik konumu) çözümlenir, içine .msixpaketlenmez. Bunları uygulamanızla birlikte dağıtın.

sonrasındaki sonraki adımlar winapp init --exe <exe> --sparse: winapp pack <appxmanifest.xml> kimliğini .msixoluşturmak için , ardından winapp embed-identity <exe>. Tam kılavuz için Bkz. Seyrek Paketleme Kılavuzu .

Ö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

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

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

Yeni

Resmi bir Windows Uygulama SDK'sı dotnet new şablonundan yeni bir WinUI uygulaması oluşturun. Varsayılan olarak etkileşimli; otomatik olarak etkileşimli olmayan ortamlarda varsayılanları kullanır.

winapp new [options]

Seçenekler:

  • -t, --template <short-name> - Şablon kısa adı (ör. winui, winui-navview, winui-mvvm, winui-lib, winui-unittest). Çalışma zamanında yüklü pakete karşı doğrulanır; komutunu çalıştırarak winapp new --list tümünü görebilirsiniz. Varsayılan: winui (boş uygulama).
  • -n, --name <name>- Yeni uygulama/projenin adı (varsayılan: ' den --outputtüretilir)WinUIApp
  • -o, --output <path> - Uygulamayı oluşturmak için dizin (varsayılan: ./<name>)
  • --use-defaults, --no-prompt - İstemde bulunmayın; varsayılan değerleri kullanın (boş şablon, 'den --output/--namead ve yüklü şablon paketini güncelleştirmek yerine saklayın)
  • --force - Çıkış dizini zaten dosya içeriyorsa bile iskele
  • --template-version <latest|installed|version> - WinUI şablon paketi sürümü: latest en yeni yayımlanan paketi yükler, installed zaten indirilmiş olan her şeyi tutar (ağ yok) veya gibi 1.2.3açık bir sürümü sabitler. Varsayılan: Paket olmadığında en son sürümü yükleyin, aksi takdirde eski bir paketi güncelleştirme isteminde bulun (altında --use-defaultsas-is tutulur).
  • --list - Kullanılabilir WinUI şablonlarını listeleyin ve çıkın (hiçbiri yüklü değilse önce en son paketi yükler)
  • --json - Çıktıyı JSON olarak biçimlendirme

Şablon:

Şablon listesi yüklü paketten canlı olarak okunur, bu nedenle her zaman sahip olduğunuz sürümü yansıtır; geçerli kümeyi görmek için komutunu çalıştırın winapp new --list . Yaygın şablonlar:

Kısa ad Açıklama
winui En az boş WinUI 3 uygulaması (MSIX paketleme)
winui-navview NavigationView başlangıç uygulaması
winui-tabview TabView başlangıç uygulaması
winui-mvvm MVVM uygulaması (CommunityToolkit.Mvvm)
winui-lib WinUI 3 sınıf kitaplığı
winui-unittest Paketlenmiş MSTest uygulaması; testler başlatıldığında çalıştırılır

Her şablonun kurallı kısa adı, bu şablonun ilk diğer ad dotnet new listeleridir; listelenen diğer adlar da (örneğin winui3, wasdk-single) kabul edilir. Mevcut bir WinUI projesinde çalıştırıldığında, dotnet new yenisini oluşturmak yerine geçerli projeye ekleyen winapp newöğe şablonlarını da (boş bir sayfa gibi) ortaya çıkar.

Şablon paketi sürümü oluşturma:

winapp new artık belirli bir şablon paketi sürümünü sabitlemez. Yüklü paket yoksa en son sürümü yükler. Daha eski bir paket zaten yüklüyse akışı denetler ve daha yeni bir paket mevcut olduğunda, yüklü paketi tutan etkileşimli olmayan/--use-defaultsçalıştırmalar dışında güncelleştirme yapılıp yapılmayacağını sorar. İstenmeden her zaman en yeni paketi almak veya --template-version installed indirilen paketi her zaman ağ denetimi olmadan kullanmak için kullanın--template-version latest. Açık bir sürüm geçirildiğinde (örn. --template-version 1.2.3) her zaman tam olarak bu sürüm yüklenir ( daha yeni bir paket mevcut olsa bile yeniden yüklenir), bu nedenle yapı iskelesi makineler arasında yeniden üretilebilir.

Ne yapar:

  • .NET SDK'sının yüklendiğini doğrular (eksikse kılavuzla hızlı başarısız olur; winapp araç zincirlerini yüklemez)
  • Resmi WinUI şablon paketini (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) isteğe bağlı olarak yükler veya güncelleştirir
  • Yüklü paketten kullanılabilir şablonları numaralandırır ve iskeleyi şu şekilde numaralandırır: dotnet new <short-name>

WinUI uygulama şablonları zaten Windows paketleme ve kimlik ()Package.appxmanifest içerir, bu nedenle ayrı winapp init bir adım gerekmez. Uygulama şablonları için uygulamasını derlemek ve başlatmak için kullanın winapp run . Şablon, winui-lib bir uygulama projesinden başvurmak için bir sınıf kitaplığı oluşturur (uygulama bildirimi yoktur). Şablonwinui-unittest, aracılığıyla değildotnet test, uygulama başlatıldığında (winapp run) testleri çalıştırılan paketlenmiş bir MSTest uygulamasıdır. winapp newyüklü .NET SDK'nızın hedef çerçevesine karşı iskeleler oluşturur ve seçtiğiniz şablon için uygun sonraki adımı yazdırır.

Temel alınan dotnet her çağrıyı (paket sorgusu, güncelleştirme denetimi, yükleme, dotnet new list, iskele) ve tam çıkışını yankılandırmak için genel --verbose (-v) bayrağını geçirin; şablon paketi veya yapı iskelesi sorunlarını tanılamak için kullanışlıdır.

Örnekler:

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

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

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

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

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

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

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. Seyrek kimlik paketleri için doğrudan klasör yerine seyrek appxmanifest.xml bir dosya geçirin (aşağıdaki Seyrek kimlik paketlerine bakın).

Seçenekler:

  • --output <filename> - Çıkış dosyası adı. Tek paketler için: <name>_<version>_<arch>.msix (, <name>_<version>.msixveya <name>_<arch>.msixöğesine <name>.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

Seyrek kimlik paketleri

Giriş bir klasör yerine seyrek appxmanifest.xml bir dosya (altında bildirimde <uap10:AllowExternalContent>true</uap10:AllowExternalContent><Properties>bulunan) olduğunda,winapp pack yalnızca .msix kimlik oluşturur; uygulama ikili dosyaları veya varlıkları olmadan yalnızca bildirimi paketler. Bu, seyrek paketleme iş akışının 2. adımıdır.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx
  • Çıkış varsayılan olarak <PackageName>.identity.msix geçerli dizinde (ile --outputgeçersiz kıl) olarak ayarlanır.
  • İmzalama yalnızca (veya --generate-cert) sağlandığında --cert gerçekleşir.
  • Bunun yerine bildirimini bildirdiği AllowExternalContentbir klasör geçirirseniz, var olan klasör paketleme davranışı uygulanır, ancak winapp pack varlıkları () veya ikili dosyaları (///.so.jpg.png.exe.dll.ico/) bulursa uyarır; seyrek paketler için bunlar içinde .msixdeğil dış konuma aittir.

Paketledikten sonra paketini çalıştırın winapp embed-identity <exe> ve ile Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>yükleyicinize kaydedin. Bkz. Seyrek Paketleme Kılavuzu.

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:

  1. Sağlanırsa --executable (giriş klasörüne göre yol), yer tutucu belirtilen değerle değiştirilir
  2. 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
  3. 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 .msixbundle içeren bir .msix 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:

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

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

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

embed-identity

Bir masaüstü uygulamasını, öğesini uygulamanın yan yana (fusion) bildirimine ekleyerek <msix>seyrek kimlik paketine bağlayın. Bu, seyrek paketleme iş akışının 3. adımıdır; çalışan exe'nin hangi kimlik paketine ait olduğunu Windows bildirir.

winapp embed-identity <target> [options]

Argümanlar:

  • target - Güncelleştirilecek dosya. Uzantı tarafından otomatik olarak algılandı:
    • .exe(EXE modu) — kullanarak öğesini doğrudan exe'nin yan yana bildirimine mt.exeekler<msix>.
    • .xml / .manifest (XML modu) — bir dış SxS bildirim dosyasına öğe ekler veya değiştirir <msix> (yoksa oluşturulur). Güncelleştirilmiş bildirimin ikili dosyaya katıştırılmış olması için uygulamanızı daha sonra yeniden oluşturun.

Seçenekler:

  • --manifest <path> - Kimlik (packageName, publisher, applicationId) okunacak seyrek appxmanifest.xml yol. Atlandığında, komut önce hedefin yanındaki bir sparse/ klasörü, ardından geçerli dizinde, ardından hedefin dizinini ve geçerli dizini için appxmanifest.xmlarar.

Örnekler:

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

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

Bu komut bir kez etkili: yeniden çalıştırmak, yinelemek yerine var olan <msix> öğelerin yerini alır.

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:

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.

winapp run girişten otomatik olarak seçilen iki moddan birinde çalışır:

  • Klasör modu — giriş bir derleme-çıkış klasörüdür (bir Package.appxmanifest/AppxManifest.xmliçerir).
  • Project modu — giriş bir .csproj, bir .sln/.slnx çözüm veya bir dizin içeren bir dizindir. winapp run projeyi oluşturur ve hem paketlenmiş hem de paketlenmemiş WinUI uygulamalarını destekleyerek başlatır. Aşağıdaki Project moduna bakın.

Tip

Mod seçimi varsayılan olarak sessizdir. Bir dizinin proje olarak derlenmesini beklediğiniz sırada derleme-çıkış klasörü olarak ele alındıysa ile yeniden çalıştırın --verbose ; klasör modu neden seçildiğini (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.) bildirir. Dizin, yalnızca çalıştırılabilir bir uygulama en üst düzeyde olduğunda.slnx.csproj/.sln/proje olarak oluşturulur; özyinelemeli olarak aranamaz.

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

Argümanlar:

  • input - Çalıştırılacak uygulama: derleme-çıktı klasörü (klasör modu), .csproj proje, .sln/.slnx çözüm veya en üst düzeyde bunlardan birini içeren bir dizin (proje modu; dizin özyinelemeli olarak aranmıyor). Projeyi geçerli dizinde derlemek/çalıştırmak için kullanın . . İsteğe bağlı — atlandığında (ile eşleşirdotnet run) varsayılan olarak geçerli dizini kullanır.

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

Project modu (.NET SDK projeleri)

Giriş bir .csprojolduğunda, bir.slnx/.sln çözüm veya içeren bir dizin (dahil.),winapp run ile dotnet build projeyi derler ve ardından başlatır. Hem paketlenmiş hem de paketlenmemiş WinUI uygulamalarını destekler ve başlatmadan önce uygulamanın ihtiyaç duyduğu çalışma zamanı Windows Uygulaması eşleşen mimariyi yükler.

Çözüm girişi: bir .sln/.slnx (veya bir dizin içeren bir dizin) üzerine gelin winapp run ve çözüm gevşek .csproj dosyalara göre tercih edilir) ve çalıştırılabilir uygulama projesini çözümler, ardından ve tanımlanan eşdüzey Solution* özelliklerle $(SolutionDir) derlenir, böylece bunlara bağımlı olan projeler Visual Studio'de olduğu gibi oluşturulur. Çözüm kuralları:

  • Otomatik seçim yapılırken test projeleri atlanır, bu nedenle bir uygulama ve testlerini içeren bir çözüm, uygulamaya gerek olmadan --project çözümlenir. (WinUI test projesinin kendisi paketlenmiş bir uygulamadır, bu nedenle tek başına çıkış türü bunu ayırt edemez.)
  • Çalıştırılabilir tek proje bir test projesiyse çalışır.
  • Birden fazla çalıştırılabilir uygulama projesi varsa, winapp run başlangıç projesini tahmin etmez; adaylar listelenirken hata oluşur. Bir test projesi seçmek de dahil olmak üzere her zaman kabul edilen öğesini seçmek için kullanın --project <name> .

Paketlenmiş ve paketlenmemiş, projenin etkili WindowsPackageType MSBuild özelliğinden otomatik olarak algılanır (bildirim varlığından hiçbir zaman):

  • Paketlenir (WindowsPackageType=MSIXWinUI varsayılan olarak paketlenir) — derlemeleri oluşturur, ardından derleme çıkışını gevşek düzen paketi olarak kaydeder ve AUMID (klasör moduyla aynı işlem hattı) aracılığıyla başlatılır.
  • Paketlenmemiş (WindowsPackageType=None) — derlemeler, çerçeveye bağımlı Windows Uygulaması Çalışma Zamanı'nın yüklenmesini sağlar, ardından derlemeyi .exe doğrudan başlatır. bunu ile -p WindowsPackageType=Nonepaketlenmiş bir proje için zorlar.

Project modu için .NET SDK 8.0.100 veya üzeri (MSBuild --getPropertyiçin) gerekir.

Project modu seçenekleri (klasör modunda yoksayılır):

  • -c, --configuration <name> - Derleme yapılandırması. Varsayılan: Debug.
  • --arch <x64|arm64|x86> - Hedef mimari. Varsayılan: geçerli işlem mimarisi. Hem derleme RID'sini hem de yüklenen Windows Uygulaması Çalışma Zamanı mimarisini belirler.
  • -r, --runtime <rid>- Hedef .NET çalışma zamanı tanımlayıcısı (örn. win-x64). Project modu yalnızca RID'nin mimarisini kullanır, her zaman kurallı win-<arch>öğesini oluşturur ve Windows olmayan RID'leri (ör. linux-x64) reddeder. Mimarisi geçersiz kılar --arch.
  • -f, --framework <tfm> - Çok hedefli projeler için hedef çerçeve adı (örn. net10.0-windows10.0.26100.0).
  • --project <name-or-path> - Giriş bir çözüm (.sln/.slnx) veya birden çok çalıştırılabilir uygulama projesine sahip bir dizin olduğunda, başlatılacak projeyi (proje adına veya yola göre) seçer.
  • --no-build - Mevcut derleme çıkışını oluşturmayı ve çalıştırmayı atlayın (yine de çıkış özelliklerini değerlendirir).
  • --no-restore - Derlemeden önce projeyi geri yüklemeyi atlayın.
  • -p, --property <Name=Value> - Hem derlemeye hem de özellik değerlendirmesine iletilen MSBuild özelliği. Yinelenebilir (örn. -p WindowsPackageType=None).

Çıkış ve ayrıntı oluşturma: Proje, çıkış akışları konsolunuza canlı olarak gelen ve ardından hızlı bir özellik değerlendirme geçişi olan iki adımda dotnet build oluşturulur. winapp, çıktıdan önce tam dotnet build … çağrıyı yazdırır ve başarılı bir derlemede bile uyarıların akışını yapar. Ayrıntı Düzeyi:

Flag dotnet ayrıntı düzeyi Ekler
(varsayılan) minimal —
--verbose minimal winapp'in derleme kararı izlemeleri
--quiet quiet —

--quiet veya altında --json çağırma ve derleme çıkışı stderr'a gider, böylece stdout saf JSON / temiz kalır.

Seçenek uygulanabilirliği: kimlik/gevşek düzen seçenekleri (--manifest, --output-appx-directory, --no-launch, --with-alias, --unregister-on-exit, , --clean), --executableyalnızca paketlenmiş uygulamalara uygulanır. Paketlenmemiş uygulamalar (MSIX paketi olmayan) için net bir hatayla reddedilirler. Başlatma/hata ayıklama seçenekleri (--args/--, --detach, --debug-output, --symbols, --json) her ikisinde de çalışır.

Project modu örnekleri:

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

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

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

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

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

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

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

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

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

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.
WinAppRunDetach false Uygulamanın çıkışını beklemek yerine başlatıldıktan hemen sonra geri dönün. PID'yi yazdırır.
WinAppRunUnregisterOnExit false Uygulama çıktıktan sonra geliştirme paketinin kaydını kaldırın
WinAppRunClean false Yeniden dağıtmadan önce mevcut paketin uygulama verilerini (LocalState, ayarlar) kaldırın
WinAppRunSymbols false Daha zengin yerel kilitlenme analizi için sembolleri Microsoft Sembol Sunucusu'ndan indirin. yalnızca ile WinAppRunDebugOutputbir etkisi vardır.
WinAppRunExecutable (boş) Build-output klasörüne göre yürütülebilir yol. Bildirim içerdiğinde $targetnametoken$ ve çıkış klasöründe birden .exefazla olduğunda kullanın.
WinAppRunArgs (boş) Ayrılmış özelliği olmayan seçenekler için komut satırına winapp run eklenen ham bağımsız değişkenler (örneğin --verbose). Yukarıdaki her özelliğin sonuna eklenir.

Birbirini dışlayan ayarlar. WinAppRunNoLaunch ve WinAppRunDetach her birinin farklı bir başlatma davranışı tanımladığından, diğer başlatma özellikleriyle ve birbirleriyle çakışırlar. Çakışan bir çiftin ayarlanması ile --X and --Y cannot be used togetherçalıştırma başarısız oluyor:

Mülkiyet ile birleştirilemez
WinAppRunNoLaunch WinAppRunDetach, WinAppRunUseExecutionAlias, WinAppRunDebugOutput, WinAppRunUnregisterOnExit
WinAppRunDetach WinAppRunNoLaunch, WinAppRunUseExecutionAlias, WinAppRunDebugOutput, WinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias, WinAppRunDebugOutputve WinAppRunUnregisterOnExit birbiriyle birleştirilebilir. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutableve WinAppLaunchArgs hiçbir kısıtlaması yoktur. WinAppRunArgs kendi kısıtlaması eklemez, ancak içinden geçirilen bir anahtar diğer tüm anahtarlar gibi denetlenir, bu nedenle WinAppRunArgs="--detach" yine ile WinAppRunNoLaunchçakılır.

<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

az-sign

Azure Güvenilen İmzalama kullanarak bir dosyayı (exe, MSIX veya MSIX paketi) kod olarak imzalayın; bu nedenle yerel makinede özel anahtar (PFX) yaşamıyor.

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

Argümanlar:

  • file-path - İmzalayacak dosyanın yolu (exe, msix veya msixbundle)

Seçenekler:

  • --subscription, -s - Kullanılacak abonelik kimliğini Azure. Sağlanmadıysa ve birden çok abonelik varsa, sizden istenecektir
  • --resource-group, -r - İmzalama hesaplarını daraltmak için kaynak grubu
  • --account - İmzalama hesabı adı. Ile kullanılmalıdır --resource-group
  • --profile, -p - Sertifika profili adı. Ile kullanılmalıdır --account
  • --metadata-file, -m - Var olan metadata.jsonbir öğesinin yolu. Kaynak bulma ve hesap/profil seçimi istemlerini atlar ve doğrudan imzalar. Etkileşimli olmayan bir Azure kimlik bilgisi zaten kullanılabilir olmalıdır; CLI aksi takdirde etkileşimli bir kiracı istemine veya az loginöğesine geri dönebilir, ancak npm programlı API her zaman etkileşimli değildir ve sorulmak yerine başarısız olur

Kimlik Doğrulaması:

az-signAzure standart kimlik bilgisi zincirini (DefaultAzureCredential) kullanır. CI/CD için , AZURE_CLIENT_IDve AZURE_CLIENT_SECRET (veya GitHub Actions OIDC / yönetilen kimlik kullanın) ayarlayınAZURE_TENANT_ID. Mevcut bir Azure CLI oturumu da (az loginGitHub Eylemi dahil azure/login ) herhangi bir ortamda kabul edilir. Yalnızca hiçbir kimlik bilgisi bulunamadığında ve oturum etkileşimli az-sign olduğunda sizin için başlatılır az login .

Ön koşullar:

  • Bir Azure Kod İmzalama hesabı ve bir sertifika profili (kimlik doğrulamasından sonra Azure portalında oluşturulur), ayrıca kimliğinize atanan Kod İmzalama Sertifikası Profili İmzalayan rolü. Daha fazla rehberlik için Azure Yapıt İmzalama hızlı başlangıç belgelerini ziyaret edin.
  • Makine genelinde x64 .NET 8 (veya üzeri) çalışma zamanı yüklü. Azure imzalama istemci kitaplığı, ayrı bir işlemde yüklenen yönetilen bir derlemedirsigntool.exe; winapp'in kendi bağımsız çalışma zamanı bunu karşılamaz. İmzalama bir çalışma zamanı yükleme hatasıyla başarısız olursa adresinden https://dotnet.microsoft.com/download yükleyin.
  • Microsoft Visual C++ Yeniden Dağıtılabilir (x64). Azure imzalama istemci kitaplığı VC++ çalışma zamanına bağlıdır ve winapp resmi istemci araçları yükleyicisi yerine ham NuGet paketini indirdiğinden, bu bağımlılık otomatik olarak yüklenmez. Temiz bir makine, .NET ve SignTool mevcut olsa bile yük devretme yapabilir. İmzalama işlemi "Uygulama doğru başlatılamadı" hatasıyla veya dlib'den https://aka.ms/vs/17/release/vc_redist.x64.exe eksik DLL hatasıyla 0xc000007bbaşarısız olursa en son x64 yeniden dağıtılabilir öğesini yükleyin.

En az ayrıcalıklı CI: Otomatik bulma (abonelikleri, kaynak gruplarını, hesapları ve profilleri listeleme) üst kapsamda okuma erişimine ihtiyaç duyar. Her koleksiyon listeleme çağrısından kaçınmak için , , --resource-group--accountve : değerlerinin dördünden --subscriptionbirini geçirin ve --profileaz-sign ardından hesabı ve profili üst koleksiyonu listelemek yerine doğrudan kaynak okumalarıyla (adlandırılmış her kaynakta get) doğrular; bu nedenle yalnızca bu hesap ve profil kapsamına sahip bir sorumlu yeterli olur. Bunlardan herhangi birinin atlanması bir listeleme çağrısını yeniden tanıtır; örneğin, dışarıda --subscriptionaz-sign bırakmak, kimliğinizin erişebileceği abonelikleri listeler ve dar kapsamlı bir sorumlunun bunu yapmasına izin verilmeyebilir. Yalnızca tek bir sertifika profili kapsamındaki bir sorumlu, önceden oluşturulmuş --metadata-file (hesap uç noktasını ve profili doğrudan belirtir) geçirerek doğrulamayı tamamen atlayabilir.

Örnekler:

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

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

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

create-external-catalog

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:

  1. winapp manifest generate --template sparse — ile seyrek bildirim oluşturma AllowExternalContent
  2. winapp create-external-catalog ./bin — Uygulamanızın yürütülebilir dosyaları için kod bütünlüğü kataloğu oluşturma
  3. 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:

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

find-ui

Çalışan bir kod örneği için WinUI denetimlerini ve örneklerini arayın. Yalnızca WinUI: corpus, WinUI 3 Galerisi ve Windows Topluluk Araç Seti 'dir (artı birkaç seçilmiş çekirdek deseni) — WPF, WinForms veya diğer ui çerçevelerini kapsamaz. Üçüncü bir kaynak olanmicrosoft-ui-reactor ReactorGallery kabul ediyor: normal bir aramadan dışlanır ve yalnızca geçtiğinizde --source reactor aranır (yalnızca C#-only bildirim temelli örnekleri standart bir XAML uygulamasına yapıştırılamaz, bu nedenle yalnızca Reactor/MVU projesi oluştururken buna ulaşın).

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

Corpus, ilk kullanımda GitHub'den getirilir ve altında <global .winapp>/cache/find-uikullanıcı başına önbelleğe alınır, bu nedenle ilk çalıştırma ağ erişimi gerektirir. Sonraki çalıştırmalar yerel önbellekten sunulur (en fazla 7 günde bir veya isteğe bağlı olarak ile --refreshyenilenir).

Seçenekler:

  • --id <id> - Kodu getirme (Gallery/Toolkit dönüş XAML ve/veya C#; Reactor C#-only) artı önceki bir aramadan bir veya daha fazla senaryo kimliği için önkoşul notları (ör. gallery-tabview-1). Tekrarlanabilir. Kimlikler büyük/küçük harfe duyarlı değildir ; GALLERY-TABVIEW-1 ile aynı gallery-tabview-1şekilde çözümlenir.
  • --list - Arama yerine her bulunabilir denetimi/örnek kimliği listeleyin (Gallery + Toolkit + core; kabul reaktör kaynağı hariç tutulur).
  • --source <gallery|toolkit|reactor|core> - Arama sonuçlarını tek bir kaynakla kısıtlayın. (Yalnızca arama — ile --list/--idgeçerli değildir.) Reactor kabul edilir - normal bir aramanın dışında tutulur, bu nedenle --source reactor aramanın tek yoludur.
  • --max <N> - Döndürülecek eşleşen denetim sayısı üst sınırı (varsayılan: 3). Yalnızca arama için geçerlidir; ile --list/--idyoksayılır.
  • --refresh- Yerel önbelleği atlayıp GitHub WinUI corpus'unu yeniden getirin.
  • --json - Yapılandırılmış JSON (aracı dostu) yayma. Arama için, her eşleşme , , , ve girdileri sourcesenaryo id başına ve header; için --idtam kodunu tutan bir scenarios dizi taşır. descriptionscorecontrol Tamsayı olmayan gibi bağımsız değişken/ayrıştırıcı hataları da dahil olmak üzere her hatanın altında--json, sıfır olmayan çıkış koduyla stdout'ta düz {"error": "..."} bir nesne olarak gösterilir, bu nedenle çıkış makine tarafından okunabilir kalır.--max

İş akışı: Doğru denetimi ve senaryo kimliklerini bulmak için kısa bir süre boyunca arama yapın, ardından ile --iden iyi eşleşme için tam kodu getirin.

Örnekler:

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

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

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

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

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

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

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 "winapp": { "jsBindings": {...} } bir package.json 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 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 npm install çalıştırın init

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ı

Bir pencereyi veya öğe bölgesini H.264 MP4'e kaydedin.

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

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

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

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o demo.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).
  • --frames - Zaman damgalı JPEG'ler, frames.ndjsonve manifest.json yazın <output-name>.frames. 1 GiB kare verisi üst sınırına sahip 1-30 fps ve --max-edge 64-4096 (varsayılan 1280) desteğine sahiptir.

ile --jsonnihai sonuç çıkış yolunu, boyutları, codec'i, yakalama modunu, tempoyu, durdurma nedenini, isteğe bağlı frameArtifactsve uyarıları içerir.

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.

  • Last updated on