.NET ile winapp CLI kullanma

Bu kılavuz çoğu .NET proje türü için çalışmalıdır. Adımlar hem konsol hem de WPF gibi kullanıcı arabirimi tabanlı projelerle test edilmiştir. Çalışan örnekler için samples klasöründeki dotnet-app (konsol) ve wpf-app (WPF) örneklerini gözden geçirin.

Bu kılavuzda, paket kimliğiyle hata ayıklamak ve uygulamanızı MSIX olarak paketlemek için .NET bir uygulamayla winapp CLI'nin nasıl kullanılacağı gösterilmektedir.

Paket kimliği, Windows app modelinde temel bir kavramdır. Uygulamanızın belirli Windows API'lerine (Bildirimler, Güvenlik, AI API'leri vb.) erişmesine, temiz bir yükleme/kaldırma deneyimine ve daha fazlasına erişmesine olanak tanır.

Standart bir yürütülebilir dosya (örneğin dotnet build ile oluşturulan) paket kimliğine sahip değildir. Bu kılavuzda hata ayıklama için nasıl ekleneceği ve ardından dağıtım için nasıl paketleneceği gösterilmektedir.

Önkoşullar

.NET SDK: .NET SDK'sını yükleyin (yüklemeden sonra yeniden başlatma gerektirir):
```
winget install Microsoft.DotNet.SDK.10 --source winget
```
winapp CLI: Aracı winget aracılığıyla yükleyin winapp (veya zaten yüklüyse güncelleştirin):
```
winget install Microsoft.winappcli --source winget
```

1. Yeni .NET Uygulaması Oluşturma

Basit bir .NET konsol uygulaması oluşturarak başlayın:

dotnet new console -n dotnet-app
cd dotnet-app

Her şeyin çalıştığından emin olmak için çalıştırın:

dotnet run

Çıktı "Hello, World!" olmalıdır

2. Kimliği Denetlemek için Kodu Güncelleştirme

Uygulamanın paket kimliğiyle çalışıp çalışmadığını denetlemek için uygulamayı güncelleştireceğiz. Paket API'lerine erişmek için Windows Çalışma Zamanı API'sini kullanacağız.

İlk olarak, project dosyanızı belirli bir Windows SDK sürümünü hedef olacak şekilde güncelleştirin. dotnet-app.csproj açın ve TargetFramework Windows SDK sürümünü içerecek şekilde değiştirin:

  <TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

Bu, ek paketlere gerek kalmadan Windows Çalışma Zamanı API'lere erişmenizi sağlar.

Şimdi öğesinin Program.cs içeriğini aşağıdaki kodla değiştirin. Bu kod, Windows Çalışma Zamanı API'sini kullanarak geçerli paket kimliğini almayı dener. Başarılı olursa Paket Aile Adı'nı yazdırır; aksi takdirde, "Paketlenmedi" yazdırır.

using Windows.ApplicationModel;

try
{
    var package = Package.Current;
    var familyName = package.Id.FamilyName;
    Console.WriteLine($"Package Family Name: {familyName}");
}
catch (InvalidOperationException)
{
    // Thrown when app doesn't have package identity
    Console.WriteLine("Not packaged");
}

3. Kimlik Olmadan Çalıştır

Şimdi uygulamayı her zamanki gibi çalıştırın:

dotnet run

"Çıkışta 'Paketlenmedi' ifadesini görmeniz gerekir." Bu, standart yürütülebilir dosyanın herhangi bir paket kimliği olmadan çalıştığını onaylar.

4. winapp CLI ile Project başlatma

winapp init komutu .csproj dosyalarını otomatik olarak algılar ve .NET özgü bir kurulum çalıştırır. İhtiyacınız olan her şeyi tek seferde ayarlar: , uygulamanızı TargetFrameworkdoğrular, gerekli NuGet paketlerini ekler, uygulama bildirimini ve varlıkları oluşturur.

