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

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ın ardından bir tire (-) ile gelir. Örnek olarak Japonya'da konuşulan Japonca için ja-JP, ABD'de 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 Diletiketi sütununa bakın. Kültür adları BCP 47 tarafından tanımlanan standarda uyar.

Uyarı

İ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 mevcut olmayan bir yerelleştirilmiş kaynak isterse, ortak dil çalışma zaman ortamı kültür hiyerarşisinde, uygulamanın isteğiyle en yakın şekilde eşleşen uygun bir geri dönüş kaynağı arar ve yalnızca son çare olarak bir özel durum meydana getirir. 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:

Tavsiye

Kaynak geri dönüş işlemini ve çalışma zamanının kaynak derlemelerini yokladığı süreci 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ı derleme için bir referans bulursa, istenen kaynağı derlemede arar. Derlemedeki girdiyi bulursa, istenen kaynağı kullanır. Girdiyi bulamazsa aramaya devam eder.
Çalışma zamanı, önce ş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. Derlemede kaynağı bulursa onu kullanır. Kaynağı bulamazsa aramaya devam eder.
Çalışma zamanı, uydu bileşeninin talep üzerine yüklenip yüklenmeyeceğini belirlemek için Windows Installer'ı sorgular. Bu koşulda, kurulumu işler, derlemeyi yükler ve derlemeyi veya istenen kaynağı arar. Derlemede kaynağı bulursa onu kullanır. Kaynağı bulamazsa aramaya devam eder.
Çalışma zamanı, uydu derlemesini AppDomain.AssemblyResolve bulamadığını belirtmek için olayı başlatır. Olayı işlemeyi seçerseniz, olay işleyiciniz kaynakların arama için kullanılacağı uydu derlemesine bir referans 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.

Ana kültür, uygun yedek kültür olarak tanımlanır. Herhangi bir kaynak sağlamak istisna oluşturmaktan daha tercih edildiğinden, ebeveynleri alternatif adaylar olarak kabul edin. Bu işlem, kaynakları yeniden kullanmanıza da olanak tanır. Yalnızca alt kültürün istenen kaynağı yerelleştirmeye ihtiyacı yoksa belirli bir kaynağı yalnızca ebeveyn düzeyine eklemeniz gerekir. Örneğin, (nötr İngilizce), en (Birleşik Krallık'ta konuşulan İngilizce) ve en-GB (ABD'de konuşulan İngilizce) en-US 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.
Şu anda yürütülmekte olan derlemenin dizini içerisinde bir üst dizin olup olmadığını denetleyerek, çalışma zamanı kontrol eder. Bir ana dizin varsa, çalışma zamanı ana kültür için geçerli bir uydu derlemesi olup olmadığını kontrol etmek üzere dizini 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 koşulda, kurulumu işler, derlemeyi yükler ve derlemeyi veya istenen kaynağı arar. Derlemede kaynağı bulursa onu kullanır. Kaynağı bulamazsa aramaya devam eder.
Çalışma zamanı, uygun bir alternatif kaynak bulamadığını belirtmek için AppDomain.AssemblyResolve olayını yükseltir. Olayı işlemeyi seçerseniz, olay işleyiciniz kaynakların arama için kullanılacağı uydu derlemesine bir referans 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 farklı olası düzeyde üst derlemeleri arar. Her kültür, CultureInfo.Parent özelliği ile tanımlanan yalnızca bir üst öğeye sahiptir, ancak bu üst öğenin kendi üst öğesi olabilir. Bir kültürün Parent özelliği CultureInfo.InvariantCulture döndürdüğünde, üst kültürlerin araması durdurulur; kaynak geri dönüşü için sabit bir kültür, üst kültür veya kaynakları olan bir 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, nihai geri dönüş konumunun kaynaklar için ana derleme yerine bir uydu derleme olduğunu belirtmek üzere, Satellite özniteliğinin Location özelliği için NeutralResourcesLanguageAttribute değerini belirtebilirsiniz.

Uyarı

Varsayılan kaynak, ana derlemeyle derlenebilir tek kaynaktır. Özellik NeutralResourcesLanguageAttribute'i kullanarak bir uydu derlemesi belirtmediğiniz sürece, bu nihai geri dönüş (son ana birim). 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ı sırasında varsayılan (geri dönüş) kültürü için bir kaynak bulamazsa, kaynağın bulunamadığını belirtmek için MissingManifestResourceException veya MissingSatelliteAssemblyException özel durum atılır.

Ö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 es-MX ile eşleşen derlemeyi bulmak 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 düzey derleme bulunamazsa, çalışma zamanı, ilgili kaynağı bulana kadar her kültür için es-MX tüm potansiyel ana derleme düzeylerinde arama yapar. 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 AppDomain.AssemblyResolve olayını ele almaz.

Aşağıdaki örnekte gösterildiği gibi uydu derlemeleri için probeyi iyileştirebilirsiniz. < öğesini ekleyip uygulama yapılandırma dosyasında > özniteliğini olarak ayarlayarak.

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

