WinUI ile winapp CLI kullanma

Bu kılavuz, WinUI 3 uygulamasının tüm iç döngüsünde winapp CLI'nin nasıl kullanılacağını gösterir: resmi bir şablondan proje oluşturma, paket kimliğiyle projeyi oluşturup başlatma, kilitlenme hatalarını ayıklama, denetimleri ve API'leri bulma, kullanıcı arabirimini otomatikleştirme ve imzalı bir MSIX paketi oluşturma. Her adım komut satırından çalıştırıldığından, herhangi bir düzenleyicide, CI'de ve yapay zeka kodlama aracılarıyla çalışır.

WinUI proje şablonları zaten bir Package.appxmanifest içerir, bu nedenle bir WinUI uygulaması için winapp init çalıştırmanız gerekmez. WinUI kullanmayan mevcut bir .NET uygulamasına paket kimliği ekliyorsanız bunun yerine .NET ile winapp CLI kullanma konusuna bakın.

Prerequisites

  • Windows 10 sürüm 1809 veya üzeri ya da Windows 11.

  • .NET SDK, sürüm 8.0.100 veya üzeri. Deneysel Reactor şablonları için .NET 10 SDK gerekir. winapp CLI araç zincirlerini yüklemez, bu nedenle winapp run ve winapp new, .NET SDK'sı eksikse yönlendirme ile durur.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Windows'un derleme çıkışınızdan uygulamayı kaydetmek için gerektirdiği Geliştirici Modu. Bunu Ayarlar > Sistem > Geliştiriciler için bölümünde açın. Bunun makinenizde neleri değiştirdiğini görmek için Güvenlik bölümüne bakın.

WinUI uygulaması oluşturma

winapp new resmi Microsoft.WindowsAppSDK.WinUI.CSharp.Templates paketinden bir WinUI uygulaması oluşturur. Şablon paketini isteğe bağlı olarak yükler veya güncelleştirir ve ardından dotnet new öğesini sizin için çağırır.

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

Yüklü paketteki şablonları görmek için winapp new --list komutunu çalıştırın. Paket şu şablonları içerir:

Template Description
winui Minimal boş XAML uygulaması (varsayılan). Ekran görüntüsüne bakın
winui-navview NavigationView kabuğuna sahip XAML uygulaması. Ekran görüntüsüne bakın
winui-tabview TabView kabuğuna sahip XAML uygulaması. Ekran görüntüsüne bakın
winui-mvvm CommunityToolkit.Mvvm ile MVVM desenini kullanan XAML uygulaması. Ekran görüntüsüne bakın
winui-lib WinUI sınıf kitaplığı
winui-unittest WinUI birim testleri için paketlenmiş MSTest projesi
reactor, reactor-mvu, reactor-navview, reactor-tabview Deneysel. XAML olmadan yalnızca C# dilinde yazılmış WinUI uygulamaları

Uyarı

Reactor şablonları yayın öncesi Microsoft.UI.Reactor paketlere atıfta bulunur. API'leri gelecekteki bir sürümde değişebilir veya kaldırılabilir.

Her seçenek için newkomut başvurusuna bakın.

Kimlikle derleme ve çalıştırma

winapp run, proje klasöründen projeyi oluşturur, eksikse mimarinizle eşleşen Windows Uygulama SDK'sı çalışma zamanını yükler, uygulamayı paket kimliğiyle kaydeder ve başlatır.

cd MyApp
winapp run

winapp run proje dosyasını, çözüm dosyasını, bunlardan birini içeren bir klasörü veya derleme çıktısı klasörünü kabul eder:

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: winapp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

winapp CLI, projenin nasıl başlatıldığına karar vermek için projenin WindowsPackageType özelliğini okur. Paketlenmiş bir proje paket kimliğiyle çalışır. WindowsPackageType değerini None olarak ayarlayan bir proje, kimliği olmayan paketlenmemiş bir uygulama olarak çalışır. Paketlenmiş bir projeyi paketlenmemiş olarak çalıştırmak için özelliği komut satırında belirtin:

winapp run -p WindowsPackageType=None

Diğer yararlı seçenekler arasında --clean ile önceki kaydı ve uygulamanın kaydedilmiş verilerini (LocalState ve ayarlar) yeni bir ilk çalıştırma için kaldırmak, --no-launch ile uygulamayı başlatmadan kayıt yapmak ve --detach --json uygulama çalışırken betiklerin ve aracıların çalışmaya devam edebilmesi için işlem kimliğini döndürmek ve çıkmak yer alır. Tam liste için bkz. Project mod (.NET SDK projeleri).

Bunun yerine dotnet run kullanın

Eğer dotnet run tercih ediyorsanız, Microsoft.Windows.SDK.BuildTools.WinApp NuGet paketini kullanın. Paket, winapp run öğesine kanca ekleyerek onun dotnet run öğesini çağırmasını ve uygulamayı kimlikle başlatmasını sağlar. winapp new ile oluşturduğunuz projeler zaten pakete başvurur, bu nedenle dotnet run ek kurulum olmadan çalışır. Diğer projeler için önce paketi ekleyin:

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

WinAppRun* seçenekleri winapp run MSBuild özellikleri olarak geçirebilirsiniz, örneğin dotnet run -p:WinAppRunDebugOutput=true. Tümleştirmeyi kapatmak için proje dosyasında EnableWinAppRunSupport öğesini false olarak ayarlayın. Ayrıntılar için bkz. dotnet run desteği.

Hata ayıklama sırasında çökmeler

