.NET uygulamalarında kaynakları paketleme ve dağıtma

Makale
04/08/2023

Uygulamalar, yerelleştirilmiş kaynakları almak için sınıfı tarafından ResourceManager temsil edilen .NET Framework Resource Manager'ı kullanır. Resource Manager, kaynakları paketlemek ve dağıtmak için bir merkez-uç modelinin kullanıldığını varsayar. Merkez, bağımsız veya varsayılan kültür olarak adlandırılan, konumlanamayan yürütülebilir kodu ve tek bir kültürün kaynaklarını içeren ana derlemedir. Varsayılan kültür, uygulamanın geri dönüş kültürüdür; yerelleştirilmiş kaynaklar bulunamazsa kaynakları kullanılan kültürdür. Her uç, tek bir kültüre yönelik kaynakları içeren ancak herhangi bir kod içermeyen bir uydu derlemesine bağlanır.

Bu modelin birkaç avantajı vardır:

Uygulamayı dağıttıktan sonra yeni kültürler için artımlı olarak kaynak ekleyebilirsiniz. Kültüre özgü kaynakların daha sonra geliştirilmesi önemli bir süre gerektirebileceğinden, bu, önce ana uygulamanızı serbest bırakmanıza ve kültüre özgü kaynakları daha sonraki bir tarihte sunmanıza olanak tanır.
Uygulamayı yeniden derlemeden uygulamanın uydu derlemelerini güncelleştirebilir ve değiştirebilirsiniz.
Bir uygulamanın yalnızca belirli bir kültür için gereken kaynakları içeren uydu derlemelerini yüklemesi gerekir. Bu, sistem kaynaklarının kullanımını önemli ölçüde azaltabilir.

Ancak, bu modelin dezavantajları da vardır:

Birden çok kaynak kümesini yönetmeniz gerekir.
Birkaç yapılandırmayı test etmeniz gerektiğinden, bir uygulamayı test etme işleminin ilk maliyeti artar. Uzun vadede, bir çekirdek uygulamayı çeşitli uydularla test etmek, çeşitli paralel uluslararası sürümleri test etmek ve sürdürmekten daha kolay ve daha düşük maliyetli olacaktır.

Kaynak adlandırma kuralları

Uygulamanızın kaynaklarını paketlediğinizde, bunları ortak dil çalışma zamanının beklediği kaynak adlandırma kurallarını kullanarak adlandırmanız gerekir. Çalışma zamanı, bir kaynağı kültür adına göre tanımlar. Her kültüre, genellikle bir dille ilişkilendirilmiş iki harfli, küçük harfli bir kültür adının ve gerekirse bir ülke veya bölgeyle ilişkilendirilmiş iki harfli, büyük harfli bir alt kültür adının birleşimi olan benzersiz bir ad verilir. Alt kültür adı, kültür adını bir tire (-) ile ayırarak izler. Örnek olarak Japonya'da konuşulan Japonca için ja-JP, Birleşik Devletler konuşulan İngilizce için en-US, Almanya'da konuşulan Almanca için de-DE veya Avusturya'da konuşulan Almanca için de-AT verilebilir. Windows tarafından desteklenen dil/bölge adları listesinde Dil etiketi sütununa bakın. Kültür adları BCP 47 tarafından tanımlanan standarda uyar.

Not

İki harfli kültür adları için Çince (Basitleştirilmiş) gibi zh-Hans bazı özel durumlar vardır.

Daha fazla bilgi için bkz . Kaynak dosyaları oluşturma ve Uydu derlemeleri oluşturma.

Kaynak geri dönüş işlemi

Kaynakları paketlemeye ve dağıtmaya yönelik merkez-uç modeli, uygun kaynakları bulmak için bir geri dönüş işlemi kullanır. Bir uygulama kullanılamayan yerelleştirilmiş bir kaynak isterse ortak dil çalışma zamanı, kültür hiyerarşisinde kullanıcının uygulamasının isteğiyle en yakından eşleşen uygun bir geri dönüş kaynağı arar ve yalnızca son çare olarak bir özel durum oluşturur. Hiyerarşinin her düzeyinde uygun bir kaynak bulunursa çalışma zamanı bunu kullanır. Kaynak bulunamazsa arama bir sonraki düzeyde devam eder.