Uydu derlemeleri için iyileştirilmiş prob, isteğe bağlı bir özelliktir. Diğer bir deyişle, uygulamanın yapılandırma dosyasında öğesi varsa ve < özniteliği > olarak ayarlandıysa, çalışma zamanı bölümünde belgelenen adımları izlemez. Bu durumda, bir uydu derlemesi için yoklama işlemi aşağıdaki gibi değiştirilir:

Çalışma zamanı, uydu derlemesini bulmak için üst kod derlemesinin konumunu kullanır. Üst montaj global derleme önbelleğine yüklenirse, çalışma zamanı önbellekte araştırılır ancak uygulamanın dizininde araştırılmaz. Üst derleme bir uygulama dizinine yüklenmişse, çalışma zamanı yalnızca uygulama dizininde yoklama yapar, genel derleme önbelleğinde ise yoklamaz.
Ç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ı AppDomain.AssemblyResolve olayını tetiklemez.

.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.
  
  Uyarı
  
  Büyük/küçük harfe duyarlı dosya sistemlerine sahip işletim sistemlerinde (Linux ve macOS) kültür adı alt dizininde arama, büyük/küçük harfe duyarlıdır. Alt dizin adı, CultureInfo.Name ile büyük/küçük harf duyarlılığı açısından tam olarak eşleşmelidir (örneğin, es veya es-MX).
  
  Uyarı
  
  Programcı AssemblyLoadContext'den özel bir derleme yük bağlamı türetmişse, durum karmaşıklaşır. Yürütülen derleme özel bağlamda yüklendiyse, çalışma zamanı uydu derlemesini özel bağlamda yükler. Ayrıntılar bu belgenin kapsamı dışında. Bkz. AssemblyLoadContext.
- Bir uydu derlemesi bulunamazsa, AssemblyLoadContext, uydu derlemesini bulamadığını belirtmek için AssemblyLoadContext.Resolving olayını tetikler. Olayı işlemeyi seçerseniz, olay işleyiciniz uydu derlemesine bir başvuru yükleyip döndürebilir.
- Bir uydu derlemesi hâlâ bulunamazsa, AssemblyLoadContext, AppDomain'in uydu derlemesini bulamadığını belirtmek üzere bir olay tetiklemesine 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. Derlemede kaynağı bulursa onu kullanır. Kaynağı bulamazsa aramaya devam eder.

Uyarı

Geçerli ResourceManager için uydu derlemesinde bir kaynak bulmak amacıyla, çalışma zamanı CultureInfo.Name tarafından istenen 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ı, ebeveyn kültür derlemelerini birçok olası düzeyde ararken her seferinde 1 ve 2. adımları yinelemektedir.

Ana kültür uygun bir yedek kültür olarak tanımlanır. Herhangi bir kaynak sağlamak istisna oluşturmaktan daha tercih edildiğinden, ebeveynleri alternatif adaylar olarak kabul edin. Bu işlem, kaynakları yeniden kullanmanıza da olanak tanır. Yalnızca alt kültürün istenen kaynağı yerelleştirmeye ihtiyacı yoksa belirli bir kaynağı yalnızca ebeveyn düzeyine eklemeniz gerekir. Örneğin, (bağımsız İngilizce), en (Birleşik Krallık'ta konuşulan İngilizce) ve en-GB (ABD'de konuşulan İngilizce) en-US 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, CultureInfo.Parent özelliği ile tanımlanan yalnızca bir üst öğeye sahiptir, ancak bu üst öğenin kendi üst öğesi olabilir. Bir kültürün Parent özelliği CultureInfo.InvariantCulture döndüğünde, üst kültürlerin aranması durdurulur. Kaynak geriye dönüşü için değişmez kültür, kaynakları olabilecek bir üst kültür veya kültür olarak değerlendirilmez.
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, Satellite özelliği için Location değeri belirleyerek kaynakların nihai geri dönüş konumunun ana derleme yerine bir uydu derlemesi olduğunu belirtebilirsiniz.

Uyarı

Varsayılan kaynak, ana derlemeyle derlenebilir tek kaynaktır. Özellik NeutralResourcesLanguageAttribute'i kullanarak bir uydu derlemesi belirtmediğiniz sürece, bu nihai geri dönüş (son ana birim). 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 bir MissingManifestResourceException veya 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 NeutralResourcesLanguageAttribute(String, UltimateResourceFallbackLocation) oluşturucuyu 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 (NeutralResourcesLanguageAttribute) dil için bir uydu derlemesinde uygulamanın geri dönüş kaynaklarını depolamak için özniteliğini kullanırfr. Örnekte adlı Greetingtek bir dize kaynağını tanımlayan iki metin tabanlı kaynak dosyası vardır. İlki olan resources.fr.txtFransızca bir kaynak içerir.

Greeting=Bon jour!

İkinci kaynak olanru.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, /resource anahtarı kullanmaya gerek kalmadan derlemeniz gerekmiyor.

Ö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.

Ayrıca bakınız

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-06-17