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

Bu konu, dış konumla paketlenmiş veya paketlenmemiş ve Windows Uygulama SDK'sı kullanan uygulamaları dağıtma hakkında rehberlik sağlar.

  • Bu tür uygulamalar masaüstü uygulamalarıdır (UWP uygulamaları değildir).
  • Bunlar C# gibi .NET bir dilde veya C++ dilinde yazılabilir.
  • Kullanıcı arabirimi için WinUI 3 veya WPF ya da WinForms ya da başka bir kullanıcı arabirimi çerçevesi kullanabilirler.

Genel Bakış

Dış konumla birlikte paketlenmiş ve paketlenmemiş uygulamalar geliştirenler, gerekli Windows Uygulama SDK'sı çalışma zamanı paketlerini son kullanıcılarına dağıtmaktan sorumludur. Bu, yükleyici çalıştırılarak veya MSIX paketlerini doğrudan yükleyerek yapılabilir. Bu seçenekler aşağıdaki Deploy Windows Uygulama SDK'sı runtime bölümünde daha ayrıntılı olarak açıklanmıştır.

Dış konumla paketlenmiş ve paketlenmemiş uygulamaların da ek çalışma zamanı gereksinimleri vardır. Windows Uygulama SDK'sı çalışma zamanı ortamına erişimi Bootstrapper API'sini kullanarak başlatmalısınız. Ayrıca, uygulamanız Windows Uygulama SDK'sı dışında diğer çerçeve paketlerini kullanıyorsa Dinamik Bağımlılıklar API'sini kullanabilirsiniz. Bu gereksinimler, aşağıdaki dış konum veya paketlenmemiş uygulamalar için çalışma zamanı gereksinimleri bölümünde daha ayrıntılı olarak açıklanmıştır.

Önkoşullar

Ek önkoşullar

  • Windows Uygulama SDK'sı deneysel ve önizleme sürümleri, çalışma zamanını yüklemek için dışarıdan yüklemenin etkinleştirilmesini gerektirir.

    • Dışarıdan yükleme, Windows 10 sürüm 2004 ve sonraki sürümlerde otomatik olarak etkinleştirilir.

    • Geliştirme bilgisayarınız veya dağıtım bilgisayarınız Windows 11 çalıştırıyorsa dışarıdan yüklemenin etkinleştirilip etkinleştirilmediğini onaylayın:

      • Ayarlar>Gizlilik ve güvenlik>Geliştiriciler için. Geliştirici modu ayarının açık olduğundan emin olun.

    • Geliştirme bilgisayarınız veya dağıtım bilgisayarınız Windows 10 sürüm 1909 veya önceki bir sürüm çalıştırıyorsa dışarıdan yüklemenin etkinleştirilip etkinleştirilmediğini onaylayın:

      • Ayarlar>Güncelleştirme ve Güvenlik>Geliştiriciler> içinGeliştirici özelliklerini kullanın. Dışarıdan yükleme uygulamalarının veya Geliştirici modunun seçili olduğunu onaylayın.

    • Geliştirici modu ayarı dışarıdan yüklemeyi ve diğer özellikleri içerir.

      Uyarı

      Bilgisayar kurumsal bir ortamda yönetiliyorsa, bu ayarların değiştirilmesini engelleyen bir ilke olabilir. Bu durumda, siz veya uygulamanız Windows Uygulama SDK'sı çalışma zamanını yüklemeye çalıştığında bir hata alırsanız dışarıdan yüklemeyi veya Geliştirici modunu etkinleştirmek için BT Uzmanınıza başvurun.

Windows Uygulama SDK'sı çalışma zamanını dağıtın

Dış konumla paketlenmiş ve paketlenmemiş uygulamalar, Windows Uygulama SDK'sı çalışma zamanını dağıtmak için iki seçeneğe sahiptir:

  • Option 1: Installer kullanın: Sessiz yükleyici tüm Windows Uygulama SDK'sı MSIX paketlerini dağıtır. X64, X86 ve Arm64 mimarilerinin her biri için ayrı bir yükleyici bulunmaktadır.
  • Option 2: Paketleri doğrudan yükleyin: Mevcut kurulum veya MSI aracınızın Windows Uygulama SDK'sı için MSIX paketlerini taşımasını ve yüklemesini sağlayabilirsiniz.

1. Seçenek: Yükleyiciyi Kullanma