Arama performansını geliştirmek için özniteliğini NeutralResourcesLanguageAttribute ana derlemenize uygulayın ve ana derlemenizle çalışacak nötr dilin adını geçirin.

.NET Framework kaynak geri dönüş işlemi

.NET Framework kaynak geri dönüş işlemi aşağıdaki adımları içerir:

İpucu

Kaynak geri dönüş işlemini ve çalışma zamanının <kaynak derlemeleri için yokladığı işlemi iyileştirmek için relativeBindForResources> yapılandırma öğesini kullanabilirsiniz. Daha fazla bilgi için bkz . Kaynak geri dönüş işlemini iyileştirme.

Çalışma zamanı önce uygulamanız için istenen kültürle eşleşen bir derleme için genel derleme önbelleğini denetler.

Genel derleme önbelleği, birçok uygulama tarafından paylaşılan kaynak derlemelerini depolayabilir. Bu, oluşturduğunuz her uygulamanın dizin yapısına belirli kaynak kümelerini eklemek zorunda kalmadan sizi serbesttir. Çalışma zamanı derlemeye bir başvuru bulursa, istenen kaynağı derlemede arar. Derlemedeki girdiyi bulursa, istenen kaynağı kullanır. Girdiyi bulamazsa aramaya devam eder.
Çalışma zamanı, şu anda yürütülmekte olan derlemenin dizinini istenen kültürle eşleşen bir alt dizin için denetler. Alt dizini bulursa, istenen kültür için geçerli bir uydu derlemesi için bu alt dizini arar. Çalışma zamanı, istenen kaynağı uydu derlemesinde arar. Derlemedeki kaynağı bulursa kullanır. Kaynağı bulamazsa aramaya devam eder.
Çalışma zamanı, uydu derlemesinin isteğe bağlı olarak yüklenip yüklenmeyeceğini belirlemek için Windows Installer'ı sorgular. Bu durumda yüklemeyi işler, derlemeyi yükler ve bu derlemeyi veya istenen kaynağı arar. Derlemedeki kaynağı bulursa kullanır. Kaynağı bulamazsa aramaya devam eder.
Çalışma zamanı, uydu derlemesini AppDomain.AssemblyResolve bulamadığını belirtmek için olayı tetikler. Olayı işlemeyi seçerseniz, olay işleyiciniz kaynakları arama için kullanılacak olan uydu derlemesine bir başvuru döndürebilir. Aksi takdirde, olay işleyicisi döndürür null ve arama devam eder.
Çalışma zamanı, bu kez istenen kültürün üst derlemesi için genel derleme önbelleğini yeniden arar. Üst derleme genel derleme önbelleğinde varsa, çalışma zamanı istenen kaynağı derlemede arar.