Aşağıdaki komutu çalıştırın ve istemleri izleyin:

winapp init

Sorulduğunda:

Paket adı: Varsayılanı kabul etmek için Enter tuşuna basın (dotnet-app)
Publisher name: Varsayılanı kabul etmek için Enter tuşuna basın veya adınızı girin
Sürüm: 1.0.0.0'ı kabul etmek için Enter'a basın
Description: Varsayılanı kabul etmek için Enter tuşuna basın (uygulama Windows) veya açıklama girin
Windows Uygulama SDK'sı kurulumu: Kararlı, Önizleme veya Deneysel'i seçin (hangi Windows Uygulama SDK'sı sürümünün ekleneceğini belirler)
TargetFramework update: TargetFramework desteklenen bir Windows SDK sürümü içermiyorsa, bunu güncelleştirmeniz istenir (örneğin, net10.0-windows10.0.26100.0)
Geliştirici Modu: "Geliştirici Modu" hakkında bilgi istenirse isterseniz bu modu açabilirsiniz, ancak bunun yönetici ayrıcalıkları gerektirdiğini unutmayın

Bu komut:

TargetFramework öğesini .csproj içinde desteklenen bir Windows TFM'ye güncelleyin (gerekiyorsa)
Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools ve Microsoft.Windows.SDK.BuildTools.WinApp NuGet paketi referanslarını .csproj ekleyin
Uygulama kimliğiniz için Package.appxmanifest ve Assets klasör oluşturun.

Uyarı

Yerel/C++ projelerinin aksine .NET akışı bir dosyası oluşturmaz. NuGet paketleri doğrudan sizin .csprojüzerinden yönetilir. Klonladıktan sonra dotnet restore veya winapp restore komutunu çalıştırın.

Görüntü adı, yayımcı ve özellikler gibi unsurları daha fazla özelleştirmek için Package.appxmanifest açabilirsiniz.

Paketlerin projenize eklendiğini doğrulamak için:

dotnet list package

Çıktıda Microsoft.WindowsAppSDK ve Microsoft.Windows.SDK.BuildTools görmeniz gerekir.

Konsol çıkışı (yapılacak bir şey yok)

Bir konsol uygulaması oluşturduğumuz için konsol çıktısının mevcut terminalde kalması gerekir. AUMID etkinleştirmesi paketlenmiş bir uygulamaya konsol sağlamaz, bu nedenle konsol uygulaması düzgün çalışır ve hiçbir şey yazdırmaz.

winapp bunu sizin için halleder: OutputType=Exe içeren bir uygulama, bunun yerine terminalinizin stdin/stdout/stderr akışlarını devralan bir yürütme takma adı aracılığıyla başlatılır. Hazırladığı bildirim dosyasına gerekli uap5:ExecutionAlias öğesini ekler, bu nedenle yapılandırılacak hiçbir şey yoktur.

Kullanıcı arabirimi uygulamaları (WPF, WinForms, WinUI), AUMID etkinleştirmesini korumak için kendi pencerelerini oluşturur.

Yine de konsol uygulaması için AUMID'yi zorlamak için, içinde aşağıdakini <PropertyGroup>dotnet-app.csproj ayarlayın; uygulama konsol olmadan çalışır ve terminale hiçbir şey yazdırmaz:

<WinAppRunUseExecutionAlias>false</WinAppRunUseExecutionAlias>

Komut adını kendiniz seçmeyi tercih ederseniz, Package.appxmanifest içinde bir ad tanımlamak için winapp manifest add-alias komutunu çalıştırın; oluşturduğunuz takma ad olduğu gibi kullanılır.

5. Kimlikle Hata Ayıklama

winapp init projenize Microsoft.Windows.SDK.BuildTools.WinApp NuGet paketini eklediğinden şunları çalıştırabilirsiniz:

dotnet run

Bu, arka planda otomatik olarak winapp run çağırır; gevşek bir düzen paketi oluşturur, Windows ile kaydeder ve uygulamanızı tam paket kimliğiyle başlatır.

öğesinden sonra yazdığınız argümanlar, proje bu pakete başvurmamış olsaydı nasıl iletilecek idiyse tam olarak o şekilde dotnet run gider:

dotnet run --devtools          # your app receives --devtools
dotnet run -- --devtools       # identical: the SDK consumes the -- before forwarding

dotnet run seçeneğini, uygulamanızın işareti aynı zamanda bir --configuration seçeneği olduğunda kullanın (--framework, --project, -c, -f, -r, --, ...) — aksi takdirde SDK belirteci sahiplenir ve uygulamanız onu asla alamaz:

dotnet run -- --configuration Release   # your app receives --configuration Release

WinApp başlatıcısını MSBuild özellikleriyle WinAppRun* yapılandırın. MSBuild bunları tükettiği için uygulamanıza hiçbir zaman ulaşmaz:

dotnet run -p:WinAppRunDebugOutput=true --devtools

Burada özellik WinApp’i yapılandırırken, --devtools uygulamanıza iletilir. Tam özellik listesi ve hangi özelliklerin birlikte kullanılamayacağı dahil olmak üzere dotnet run destek bölümüne bakın.

Uyarı

Paket kaynakları hakkında NuGet güvenlik açığı uyarıları (NU1900) görebilirsiniz. Bunları görmezden gelmek güvenlidir çünkü derlemenizi etkilemez.

Aşağıdakine benzer bir çıktı görmeniz gerekir:

Package Family Name: dotnet-app_12345abcde

Bu, uygulamanızın geçerli bir paket kimliğiyle çalıştığını onaylar!

Alternatif: El ile `winapp run`

winapp init kullanmadıysanız (veya NuGet paketini kaldırdıysanız), manuel olarak derleyip çalıştırabilirsiniz. winapp run projeyi doğrudan kabul eder (proje modu) — .csproj derlemesini oluşturur ve başlatır, böylece derleme-çıkış klasörünü işaret etmek veya ayrı derleme yapmak zorunda değilsiniz:

# Build and run the project in one step (project mode)
winapp run .

# ...or run a specific project / configuration / architecture
winapp run .\dotnet-app.csproj -c Debug --arch x64

Projenin Yerel AOT yapılandırmasını çalıştırmak için projede AOT'yi etkinleştirin ve şunu çalıştırın:

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

x64 veya ARM64 kullanın. Bir kerelik geçersiz kılma için sonuna -p PublishAot=true ekleyin.

İsterseniz winapp run öğesini yine de önceden oluşturulmuş bir çıktı klasörüne işaret edebilirsiniz (klasör modu):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Project modu hem paketlenmiş hem de paketlenmemiş WinUI uygulamalarını destekler; projectWindowsPackageType'lerden hangilerini algılar ve eşleşen mimari Windows Uygulaması Çalışma Zamanı'nı otomatik olarak yükler. Paketlenmiş bir projenin paketlenmeden çalıştırılmasını zorlamak için -p WindowsPackageType=None ekleyin.

Çok projeli uygulamalar (sınıf kitaplıklarına başvuran bir uygulama) doğru şekilde derlenir: winapp, AnyCPU/netstandard2.0 referanslarını, uygulamanın mimarisini grafik genelinde dayatmak yerine, kendi uyumlu platformlarında tutar. RID-only varsayılan olarak kalır; geçerli yapılandırma bağımsız bir profil gerektirdiğinde (örneğin, kırpılmış bir Release derlemesinde), winapp başvurulan kitaplıkların platformlarını değiştirmeden eşleşen profili seçer.

dotnet build çıkış akışı gerçek zamanlı olarak akar; önce çağrının tam hâli yazdırılır. winapp’in kendi derleme karar izleri için --verbose ekleyin. .NET SDK 8.0.100 veya üzerini gerektirir. Tam seçenek listesi için winapp run kullanım referansına bakın.

Windows SDK yüklü değil mi? C#/WinRT yazma projelerinin oluşturulması için normalde kayıtlı bir Windows SDK'sı gerekir. Proje modu hiçbir şey algılamadığında (temiz CI ortamları, konteynerler, SDK’sız geliştirme ortamları), derlemenin yine de başarılı olması için cswinrt’yi otomatik geri yüklenen Microsoft.Windows.SDK.NET.Ref paketindeki winmd’lere yönlendirir — herhangi bir işlem yapmanız gerekmez. SDK yüklendiğinde veya kendinizi ayarladığınızda -p CsWinRTWindowsMetadata=… hiçbir şey yapmaz.

NuGet paketini geri eklemek için: dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease

Tavsiye

Otomatik dotnet run tümleştirmeyi devre dışı bırakmak için <EnableWinAppRunSupport>false</EnableWinAppRunSupport> dosyanıza .csproj ekleyin. Özelleştirme seçenekleri için dotnet çalıştırma destek belgelerine bakın.

Alternatif: Minimal paket kimliği

Seyrek paket davranışına özellikle ihtiyacınız varsa (dosyaları kopyalamadan kimlik), bunun yerine kullanabilirsiniz create-debug-identity . Bu, gevşek bir düzen oluşturmak yerine exe'nize işaret eden seyrek bir paket kaydeder:

winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Ardından yürütülebilir dosyayı doğrudan çalıştırın (dosyayı yeniden oluşturabileceği/üzerine yazabileceği için kullanmayın dotnet run ):

.\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

Alternatif: Manuel MSBuild hedefi

NuGet paketini kullanmamak isterseniz, Hata ayıklama derlemelerinden sonra çalıştırılan create-debug-identity özel bir MSBuild hedefi ekleyebilirsiniz. Bunu, kapanış .csproj etiketinden hemen önce </Project> dosyanıza ekleyin:

  <!-- Automatically apply debug identity after Debug builds -->
  <Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Bu yapılandırmayla dotnet build hata ayıklama kimliğini uygular ve yürütülebilir dosyayı hemen çalıştırabilirsiniz. dotnet run kimliği yeniden oluşturup üzerine yazabileceğini unutmayın, bu nedenle exe dosyasını derledikten sonra manuel olarak çalıştırın.

Tavsiye

Gelişmiş hata ayıklama iş akışları (hata ayıklayıcıları ekleme, IDE kurulumu, başlatma hata ayıklama) için Hata Ayıklama Kılavuzu'na bakın.

Bunu ne zaman atlamalısınız: Kimliğin ne zaman uygulanacağı üzerinde açık denetim tercih ediyorsanız veya geliştirme döngünüzün büyük bir bölümünde kimliğe ihtiyaç duymayan bir kod üzerinde çalışıyorsanız, yukarıdaki el ile yaklaşım daha basit olabilir.

6. Windows Uygulama SDK'sı Kullanma (İsteğe Bağlı)

Windows Uygulama SDK'sı, temel Windows SDK'sının sağladığının ötesinde modern Windows API'lerine (bildirim sistemi, pencere API'leri, uygulama yaşam döngüsü yönetimi ve cihaz içi yapay zeka gibi) erişmenizi sağlar. Uygulamanızın bu özelliklerden herhangi birine ihtiyacı varsa, bu adım tam size göredir. Yalnızca dağıtım için paket kimliğine ihtiyacınız varsa 7. adıma atlayabilirsiniz.

winapp init (4. Adım) çalıştırdıysanız, Microsoft.WindowsAppSDK zaten .csproj nuGet paketi başvurusu olarak eklenmiştir. ile dotnet list packagedoğrulayabilirsiniz. Başlatma sırasında SDK kurulumunu atladıysanız veya el ile eklemeniz gerekiyorsa şunu çalıştırın:

dotnet add package Microsoft.WindowsAppSDK

Program.cs dosyasını güncelleştir

Program.cs içeriğinin tamamını, Windows Uygulaması Çalışma Zamanı sürüm denetimi ekleyen aşağıdaki kodla değiştirin:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");
            
            // Get Windows App Runtime version using the API
            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            // Thrown when app doesn't have package identity
            Console.WriteLine("Not packaged");
        }
    }
}

Derleme ve Çalıştırma

uygulamayı Windows Uygulama SDK'sı ile yeniden derleyin ve çalıştırın. WinAppSDK'yi eklediğimizden, çalışma zamanı bağımlılığını ekleyebilmek winapp için kimlikle yeniden kaydetmemiz gerekir. WinApp NuGet paketini eklediyseniz (önerilir), komutunu çalıştırmanız dotnet runyeterlidir. Aksi takdirde (proje adınızla değiştirin dotnet-app):

dotnet build -c Debug
winapp run .\bin\Debug\net10.0-windows10.0.26100.0

Şimdi aşağıdaki gibi bir çıkış görmeniz gerekir:

Package Family Name: dotnet-app.debug_12345abcde
Windows App Runtime Version: 8000.770.947.0

Windows Uygulama SDK'sı NuGet paketi, modern Windows API'lerine erişmek için gerekli tüm derlemeleri içerir:

Bildirimler ve canlı kutucuklar
Pencereleme ve uygulama yaşam döngüsü
Anında iletme bildirimleri
Ve daha birçok Windows Uygulama SDK'sı bileşeni

Daha gelişmiş Windows Uygulama SDK'sı kullanımı için Windows Uygulama SDK'sı belgelerine göz atın.

7. MSIX ile paketle

Uygulamanızı dağıtmaya hazır olduğunuzda, aynı bildirimi kullanarak bir MSIX olarak paketleyebilirsiniz.

Yayın için Derleme

İlk olarak, en iyi performans için uygulamanızı yayın modunda derleyin:

dotnet build -c Release

Uyarı

NuGet güvenlik açığı uyarıları (NU1900) görebilirsiniz. Bunları görmezden gelmek güvenlidir ve derleme çıktınızı etkilemez.

Geliştirme Sertifikası Oluşturma

Paketlemeden önce imzalama için bir geliştirme sertifikasına ihtiyacınız vardır. Henüz oluşturmadıysanız bir tane oluşturun:

winapp cert generate --if-exists skip

İmzala ve Paketle

Artık paketleyip imzalayabilirsiniz. Paket komutunu derleme çıktı klasörünüze (ve TFM yolunu projenizin değerleriyle değiştirin dotnet-app ) işaret edin:

# package and sign the app with the generated certificate
winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\Package.appxmanifest --cert .\devcert.pfx

Not: Komut, pack geçerli dizininizdeki Package.appxmanifest dosyasını otomatik olarak kullanır ve paketlemeden önce hedef klasöre kopyalar. Oluşturulan .msix dosyası geçerli dizinde olacaktır.

İpucu: Derleme-çıktı klasörünü ve paketi doğrudan projeden bulma işlemini de atlayabilirsiniz; winapp package .\dotnet-app.csproj --cert .\devcert.pfx projeyi yayımlar ve çıktısını tek adımda paketler (proje modu varsayılan olarak Yayın yapılandırmasıdır). Proje modu, --no-build, -f, --arch, --no-restore, -p, --no-build derleme seçeneklerini kabul eder; mevcut bir derlemeyi yeniden derlemeden paketlemek için -c ekleyin.

Sertifikayı Yükleme

MSIX paketini yükleyebilmeniz için önce geliştirme sertifikasını yüklemeniz gerekir. Bu komutu yönetici olarak çalıştırın:

winapp cert install .\devcert.pfx

Yükleme ve Çalıştırma

Oluşturulan *.msix dosyasına çift tıklayarak paketi yükleyin.