Yükleyiciyi çalıştırarak tüm Windows Uygulama SDK'sı çalışma zamanı paketlerini dağıtabilirsiniz. Yükleyici, Windows Uygulama SDK'sı İndirilenler bölümünde kullanılabilir. Yükleyiciyi (.exe) çalıştırırken aşağıdakine benzer bir çıkış görmeniz gerekir:

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: MicrosoftCorporationII.WindowsAppRuntime.Main.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.Singleton_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x6_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x8_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

All install operations successful.

Yükleyiciyi kullanıcı etkileşimi olmadan çalıştırabilir ve şu seçenekle tüm metin çıkışlarını gizleyebilirsiniz --quiet :

WindowsAppRuntimeInstall.exe --quiet

MsIX paketlerini güncelleştirmeye zorlamayı ve --force seçeneğini kullanarak şu anda çalışan Windows Uygulama SDK'sı işlemleri kapatmayı da seçebilirsiniz. Bu özellik 1.1'de kullanıma sunulmuştur.

WindowsAppRuntimeInstall.exe --force

Tüm yükleyici komut satırı seçeneklerini görmek için komutunu çalıştırın WindowsAppRuntimeInstall --h.

Yükleme tamamlandıktan sonra paketlenmiş uygulamanızı dış konumla veya paketlenmemiş uygulamayla çalıştırabilirsiniz. Dış konum kullanarak paketlenmiş veya Windows Uygulama SDK'sı kullanan paketlenmemiş bir uygulamanın nasıl derleneceği ve çalıştırılacağına dair bir örnek için bkz. Öğretici: Windows Uygulama SDK'sı kullanan dış konumla paketlenmiş veya paketlenmemiş bir uygulamada önyükleyici API'sini kullanma.

Windows Uygulama SDK'sı yükleyicisini uygulamanızın kurulumuna zincirleme

Uygulamanız için özel bir kurulum programınız varsa, uygulamanızın kurulum işleminde Windows Uygulama SDK'sı kurulum işlemini zincirleyebilirsiniz. Windows Uygulama SDK'sı yükleyicisi şu anda varsayılan bir kullanıcı arabirimi sağlamadığından kurulumunuzun özel kullanıcı arabirimini kullanarak zincirleme yapmanız gerekir.

ShellExecute kullanarak kurulum ilerleme durumunun kendi görünümünü gösterirken Windows Uygulama SDK'sı kurulumunu sessizce başlatabilir ve izleyebilirsiniz. Windows Uygulama SDK'sı yükleyicisi Windows Uygulaması MSIX paketini sessizce açar ve yüklemeyi tamamlamak için PackageManager.AddPackageAsync yöntemini çağırır. Bu, .NET, Visual C++ veya DirectX gibi kullanmış olabileceğiniz diğer çalışma zamanı yükleyicilerine çok benzer.

Kurulum programınızdan Windows Uygulama SDK'sı yükleyicisinin nasıl çalıştırıldığını gösteren bir kod örneği için, installer işlevsel testleri içindeki RunInstaller işlevine bakın.

Yükleyici örneği

Kurulum sırasında bir konsol penceresi açmadan yükleyiciyi win32 kurulum programından başlatmayı görmek için aşağıdaki örneğe bakın:

Explore Installer örneği

Sorun giderme

İade kodları

Aşağıdaki tabloda, Windows Uygulama SDK'sı .exe yükleyicisi için en yaygın dönüş kodları listelenmektedir. Dönüş kodları, yükleyicinin tüm sürümleri için aynıdır.

İade kodu Description
0x0 Paket yükleme veya sağlama başarıyla tamamlandı.
0x80073d06 Bir veya daha fazla paket yüklenemedi.
0x80070005 Uygulama yükseltilmiş çalışmadığından veya yüklemeyi yapan kullanıcının yönetici ayrıcalıkları olmadığından sistem genelinde yükleme veya sağlama mümkün değildi.

Yükleme hataları

Windows Uygulama SDK'sı yükleyicisi yükleme sırasında bir hata döndürürse, sorunu açıklayan bir hata kodu döndürür.

2. Seçenek: Windows Uygulama SDK'sı çalışma zamanı paketlerini doğrudan dağıtma

Son kullanıcılara dağıtım için Windows Uygulama SDK'sı yükleyicisini kullanmaya alternatif olarak, MSIX paketlerini uygulamanızın programı veya MSI aracılığıyla el ile dağıtabilirsiniz. Bu seçenek, daha fazla denetim isteyen geliştiriciler için en iyi seçenek olabilir.

Kurulum programınızın MSIX paketlerini nasıl yükleyebileceğini gösteren bir örnek için Windows Uygulama SDK'sı yükleyici kodundaki install.cpp bölümüne bakın.

Windows Uygulama SDK'sı zaten yüklü olup olmadığını denetlemek için (ve yüklüyse, hangi sürümde), PackageManager.FindPackagesForUserWithPackageTypes çağrısı yaparak belirli paket ailelerini denetleyebilirsiniz.

MediumIL (tam güvenli) paketlenmemiş bir işlemden (bkz. Uygulama öğesi), geçerli kullanıcıya kayıtlı bir paketi kontrol etmek için aşağıdaki kodu kullanabilirsiniz:

using Windows.Management.Deployment;

public class WindowsAppSDKRuntime
{
    public static bool IsPackageRegisteredForCurrentUser(
        string packageFamilyName,
        PackageVersion minVersion,
        Windows.System.ProcessorArchitecture architecture,
        PackageTypes packageType)
    {
        ulong minPackageVersion = ToVersion(minVersion);

        foreach (var p in new PackageManager().FindPackagesForUserWithPackageTypes(
            string.Empty, packageFamilyName, packageType))
        {
            // Is the package architecture compatible?
            if (p.Id.Architecture != architecture)
            {
                continue;
            }

            // Is the package version sufficient for our needs?
            ulong packageVersion = ToVersion(p.Id.Version);
            if (packageVersion < minPackageVersion)
            {
                continue;
            }

            // Success.
            return true;
        }

        // No qualifying package found.
        return false;
    }

    private static ulong ToVersion(PackageVersion packageVersion)
    {
        return ((ulong)packageVersion.Major << 48) |
               ((ulong)packageVersion.Minor << 32) |
               ((ulong)packageVersion.Build << 16) |
               ((ulong)packageVersion.Revision);
    }
}

Yukarıdaki senaryo için FindPackagesForUserWithPackageTypes çağrısı, FindPackagesForUser çağrısı yapmak için tercih edilir. Bunun nedeni aramayı yalnızca çerçeve veya ana paketler olarak daraltabilmenizdir (bu örnekte). Bu da bu örnekte ilgi çekici olmayan diğer paket türlerinin ( kaynak, isteğe bağlı veya paket gibi) eşleşmesini önler.

Geçerli/çağıran kullanıcı bağlamını kullanmak için userSecurityId parametresini boş bir dize olarak ayarlayın.

Şimdi de yukarıdaki kod örneğinde işlevi nasıl çağırabileceğinize karar vermenize yardımcı olacak bazı bilgiler. Düzgün yüklenmiş bir çalışma zamanı, sistemin CPU mimarisine bağlı olan birden çok paketlerden oluşur:

  • x86 makinesinde: Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
  • Bir x64 makinesinde: Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
  • Arm64 makinesinde: Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].

Main ve Singleton paketleri için mimarileri sistemin CPU mimarisiyle eşleşmelidir; örneğin, bir x64 sistemindeki x64 paketleri. Çerçeve paketi için bir x64 sistemi hem x64 hem de x86 uygulamalarını çalıştırabilir; benzer şekilde arm64 sistemi arm64, x64 ve x86 uygulamalarını çalıştırabilir. DDLM paket denetimi, çerçeve denetimine benzer, ancak PackageType=main, ve packagefamilyname farklıdır ve DDLM'nin benzersiz adlandırma düzeni nedeniyle birden fazla (farklı) paket adı uygulanabilir. Daha fazla bilgi için bkz. MSIX paketleri belirtimi. Bu nedenle denetimler daha çok şöyledir:

public static bool IsRuntimeRegisteredForCurrentUser(PackageVersion minVersion)
{
    ProcessorArchitecture systemArchitecture = DetectSystemArchitecture();

    return IsFrameworkRegistered(systemArchitecture, minVersion) &&
           IsMainRegistered(systemArchitecture, minVersion) &&
           IsSingletonRegistered(systemArchitecture, minVersion) &&
           IsDDLMRegistered(systemArchitecture, minVersion);
}

private static ProcessorArchitecture DetectSystemArchitecture()
{
    // Implementation: call IsWow64Process2() as shown in IsPackageApplicable() in
    // [install.cpp](https://github.com/microsoft/WindowsAppSDK/blob/main/installer/dev/install.cpp)
    // lines 99-116. WARNING: Use IsWow64Process2 — other similar APIs give unreliable results.
    throw new NotImplementedException();
}

private static bool IsFrameworkRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // Check x86.
    if (!IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
        minVersion, ProcessorArchitecture.X86,
        PackageTypes.Framework))
    {
        return false;
    }

    // Check x64 (if necessary).
    if ((systemArchitecture == ProcessorArchitecture.X64) || 
        (systemArchitecture == ProcessorArchitecture.Arm64))
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.X64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    // Check arm64 (if necessary).
    if (systemArchitecture == ProcessorArchitecture.Arm64)
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.Arm64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    return true;
}

private static bool IsMainRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Main.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsSingletonRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Singleton.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsDDLMRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // ...similar to IsFrameworkRegistered, but the packageFamilyName is more complicated...
    // ...and no predefined constant is currently available...
    // ...for more details, see
    // https://github.com/microsoft/WindowsAppSDK/blob/main/specs/Deployment/MSIXPackages.md.
}

Yukarıdaki bilgiler ve kod, temel algılama senaryolarını kapsar. Çalışma zamanının tüm kullanıcılar için sağlanıp sağlanmadığını algılamak veya yukarıdaki işlemi bir Uygulama Kapsayıcısından ve/veya paketlenmiş bir mediumIL işleminden yapmak için ek mantık gerekir.

Dağıtım senaryoları

  • Windows Uygulama SDK'sı Çalışma Zamanı sistem genelinde yükleme: Sistem genelinde yükleme, gelecekte eklenecek yeni kullanıcılar da dahil olmak üzere tüm kullanıcılar için makineyi değiştirir. Uygulama yükseltilmiş olarak çalışıyorsa ve yüklemeyi yapan kullanıcının yönetici ayrıcalıkları varsa, yükleyici ProvisionPackageForAllUsersAsync'i çağırarak sistem genelinde MSIX paketlerini kaydeder. Sistem genelinde kayıt başarılı olmazsa, yükleme yalnızca yüklemeyi yapan geçerli kullanıcı için gerçekleştirilir. Yönetilen bir Kurumsal ortamda BT yöneticisinin herkes için her zamanki gibi sağlama yapabilmesi gerekir.

  • Windows Uygulama SDK'sı yükleyicisi tarafından dağıtılan mimariler: Windows Uygulama SDK'sı yükleyicisi x86, x64, ve Arm64 mimarilerinde mevcuttur. Yükleyicinin her sürümü, yalnızca adını aldığı belirli mimariye yönelik MSIX paketlerini içerir. Örneğin, x86WindowsAppRuntimeInstall.exe'i bir x64 veya Arm64 cihazında çalıştırırsanız, x86 yükleyici bu cihaza yalnızca x86 mimarisi için olan paketleri dağıtır.

  • Tüm Windows Uygulama SDK'sı MSIX paketleri bilgisayarda zaten yüklü: MSIX paketleri, diskte yalnızca bir kopyası olan sistem genelinde bir konuma yüklenir. Bir uygulama, makinede tüm MSIX paket bağımlılıkları zaten yüklü olduğunda Windows Uygulama SDK'sı yüklemeyi denerse, yükleme gerçekleştirilmez.

  • Windows Uygulama SDK'sı MSIX paketlerinden biri veya daha fazlası bilgisayara yüklü değil: Windows Uygulama SDK'sı dağıtırken, tüm bağımlılıkların yüklendiğinden ve son kullanıcı deneyiminde kesinti yaşanmasını önlemek için her zaman tüm MSIX paketlerini (çerçeve, ana, tekil, DDLM) yüklemeyi deneyin.

Dış konumla paketlenmiş veya paketlenmemiş uygulamalar için çalışma zamanı gereksinimleri

Dış konumla paketlenmiş veya paketlenmemiş uygulamalar, Windows Uygulama SDK'sı çalışma zamanını kullanmak için ek çalışma zamanı gereksinimlerine sahiptir. Bu, çalışma zamanında Windows Uygulama SDK'sı Framework paketine başvurmayı ve başlatmayı içerir. Ayrıca Dinamik Bağımlılıklar API'sini kullanarak Windows Uygulama SDK'sı dışındaki diğer çerçeve paketlerine başvurabilirsiniz.

Windows Uygulama SDK'sı çalışma zamanını kullanma