Üst kültür, uygun geri dönüş kültürü olarak tanımlanır. Herhangi bir kaynak sağlamak bir özel durum oluşturma tercih edildiğinden, ebeveynleri geri dönüş adayı olarak kabul edin. Bu işlem, kaynakları yeniden kullanmanıza da olanak tanır. Yalnızca alt kültürün istenen kaynağı yerelleştirmesi gerekmiyorsa belirli bir kaynağı üst düzeye eklemeniz gerekir. Örneğin, (bağımsız İngilizce), en-GB (Birleşik Krallık'ta konuşulan İngilizce) ve en-US (Birleşik Devletler konuşulan İngilizce) en için en uydu derlemeleri sağlarsanız, uydu ortak terminolojiyi içerir ve en-GB ve en-US uyduları yalnızca farklı terimler için geçersiz kılmalar sağlayabilir.
Çalışma zamanı, şu anda yürütülmekte olan derlemenin dizinini denetleerek bir üst dizin içerip içermediğini denetler. Bir üst dizin varsa, çalışma zamanı dizinde üst kültür için geçerli bir uydu derlemesi arar. Derlemeyi bulursa, çalışma zamanı istenen kaynağı derlemede arar. Kaynağı bulursa kullanır. Kaynağı bulamazsa aramaya devam eder.
Çalışma zamanı, üst uydu derlemesinin isteğe bağlı olarak yüklenip yüklenmeyeceğini belirlemek için Windows Installer'ı sorgular. Bu durumda yüklemeyi işler, derlemeyi yükler ve bu derlemeyi veya istenen kaynağı arar. Derlemedeki kaynağı bulursa kullanır. Kaynağı bulamazsa aramaya devam eder.
Çalışma zamanı, uygun bir geri dönüş kaynağını bulamadığını belirtmek için olayı tetikler AppDomain.AssemblyResolve . Olayı işlemeyi seçerseniz, olay işleyiciniz kaynakları arama için kullanılacak olan uydu derlemesine bir başvuru döndürebilir. Aksi takdirde, olay işleyicisi döndürür null ve arama devam eder.
Çalışma zamanı, önceki üç adımda olduğu gibi birçok olası düzeyde üst derlemeleri arar. Her kültürün özelliği tarafından CultureInfo.Parent tanımlanan yalnızca bir üst öğesi vardır, ancak üst öğe kendi üst öğesi olabilir. Bir kültürün Parent özelliği döndürüldüğünde üst kültür araması durdurulur CultureInfo.InvariantCulture; kaynak geri dönüşü için sabit kültür, kaynakları olabilecek bir üst kültür veya kültür olarak kabul edilmez.
Başlangıçta belirtilen kültür ve tüm üst öğeler arandıysa ve kaynak hala bulunamazsa, varsayılan (geri dönüş) kültürü için kaynak kullanılır. Genellikle, varsayılan kültür kaynakları ana uygulama derlemesine dahil edilir. Ancak, kaynaklar için Location nihai geri dönüş konumunun NeutralResourcesLanguageAttribute ana derleme yerine bir uydu derleme olduğunu belirtmek üzere özniteliğinin özelliği için değerini Satellite belirtebilirsiniz.

Not

Varsayılan kaynak, ana derlemeyle derlenebilir tek kaynaktır. Özniteliğini kullanarak bir uydu derlemesi NeutralResourcesLanguageAttribute belirtmediğiniz sürece, bu son geri dönüştür (son üst). Bu nedenle, ana derlemenize her zaman varsayılan bir kaynak kümesi eklemenizi öneririz. Bu, özel durumların oluşmasını önlemeye yardımcı olur. Varsayılan bir kaynak ekleyerek, dosya tüm kaynaklar için bir geri dönüş sağlar ve kültürel olarak özel olmasa bile kullanıcı için her zaman en az bir kaynağın mevcut olduğundan emin olursunuz.
Son olarak, çalışma zamanı varsayılan (geri dönüş) kültürü için bir kaynak bulamazsa, kaynağın bulunamadığını belirtmek için veya MissingManifestResourceException MissingSatelliteAssemblyException özel durumu oluşturulur.

Örneğin, uygulamanın İspanyolca (Meksika) (kültür) için yerelleştirilmiş bir kaynak isteğinde olduğunu es-MX varsayalım. Çalışma zamanı ilk olarak ile eşleşen es-MXderleme için genel derleme önbelleğini arar, ancak bunu bulamaz. Çalışma zamanı, şu anda yürütülmekte olan derlemenin dizininde bir es-MX dizin arar. Başarısız olursa, çalışma zamanı genel derleme önbelleğinde, uygun geri dönüş kültürünü yansıtan bir üst derlemeyi (bu durumda İspanyolca es ) yeniden arar. Üst derleme bulunamazsa, çalışma zamanı ilgili kaynağı bulana kadar kültür için es-MX tüm olası üst derleme düzeylerini arar. Kaynak bulunamazsa, çalışma zamanı varsayılan kültür için kaynağı kullanır.

.NET Framework kaynak geri dönüş işlemini iyileştirme

Aşağıdaki koşullar altında, çalışma zamanının uydu derlemelerindeki kaynakları arama işlemini iyileştirebilirsiniz:

Uydu derlemeleri, kod derlemesi ile aynı konuma dağıtılır. Kod derlemesi Genel Derleme Önbelleği'nde yüklüyse, uydu derlemeleri de genel derleme önbelleğine yüklenir. Kod derlemesi bir dizinde yüklüyse, uydu derlemeleri bu dizinin kültüre özgü klasörlerine yüklenir.
Uydu derlemeleri isteğe bağlı olarak yüklenmez.
Uygulama kodu olayı işlemez AppDomain.AssemblyResolve .

Aşağıdaki örnekte gösterildiği gibi relativeBindForResources öğesini ekleyerek <ve özniteliğini enabledtrue uygulama yapılandırma dosyasında olarak ayarlayarak araştırmayı uydu derlemeleri> için iyileştirebilirsiniz.

<configuration>
   <runtime>
      <relativeBindForResources enabled="true" />
   </runtime>
</configuration>

Uydu derlemeleri için iyileştirilmiş yoklama, bir kabul etme özelliğidir. Diğer bir deyişle, uygulamanın yapılandırma dosyasında relativeBindForResources> öğesi yoksa ve enabled özniteliği olarak ayarlanmadıysa <trueçalışma zamanı Kaynak geri dönüş işlemi bölümünde belgelenen adımları izler. Bu durumda, bir uydu derlemesi için yoklama işlemi aşağıdaki gibi değiştirilir:

Çalışma zamanı, uydu derlemesini araştırmak için üst kod derlemesinin konumunu kullanır. Üst derleme genel derleme önbelleğine yüklenirse, çalışma zamanı önbellekte yoklanır ancak uygulamanın dizininde yoklanır. Üst derleme bir uygulama dizinine yüklenmişse, çalışma zamanı uygulama dizininde yoklanır ancak genel derleme önbelleğinde yoklanır.
Çalışma zamanı, uydu derlemelerinin isteğe bağlı yüklenmesi için Windows Installer'ın sorgusunu yapmaz.
Belirli bir kaynak derlemesi için yoklama başarısız olursa, çalışma zamanı olayı tetiklemiyor AppDomain.AssemblyResolve .

.NET Core kaynak geri dönüş işlemi

.NET Core kaynak geri dönüş işlemi aşağıdaki adımları içerir:

Çalışma zamanı istenen kültür için bir uydu derlemesi yüklemeyi dener.
- şu anda yürütülmekte olan derlemenin dizinini istenen kültürle eşleşen bir alt dizin için denetler. Alt dizini bulursa, istenen kültür için geçerli bir uydu derlemesi için bu alt dizini arar ve yükler.
  
  Not
  
  Büyük/küçük harfe duyarlı dosya sistemlerine (Linux ve macOS) sahip işletim sistemlerinde kültür adı alt dizini araması büyük/küçük harfe duyarlıdır. Alt dizin adı, büyük/küçük harfle CultureInfo.Name tam olarak eşleşmelidir (örneğin, es veya es-MX).
  
  Not
  
  Programcı'dan AssemblyLoadContextözel bir derleme yük bağlamı türetmişse, durum karmaşıktır. Yürütülen derleme özel bağlama yüklendiyse, çalışma zamanı uydu derlemesini özel bağlama yükler. Ayrıntılar bu belgenin kapsamı dışında. Bkz. AssemblyLoadContext.
- Bir uydu derlemesi bulunamazsa, AssemblyLoadContext uydu derlemesini AssemblyLoadContext.Resolving bulamadığını belirtmek için olayı tetikler. Olayı işlemeyi seçerseniz, olay işleyiciniz uydu derlemesine bir başvuru yükleyip döndürebilir.
- Bir uydu derlemesi hala bulunamazsa AssemblyLoadContext, AppDomain'in uydu derlemesini bulamadığını belirtmek için bir AppDomain.AssemblyResolve olayı tetiklemesi için neden olur. Olayı işlemeyi seçerseniz, olay işleyiciniz uydu derlemesine bir başvuru yükleyip döndürebilir.
Bir uydu derlemesi bulunursa, çalışma zamanı istenen kaynağı arar. Derlemedeki kaynağı bulursa kullanır. Kaynağı bulamazsa aramaya devam eder.

Not

Uydu derlemesinde bir kaynak bulmak için çalışma zamanı geçerli CultureInfo.Nameiçin tarafından istenen ResourceManager kaynak dosyasını arar. Kaynak dosyasının içinde istenen kaynak adını arar. Bu kaynaklardan biri bulunamazsa, kaynak bulunamadı olarak değerlendirilir.
Çalışma zamanı, üst kültür derlemelerini her seferinde 1 . 2. adımları yineleyerek birçok olası düzeyde arar.

Üst kültür uygun bir geri dönüş kültürü olarak tanımlanır. Herhangi bir kaynak sağlamak bir özel durum oluşturma tercih edildiğinden, ebeveynleri geri dönüş adayı olarak kabul edin. Bu işlem, kaynakları yeniden kullanmanıza da olanak tanır. Yalnızca alt kültürün istenen kaynağı yerelleştirmesi gerekmiyorsa belirli bir kaynağı üst düzeye eklemeniz gerekir. Örneğin, (bağımsız İngilizce), en-GB (Birleşik Krallık'ta konuşulan İngilizce) ve en-US (Birleşik Devletler konuşulan İngilizce) en için en uydu derlemeleri sağlarsanız, uydu ortak terminolojiyi içerir ve en-GB ve en-US uyduları yalnızca farklı terimler için geçersiz kılmalar sağlar.

Her kültürün özelliği tarafından CultureInfo.Parent tanımlanan yalnızca bir üst öğesi vardır, ancak üst öğe kendi üst öğesi olabilir. Bir kültürün özelliği döndürdüğünde üst kültür Parent araması durdurulur CultureInfo.InvariantCulture. Kaynak geri dönüşü için sabit kültür, kaynakları olabilecek bir üst kültür veya kültür olarak kabul edilmez.
Başlangıçta belirtilen kültür ve tüm üst öğeler arandıysa ve kaynak hala bulunamazsa, varsayılan (geri dönüş) kültürü için kaynak kullanılır. Genellikle, varsayılan kültür kaynakları ana uygulama derlemesine dahil edilir. Ancak, kaynaklar için nihai geri dönüş konumunun Satellite Location ana derleme yerine bir uydu derlemesi olduğunu belirtmek üzere özelliği için değerini belirtebilirsiniz.

Not

Varsayılan kaynak, ana derlemeyle derlenebilir tek kaynaktır. Özniteliğini kullanarak bir uydu derlemesi NeutralResourcesLanguageAttribute belirtmediğiniz sürece, bu son geri dönüştür (son üst). Bu nedenle, ana derlemenize her zaman varsayılan bir kaynak kümesi eklemenizi öneririz. Bu, özel durumların oluşmasını önlemeye yardımcı olur. Varsayılan bir kaynak dosyası ekleyerek, tüm kaynaklar için bir geri dönüş sağlar ve kültürel olarak özel olmasa bile kullanıcı için her zaman en az bir kaynağın mevcut olduğundan emin olursunuz.
Son olarak, çalışma zamanı varsayılan (geri dönüş) kültürü için bir kaynak dosyası bulamazsa, kaynağın bulunamadığını belirtmek için veya MissingManifestResourceException MissingSatelliteAssemblyException özel durumu oluşturulur. Kaynak dosyası bulunursa ancak istenen kaynak mevcut değilse istek döndürür null.

Uydu derlemesine nihai geri dönüş

İsteğe bağlı olarak kaynakları ana derlemeden kaldırabilir ve çalışma zamanının belirli bir kültüre karşılık gelen bir uydu derlemesinden nihai geri dönüş kaynaklarını yüklemesi gerektiğini belirtebilirsiniz. Geri dönüş işlemini denetlemek için UltimateResourceFallbackLocation oluşturucuyu NeutralResourcesLanguageAttribute(String, UltimateResourceFallbackLocation) kullanır ve Resource Manager'ın geri dönüş kaynaklarını ana derlemeden mi yoksa bir uydu derlemesinden mi ayıklaması gerektiğini belirten bir parametre değeri sağlarsınız.

Aşağıdaki .NET Framework örneği, fransızca (fr) dil için bir uydu derlemesinde uygulamanın geri dönüş kaynaklarını depolamak için özniteliğini kullanırNeutralResourcesLanguageAttribute. Örnekte adlı Greetingtek bir dize kaynağını tanımlayan iki metin tabanlı kaynak dosyası vardır. İlki resources.fr.txt Fransızca dil kaynağı içerir.

Greeting=Bon jour!

İkincisi, kaynaklar,ru.txt, Rusça bir kaynak içerir.

Greeting=Добрый день

Bu iki dosya, komut satırından Kaynak Dosya Oluşturucu (resgen.exe) çalıştırılarak .resources dosyalarına derlenir. Fransızca dil kaynağı için komutu şu şekildedir:

resgen.exe resources.fr.txt

Rusça kaynak için komutu şu şekildedir:

resgen.exe resources.ru.txt

.resources dosyaları, Fransızca dil kaynağının komut satırından Assembly Linker (al.exe) çalıştırılarak dinamik bağlantı kitaplıklarına aşağıdaki gibi eklenir:

al /t:lib /embed:resources.fr.resources /culture:fr /out:fr\Example1.resources.dll

ve Rusça kaynağı için aşağıdaki gibi:

al /t:lib /embed:resources.ru.resources /culture:ru /out:ru\Example1.resources.dll

Uygulama kaynak kodu Example1.cs veya Example1.vb adlı bir dosyada bulunur. Varsayılan uygulama kaynağının NeutralResourcesLanguageAttribute fr alt dizininde olduğunu belirtmek için özniteliğini içerir. Resource Manager örneğini oluşturur, kaynağın Greeting değerini alır ve konsolda görüntüler.

using System;
using System.Reflection;
using System.Resources;

[assembly:NeutralResourcesLanguage("fr", UltimateResourceFallbackLocation.Satellite)]

public class Example
{
   public static void Main()
   {
      ResourceManager rm = new ResourceManager("resources",
                                               typeof(Example).Assembly);
      string greeting = rm.GetString("Greeting");
      Console.WriteLine(greeting);
   }
}

Imports System.Reflection
Imports System.Resources

<Assembly: NeutralResourcesLanguage("fr", UltimateResourceFallbackLocation.Satellite)>
Module Example
    Public Sub Main()
        Dim rm As New ResourceManager("resources", GetType(Example).Assembly)
        Dim greeting As String = rm.GetString("Greeting")
        Console.WriteLine(greeting)
    End Sub
End Module

Ardından C# kaynak kodunu komut satırından aşağıdaki gibi derleyebilirsiniz:

csc Example1.cs

Visual Basic derleyicisinin komutu çok benzerdir:

vbc Example1.vb

Ana derlemeye eklenmiş kaynak olmadığından, anahtarı kullanarak /resource derlemeniz gerekmez.

Örneği, dili Rusça dışında bir şey olan bir sistemden çalıştırdığınızda, aşağıdaki çıkış görüntülenir:

Bon jour!

Önerilen paketleme alternatifi

Zaman veya bütçe kısıtlamaları, uygulamanızın desteklediği her alt kültür için bir kaynak kümesi oluşturmanızı engelleyebilir. Bunun yerine, tüm ilgili alt kültürlerin kullanabileceği bir üst kültür için tek bir uydu derlemesi oluşturabilirsiniz. Örneğin, bölgeye özgü İngilizce kaynakları isteyen kullanıcılar tarafından alınan tek bir İngilizce uydu derlemesi (en) ve bölgeye özgü Almanca kaynaklar isteyen kullanıcılar için tek bir Almanca uydu derlemesi (de) sağlayabilirsiniz. Örneğin, Almanya'da konuşulan Almanca (de-DE), Avusturya (de-AT) ve İsviçre (de-CH) istekleri Alman uydu derlemesine (de) geri döner. Varsayılan kaynaklar son geri dönüş olacaktır ve bu nedenle uygulamanızın kullanıcılarının çoğunluğu tarafından istenecek kaynaklar olmalıdır, bu nedenle bu kaynakları dikkatli bir şekilde seçin. Bu yaklaşım daha az kültürel kaynaklar dağıtır, ancak uygulamanızın yerelleştirme maliyetlerini önemli ölçüde azaltabilir.

Aracılığıyla paylaş