Artık şunu yazarak uygulamanızı terminalde herhangi bir yerden çalıştırabilirsiniz:

dotnet-app

Yüklendiğini ve kimlikle çalıştığını onaylayan "Paket Aile Adı" çıkışını görmeniz gerekir.

Tavsiye

Uygulamanızı yeniden paketlemeniz gerekiyorsa (örneğin, kod değişikliklerinden sonra), Version komutunu tekrar çalıştırmadan önce, Package.appxmanifest içindeki winapp pack değerini artırın. Windows yüklü bir paketi güncelleştirmek için daha yüksek bir sürüm numarası gerekir.

Tips

Dağıtıma hazır olduğunuzda, kullanıcılarınızın otomatik olarak imzalanan bir sertifika yüklemesini gerektirmeyecek şekilde MSIX'inizi Sertifika Yetkilisi'nden bir kod imzalama sertifikasıyla imzalayabilirsiniz.
Microsoft Store MSIX'i sizin için imzalar, göndermeden önce imzalamanız gerekmez.
Desteklediğiniz her mimari için (x64, Arm64) bir tane olmak üzere birden çok MSIX paketi oluşturmanız gerekebilir. belirli mimarileri hedeflemek için bayrağını -rdotnet build kullanın: dotnet build -c Release -r win-x64 veya dotnet build -c Release -r win-arm64.

MSIX Paketlemeyi Otomatikleştirme (İsteğe Bağlı)

MsIX paketlemesini Yayın derlemelerinizin bir parçası olarak otomatikleştirmek için bu hedefi dosyanıza .csproj ekleyin (hata ayıklama kimliği hedefiyle birlikte ekleyebilirsiniz):

  <!-- Automatically package as MSIX after Release builds -->
  <Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <!-- Package and sign directly from build output -->
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;" 
          WorkingDirectory="$(ProjectDir)" 
          IgnoreExitCode="false" />
  </Target>

Bu yapılandırmayla:

Sürüm modunda (dotnet build -c Release) derleme yapıldığında MSIX paketi otomatik olarak oluşturulur
MSIX paketlenmiş ve geliştirme sertifikanızla imzalanmıştır
Son .msix dosya projenin kökünde olacak

Ayrıca, koşulu PackagedReleaseolarak değiştirerek özel bir yapılandırma (ör. '$(Configuration)' == 'PackagedRelease') oluşturabilirsiniz.

Sonraki Adımlar

winget aracılığıyla dağıtın: MSIX'inizi Windows Paket Yöneticisi Topluluk Deposu'na gönderin
Microsoft Store: Paketinizi göndermek için kullanın
CI/CD'yi ayarlayın: İşlem hattınızda paketlemeyi otomatikleştirmek için setup-WinAppCli GitHub Eylemi'ni kullanın
Explore Windows API'leri: Paket kimliğiyle, artık Notifications, on-device AI ve diğer identity bağımlı API'leri kullanabilirsiniz

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-09-24

.NET ile winapp CLI kullanma

Önkoşullar

1. Yeni .NET Uygulaması Oluşturma

2. Kimliği Denetlemek için Kodu Güncelleştirme

3. Kimlik Olmadan Çalıştır

4. winapp CLI ile Project başlatma

Konsol çıkışı (yapılacak bir şey yok)

5. Kimlikle Hata Ayıklama

Alternatif: El ile winapp run

Alternatif: Minimal paket kimliği

Alternatif: Manuel MSBuild hedefi

6. Windows Uygulama SDK'sı Kullanma (İsteğe Bağlı)

Program.cs dosyasını güncelleştir

Derleme ve Çalıştırma

7. MSIX ile paketle

Yayın için Derleme

Geliştirme Sertifikası Oluşturma

İmzala ve Paketle

Sertifikayı Yükleme

Yükleme ve Çalıştırma

Tips

MSIX Paketlemeyi Otomatikleştirme (İsteğe Bağlı)

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar

Alternatif: El ile `winapp run`