.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. Kopyalamadan sonra paketleri geri yüklemek için kullanın dotnet restore .

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.

Yürütme Takma Adı Ekle (konsol uygulamaları için)

Konsol uygulaması derlediğimiz için, konsol çıkışını geçerli terminalde tuttuğumuzdan emin olmamız gerekir dotnet run. Varsayılan olarak, dotnet run yeni bir pencere açan AUMID etkinleştirmesi aracılığıyla paketlenmiş uygulamayı başlatır ve konsol uygulaması tamamlandığında pencere hemen kapatılır ve herhangi bir çıktıyı yutar.

Manifest'e bir çalıştırma takma adı ekleyecek ve çalışma entegrasyonunun bu takma ad aracılığıyla başlatacağını belirteceksiniz.

Ui uygulaması oluşturuyorsanız bu adımı atabilirsiniz (WPF, WinForms, WinUI). Bu uygulamalar kendi pencerelerini oluşturur, bu yüzden istediğiniz şey varsayılan AUMID başlatma işlemidir.

Manifest dosyanıza yürütme diğer adını ekleyin.
```
winapp manifest add-alias
```
Bu, projenizin exe adına varsayılan olarak, uygulamanın bir terminalden adla başlatılabilmesi için uap5:ExecutionAlias öğesini Package.appxmanifest öğesine ekler.
Tümleştirmeye dotnet run diğer adı kullanmasını söyleyin. dotnet-app.csproj'i açın ve herhangi bir <PropertyGroup> içine aşağıdakileri ekleyin (gerekirse yeni bir <PropertyGroup> oluşturun):
```
<WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
```
Bu özellik kümesiyle uygulamayı dotnet run yürütme diğer adı aracılığıyla başlatır ve konsol çıkışını satır içinde görebilmeniz için geçerli terminalin stdin/stdout/stderr değerini devralı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.

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`

NuGet paketini kullanmadıysanız winapp init (veya kaldırdıysanız) el ile derleyebilir ve çalıştırabilirsiniz:

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

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 .csproj dosyanıza <EnableWinAppRunSupport>false</EnableWinAppRunSupport> 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.

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), winapp pack komutunu tekrar çalıştırmadan önce, Package.appxmanifest içindeki Version 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-05-12

.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

Yürütme Takma Adı Ekle (konsol uygulamaları için)

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`