Uygulama çalışırken --debug-outputiletileri--debug-output ve ilk şans özel durumlarını yakalamak için OutputDebugString ekleyin. WinUI uygulaması stowed exception ile başarısız olduğunda winapp CLI kilitlenme dökümünü analiz eder ve genel hata kodu yerine özgün hatayı ve çağrı yığınını yazdırır.

winapp run --debug-output

Tam yerel işlev adları için simgeleri indirmek üzere --symbols ekleyin. --debug-output Winapp CLI'yi hata ayıklayıcı olarak iliştirdiğinden, aynı işleme Visual Studio veya başka bir hata ayıklayıcı iliştiremezsiniz. Bunun yerine IDE'nizle hata ayıklamak için bkz. winapp CLI ile hata ayıklama. Stowed-exception analizi hakkında ayrıntılı bilgi için bkz. WinUI stowed-exception değerlendirmesi.

Denetimleri ve API'leri bulun

winapp find-uiWinUI Galerisi'nden ve Windows Community Toolkit'ten niyete göre XAML ve C# örneklerini arar ve seçtiğiniz senaryonun kodunu döndürür. winapp find-api, Windows Uygulama SDK'sı ve Windows SDK türleri, üyeleri ve sabit listeleri gibi projenizin başvurduğu Windows ve WinRT API yüzeyinde arama yapar.

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

Her iki komut da --json öğesini desteklediği için yapay zeka kodlama aracıları bunları kullanarak denetimleri seçebilir ve API adlarını doğrulayabilir. Daha fazla bilgi için, find-api ve find-ui kaynaklarına bakın.

Kullanıcı arayüzünü otomatikleştirin ve doğrulayın

winapp ui Microsoft UI Otomasyonu aracılığıyla çalışan bir uygulamayı denetler. Öğe ağacını incelemek, denetimleri tetiklemek, durum değişikliklerini beklemek ve ekran görüntüleri almak için kullanın. Temsilciler kendi değişikliklerini denetlemek için aynı komutları kullanabilir.

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

PART_PaneToggleButton seçici, winui-navview şablonundaki menü düğmesini hedefler. Kendi denetimleriniz için, winapp ui search veya winapp ui inspect çıktısından bir seçici kopyalayın.

Uygulamayı masaüstünüzde değil, Windows Korumalı Alanı'nda çalıştırmak için winapp ui öğesini winapp run ve --on sandbox öğelerine ekleyin. Daha fazla bilgi için bkz. UI otomasyonu ve Korumalı alan yürütme.

Paketle ve imzala

Bir paketi yerel olarak test etmeye hazır olduğunuzda, yayımcısı bildiriminizle eşleşen bir geliştirme sertifikası oluşturun ve ardından projeyi tek adımda derleyip paketleyin:

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack projeyi derler ve imzalı .msix üretir. Birkaç mimarinin derlemelerini tek bir .msixbundlepakette birleştirmek için bkz. Çoklu mimari paketleri. Projenin paketlenmesi gerekir, bu nedenle WindowsPackageType değerini None olarak ayarlayan bir proje paketlenemez. WinUI projeleri için Windows Uygulama SDK'sı derlemesi bildirimin, giriş noktasının ve kaynak oluşturma işleminin sahibidir; bu nedenle --manifest, --executable ve --skip-pri kabul edilmez.

Geliştirme sertifikası yalnızca yerel test içindir ve varsayılan bir parola kullanır. Uygulamanızı dağıtmadan önce, örneğin winapp az-sign ve Azure Güvenilen İmzalama ile güvenilir bir sertifikayla imzalayın. Daha fazla bilgi için bkz . Projeyi doğrudan paketleme ve Güvenlik.

Mevcut WinUI projeleri

winapp CLI, Visual Studio'da oluşturduğunuz WinUI projeleriyle çalışır. winapp run öğesini proje dosyasına, çözüm dosyasına veya bunlardan birini içeren klasöre yöneltin. winapp pack için .csproj öğesini geçirin. Visual Studio'de oluşturmaya ve hata ayıklamaya devam edebilir ve betikler, CI ve aracı iş akışları için winapp CLI kullanabilirsiniz.

C++ ile WinUI

winapp run ayrıca Visual Studio WinUI Blank App (Packaged) şablonundan oluşturduğunuz C++/WinRT WinUI projelerini (.vcxproj) de derler ve başlatır. projeyi Visual Studio MSBuild ile oluşturur, uygulamayı paket kimliğiyle kaydeder ve başlatır:

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

C++ projeleri için, C++ ile Masaüstü geliştirme iş yükü ve C++ WinUI uygulama geliştirme araçları ile birlikte Visual Studio veya Visual Studio için Derleme Araçları gerekir. winapp pack, .vcxproj projelerini derlemez, bu nedenle MSIX paketini Visual Studio'da oluşturun. Önkoşullar ve seçenekler için bkz. C++ projeleri (.vcxproj). WinUI kullanmayan C++ uygulamaları için bkz. C++ ile winapp CLI kullanma.

Samples

  • winui-app: otomasyon için winapp ui ayarlanmış denetimlere sahip paketlenmiş bir WinUI uygulaması
  • winui-unpackaged-app: Paket kimliği olmadan çalışan bir WinUI uygulaması
  • winui-solution: winapp run'in uygulama projesini nasıl seçtiğini gösteren çok projeli bir çözüm
  • cpp-winui-app: winapp run ile çalışan paketlenmiş bir C++/WinRT WinUI uygulaması (XAML’li Visual Studio .vcxproj)

Sonraki Adımlar

  • Son güncelleştirme: