CLI Belgeleri ve Kullanımı

Version

Yüklü winapp sürümünü veya kısa biçimiyle --version-Vyazdırın:

winapp -V

Küçük harf -v , on komutlarının --verbose kısa biçimidir (örneğin, winapp restore -v).

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: seçili proje dizini veya proje algılanmıyorsa 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
Seçili --setup-sdks kanaldaki en yeni Windows Uygulama SDK'sı sürümünü kullanır. Bu sürüm hala yayımlanıyorsa ve bazı paketleri henüz kullanılamıyorsa, init bunun yerine önceki sürümü kullanır ve bunu belirten bir not yazdırır. Yeni sürüme daha sonra gitmek için , veya .NET bir proje dotnet add package Microsoft.WindowsAppSDK --version <new version>için komutunu çalıştırınwinapp update.
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ı (örneğinwinui, , winui-navview, winui-libwinui-mvvm, , winui-unittestveya veya gibi reactorreactor-mvudeneysel bir Reactor şablonu). Ç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ş XAML uygulaması).
-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 sorulmadan en yeni yayımlanan pakete güncelleştirmeler (yerel yayın öncesi derleme gibi zaten daha yeni olan yüklü bir paket tutulur; akış denetlenemezse başarısız olur), installed önceden 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:

Paket, winUI uygulamasının iki stilini içerir. XAML şablonları, kullanıcı arabirimini arka planda bir C# koduyla işaretlemede tanımlar. Reaktör şablonları, MVU (Model-View-Update) deseni kullanılarak XAML içermeyen saf C# şeklindedir. Ş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 . Etkileşimli seçici ve --list önce WinUI şablonlarını, ardından diğer tüm grupları alfabetik sırada gösterir. Yaygın şablonlar:

Kısa ad	Açıklama
`winui`	En az boş XAML uygulaması (MSIX paketleme)
`winui-navview`	XAML NavigationView başlangıç uygulaması
`winui-tabview`	XAML TabView başlangıç uygulaması
`winui-mvvm`	XAML 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
`reactor`	Deneysel. Blank Reactor uygulaması — saf C#, XAML yok
`reactor-mvu`	Deneysel. MVU desenini gösteren reactor uygulaması
`reactor-navview`	Deneysel. Reactor NavigationView başlangıç uygulaması
`reactor-tabview`	Deneysel. Reactor TabView başlangıç uygulaması

Reaktör şablonları deneyseldir. Api'leri gelecekteki bir sürümde değiştirilebilen veya kaldırılabilen yayın öncesi paketlere Microsoft.UI.Reactor başvurur. winapp newetkileşimli seçicide --list ve içinde bunları işaretler (Deneysel), içinde ayarlar "Experimental": true--jsonve yapı iskelesini yaptıktan sonra bir uyarı yazdırır. Bunlar hiçbir zaman varsayılan şablon olarak seçilmez. Reactor ayrıca .NET 10 SDK veya daha yenisini gerektirir; eski bir SDKwinapp new'da, oluşturamazsınız bir projeyi iskeleye almak yerine ihtiyaç duyduğu sürümle ön hata verir.

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, winui-reactor) kabul edilir. Başka bir yüklü şablon paketi aynı kısa adı (örneğin, reactor öğesinden Microsoft.UI.Reactor.Templates) winapp new kaydederse, yine de diğer diğer adlarından birini kullanarak WinUI paketinin şablonunu oluşturur. Başka bir paket, şablonun sahip olduğu tüm diğer adları kaydederse, winapp new durur ve bu paketi adlandırın. ile dotnet new uninstall <package> kaldırın ve yeniden çalıştırın. 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 (yüklü bir paketi asla eski bir paketle değiştirmez ve akış denetlenemezse başarısız olur) 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.

İlk çalıştırma daha uzun sürebilir: Şablon paketini yüklemek veya güncelleştirmek ya da seçili şablon tarafından kullanılan eksik Windows Uygulama SDK'sı NuGet paketlerini geri yüklemek ek indirmeler gerektirebilir. Bu, yeni bir Windows Uygulama SDK'sı sürümü yayımlandıktan sonra da oluşabilir. yapı iskelesi 10 saniye sonra hala çalışıyorsa, winapp new paketlerin indiriliyor veya geri yükleniyor olabileceğini belirtmek için durum iletisini güncelleştirir.

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

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# 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 [base-directory] [options]

Argümanlar:

base-directory - Geri yükleneceği dizin (varsayılan: geçerli dizin). Ayrıca geçersiz kılmadığı sürece --config-dir nereden winapp.yaml okunup nuget.config okunacaklarını da seçer.

Seçenekler:

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

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ı

.NET projelerde SDK winapp.yaml sürümleri içinde girdi .csproj olarak PackageReference bulunur, bu nedenle winapp restore sizin için çalışırdotnet restore.

Örnekler:

# Restore from winapp.yaml in current directory
winapp restore

# Restore a specific project directory (reads ./my-project/winapp.yaml)
winapp restore ./my-project

Özel ve özel NuGet akışları:

winapp init, restoreve update standart hiyerarşinize nuget.config uygun şekilde NuGet aracılığıyla Windows SDK'sını ve Windows Uygulama SDK'sı paketlerini indirin. Özel akışlar ve yansıtmalar, akış kimlik bilgileri (kimlik bilgisi sağlayıcıları dahil) ve özel globalPackagesFolder hepsi için dotnet restoreolduğu gibi çalışır. Yalnızca kendi yansıtmanızdan geri yüklemek için devralınan <clear /> kaynaklar ve yalnızca sizinkileri ekleyin:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

Uyarı

Yerel projeler için winapp üzerinde çalıştığı dizinden çözümlernuget.config:restoreinit/dizin bağımsız değişkeni, --config-dir verildiğinde, aksi halde geçerli dizin. .NET projelerde kaynaklar bunun yerine projenin kendi nuget.config hiyerarşisinden gelir, çünkü bu ve dotnet add packagedotnet restore kullanımdır, bu nedenle özel akışın yapılandırmasını proje dizinine veya bir ata yerleştirin. --config-dir Projenin geri yükleyemeyeceği sürümleri sessizce seçmek yerine bu hiyerarşinin dışındaki bir raporlanır ve yoksayılır. Bu komutları yalnızca güvendiğiniz dizinlerde çalıştırın. Bu, için dotnet restoregeçerli olan aynı uyarıdır. Birkaç kaynak yapılandırıldığında, her paketi bir akışa sabitlemek için Paket Kaynağı Eşlemesi'ni kullanın.

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. Yayımlanmaya devam eden bir Windows Uygulama SDK'sı sürümü, tüm paketleri kullanılabilir duruma gelene kadar atlanır ve update bunun yerine kullandığı sürümü adlandıran bir not yazdırır. Yeni sürüme geçmek için daha sonra yeniden çalıştırın winapp update .
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

Bir projeden veya hazırlanmış 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)

Projeyi derlemek ve çıktısını tek adımda paketlemek için tek .csproj bir geçiş yapın (proje modu, bkz. Projeyi doğrudan aşağıda paketleme ). Ç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 - Derlemek ve paketlemek için tek .csproj bir dizin (proje modu) veya 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
--no-sign - Herhangi bir proje imzalama yapılandırmasını geçersiz kılarak paketi imzasız olarak teslim edin (örneğin, Mağaza gönderimi veya bir dış imzalama işlem hattı için). veya --certile --generate-cert birleştirilemez.
--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.

Project modu seçenekleri (giriş gerektirir.csproj; klasör/paket/bildirim girişleri için reddedilir):

--configuration <name> (-c) - Derleme yapılandırması (varsayılan: Release)
--arch <arch> - Hedef mimari: x64, arm64veya x86 (varsayılan: geçerli işlem mimarisi)
--framework <tfm> (-f) - Çok hedefli projeler için hedef çerçeve adı
--no-build - Mevcut derleme çıkışını yeniden derlemeden paketleyin
--no-restore - Derlemeden önce projeyi geri yüklemeyi atlayın
--property <name=value> (-p) - Derleme ve değerlendirmeye iletilen MSBuild özelliği (yinelenebilir)

Not: WinUI / EnableMsixTooling.csproj (MSIX araçlı proje modu) için Windows Uygulama SDK'sı bildirimin, giriş noktasının ve PRI oluşturma işleminin sahibidir, bu nedenle --manifest, --executableve --skip-pri reddedilir; projenin giriş noktasını ve projedeki kaynak derlemesini yapılandırın<AppxManifest>. Bu üç seçenek yine klasör girişleri ve genel (MSIX araçları olmayan) .csproj proje modu için geçerlidir.

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

Projeyi doğrudan paketleme

Giriş tek .csprojbir giriş olduğunda, winapp pack projeyi oluşturur (yukarıdaki seçenekleri kullanarak) ve sonuçta elde edilen çıkışı paketler; önce ayrı ayrı derlemeniz veya çıkış klasörünü bulmanız gerekmez. Bu, 'nin proje modunu yansıtır winapp run.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

Hedef mimari , veya geçirmediğinizde --arch yalnız -p RuntimeIdentifier=<rid> bir mimariden gelir --arch(tam RID korunur ve derlemeyi yönetir). hem hem -p RuntimeIdentifier de --arch geçişi bir çakışmadır ve reddedilir.

Projenin paketlenmiş bir uygulama (EnableMsixTooling=true ile Package.appxmanifest); paketlenmemiş uygulama (WindowsPackageType=None) olarak derlenen bir proje olarak derlenip eyleme dönüştürülebilir bir hata raporlamak için winapp pack MSIX bildirimi olmaması gerekir. Klasör, paket ve seyrek bildirim girişleri değişmez.

Project modu tek .msix veya yalnızca .msixbundle mimari oluşturur (bkz. Çoklu mimari paketleri). Mağaza yükleme arşivleri veya kaynak bölme (dil/ölçek) paketleri oluşturmaz: açık -p UapAppxPackageBuildMode=StoreUpload veya -p AppxBundleAutoResourcePackageQualifiers=... bu akışlar için doğrudan yerel SDK paketleme komutunu çalıştırmak üzere bir notla reddedilir.

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:

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

Örnekler:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

Çok mimarili paketler

Birden çok giriş klasörü geçirildiğinde, winapp pack mimari başına bir tane .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:

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

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

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

hata ayıklama kimliği oluştur

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

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

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

Argümanlar:

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

Seçenekler:

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

Ne yapar:

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

Örnekler:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

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ı>). Tek değerli, virgülle ayrılmış bileşenlere sahip bir X.500 DN kabul eder (çok değerli + RDN'ler ve ters eğik çizgi desteklenmez); çıplak adlar CN=<name> olarak otomatik olarak kaydırılır.
--version <version> - Sürüm (varsayılan: "1.0.0.0")
--description <text> - Açıklama (varsayılan: "Uygulamam")
--entrypoint <path> - Giriş noktası yürütülebilir dosyası veya betiği
--template <type> - Şablon türü: packaged (varsayılan) veya sparse
--logo-path <path> - Logo resim dosyasının yolu
--if-exists <Error|Overwrite|Skip> - Bildirim dosyası hedef yolda zaten mevcut olduğunda davranış (varsayılan: Error)

Şablon:

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

Manifesto yer tutucuları

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

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

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

Yer tutucular nasıl çözümlenir:

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

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

Örnekler:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

bildirim ekleme diğer adı

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

winapp manifest add-alias [options]

Seçenekler:

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

Ne yapar:

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

Örnekler:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

manifesto varlıkları güncelle

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

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

Argümanlar:

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

Seçenekler:

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

Açıklama:

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

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

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

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

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

Additionally:

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

ile : --light-image

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

SVG desteği: SVG dosyaları kaynak görüntü olarak tam olarak desteklenir. Bunlar her hedef boyutta doğrudan vektör olarak işlenir ve tüm çözünürlüklerde piksel mükemmel sonuçlar üretir. Dosya, bir veya mutlak width ve height öznitelikler aracılığıyla viewBox kendi boyutunu bildirmelidir; hiçbir değeri olmayan viewBox yüzde genişliği belirli bir boyutu tanımlamaz. Boş varlıklar üretmek yerine ile SVG image has no usable dimensions hiçbiri bildiren bir kaynak ile reddedilir.

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 üç 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 C++ .vcxproj, bir .sln/.slnx çözüm veya bir dizin içeren bir dizindir. winapp run projeyi oluşturur ve hem paketlenmiş hem de paketlenmemiş uygulamaları destekleyerek başlatır. Aşağıdaki Project modu ve C++ projeleri bölümüne bakın.
Tek dosya modu — giriş .NET dosya tabanlı bir.cs uygulamadır. winapp run bunu oluşturur, yönergelerinden #:property bir bildirim oluşturur ve paket kimliğiyle başlatır.

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/.vcxproj/.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.sln/.slnx.csproj.vcxproj//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), .cs .NET dosya tabanlı uygulama (tek dosya modu), bir .csproj veya C++ .vcxproj projesi, bir .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 için çıkış dizini (varsayılan: AppX giriş klasörünün içinde). Varsayılan düzen artık derlemedeki dosyaları kaldırmaz; özel bir dizin ek dosyalar tutar. Temiz bir düzene ihtiyacınız olduğunda yeni bir özel dizin kullanın.
--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. Nadiren gereklidir: zaten OutputType=Exe bu şekilde başlatılan bir uygulama varsayılan olarak. winapp, AppX düzeninde aşamalı olarak bildirimine gerekli uap5:ExecutionAlias olan öğesini ekler, bu nedenle iade edilmiş bildiriminizde değişiklik yapılması gerekmez; uygulamanın kendisini bildireceği diğer ad as-iskullanılır. , , --no-launch--detachveya --without-aliasile --jsonbirleştirilemez.
--without-alias - Başka bir şekilde yürütme diğer adı aracılığıyla başlatacak bir uygulama için AUMID etkinleştirmesini zorla. Ardından konsol uygulaması konsol olmadan çalışır ve bu terminale hiçbir şey yazdırmaz. ile --with-aliasbirleş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. Bu olmadan çalıştırırsanız ve uygulama sıfır olmayan bir kodla çıkarsa, winapp ile --debug-outputyeniden çalıştırmak için bir ipucu yazdırır.
--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. Yerel çalıştırmalar PID'yi yazdırır; hedef çalıştırmaları, kapsamı belirlenmiş ui hedefini yazdırır. JSON, PID ve hedef kapsamı içerir. , , --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.
--on <target> - Konağı derleyin, ardından hedefe kaydolun ve çalıştırın. Şu anda yerel yürütmeye geri dönüş olmadan destekler sandbox. kullanıcı arabirimi komutlarını izlemeden önce kullanın --detach . Korumalı alan --debug-output için paketlenmiş bir uygulama gerekir. Bkz. kurulum, çalışma zamanı desteği ve ayrılmış uygulama ömrü için korumalı alan yürütme Windows.

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.

Yerel AOT: bu özellik grubunu project dosyasının <Project> öğesinin içine ekleyin --aotve ekleyin:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

winapp run . --aot
winapp run . --aot -c Release

--aotx64 ve ARM64 projelerini destekler ve .NET SDK 8.0.300 veya üzerini gerektirir. Projenin AOT yapılandırmasıyla çalışır dotnet publish , ardından bu çıkışı başlatır; tek seferlik geçersiz kılma için kullanın -p PublishAot=true . Ayrı çalışma zamanı sertifikası gerçekleştirmez ve veya --manifestile --no-build birleştirilemez.

Oluşturulan BIR MSIX düzeni olmadan paket kimliği kullanan uygulamalar için projenin yayımlama çıktısını ekleyin Package.appxmanifest veya appxmanifest.xml ekleyin. Winapp, yayımlanan dosyaları bu bildirimle birlikte hazırlar. Her iki ad da varsa, winapp bir ad seçmek yerine durur; eski bildirimi kaldırın ve projeyi yalnızca istenen bildirimi yayımlayacak şekilde yapılandırın.

Project modu seçenekleri (belirtilmediği sürece klasör modunda yoksayılır):

-c, --configuration <name> - Derleme yapılandırması. Varsayılan: Debug. (Tek dosya modunda da kabul edilir.)
--arch <x64|arm64|x86> - Hedef mimari. Varsayılan: geçerli işlem mimarisi. Derleme RID ve Windows Uygulaması Çalışma Zamanı mimarisini belirler ve etkili derleme için gerektiğinde platforma bağımlı eşleşen bir yayımlama profili seçer. (Tek dosya modunda da kabul edilir.)
-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 ve gerekli yayımlama profilini seçebilir. (Ayrıca, dosya tarafından bildirilen bir #:property RuntimeIdentifier öğesini geçersiz kıldığı tek dosya modunda da kabul edilir.)
-f, --framework <tfm> - Çok hedefli projeler için hedef çerçeve adı (örn. net10.0-windows10.0.26100.0). (Tek dosya modunda reddedildi — kullanın #:property TargetFramework=....)
--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. (Tek dosya modunda reddedildi; dosya tabanlı bir .cs uygulama projedir.)
--no-build - Mevcut derleme çıkışını oluşturmayı ve çalıştırmayı atlayın (yine de çıkış özelliklerini değerlendirir). (Tek dosya modunda da kabul edilir.)
--no-restore - Derlemeden veya Yerel AOT yayımlamadan önce geri yüklemeyi atlayın. (Tek dosya modunda da kabul edilir.)
--aot- Projenin yapılandırılmış .NET Yerel AOT yayımlamasını çalıştırın. Etkili PublishAot=truegerektirir. Klasör ve tek dosya modlarında reddedildi.
-p, --property <Name=Value> - Hem derlemeye hem de özellik değerlendirmesine iletilen MSBuild özelliği. Birden çok özellik için yineleyin-p; değerdeki %2C değişmez noktalı virgül veya virgül için veya kullanın%3B. (Ayrıca, ayarlamanın TargetFrameworktek yolu olduğu tek dosya modunda da kabul edilir.)

Derleme çıktısı ve ayrıntı düzeyi: sıradan bir proje çalıştırması kullanır dotnet buildve ardından yerleşik çıkışı değerlendirir. Kimliği doğrulanmış akış URL'lerinden alınan kimlik bilgileriyle çıkış akışını canlı olarak geri yükleyin ve derleyin. ile --aot, winapp kullanır dotnet publish; --verbose yayımla komutunu ve çözümlenen yolları gösterir. Gösterilenleri denetlemek için aşağıdaki ayrıntı seçeneklerini kullanın:

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

Yerel AOT çıktı akışlarını geldikçe yayımlar. altında --json, geri yükleme/derleme çağrıları ve alt çıkış stderr'a gider, böylece stdout saf JSON olarak kalır. altında --quietçağrılar gizleniyor ve dotnet'in sessiz geri yükleme/derleme çıkışı stderr'a yönlendiriliyor, böylece stdout temiz kalıyor. Yerel AOT yayımlama çıkışı da iki seçenek altında stderr'a gider.

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

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

# 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

C++ projeleri (.vcxproj)

.vcxproj Tek çalıştırılabilir uygulaması tek olan bir klasörün veya çözümün üzerine gelin winapp run ve projeyi Visual Studio MSBuild ile derleyip .NET projesiyle aynı şekilde başlatır:

winapp run .\MyApp.vcxproj
winapp run . -c Release --arch arm64
winapp run . --no-build --detach --json

Visual Studio WinUI Boş Uygulama (Paketlenmiş) şablonundan bir WinUI 3 C++/WinRT uygulaması paketlenmiş olarak çalıştırılır. konsol uygulaması veya ile -p WindowsPackageType=Nonederlenmiş bir WinUI uygulaması gibi diğer uygulama projeleri, kendi derledikleri .exeuygulamasından paketlenmemiş olarak çalışır.
Varsayılan olarak geçerli mimari için derlemeler Debug . --arch x64|arm64|x86 veya -p Platform=x64|ARM64|Win32 mimariyi seçer (her ikisini de farklı mimarilerle geçirmek bir hatadır); özel -p Platform bir ad geçirilir.
packages.config Önce NuGet paketlerini geri yükler (ile --no-restoreatlar) ve sabitledikleri Windows Uygulaması Çalışma Zamanı sürümünü yükler. Paketlenmiş uygulamalar, eksik olduğunda yüklenen Hata Ayıklama VC++ çalışma zamanı gibi derleme başvurularının çerçeve paketlerini de alır.
--frameworkve --aot yalnızca .NET projelere uygulayın.
Derleme çıkışı, MSBuild'in uyarılarını ve hatalarını yalnızca oluştururken bir değiştirici ile gösterir; --verbose MSBuild'in tam çıkışını ve tam komutunu gösterir.
Çalıştırılabilir bir C# uygulamasına da sahip olan bir klasör veya çözümde C# uygulaması seçilir; C++ uygulamasını çalıştırmak için kullanın --project <name> . C++ uygulamasının yanındaki C# kitaplıkları ve test projeleri bu şekilde çalışmaz.
C++ projesine başvuran bir C# uygulaması (örneğin yerel DLL) ile dotnetoluşturulamaz. Visual Studio veya MSBuild.exeile derleyin, ardından komutunu çalıştırın winapp run <app>.csproj --no-buildveya çıkış klasörünü ile paketleyinwinapp package <folder>.

Önkoşullar: hedef mimari için MSVC C++ derleme araçları (C++ iş yüküyle masaüstü geliştirme) ve projenin hedef Windows SDK'sı ile Visual Studio 2022 sürüm 17.8 veya üzeri için Visual Studio veya Derleme Araçları. WinUI 3 uygulamalarının C ++ WinUI uygulama geliştirme araçlarına da ihtiyacı vardır; winapp, birkaç yüklemeyle projeyi oluşturabilecek en yenisini kullanır. .NET SDK'sı gerekli değildir. Derleme araçları, platform araç takımı (MSB8020) veya Windows SDK'sı (MSB8036) eksik olduğunda, winapp run komut winget da dahil olmak üzere nelerin yükleneceğini söyler.

Bkz. cpp-winui-app örneği.

Tek dosya modu (dosya tabanlı uygulamalar .NET)

.NET 10, proje dosyası olmadan tek .cs bir dosya çalıştırmanıza olanak tanır ve üst kısımdaki yönergelerle #: yapılandırılır. Bu dosyanın üzerine gelin winapp run ve uygulamayı derleyin, bunun için bir appxmanifest oluşturup paket kimliğiyle başlatın; böylece Windows.ApplicationModel.Package.Current uygulama gerçek bir AUMID ve Başlat menüsü girdisi alır ve yalnızca kimlik gerektiren API'ler (uygulama bildirimleri, ApplicationDatacihaz içi AI) çalışır.

Protokol işleyicileri, dosya ilişkilendirmeleri, paylaşım hedefleri ve başlangıç görevleri gibi kabuk tümleştirmeleri, oluşturulan bildirimin içermediği bildirilen <Extensions> bir girdiye ihtiyaç duyar. Bir bildirim eklemek için kendi bildiriminizi yazın; aşağıdaki Kendi bildiriminizi getirme bölümüne bakın.

winapp run counter.cs

Ya da düz dotnet run olarak çalıştırın— aşağıdaki Ile dotnet runçalıştırılıyor bölümüne bakın.

Bildirim yazmazsınız. Bunun yerine paketi yönergeleriyle #:property açıklayın:

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

Bildirim özellikleri. Tümü isteğe bağlıdır; her biri mantıklı bir varsayılan değere geri döner:

Mülkiyet	Ayarlar	Varsayılan
`WinAppPackageName`	`Identity/@Name` (paket kimliği)	olarak temizlenmiş `[-.A-Za-z0-9]`dosya adı ve dosya yolunun kısa bir karması (`counter.cs` → `counter-a1b2c3d4`)
`WinAppDisplayName`	Başlangıç ve Ayarlar'da gösterilen ad	uzantısı olmayan dosya adı
`WinAppPublisher`	`Identity/@Publisher`	`CN=<your Windows user name>`. Çıplak ad olarak `CN=<name>`sarmalanır.
`WinAppVersion`	`Identity/@Version`	`$(Version)`, normalleştirilmiş (aşağıya bakın)
`WinAppDescription`	Yükleme sırasında ve Ayarlar'da gösterilen açıklama	görünen ad
`WinAppCapabilities`	veya ile `;` ayrılmış olarak bildirme özellikleri `,`	none

Version. Paket sürümü her 0-65535 olmak üzere tam olarak dört sayı olmalıdır. WinAppVersion (veya ayarlamazsanız, standart Version özellik) sığacak şekilde normalleştirilir: herhangi biri -preview/-rc son eki bırakılır ve eksik bileşenler sıfırlarla doldurulur, bu nedenle #:property Version=1.2.3-preview.4 derleme sürümünüzü ve paket sürümünüzü bir arada oluşturur 1.2.3.0 ve ayarlar. Sığdırılmayan bir değer (65535 veya dörtten fazla bileşenin üzerindeki bir bileşen) sessizce değiştirilmek yerine bir hatayla reddedilir .

Yetenekler

Uygulamanız kimlikle tam güven çalıştırır ve bu da yalnızca paketlenmiş bir uygulama gerektiren API'leri karşılar. Ancak bazı API'ler her ne olursa olsun bildirilen bir özellikte geçitlenir; Windows yapay zeka API'leri yaygın bir durumdur. (Protokol işleyicileri ve dosya ilişkilendirmeleri gibi kabuk tümleştirmeleri üçüncü bir durum olduğundan, bunlar <Extensions> için kendi bildiriminizi kullanın.

#:property WinAppCapabilities=systemAIModels

Bildirimden Phi Silica ve diğer cihaz içi model API'lerinin ihtiyacı olan tek şey bu. Bunları ayırarak birkaç tane bildirin:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp, her birini gerçekten gerektirdiği öğeye ve XML ad alanına yazar, bu ad alanını bildirir ve özellik daha yeni bir ad alanına ihtiyaç duyduğunda yükseltir MaxVersionTested . Bu, göründüğünden daha önemli: özellikler birkaç farklı öğeye yayılır ve yukarıdaki aynı liste üç farklı şekle dönüşür —

<systemai:Capability Name="systemAIModels" />
<Capability Name="internetClient" />
<DeviceCapability Name="microphone" />

Winapp'in bildiği adlar sizin için yazılır. Diğer her şey için (kısıtlı küme zaman içinde büyür), ad alanı ön eki ile kendiniz niteler:

Önek	Yayar
`rescap:`	`<rescap:Capability>` — kısıtlı özellikler
`uap:`, `uap6:`, `uap7:`, `uap11:`	`<uap*:Capability>`
`systemai:`	`<systemai:Capability>`
`device:`	`<DeviceCapability>`
`app:`	`<Capability>` varsayılan ad alanında

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Tanınmayan bir çıplak ad, tahmin etmek yerine bu ön ekleri adlandırma hatasıyla reddedilir; yanlış ad alanında yayılan bir özellik bir bildirim oluşturur Windows kaydetmeyi reddeder veya sessizce vermezken kabul eder.

Kendi bildiriminizi getirin

Özelliklerin kapsamayacağı bir şeye ihtiyacınız varsa (protokol işleyicisi, dosya ilişkilendirmesi, yürütme diğer adı) bir bildirim yazar ve winapp run bunu oluşturmak yerine ayrıntılı olarak kullanır. Şu sırayla teslim alınır:

--manifest <path> öğesini seçin.
#:property WinAppManifestPath=<path> öğesini seçin .cs .
Dosyanın yanında yer alan .cs ve adlı <filename>.appxmanifest bir bildirim (örneğin counter.appxmanifest yanında counter.cs).

Yalnızca dosya başına ad otomatik olarak alınır. Bir Package.appxmanifest veya appxmanifest.xml aynı klasördekiler kasıtlı olarak yoksayılır; birkaç .cs dosya bir klasörü paylaşabilir ve paylaşılan bir adı benimsemek bir uygulamayı sessizce başka bir kişinin kimliği altında çalıştırır. Birkaç dosya için bir bildirim kullanmak için, bildirimi veya WinAppManifestPathile --manifest açıkça adlandırabilirsiniz.

Aksi takdirde, derleme çıkışında varsayılan görüntü varlıklarıyla birlikte bir Package.appxmanifest oluşturulur ve her çalıştırmada yenilenir.

Options. Her klasör modu seçeneği çalışır: , , , , --detach, --clean, , --debug-output, --symbols, , --json--args----output-appx-directory--executable--manifest/--unregister-on-exitartı -c/--configuration, --no-build--no-restoreve .-p/--property--without-alias--with-alias--no-launch

Tip

Konsol uygulaması varsayılan olarak terminalinize yazdırılır. AUMID aracılığıyla başlatılan paketlenmiş bir uygulamanın konsolu yoktur, bu nedenle yalnızca konsola yönelik bir uygulama düzgün çalışır ve hiçbir şey yazdırmaz. winapp bunu önler: ile OutputType=Exe bir uygulama, bunun yerine bu terminalin stdin/stdout/stderr öğesini devralan bir yürütme diğer adı aracılığıyla başlatılır. Paket kimliğini almaya devam edersiniz ve bunu istemeniz gerekmez:

winapp run counter.cs

Bunun yerine AUMID etkinleştirmesini zorlamak için geçiş yapın --without-alias ; uygulama konsol olmadan çalışır ve burada hiçbir şey yazdırmaz. Pencereli bir uygulama (WinExe) bir pencere gösterir, bu nedenle AUMID etkinleştirmesini korur; yine de bu terminalde bir tane istiyorsanız geçirin --with-alias . Dosyada her komut satırı yerine seçimi düzeltmek için, bir .csproj komutun kullandığı özelliği ayarlayın:

#:property WinAppRunUseExecutionAlias=false

Winapp'in bildirdiği diğer ad, paket ailesi adından sonra bir winapp- ön ek ile adlandırılır; bu nedenle com.contoso.counter tarafından CN=You yayımlanır winapp-com.contoso.counter_gspb8g6x97k2t.exe. Sondaki bölüm yayımcı karması Windows türetilir, dolayısıyla farklı yayımcılar altında bir adı paylaşan iki uygulama farklı diğer adlar almaya devam eder. Ön ek, gerçek komutların adını temiz tutar: içindeki python.cs bir winapp-… uygulama hiçbir zaman python.exediğer ad alır. Kendi bildiriminizi yazarsanız, orada bildirdiğiniz diğer ad as-is kullanılır ve winapp hiçbir şey eklemez.

Bu yalnızca diğer ad için geçerlidir. Kaydın kendisi paket adında anahtarlanır, bu nedenle farklı bir yayımcı altında aynı WinAppPackageName bildirimi veren ikinci bir uygulamanın çalıştırılması, ilk kaydın yanında oturmak yerine yerini alır. Her iki uygulamanın da aynı anda kaydedilmesini istiyorsanız her uygulamaya kendi adını verin.

winapp run kaydettiğiniz diğer adı yazdırır, böylece karmayı bulmak için hesaplamanız gerekmez.

Diğer ad, PATH'inizde paket kayıtlı kaldığı sürece devam eden bir komutdur. Adın sahibi başka bir paketse, winapp bunu söyler. Sizin için diğer adı çıkardığında, bunun yerine yanlış uygulamayı başlatmak yerine AUMID aracılığıyla başlatılır; veya ile --with-alias#:property WinAppRunUseExecutionAlias=true açıkça bir tane istediğinizde, sessizce başka bir şey yapmak yerine başarısız olur.

Dosya tabanlı bir uygulama kendisini yapılandırdığından iki proje modu seçeneği geçerli değildir . Bunlar, bunun yerine kullanılacak yönergeyi adlandıran bir iletiyle reddedilir:

Seçenek	Bunun yerine kullan
`-f/--framework`	`#:property TargetFramework=net10.0-windows10.0.22621.0`
`--project`	nothing — `.cs` dosya projedir

--arch ve -r/--runtime proje modunda olduğu gibi çalışın. İkisini de geçirmediğinizde, makinenizin mimarisi için winapp derlemeleri oluşturur; bu, bağımsız bir Windows Uygulama SDK'sı uygulamasına ihtiyaç duyar, çünkü bu olmadan SDK ile derlenip AnyCPU başarısız olurWindowsAppSDKSelfContained requires a supported Windows architecture. Dosyadaki A'ya #:property RuntimeIdentifier=win-arm64 uyulur; açık --arch/--runtime bir dosya bunu geçersiz kılar.

Paketlenmiş ve paketlenmemiş her iki iş de tam olarak proje modunda olduğu gibi etkili WindowsPackageType olarak algılandı: varsayılan ayar gevşek bir düzeni kaydeder ve kimlikle başlatır, uygulamayı oluştururken #:property WindowsPackageType=None eşleşen Windows Uygulaması Runtime'ı yükler ve doğrudan başlatır.exe. (Paketlenmiş bir uygulama, yürütme diğer adı veya AUMID etkinleştirmesi aracılığıyla başlatılır; yukarıdaki konsol notunu inceleyin; bu seçenek paketlenip paketlenmediğinden ayrıdır.) Kimlik seçenekleri (, , , , , , --manifest, ), --output-appx-directoryyalnızca paketlenmiş uygulamalara uygulanır. --unregister-on-exit--clean--without-alias--with-alias--no-launch

ile çalıştırma `dotnet run`

Hiç yazmanıza winapp gerek yok. Dosyadan pakete Microsoft.Windows.SDK.BuildTools.WinApp başvurun ve düz dotnet run size aynı paketlenmiş başlatmayı verir:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

Paketin MSBuild hedefleri çalıştırmayı winapp'e yönlendirir. Bu, yeni oluşturulan uygulamayı dotnet run paketler, kaydeder ve başlatır; yeniden oluşturulmaz. Bildirim işleme değişmedi: winapp bunu tam olarak için winapp runolduğu gibi çözümler, bu nedenle #:property WinAppManifestPath=… ve <filename>.appxmanifest yanında .cs her ikisi de onurlandırılır (bkz . Kendi bildiriminizi getirme), dizin genelindeki Package.appxmanifest bir öğe yine yoksayılır ve aksi takdirde yönergelerinizden #:property bir tane oluşturulur ve her çalıştırma yenilenir.

Yeniden yönlendirmenin gerçekleşmesi için iki koşulun tutulması gerekir:

Yönerge	Neden?
`#:package Microsoft.Windows.SDK.BuildTools.WinApp@*`	bu pakette yeniden yönlendirme gönderimini yapan hedefler
`#:property TargetFramework=net10.0-windows…`	düz `net10.0` bir dosya yalnız bırakıldığından paketlenmemiş olarak çalışır

Ekleme #:property WindowsPackageType=None işlemi de dosyayı tek başına bırakır: dotnet run ardından doğrudan kimlik olmadan dosyasını çalıştırır .exe . Önce eşleşen Windows Uygulaması Çalışma Zamanı'nın yüklenmesini istiyorsanız paketlenmemiş yol için kullanınwinapp run.

Yeniden yönlendirmeyi tamamen devre dışı bırakacak şekilde ayarlayın ve başlatmayı WinAppRun* şekillendirmek için Yapılandırma bölümünde açıklanan özellikleri ayarlayın#:property EnableWinAppRunSupport=false; örneğin:

#:property WinAppRunUnregisterOnExit=true

Uygulamayı beklediğiniz zaman paketten çıkarılmış olarak çalıştırırsa dotnet run , MSBuild'e nedenini sorun. Kullanın dotnet build, değil dotnet msbuild — yalnızca dotnet build dosya tabanlı bir uygulamanın derlediği sanal projeyi sentezler:

dotnet build counter.cs -t:WinAppRunSupportInfo

Tek dosya modu, .NET SDK 10.0.300 veya üzerini gerektirir.

Kayıt, çalıştırmadan sonra devam eder. winapp run counter.cs uygulama çıktıktan sonra, klasör ve proje modu gibi kayıtlı paketi bırakır; bu nedenle LocalState devam eder ve aynı dosyayı yeniden çalıştırmak kayıtları toplamak yerine aynı kimliği yeniden kullanır. winapp, bir uygulamayı ilk kaydedişinde .cs bunu söyler ve winapp unregister kendisini alır:

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.csbildirim yolu gerektirmez: Dosyanın değerlerini aynı şekilde run değerlendirir ve yalnızca o dosyanın #:property derleme çıkışından kayıtlı bir paketi kaldırır. Geçirmediğiniz --forcesürece farklı bir klasörden kaydedilen aynı adlı uygulama reddedilir. Çalıştırma, kimliği veya düzeni şekillendiren bir seçenek kullandıysa, aynı seçeneği öğesine unregistergeçirin:

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-p, dosyanın kendi yönergelerini geçersiz kılar ve Directory.Build.props can anahtarının $(Configuration).csWinAppPackageName yanındaki veya $(RuntimeIdentifier) öğesini geçersiz kılar; böylece bunların her biri hangi paketin kaydedileceğini değiştirebilir.

SDK'nın geçici çıkışı temizlendikten sonra, winapp unregister counter.cs artık kaydın bu dosyadan geldiğini onaylayabilir ve bu kaydı atlar; dosyaları gitmiş olan kayıtları temizlemek veya --force yine de belirli bir kaydı kaldırmak için kullanınwinapp unregister --prune. çalıştırması kullandıysa --output-appx-directory, düzeni tanıyabilmesi için aynı dizini 'ye unregister geçirin.

Aynı durum özel çıkış yolu için de geçerlidir: sahiplik SDK'nın standart <root>\bin\<configuration> düzeninden doğrulanır, bu nedenle ile oluşturulan bir çalıştırma kaynak dosyasıyla -p OutputPath=<somewhere-else> eşleştirilemez. unregister daha geniş bir dizinde tahmin etmek yerine bunu atlar; düzeni ile --output-appx-directoryadlandırın veya kullanın --force.

Tek dosyalı örnekler:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

Uyarı

Varsayılan kimlik, dosyanın yolunun kısa bir karması içerir, counter.cscounter-a1b2c3d4 bu nedenle farklı klasörlerdeki iki counter.cs dosya farklı uygulamalardır ve kendi ayarlarını ve LocalState'yi tutar. Karma yoldan türetilir, bu nedenle düzenlemelerden ve yeniden çalıştırmalardan devam eder ve yalnızca dosyayı taşırsanız değişir. Kararlı bir kimliği kendiniz seçmek için ayarlayın #:property WinAppPackageName=<name> ; izin veren şekilde normalleştirilir Identity/@Name ; dışındaki [-.A-Za-z0-9] karakterler bırakılır, 3 karakterden kısa adlar ile 1doldurulur ve sonuç 50 karakterle eşlenir, böylece My App olarak MyAppkaydedilir. Başlat menüsü ve Ayarlar her iki şekilde de kimliğinizi değil (varsayılan: dosya adı) gösterilir WinAppDisplayName . Kimliğin kapsamı her zaman kullanıcı hesabınıza göre belirlenmiştir, bu nedenle aynı makinedeki başka bir kullanıcıyla hiçbir zaman çarpışmaz.

MSBuild özellikleri (NuGet paketi):

Microsoft.Windows.SDK.BuildTools.WinApp NuGet paketini kullanırken dotnet run otomatik olarak winapp run çağırır.

Sonrasında dotnet run yazılan her şey, tam olarak paket olmadan olduğu gibi uygulamanıza geçirilir. Başlatıcıyı aşağıdaki MSBuild özellikleriyle yapılandırın:

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

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`	uygulamadan çıkarılır	AUMID etkinleştirmesi yerine yürütme diğer adıyla başlatın. Sol kümeyi açmadan, winapp bunu çıkarsar: Bir konsol uygulaması, çıkışı terminale ulaşmak için bir diğer ad kullanır, pencereli bir uygulama AUMID kullanır. Kendiniz karar vermek için veya `false` ayarlayın`true`.
`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 `WinAppRunDebugOutput`bir 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 `.exe`fazla 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`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`
`WinAppRunDetach`	`WinAppRunNoLaunch`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`

WinAppRunUseExecutionAlias kasıtlı olarak bu listede değil , her iki yönde de. false başlatma olmayan ve ayırmanın zaten kullandığı AUMID etkinleştirmesini ister; true herhangi biri ayarlandığında uygulanmaz çünkü yürütme diğer adının izlenen, çalışan bir işleme ihtiyacı vardır. Bu nedenle, iade <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> eden bir proje hala altında dotnet run -p:WinAppRunDetach=truetemiz bir şekilde çalışır ve başarısız olmak yerine AUMID aracılığıyla başlatılır.

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

Argümanlar:

input- Paketin kaydı kaldırılacak .NET dosya tabanlı uygulamanın (tek .csbir ) yolu. Kimliği aynı şekilde winapp run çözümlenir ( uygulamanın bir bildirimi varsa, başka bir deyişle değerlerinden geliyorsa) yazılmış bir bildirimden #:property , bu nedenle bildirim yolu gerekmez. Geçerli dizindeki bir bildirimi kullanmak --manifest veya otomatik olarak algılamak için atlayın. paketi farklı bir şekilde adlandıran ve farklı bir pakete çözümleyebilen ile --manifestbirleştirilemez.

Seçenekler:

--manifest <path> - Package.appxmanifest yolu (varsayılan: geçerli dizinden otomatik algılama)
--force - Yalnızca yerel kaydı kaldırmak için yükleme konumu dizin denetimini atlayın ve paket farklı bir proje ağacından kaydedilmiş olsa bile kaydını kaldırın. ile --onreddedilir; hedef sahiplik denetimleri atlanamaz.
--on <target> - Bu makineden değil, winapp'e ait eşleşen geliştirme kaydını kaldırın sandbox. Bir bildirim gerektirir ve desteklemez --force. Bkz . Korumalı alan uygulaması temizleme.
--prune - Dosyaları gitmiş olan tüm geliştirme modu kayıtlarını kaldırın. giriş, --manifest, , --arch--runtime--property--configurationveya --output-appx-directoryile birleştirilemez.
-p, --property <Name=Value> - Dosya tabanlı bir .cs uygulamanın kimliği çözümlendiğinde kullanılan MSBuild özelliği. Tekrarlanabilir. Komut satırı özelliği dosyanın kendi #:property yönergelerini geçersiz kıldığından, kullanılan çalıştırmanın aynı kimlik etkileyen özelliklerini (örn. -p WinAppPackageName=...) geçirin. Yalnızca giriş .cs için geçerlidir.
-c, --configuration <name> - Dosya tabanlı bir .cs uygulamanın kimliğini çözerken kullanılan derleme yapılandırması. Varsayılan: Debug. Kullanılan çalıştırmanın aynı yapılandırmasını geçirin: Directory.Build.props öğesinin .cs yanındaki veya WinAppManifestPath koşullu olarak üzerinde $(Configuration)ayarlanabilirWinAppPackageName. Yalnızca giriş .cs için geçerlidir.
--arch <x64|arm64|x86> - Dosya tabanlı bir .cs uygulamanın kimliğini çözümlerken kullanılan hedef mimari. Varsayılan: geçerli işlem mimarisi. Kimlik de anahtarı $(RuntimeIdentifier)alınabileceğinden, kullanılan çalıştırmanın aynı mimarisini geçirin. Yalnızca giriş .cs için geçerlidir.
-r, --runtime <rid>- Dosya tabanlı bir .cs uygulamanın kimliği çözümlendiğinde kullanılan hedef .NET çalışma zamanı tanımlayıcısı (örneğinwin-x64). Yalnızca mimarisi kullanılır ve geçersiz kılar --arch. Yalnızca giriş .cs için geçerlidir.
--output-appx-directory <path> - Paketin kaydedilildiği AppX düzen dizini. Yalnızca çalıştırma kullanıldığında --output-appx-directorygereklidir, çünkü çalıştırılan paket kaydındaki hiçbir şey düzenini oluşturmamıştır.
--json - Çıktıyı JSON olarak biçimlendirme

Ne yapar:

Paket adını belirler— dosyanın çözümlenen kimliğinden .cs veya bildirimi okuyarak
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 , (sürece --force) adlı uygulamaya ait olduğunu doğrular; yükleme konumu tanımladığınız bir dizinin altında bulunmalıdır: .cs dosyanın kendi derleme çıkışı, bildirimin dizini, geçerli dizin veya açık --output-appx-directorybir . Tek başına kimlik sahiplik kanıtı olmadığından yükleme konumu çözümlenemeyen (dosyaları silinmiş) bir paket atlanır: her iki ayarda #:property WinAppPackageName=counter da aynı kimliği farklı klasörlerden kaydeden iki uygulama. Dosyaları gitmiş olan kayıtları temizlemek için kullanın --prune .
Eşleşen paketlerin kaydını kaldırma

Ölü kayıtları temizleme (--prune):

Kayıt, dosyalarından daha uzun süre yaşar. Derleme çıkışını, proje ağacını veya (dosya tabanlı bir uygulama için) silme işlemi, Windows temizlemesine %LOCALAPPDATA%\Tempizin verir ve paket kayıtlı kalır: Windows kimliği ve Başlat menüsü girişini korur, ancak etkinleştirme sessizce hiçbir şey yapmaz. Bunlar görünmez bir şekilde birikiyor.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

Yalnızca geliştirme modu kayıtları dikkate alınır ve her biri tam paket adıyla kaldırılır, bu nedenle canlı bir konumdan yüklenen aynı adlı pakete dokunulmaz. Eksik yükleme konumu genellikle silinmiş bir klasör olduğundan, ancak bağlantısı kesilmiş bir ağ paylaşımından veya çıkarılabilir sürücüden kaydedilmiş bir paketi de açıkladığı için istem mevcut; onaylamadan önce listeyi gözden geçirin.

Örnekler:

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

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

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

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

# Remove every dev registration whose files are gone
winapp unregister --prune

# 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>- Bildirimin Identity/@Publisheriçindeki sertifika publisher ayıklayın. Yalnızca yayımcı gereklidir, bu nedenle kısmen tamamlanmış bir bildirim çalışmaya devam eder. Bildirimin kullanılabilir yayımcısı yoksa, komut varsayılan yerine başarısız olur, bu nedenle sertifika hiçbir zaman bildirimle sessizce uyuşmaz.
--publisher <name>- Sertifika için Publisher. Sertifika oluştururken bu seçenek önceliklidir --manifest; bildirim yayımcısını kullanmak yerine açıkça boş bir değer başarısız olur. Tam X.500 ayırt edici adını (örneğin, CN=Contoso, O=Contoso Ltd, C=US) veya olarak otomatik olarak CN=<name>sarmalanan çıplak bir adı kabul eder. Bileşenler tek değerli ve virgülle ayrılmış olmalıdır; MSIX bildirim yayımcısı bunları temsil edemeyeceğinden çok değerli RDN'ler (CN=Foo+OU=Bar) ve ters eğik çizgiler desteklenmez. Yanlış biçimlendirilmiş ayırt edici ad (örneğin CN= , veya CN=A,,O=B) sıfır olmayan bir çıkışla ve bildirim yayımcısıyla hiçbir zaman eşleşmeyen bir sertifika üretmek yerine sorunu adlandıran bir hatayla reddedilir.
--output <path> - Çıkış sertifikası dosya yolu (mutlak ve göreli yolları destekler)
--password <password> - Sertifika parolası (varsayılan: password, genel olarak bilinir — bkz. JSON çıktısı ve Güvenlik)
--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.

JSON çıkışı:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ],
  "skipped": false
}

publisher , sertifikanın verildiği görünen ad ve subjectName tam ayırt edici addır. defaultPasswordIsPublic bir sertifika oluşturulduğunda her zaman bulunur. olduğunda true, .pfx herkesin tahmin ettiği bir parolayla korunur, bu nedenle sertifikanın yalnızca kendi makinelerinizde kalan derlemeleri imzalaması gerekir; bir betik sertifikayı başka bir şeye teslim etmeden önce bunu denetleyin. warnings metinle aynı açıklamayı taşır ve raporlanması gereken bir şey olmadığında atlanır. publicCertificatePath yalnızca ile --export-cergörünür.

ile --if-exists skip, sertifika dosyası zaten mevcut olduğunda komut bu dosyayı dokunulmadan bırakır ve yalnızca yolunu döndürür:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "skipped": true
}

Diğer alanları okumadan önce denetleyin skipped . Mevcut sertifikayı incelemek için komutunu çalıştırın winapp cert info.

sertifika bilgileri

PFX veya CER 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 veya CER)

Seçenekler:

--password <password> - Genel CER için yoksayılan 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> <cert-path> [options]

Argümanlar:

file-path - İmzalayacak MSIX paketi veya yürütülebilir dosyası yolu
cert-path - İmzalama sertifikasının yolu (.pfx)

Seçenekler:

--password <password> - Sertifika parolası (varsayılan: "parola")
--timestamp <url> - RFC 3161 zaman damgası sunucusu URL'si

Örnekler:

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

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --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:

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

İmza doğrulama

Derleme araçları NuGet'ten indirilip yürütülür, bu nedenle winapp her birini çalıştırmadan hemen önce geçerli bir Microsoft Authenticode imzası olup olmadığını denetler. Sertifikanın Microsoft Corporation'ın imza kuruluşu olarak ad vermesi gerekir. Bu, , packageve signdahil olmak üzere toolbir SDK aracına kabuk oluşturan her komut için geçerlidir. Denetim başarısız olan bir araç çalıştırılmaz:

'mt.exe' is not validly signed by Microsoft, so it was not run (C:\...\mt.exe).

Burada hata olması, disk üzerindeki dosyanın yayımlanan Microsoft olmadığı anlamına gelir; çoğu zaman bozuk veya kısmi bir indirmedir. Paketi NuGet önbelleğinden silin ve winapp'in yeniden indirmesi için komutu yeniden çalıştırın.

Winapp daha sonra aracı çalıştığı sürece açık tutar, bu nedenle işaretlediği dosya Windows yüklenir. Aracı yerinde tutamıyorsa, şu iki durumda da çalıştırılmaz:

'mt.exe' could not be held open for verification, so it was not run (C:\...\mt.exe).

Dosyayı kullanan her şeyi kapatın (virüsten koruma taraması veya açık düzenleyici her zamanki nedendir) ve komutu yeniden çalıştırın. Araç kullanımda değil de gitmişse paketi NuGet önbelleğinden silip winapp'in yeniden indirmesini sağlayın.

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ı

target

Komutları çalıştırın, dosyaları kopyalayın, durumu inceleyin veya tüm konuk masaüstünü yakalayın.

Her fiil ilk bağımsız değişkeni olarak alır sandbox . snapshotdışında, bu komutlar Korumalı Alanı hazırlayabilir veya başlatabilir. Önkoşullar, izinler, yaşam döngüsü ve kurtarma için bkz. Windows Korumalı alan yürütme.

target exec

Konuk kullanıcı olarak bir komut çalıştırın.

winapp target exec <target> [--cwd <path>] [--json] -- <executable> [arguments...]
winapp target exec sandbox -- dotnet --info

Bağımsız değişkenler, sınırlarını koruduktan sonra -- . Standart akışlar ve konuk işleminin çıkış kodu iletilir; bu tam bir terminal değildir. --json , alt komutun stdout değerini değiştirmeden stderr üzerinde winapp hatalarını biçimlendirır. Bir hedef hatayı uygulamanın kendi çıkış durumundan ayırmak için yapılandırılmış error.code değerini kullanın.

Açık WINAPP_UI_WORKFLOW_ID bir komut tarafından yapılan konuk kullanıcı arabirimi çağrılarını da gruplar; bkz . Korumalı alan kullanıcı arabirimi koordinasyonu.

hedef gönderme ve hedef çekme

Fiil tarafından adlandırılan yönde bir dosya veya dizin kopyalayın.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

Hedef yollar, hedefin yönetilen çalışma alanına göredir; mutlak, kök ve UNC hedef yolları reddedilir. Dosya hedefi, dosya adını içerir. Bkz. Dizin düzeni, bağlantı işleme ve kopyalanan betiği çalıştırma için komutları çalıştırma ve dosyaları kopyalama .

hedef anlık görüntü

Korumalı Alan başlatmadan hazır olma durumunu, dağıtımları ve konuk pencerelerini bildirin.

winapp target snapshot <target> [--json]
winapp target snapshot sandbox

Bir istemciyi yeniden bağlamaz veya aracıyı onarmaz. Korumalı Alan çalıştırma işlemi başarılı bir sonuç değildir, hata değildir. Hazır olma durumunu ve işlem kimliklerini yorumlamak için bkz. Korumalı Alanı İnceleme .

hedef ekran görüntüsü

Konuk masaüstünü, uygulama seçicisi veya konak penceresi kenarlıkları olmadan konak PNG'sı olarak yerel piksel boyutunda yakalayın. --json konuk koordinat kaynağını bildirir.

winapp target screenshot <target> [-o <host-path>] [--json]
winapp target screenshot sandbox -o .\sandbox.png

Bunun yerine uygulama penceresi için kullanın ui screenshot --on sandbox -a <app> . İstemci gereksinimleri, odak sınırlamaları ve çıkış işleme için ekran görüntüleri ve kayıtlar bölümüne bakın.

hedef kayıt

Konuk masaüstünü H.264 MP4'e kaydedin. Kayıt tamamlandıktan sonra konak video ve çerçeve dosyaları gelir; JSON ve çerçeve bildirimi, ölçeklendirme veya doldurmayı açıklar.

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

süre, çerçeve, üzerine yazma ve sonuç seçeneklerini ui recordkullanır, ancak tek bir uygulama yerine masaüstünü yakalar. Katılımsız CLI kullanımı için pozitif --duration-sec bir tercih; npm yardımcısı gerektirir durationSec. Kısmi kanıt ve yakalama hazırlığı hataları için bkz. Korumalı alan yakalama .

find-ui

Aracı öncelikli. find-ui öncelikli olarak yapay zeka kodlama aracıları için oluşturulur; aracının gerçek bir şekilde çekmesine olanak tanır ve winUI işaretlemesini icat yerine sevkiyat galerilerinden derler ve --json her sonucu (ve her hatayı) makine tarafından okunabilir hale getirir. El ile yazıldığı gibi çalışır.

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

Galeri, Toolkit ve Reactor corpora CLI içinde sevk, bu nedenle find-ui hiçbir ağ erişimi ile çalışır — bir aracı korumalı alanda ilk çalıştırmada veya engelleyen raw.githubusercontent.combir kurumsal proxy arkasında dahil olmak üzere. GitHub ulaşıldığında, CLI ondan yenilenir ve kullanıcı <global .winapp>/cache/find-uibaşına sonucu altında önbelleğe alır; yerleşik corpus yalnızca bir zemindir, hiçbir zaman tavan değildir. Önbelleğe alınan veriler en fazla 24 saatte bir veya isteğe bağlı olarak ile --refreshyenilenir.

Yerleşik corpus, kararlı bir sürüm oluşturulduğunda GitHub'den yeniden getirilir ve başarısız olan bir yenileme eski verileri sessizce göndermek yerine sürüm derlemesini durdurur; fırıncı aynı kod yolunun --refresh kullandığı şekilde getirir, bu nedenle orada bir hata olması canlı yenilemenin de bozulduğunu ve göndermeden önce araştırmaya değer olduğu anlamına gelir. Bir yayın daha önce kaydedilmiş corpus'a karşı kesilebilir, ancak yalnızca açık bir geçersiz kılma olarak. Sonuçlar Gallery/Toolkit/Reactor corpora'nın yerleşik kopyasından sunulduğunda, find-ui stderr ve --json çıkış taşımalarında "corpus": "embedded" bunu söyler (diğer değerler: "network" yeni getirme için, "cache" yerel önbellek için). Seçilen çekirdek desenleri CLI'da derlendiğinden ve hiçbir zaman getirilmediğinden, yalnızca çekirdek isteği (--source coreveya tüm çekirdek desenleri "embedded" olan bir --id küme) raporlar; değiştiremediği için --refresh eskime bildirimi yazdırmaz. Alan corpus her sonuç sunulduğunda raporlanır; yalnızca hiçbir korpus yüklenemediğinde yoktur.

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

İlgili:find-ui WinUI örneklerini arar; bir proje başvurusunu API yüzeyinde (türler, üyeler, numaralandırmalar) aramak ve winapp ui searchçalışan bir uygulamanın kullanıcı arabirimi ağacında arama yapmak için kullanınfind-api.

find-api

Aracı öncelikli. find-api öncelikli olarak yapay zeka kodlama aracıları için oluşturulmuştur. Api yüzeyinde oluşturulan kodun, modelin yeniden toplaması yerine bir projenin aslında başvurmuş olduğu ve --json eksik sembollerdeki sıfır olmayan çıkış kodlarının, bir aracı geçidi kod oluşturmasının yanıta izin vermesine neden olur. El ile yazıldığı gibi çalışır.

Başvurulan .winmd/.dll meta verilerden çözümlenen bir projede kullanılabilen Windows/WinRT API yüzeyini (türler, üyeler, sabit listeleri, ad alanları) arayın ve inceleyin. Çıplak form aramaları; alt fiiller belirli bir türe, ad alanına veya dizinin kendisine detaya gitme.

winapp find-api "<query>" [options]
winapp find-api [command] [options]

Dizin, ilk kullanımda projenin geri yüklenen NuGet/SDK paketlerinden (aracılığıyla project.assets.json) oluşturulur ve proje geri yüklendiğinde otomatik olarak yenilenir. Genel .winapp önbellek (cache/find-api/) altında yer alır ve projeler arasında paylaşılır. Önce projeyi geri yükleyin (winapp restore veya dotnet restore).

Her eşleşme, ad alanının altında onu getiren paketle ve ne yaptığının tek satırlık bir özetiyle listelenir, bu nedenle ikinci members bir çağrı olmadan bir sonuç kullanılabilir:

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

Ayrıca, her ad alanını destekleyen disk içi önbellek dosyasını yazdırmak için ekleyin --verbose . Bu, eski veya beklenmeyen bir dizini tanılarken kullanışlıdır.

Hiç sorgu olmadan çalıştırmak winapp find-api kısa bir kullanım özeti yazdırır ve çıkışlar 0 oluşturur; hiçbir şey bulan bir arama değil, yardım isteğidir.

Kapsam. Her yanıt, içinde ve metin çıkışında --json not olarak scope bildirilen tam olarak bir kapsamdan gelir:

project - geçerli dizindeki (veya --project / --project-dir) proje. Windows SDK'sını, Windows Uygulama SDK'sı ve projenin kendi NuGet paketlerini kapsar. Windows Uygulama SDK'sı meta verileri, projenin başvurdığı yayındır: Makinede daha yeni bir Windows Uygulaması Çalışma Zamanı yüklüyse, find-api projenin derlenemeyeceği türleri onaylamak yerine uyarır ve dışarıda bırakır.
sdk- makine genelinde Windows SDK + Windows Uygulama SDK'sı meta verileri, geçerli dizin proje veya çözüm içermediğinde otomatik olarak kullanılır. Bu, herhangi bir proje mevcut olmadan önce API'leri keşfetmek için kullanılabilir hale gelir find-api ve ağ erişimi gerekmez. Kasıtlı olarak üçüncü taraf NuGet paketlerini içermez, bu nedenle Topluluk Araç Seti'nden (örneğin) bir tür bu kapsamda bulunmaz.

Proje içermeyen ve çözüm içermeyen bir dizinden gelen sorgu, hiçbir zaman kapsam tarafından sdk yanıtlanır; paylaşılan önbellekte hangi proje dizine alınırsa dizine alınırsa o zaman sonuçlar hiçbir zaman ilgisiz genel duruma bağımlı olmaz. Projenin içinden SDK kapsamını açıkça seçmek ve winapp find-api refresh --project sdk yeni bir Windows SDK yükledikten sonra yeniden oluşturmak için geçirin--project sdk.

Çözüm dizinleri. Yanında proje dosyası olmayan bir .sln/.slnx dizininden, çözümün derledikleri projeler kapsam yerine sdk yanıtlar oluşturur; isteğe bağlı olarak dizinlenirler, bu nedenle NuGet paketleri dahil edilir. Çözüm birden fazla dizinli proje oluşturduğunuzda, sorgu bunları listeler ve birini seçmek yerine ister --project <name> .

Komut:

(çıplak)find-api "<query>" ["<query>"...] - Arama türü ve üye adları, belgelenmiş özetlerine geri döner ve ad alanına göre gruplandırılır
members <type> [<type>...] [--filter <text>] - Bir türün özelliklerini, olaylarını ve yöntemlerini listeleyin (imzalarla bildirilen üyeler, tür bildirilerek özetlenen devralınan üyeler)
check-property <type> <property> [<property>...] - Özelliklerin bir tür üzerinde mevcut olduğunu doğrulayın (eksikse sıfır olmayandan çıkar). Salt okunur bir özellik , düz ✅yerine ️ ve "salt okunur, atanamaz" ile ⚠bildirilir, bu nedenle gibi ActualWidth bir özellik ayarlayabileceğiniz bir şeyle karıştırılmaz. Özellik adları büyük/küçük harfe duyarlı olarak eşleştirilir, çünkü C# ve XAML şunlardır: check-property Button background sıfırdan çıkar ve gerçekten yazamayacağınız bir adı raporlamak yerine yakın bir eşleşme olarak sunar Background .
enums <type> [<type>...] [--filter <text>] - Bir sabit listesinin değerlerini listeleme (tür bir sabit listesi olmadığında sıfır olmayandan çıkar)
packages - Paket başına tür/üye sayılarıyla dizine alınan meta veri paketlerini listeleme
stats - Toplam dizin istatistiklerini göster (paketler, ad alanları, türler, üyeler, .winmd dosyalar)
refresh [--scan] - Bir projenin dizinini yeniden derleyin (--scan dizinin altındaki her projeyi dizinler). ile --project <name>, geçerli dizine dizin oluşturmak yerine tek dizinli projeyle eşleşen bir ad başarısız olur.

Batching.search, members, enumsve check-propertytek bir çağrıda birden çok konuyu kabul edin. Yapay zeka aracısı için bu en büyük maliyet koludur: Aramanın marjinal maliyeti, yükün boyutuna göre değil gidiş dönüş (her aramanın tüm konuşmayı yeniden göndermesi) tarafından yönetilir, dolayısıyla on soruyu yanıtlayan bir arama on çağrıdan çok daha ucuzdur.

Tek bir konu, hem metinde --jsonhem de içinde her zaman sahip olduğu yük şeklini döndürür.
İki veya daha fazla konu, içinde bir zarf döndürür; { "count": N, "results": [ ... ] }--jsonher öğe normal tek konu yükü olur; check-property ekler missingCount. Metin çıkışı, her konuyu bir kapsam üst bilgisi altında sıralı olarak işler.
check-property özellikleri tek bir tür üzerinde toplu olarak oluşturur: ilk bağımsız değişken türüdür ve bir özellik sonrasındaki her bağımsız değişkendir. Toplu iş modunda, var olan bir özellik tek ✅ bir satır yazdırır; tam eksik ayrıntı yalnızca olmayanlar için yazdırılır.
Toplu işlem yalnızca herkonu çözümlenip bulunduysa çıkar0; bu nedenle bir toplu iş kod oluşturma işleminin açık olması için güvenlidir.

Arama derecelendirmesi. Bir tür adıyla tam olarak eşleşen bir sorgu, kısmi eşleşmelerin önünde sıralanır ve birkaç ad alanı tarafından kısa bir ad paylaşıldığında yalnızca tam ad çakışmaları belirsiz olarak listelenir; benzer NavigationView şekilde adlandırılmış bir simge içeren her ad alanı yerine tam türü tanımlayan birkaç ad alanını bildirir. Belirsizlik listesi öğesine uyar --maxve normal sonuçlar hala altında yazdırılır.

names.members, check-propertyyazın ve enums kısa bir ad (NavigationView) veya tam olarak nitelenmiş bir ad (Microsoft.UI.Xaml.Controls.NavigationView) kabul edin. Modern bir tür ve eski Windows.* UWP ikizi tarafından kısa bir Microsoft.* ad paylaşıldığında, Microsoft.* tür yanıtlar (Windows Uygulama SDK'sı bir uygulamanın kullandığı projeksiyondur) ve çözümlenen tam ad her zaman gösterilir. Diğer tüm çakışmalar sıfır olmayandan çıkar ve tahmin etmek yerine adayları listeler.

Yöntem imzaları. bir imza, çağrıyı yazdığınız gibi yazdırılır: bir örnekte değil türünde çağırdığınız bir yöntem ile staticgösterilir ve gerçekten ihtiyaç duyduğu anahtar sözcükle bir başvuru parametresi gösterilir: out, in, veya ref. Bu nedenle TryGetValue , yazıldığı gibi derlenen öğesini okur Boolean TryGetValue(String key, out String value).

Seçenekler:

--max <n> - Ad alanı gruplandırılmış arama sonuçlarının en fazla sayısı (varsayılan 5; yalnızca arama). Ayrıca belirsizlik listesini de kapsadığından, birçok ad alanında çakışan kısa bir sorgu okunabilir kalır.
--filter <text> - Ve üzerinde membersenumsbir döküm daraltın: üye/değer adında büyük/küçük harfe duyarlı olmayan alt dize eşleşmesi. En iyi yüzlerce üyesi olan türlerde kullanılır. Çoğu sabit listesi tam dökümü için yeterince küçüktür (hatta Symbol, 197 değerlerinde WinUI'deki en büyük), bu nedenle bunları filtrelemek genellikle ikinci bir tahminde dikkate aldıktan sonra tasarruf etmekten daha pahalıya mal olur. Aynı komutu hiçbir zaman farklı filtre metniyle yeniden çalıştırmayın; bir kez dökümünü alıp okuyun.
--all - üzerinde memberstam yüzeyi listeleyin: devralınan üyeler için tam imzaların yanı sıra, tümü filtrelenmemiş bir dökümü atlayan bağımlılık özelliği tanımlayıcı statikleri ve üye başına açıklamalar (aşağıdaki listeleme boyutuna bakın). --verbosebunu ima eder; ile birleştirilemeyen --verboseve istediğiniz --jsonzaman kullanın--all.
--scan - Dizin altındaki her projeyi özyinelemeli olarak bulma ve dizinleme (refresh yalnızca)
--project <name>- Project sorgulamak (adla .csproj/.vcxproj eşleşir) veya sdk makine genelindeki Windows SDK kapsamını sorgulamak için
--project-dir <path>- Sorgulanacak dizini Project (varsayılan olarak geçerli dizindir). Var olmayan bir yol bir hatadır; hiçbir zaman kapsamdan sdk sessizce yanıtlanmaz.
--json - stdout üzerinde makine tarafından okunabilir bir yük yayma (her fiil tarafından desteklenir). Sorgu yükleri , ( veya ), ve (SDK kapsamı için yok) yoluyla scope yanıt veren dizini tanımlar; proje adları dizinler arasında benzersiz değildir ve güvenilir kimlik de projectDir öyledir.projectDirprojectNamesdkproject 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

Örnekler:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

Uygulandığında--filter, çıkış yine de filtrelenmemiş toplamı (totalValuesveyatotalEvents//totalPropertiestotalMethods içinde--json) bildirir, bu nedenle dar bir görünüm hiçbir zaman küçük bir API ile karıştırılmaz. Hiçbir şey eşleşmeyen bir filtre yine de çıkar 0 ve bunu açıkça söyler; "filtrenizle eşleşen bir şey yok", "böyle bir tür yok" değil.

Listeleme boyutu. Filtrelenmemiş members liste pahalı bir şekildir; members Button 288 üyeyi kapsar ve bunların 280'i 6 temel türden devralınır. Filtrelenmemiş çağrı bir yönlendirme sorgusudur ("bu tür nedir, kabaca ne yapabilir?"), bu nedenle hiçbir şeyin yazılmaması gereken bölümleri yanıtlar ve atlar:

Devralınan üye imzaları — devralınan üyeler tür bildirilerek gruplandırılır ve yalnızca ada göre listelenir, dolayısıyla devralınan yüzeyin şekli 280 tam imza olmadan da görünür.
Bağımlılık-özellik tanımlayıcı statikleri (BackgroundProperty) — Tipik bir WinUI denetiminin özelliklerinin 28%. Bu kişiler atanmamış olarak öğesine GetValue/SetValuegeçirilecek şekilde mevcut.
Üye başına açıklamalar — YÜKÜn yaklaşık 16% XML-doc sürümü.
içindeki çevresi --jsontarafından örtülen alanlar: kind (içereneventspropertiesmethods// dizi tarafından örtülür), returnType (baştaki belirteci signature) ve inherited false olduğunda (tarafından declaringTypeörtülür).

Atlanan her zaman bildirilir (hiddenDependencyProperties, descriptionsOmitted, ve içindeki --json; hint metinde "Atlanan:" satırı) ve toplamlar yine de türün tamamını açıklar. --all Hem hem de --filter tam imzalar ve açıklamalar içeren tam yüzeyi görün, bu nedenle members Button --filter BackgroundProperty tanımlayıcıyı bulur ve members Button --filter Click yine de devralınan imzayı döndürürClick. üzerinde samples/winui-appölçülür, bu 91.954 ile 10.567 karakter (−88,5%) arasında sürerken members Button --json , çıkış --filter ve --all bayt özdeş olur.

Sorgu nasıl eşleştirilir? winapp find-api "language model" yukarıdaki dereceler LanguageModel , türleri dizine eklendiğinde projenin dışında da dahil olmak üzere, sözcükleri ad alanlarına ve üyelere dağılmış olan eşleşmeleri gösterir. Arama sözcük temellidir, anlamsal değildir: herhangi bir harf çalıştırması yerine tanımlayıcı sözcüklerin tamamıyla eşleşir, bu nedenle llm bulur ancak eşleşmez IImageLLMAdapterSessionScrollMode. Bir sorgu hiçbir adla eşleşmediğinde, belgelenmiş tür ve üye özetlerinde denenir ve bu da öğesini bulmanızı IRandomAccessStreamsağlar"random-access stream". Açıklamalar her ad eşleşmesinin altında yer alır ve yalnızca aslında gönderilen paketlerin özetleri aranabilir; XML belgesi olmayan bir paket açıklama metnine katkıda bulunmaz.

MSBuild proje dosyası olmayan projeler. Bir Electron uygulamasının (veya tarafından yönetilen winapp.yamldiğer .NET olmayan herhangi bir uygulamanın) yoktur .csproj ve bu nedenle yokturproject.assets.json. find-api .winapp/winmds.lock.json winapp restore, her çözümlenen paketi, sürümünü ve .winmd katkıda bulunduğu dosyaları kaydeden yazandan dizine alır. Böyle bir proje dizininden sonra adlandırılır ve kilit dosyası yeniden yazıldığında dizini eskir. hem a .csproj hem de öğesini tutan bir winapp.yaml dizin, projenin neyle derlendiğine ilişkin daha kesin bir açıklama olan dizininden .csprojdizine eklenir.

Dizin eksik olduğunda negatif yanıtlar nitelenir. Bir paketin meta verileri okunamadıysa , "böyle bir tür yok" ve "bu paket hiçbir zaman dizine alınmadı" aynı görünür ve ikinci olduğunda aslında size söylenen bir API'ye karşı kod oluşturan ilk öğe üzerinde işlem yapar. Bu nedenle sıfır sonuç döndüren bir search de dahil olmak üzere her negatif yanıt dizinin kısmi olduğuna ve öğesine işaret winapp find-api refresholduğuna dair bir not taşır. Olumlu yanıtlar etkilenmez.

Genel tür adları. Meta veriler, genel türleri bir arity soneki ()IAsyncOperation`1 ile depolar ve bu, bunları herkesin yazma şekli değildir. members, enumsve check-property her formu kabul edin: IAsyncOperation, IAsyncOperation<StorageFile>ve IAsyncOperation`1 tümü aynı türe çözümlensin. Çıplak ad herhangi bir arity ile eşleşir; belirtilen bir arity (her iki gösteriminde de) eşleşmelidir, bu nedenle Holder<A, B> tek parametreli Holder<T>olarak çözümlenmez.

--json yükleri tanılamayı atlar. Önbellek dosyası yolları yalnızca altında --verbose görünür (zaten yalnızca ayrıntılı olan eşleşen metin çıktısı) ve boş öneri dizileri olarak []serileştirilmez.

Çıkış kodları:search isabetsiz, check-property eksik bir özelliğe ve enums sabit listesi olmayan bir değere sıfır olmayan tüm çıkışları yazın; geçit kodu oluşturma ve ci denetimleri bunlar üzerinde. Herhangi bir konu başarısız olursa toplu çağrı sıfırdan çıkar. Salt okunur özellik bir hata değildir; var check-property olduğundan çıkışta (writable: false içinde--json) bu özelliğin çıkışını 0 açar ve bayraklar. Bir init özellik aynı nedenle raporlar writable: false : bir nesne başlatıcıda ayarlanabilir ve imzasında ifadesi bulunur { get; init; }, ancak daha sonra atanması derlenmez.

İlgili:find-api "Bu API var mı ve üyeleri nelerdir?" yanıtını verir; bir denetim için çalışan bir WinUI örneği bulmak için kullanın find-ui .

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

Winapp, bir komut ilk ihtiyaç duyduğunda bu dizini oluşturur.

Winapp genel önbellek dizinine yazamıyorsa

Aracı korumalı alanları gibi yalnızca geçerli projeye yazma işlemine izin veren bazı ortamlar için %USERPROFILE%\.winapperişimini engelleyin. Komutların çoğu orada çalışmaya devam ediyor ve güncelleştirme denetimi atlanıyor. Winapp bu dizindeki ilk çalıştırmasını tamamlamadıysa, her çalıştırma stderr'a tek satırlık bir telemetri bildirimi de yazdırır.

Bu komutların önbellek dizinine yazması ve yolu adlandıran bir hatayla durması gerekir:

Komut	Yazacakları
`find-api`	API dizininin derlenmesi veya yenilenmesi gerektiğinde. Var olan up-to-date dizini hala okunur.
`store`	İlk kez yüklendiğinde Microsoft Store Geliştirici CLI'sı.

Bunu düzeltmek için winapp'in yazabileceği bir klasöre (örneğin, projenizin içinde bir tane) ayarlayın WINAPP_CLI_CACHE_DIRECTORY ve sonra yeniden deneyin.

winapp ui komutları, teslim alma durumlarını içinde %USERPROFILE%\.winapp\state\uitutar. Erişemiyorlarsa, yine de çalışır, ancak aynı masaüstünde diğer winapp ui komutları beklemeden ve bir uyarı yazdırır (veya --quietile --json atlanır). Bu masaüstünde aynı anda diğer winapp ui komutları çalıştırmaktan kaçının.

korumalı alan komutlarını Windows durumunda %USERPROFILE%\.winapp\statetutar. Bu klasör yazılabilir değilse, ile durur sandbox_state_unavailable ve ayarlanacağı değişkeni adlandırırlar.

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

UI iş akışı kimliği

winapp ui fiziksel masaüstünü yönlendiren komutlar her zaman işbirliğine dayalı sırayla çalışır, bu nedenle aynı anda çalışan iki iş akışı birbirlerinin odağını çalamaz veya birbirlerinin menülerini kapatamaz. Bu tahkim için kurulum gerekmez ve kapatılamaz.

İsteğe bağlı olan sürekliliktir. Varsayılan olarak her komut, masaüstü biter bitmez serbest bırakan bağımsız tek seferlik bir komut olur. Masaüstünü çeşitli komutlar arasında tutmak için tümüne aynı iş akışı kimliğini verin:

$env:WINAPP_UI_WORKFLOW_ID = [guid]::NewGuid().ToString()

İşlemleri işbirliği için aynı değeri (örneğin bir kayıt ve yakalaması gereken tıklamalar) ve bağımsız iş akışları için farklı değerleri kullanın. Kimliği olmayan her komut, bir kabuktan birkaç tane başlatıldığında bile kendi tek seferlik iş akışıdır, bu nedenle komut başına yeni bir kabuk başlatan konakların her birine aynı açık değeri eklemesi gerekir. Değer opaktır, hiçbir zaman kimlik bilgisi olarak kabul edilir ve yalnızca SHA-256 karması olarak kalıcı hale gelmez. Bkz. UI Otomasyonu → Eşzamanlı kullanıcı arabirimi iş akışlarını koordine etme.

Uı

UI Otomasyonu (UIA) kullanarak çalışan Windows uygulama URI'lerini inceleyin ve bunlarla etkileşime geçin. Çekirdek iş akışı için komutunu çalıştırın winapp ui --help ; kılavuzun tamamı için bkz. UI otomasyonu .

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 - Pencere/öğeyi PNG olarak yakala (birden çok pencere bileşik PNG etiketli bir pencere oluşturur; bkz . yakalama kapsamı)
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); --action tam bir işlem seçer (bkz . çağırma)
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
yield - Geçerli iş akışının kullanıcı arabirimini serbest bırakın; gerektirir WINAPP_UI_WORKFLOW_ID

Seçenekler:

-a, --app <app> - Hedef uygulama (ad, başlık veya PID)
-w, --window <hwnd> - HWND tarafından hedef pencere (kararlı)
--on <target> - içinde herhangi bir ui fiil sandboxçalıştırın; adlar, PID'ler ve pencere tutamaçları konuk için geçerlidir. Çıkışlar konağa teslim edilir. Kurulum, iş akışı koordinasyonu ve istemci gereksinimleri için bkz . Korumalı alan kullanıcı arabirimi otomasyonu .
--type, --root, --class-name - Kapsamlı ve yazılan sorgularda listelenen komutlarda bir seçiciyi daraltma

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 evidence.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).
--overwrite - Yeni kayıt tamamlandıktan sonra mevcut kayıt çıkışlarını değiştirin; mevcut çıkışlar varsayılan olarak reddedilir. Önceki çerçeve paketleri korunur. Bkz . Çıkış kurtarmayı kaydetme.
--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.

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-10-16

CLI Belgeleri ve Kullanımı

Version

Kabuk Tamamlama

başlat

Yeni

eski haline döndürmek

güncelleştirmek

pack

Projeyi doğrudan paketleme

Seyrek kimlik paketleri

WinRT bileşeni bulma

Çok mimarili paketler

hata ayıklama kimliği oluştur

embed-identity

manifesto

bildirim oluşturma

Manifesto yer tutucuları

bildirim ekleme diğer adı

manifesto varlıkları güncelle

run

Project modu (.NET SDK projeleri)

C++ projeleri (.vcxproj)

Tek dosya modu (dosya tabanlı uygulamalar .NET)

Yetenekler

Kendi bildiriminizi getirin

ile çalıştırma dotnet run

kaydını kaldırma

cert

sertifika oluşturma

sertifika bilgileri

sertifika yükleme

işaret

az-sign

create-external-catalog

araç

store

get-win-uygulama-yolu

target

target exec

hedef gönderme ve hedef çekme

hedef anlık görüntü

hedef ekran görüntüsü

hedef kayıt

find-ui

find-api

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

node eklenti-oluştur

node add-electron-debug-identity

node clear-electron-debug-identity

Genel Seçenekler

Genel Önbellek Dizini

Winapp genel önbellek dizinine yazamıyorsa

Güncelleştirme Denetimleri

UI iş akışı kimliği

Uı

ui kaydı

Geri Bildirim

Ek kaynaklar

ile çalıştırma `dotnet run`