Çerçeveye bağımlı paketlenmiş uygulamalar için Windows Uygulama SDK'sı dağıtım kılavuzu

Bu makalede, Windows Uygulama SDK'sı kullanan çerçeveye bağımlı paketlenmiş uygulamaları dağıtma hakkında yönergeler sağlanır (bkz. MSIX nedir?). Diğer çerçeveye bağımlı paketleme seçenekleri için eşdeğer konu, dış konumla paketlenmiş veya paketlenmemiş çerçeveye bağımlı uygulamalar için Windows Uygulama SDK'sı dağıtım kılavuzudur.

Overview

Varsayılan olarak, Visual Studio'deki WinUI 3 şablonlarından birini kullanarak bir proje oluşturduğunuzda, projeniz tek projeli MSIX kullanarak uygulamayı bir MSIX paketinde derlemek üzere yapılandırılır (bkz. Uygulamanızı tek projeli MSIX kullanarak paketleme) veya bir Windows Uygulama Paketleme projesi (bkz. Visual Studio'de MSIX paketlemesi için masaüstü uygulamanızı ayarlama). Daha sonra Visual Studio'da masaüstü veya UWP uygulamasını paketleme başlığındaki yönergeleri kullanarak uygulamanız için bir MSIX paketi oluşturabilirsiniz. Uygulamanız için bir MSIX paketi derledikten sonra, MSIX dağıtımınızı yönetmeiçin çeşitli seçenekleriniz vardır.

Paketlenmiş uygulamanızın Windows Uygulama SDK'sı'yı kullanırken ihtiyaç duyabileceği paketler hakkında daha fazla bilgi edinmek için Windows Uygulama SDK'sı için Dağıtım mimarisi başlığına bakın. Bunlar Framework, Main ve Singleton paketlerini içerir; microsoft tarafından imzalanmış ve yayımlanmıştır. Paketlenmiş bir uygulamayı dağıtmak için iki ana gereksinim vardır:

  1. Windows Uygulama SDK'sı framework paketini dağıtın.
  2. Dağıtım API'siniçağırın.

Prerequisites

  • Paketlenmiş uygulamalar için VCLibs çerçevesi paket bağımlılığı bir gereksinimdir. Daha fazla bilgi için bkz. Desktop Bridgeiçin C++ Çalışma Zamanı çerçeve paketleri.
  • C#. .NET 6 veya üzeri gereklidir. Daha fazla bilgi için bkz. .NET İndirmeler.

Windows Uygulama SDK'sı çerçeve paketini dağıtma

Windows Uygulama SDK'sı çerçeve paketi, çalışma zamanında kullanılan Windows Uygulama SDK'sı ikili dosyalarını içerir ve uygulamanızla birlikte yüklenir. Çerçeve, Windows Uygulama SDK'sı farklı kanalları için farklı dağıtım gereksinimlerine sahiptir.

Kararlı sürüm

Geliştirme bilgisayarınıza Windows Uygulama SDK'sı NuGet paketinin kararlı bir sürüm sürümünü yüklediğinizde ve sağlanan WinUI proje şablonlarından birini kullanarak bir proje oluşturduğunuzda, oluşturulan paket bildirimi çerçeve paketine bağımlılığı belirten bir PackageDependency öğesi içerir.

Ancak, uygulama paketinizi ayrı bir Windows Uygulama Paketleme Projesi kullanarak el ile derlerseniz, dosyanızda aşağıdaki gibi bir Application (package).wapproj bildirmeniz gerekir:

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

Bu paket bağımlılığı, uygulamanız başka bir bilgisayara dağıtıldığında Framework paketinin yüklenmesini sağlar.

Önizleme sürümü

Geliştirme bilgisayarınıza Windows Uygulama SDK'sı NuGet paketinin önizleme sürümü yüklediğinizde, derleme zamanında NuGet paketi bağımlılığı olarak Windows Uygulama SDK'sı çerçeve paketinin önizleme sürümü dağıtılır.

Dağıtım API'sini çağırma

Ayrıca bkz. Windows Uygulama SDK'sı başlatma.

Dağıtım API'si, Windows Uygulama SDK'sı çerçeve paketi tarafından sağlanır ve Microsoft.Windows.ApplicationModel.WindowsAppRuntime ad alanında kullanılabilir. Windows uygulama modeli, Main ve Singleton paketlerine bağımlılık bildirmeyi desteklemez. Bu nedenle Dağıtım API'sinin şu nedenlerle gerekli olması gerekir:

  1. Çerçeve paketinde bulunmayan özellikler (örneğin, anında iletme bildirimleri) için Singleton paketini dağıtmak için.
  2. Microsoft Store'dan Framework paketine otomatik güncelleştirmeler sağlayan Main paketini dağıtmak için.

Mağaza aracılığıyla dağıtılmayan paketlenmiş uygulamalar için, Framework paketini dağıtmak geliştirici olarak sizin sorumluluğundadır. Kritik hizmet güncelleştirmelerinin teslimi için Dağıtım API'sini çağırmanızı öneririz. Çerçeve paketi dışındaki özellikleri (örneğin, anında iletme bildirimleri) kullanmak için Singleton paketinin dağıtılması gerektiğini unutmayın (bu, Dağıtım API'siyle veya MSIX paketlerini kendi yükleme yönteminizle yeniden dağıtarak yapılabilir).

Important

Yalnızca tam güven olan veya packageManagement kısıtlanmış özelliğine sahip paketlenmiş uygulamalar, Main ve Singleton paket bağımlılıklarını yüklemek için Dağıtım API'sini kullanma iznine sahiptir.

Uygulamanızın işlemi başlatıldıktan sonra, ancak uygulamanız Singleton paketini kullanan Windows Uygulama SDK'sı çalışma zamanı özelliklerini (örneğin, anında iletme bildirimleri) kullanmadan önce Dağıtım API'sini çağırmalısınız. Dağıtım API'sinin ana yöntemleri, DeploymentManager sınıfının statik GetStatus ve Initialize yöntemleridir.

  • GetStatus yöntemi, şu anda yüklü olan Windows Uygulama SDK'sı çalışma zamanının geçerli dağıtım durumunu döndürür. Geçerli uygulama Windows Uygulama SDK'sı özellikleri kullanabilmeden önce Windows Uygulama SDK'sı çalışma zamanı paketlerini yüklemek için gereken işlerin olup olmadığını belirlemek için bu yöntemi kullanın.
  • Initialize yöntemi, tüm gerekli paketlerin şu anda yüklü olan Windows Uygulama SDK'sı çalışma zamanı için gereken en düşük sürümde mevcut olup olmadığını doğrular. Herhangi bir paket bağımlılığı eksikse, yöntemi bu eksik paketleri kaydetmeyi dener. Windows Uygulama SDK'sı 1.1 sürümünden başlayarak Initialize yöntemi Windows Uygulama SDK'sı çalışma zamanı paketlerini zorla dağıtma seçeneğini de destekler. Bu, Main ve Singleton çalışma zamanı paketleri için tüm işlemleri kapatır ve böylece hizmetlerini kesintiye uğratır (örneğin, anında iletme bildirimleri bu süre boyunca bildirim sunmaz). Initialize'ı yalnızca bir kez çağırmalısınız. Visual Studio'da Start Without Debugging ve Start Debugging komutları aracılığıyla dağıtılan uygulamalar için Initialize çağrısı yapmanız gerekmez.

Important

<WindowsAppSdkDeploymentManagerInitialize> Visual Studio özelliğinin varsayılan değeri true değeridir. Bu nedenle, DeploymentManager.Initialize açıkça çağırmak istiyorsanız, Visual Studio proje dosyanızda <WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize> ayarlayın.

Dağıtım API'si örnek uygulaması

DeploymentManager sınıfının GetStatus ve Initialize yöntemlerini kullanma hakkında ek yönergeler için kullanılabilir örnek uygulamayı keşfedin.

Dağıtım API'sini keşfetme örnek uygulaması

Yükleme hatalarını giderme

Dağıtım API'si Windows Uygulama SDK'sı çalışma zamanı paketlerinin yüklenmesi sırasında bir hatayla karşılaşırsa, sorunu açıklayan bir hata kodu döndürür.

Aşağıdaki tabloda Dağıtım API'sinden gelen yaygın hata kodları ve bunların tipik nedenleri listelenmektedir:

Hata kodu İsim Yaygın neden
0x80070005 ACCESS_DENIED Uygulama tam güvenilir değil ya da packageManagement kısıtlı yeteneğine sahip değil. Yükseltilmiş olarak çalıştırın veya gerekli özelliği ekleyin.
0x80073CF0 ERROR_INSTALL_OPEN_PACKAGE_FAILED MSIX paketi bozuk veya erişilemiyor. Paket dosyasının bozulmadığını ve yolun doğru olduğunu doğrulayın.
0x80073CF3 ERROR_INSTALL_PREREQUISITE_FAILED Gerekli bir bağımlılık paketi eksik veya uyumsuz. VCLibs çerçeve paketinin ve diğer önkoşulların yüklendiğinden emin olun.
0x80073D06 PAKETLER_KULLANIMDA_HATASI Bir veya daha fazla paket kullanımda ve güncelleştirilemiyor. Windows Uygulama SDK'sı çalışma zamanını kullanarak tüm uygulamaları kapatın ve yeniden deneyin.
0x80073CFB ERROR_PACKAGE_ALREADY_EXISTS Paket sürümü zaten kayıtlı. Bu bilgilendirme amaçlıdır; uygulamanız devam edebilir.
0x80073CF9 ERROR_INSTALL_FAILED Genel bir yükleme hatası. Daha fazla ayrıntı için olay günlüklerini denetleyin (aşağıya bakın).

Tavsiye

MSIX paketi yükleme hata kodlarının tam listesi için bkz. Windows uygulamaları paketleme, dağıtım ve sorgu sorunlarını giderme.

Hata kodu yeterli bilgi sağlamıyorsa ayrıntılı olay günlüklerinde daha fazla tanılama bilgisi bulabilirsiniz (bkz. Tanılama bilgilerini alma ). Olay günlükleri, Uygulama ve Hizmet Günlükleri>Microsoft Windows>>AppxDeployment-Server altında Olay Görüntüleyicisi bulunur.

Tanılayamadığınız hatalarla karşılaşırsanız, sorunu araştırabilmemiz için WindowsAppSDK GitHub deposunda hata kodu ve olay günlükleriyle bir sorun oluşturun.

  • Last updated on