Dış konumla paketlenmiş ve paketlenmemiş uygulamalar, çalışma zamanında Windows Uygulama SDK'sı kullanmak için Bootstrapper API'sini çağırmalıdır. Bu, uygulamanın WinUI, Uygulama Yaşam Döngüsü, MRT Core ve DWriteCore gibi Windows Uygulama SDK'sı özelliklerini kullanabilmesi için gereklidir. Bir önyükleyici bileşeni, dış konumla veya paketlenmemiş olan uygulamalarla paketlendiğinde şu önemli görevleri yerine getirmelerini sağlar:

  • Windows Uygulama SDK'sı çerçeve paketini bulun ve uygulamanın paket grafiğine yükleyin.
  • Windows Uygulama SDK'sı çerçeve paketi için Dinamik Bağımlılık Yaşam Süresi Yöneticisi'ni (DDLM) başlatın. DDLM'nin amacı, dış konumla paketlenmiş veya paketlenmemiş bir uygulama tarafından kullanılırken Windows Uygulama SDK'sı çerçeve paketinin güncellenmesini önlemektir.

Dış konum ile paketlenmemiş uygulamalar ve paketlenmiş uygulamalar için Windows Uygulama SDK çalışma zamanını yüklemenin en kolay yolu, proje dosyanızda (.csproj veya .vcxproj) <WindowsPackageType>None</WindowsPackageType> özelliğini ayarlamaktır. Başlatma üzerinde daha fazla denetim için önyükleyici API'sini doğrudan uygulamanızın başlangıç kodunda da çağırabilirsiniz. Daha fazla ayrıntı için, Uygulamalarınızı dış konumla veya paketlenmemiş olarak kullanmak için Windows Uygulama SDK'sı çalışma zamanını kullanma ve Uygulamanızı dış konumla veya paketlenmemiş olarak paketleyen ve Windows Uygulama SDK'sı kullanan bir uygulamada bootstrapper API'sini kullanma Eğitimini inceleyin.

Dinamik Bağımlılıklar desteği, dış konum ve paketlenmemiş uygulamalarla paketlenmiş uygulamaların MSI veya herhangi bir yükleyici gibi mevcut dağıtım mekanizmalarını korumasını ve uygulamalarında Windows Uygulama SDK'sı kullanabilmesini sağlar. Dinamik bağımlılıklar paketlenmiş, dış konumla paketlenmiş ve paketlenmemiş uygulamalar tarafından kullanılabilir; ancak öncelikle dış konum ve paketlenmemiş uygulamalarla paketlenmiş olarak kullanılması amaçlanmıştır.

Windows Uygulama SDK'sı çerçeve paketinin her sürümü ve mimarisi için bir DDLM vardır. Bu, bir x64 bilgisayarda her iki mimarinin uygulamalarını desteklemek için DDLM'nin hem bir x86 sürümüne hem de sürümüne x64 sahip olabileceğiniz anlamına gelir.

Dinamik Bağımlılıklar API'lerini kullanarak diğer çerçeve paketlerine başvurma

Windows Uygulama SDK'sı dışındaki çerçeve paketlerinin (örneğin, DirectX) özelliklerini, harici bir konumda olan veya paketlenmemiş uygulamalarla birlikte kullanmak istiyorsanız Dinamik Bağımlılıklar API'sini çağırabilirsiniz. Önyükleyici bileşenine ek olarak, Windows Uygulama SDK'sı dynamic dependency API uygulayan daha geniş bir C/C++ işlevleri ve WinRT sınıfları kümesi de sağlar. Bu API, çalışma zamanında herhangi bir çerçeve paketine dinamik olarak başvurmak için kullanılacak şekilde tasarlanmıştır.

Daha fazla bilgi için bkz. Masaüstü uygulamanızdan dinamik olarak MSIX çerçeve paketlerini kullanma ve Dinamik Bağımlılıklar örneği

.winmd dosyalarını hedef makineye dağıtma

Uygulamanızla birlikte, devam edip Windows Meta Verileri (.winmd) dosyalarını dağıtmanızı öneririz. Meta veriler çalışma zamanında çeşitli API'ler ve davranışlar tarafından kullanılabilir ve yokluğu işlevselliği sınırlayabilir veya kesebilir. Örneğin, nesneleri apartman sınırları boyunca sıralamak için meta veriler kullanılabilir; ve sıralama gereksinimi, makine performansının bir işlevi olabilir. Meta verilere ihtiyacınız olup olmadığını bilmenin belirleyici bir yol yoktur, bu nedenle boyut konusunda son derece kaygılanmıyorsanız, .winmd yerleştirmeniz gerekir.

  • Last updated on