.NET アプリでのリソースのパッケージ化とデプロイ

2025-06-19

アプリケーションは、ローカライズされたリソースを取得するために、 ResourceManager クラスで表される .NET Framework Resource Manager に依存します。 Resource Manager は、リソースのパッケージ化とデプロイにハブアンドスポークモデルが使用されることを前提としています。ハブは、非ローカライズ可能な実行可能コードと、ニュートラルカルチャまたは既定のカルチャと呼ばれる 1 つのカルチャのリソースを含むメインアセンブリです。既定のカルチャは、アプリケーションのフォールバックカルチャです。ローカライズされたリソースが見つからない場合にリソースが使用されるカルチャです。各スポークは、1 つのカルチャのリソースを含むサテライトアセンブリに接続しますが、コードは含まれません。

このモデルにはいくつかの利点があります。

アプリケーションをデプロイした後は、新しいカルチャのリソースを段階的に追加できます。カルチャ固有のリソースの後続の開発にはかなりの時間が必要な場合があるため、これにより、最初にメインアプリケーションを解放し、後でカルチャ固有のリソースを配信できます。
アプリケーションを再コンパイルすることなく、アプリケーションのサテライトアセンブリを更新および変更できます。
アプリケーションは、特定のカルチャに必要なリソースを含むサテライトアセンブリのみを読み込む必要があります。これにより、システムリソースの使用が大幅に削減される可能性があります。

ただし、このモデルには欠点もあります。

複数のリソースセットを管理する必要があります。
複数の構成をテストする必要があるため、アプリケーションのテストの初期コストが増加します。長期的には、複数の並列国際バージョンをテストして維持するよりも、複数のサテライトで 1 つのコアアプリケーションをテストする方が簡単でコストが低くなることに注意してください。

リソースの名前付け規則

アプリケーションのリソースをパッケージ化するときは、共通言語ランタイムで想定されるリソースの名前付け規則を使用して名前を付ける必要があります。ランタイムは、カルチャ名でリソースを識別します。各カルチャには一意の名前が付けられます。通常は、言語に関連付けられた 2 文字の小文字カルチャ名と、必要に応じて、国または地域に関連付けられた 2 文字の大文字のサブカルチャ名の組み合わせです。サブカルチャ名は、ダッシュ (-) で区切られたカルチャ名に従います。たとえば、日本で話されている日本語の ja-JP、米国で話されている英語の en-US、ドイツで話されているドイツ語の de-DE、オーストリアで話されているドイツ語の de-AT などがあります。 Windows でサポートされている言語/地域名の一覧の [言語タグ] 列を参照してください。カルチャ名は、BCP 47 で定義されている標準に従います。

注

中国語 (簡体字) の zh-Hans など、2 文字のカルチャ名にはいくつかの例外があります。

詳細については、「リソースファイルの作成」および「サテライトアセンブリの作成」を参照してください。

リソースフォールバックプロセス

リソースをパッケージ化およびデプロイするためのハブアンドスポークモデルでは、フォールバックプロセスを使用して適切なリソースを見つけます。使用できないローカライズされたリソースをアプリケーションが要求した場合、共通言語ランタイムはカルチャの階層を検索して、ユーザーのアプリケーションの要求に最も近い適切なフォールバックリソースを検索し、最後の手段としてのみ例外をスローします。階層の各レベルで、適切なリソースが見つかった場合、ランタイムはそれを使用します。リソースが見つからない場合、検索は次のレベルで続行されます。

参照のパフォーマンスを向上させるには、 NeutralResourcesLanguageAttribute 属性をメインアセンブリに適用し、メインアセンブリで動作するニュートラル言語の名前を渡します。

.NET Framework リソースフォールバックプロセス

.NET Framework リソースフォールバックプロセスには、次の手順が含まれます。

ヒント

<relativeBindForResources> 構成要素を使用して、リソースフォールバックプロセスと、ランタイムがリソースアセンブリをプローブするプロセスを最適化できます。詳細については、リソースフォールバックプロセスの最適化を参照してください。

ランタイムは最初に、アプリケーションの要求されたカルチャに一致するアセンブリのグローバルアセンブリキャッシュをチェックします。

グローバルアセンブリキャッシュには、多くのアプリケーションで共有されているリソースアセンブリを格納できます。これにより、作成するすべてのアプリケーションのディレクトリ構造に特定のリソースセットを含める必要ができなくなります。ランタイムは、アセンブリへの参照を検索すると、要求されたリソースをアセンブリで検索します。アセンブリ内のエントリが見つかると、要求されたリソースが使用されます。エントリが見つからない場合は、検索を続行します。
ランタイムは次に、現在実行中のアセンブリのディレクトリで、要求されたカルチャに一致するサブディレクトリをチェックします。サブディレクトリが見つかると、そのサブディレクトリで、要求されたカルチャの有効なサテライトアセンブリが検索されます。ランタイムは、要求されたリソースをサテライトアセンブリで検索します。アセンブリ内のリソースが見つかると、そのリソースが使用されます。リソースが見つからない場合は、検索を続行します。
ランタイムは次に、Windows インストーラーにクエリを実行して、サテライトアセンブリをオンデマンドでインストールするかどうかを判断します。その場合は、インストールを処理し、アセンブリを読み込み、そのアセンブリまたは要求されたリソースを検索します。アセンブリ内のリソースが見つかると、そのリソースが使用されます。リソースが見つからない場合は、検索を続行します。
ランタイムは AppDomain.AssemblyResolve イベントを発生させ、サテライトアセンブリが見つからないことを示します。イベントを処理することを選択した場合、イベントハンドラーは、参照にリソースが使用されるサテライトアセンブリへの参照を返すことができます。それ以外の場合、イベントハンドラーは null を返し、検索を続行します。
ランタイムは次に、要求されたカルチャの親アセンブリについて、グローバルアセンブリキャッシュをもう一度検索します。親アセンブリがグローバルアセンブリキャッシュに存在する場合、ランタイムは要求されたリソースをアセンブリで検索します。

親カルチャは、適切なフォールバックカルチャとして定義されます。例外をスローするよりは何らかのリソースを提供する方がよいので、親をフォールバック候補として考えます。このプロセスでは、リソースを再利用することもできます。子カルチャで要求されたリソースをローカライズする必要がない場合にのみ、親レベルで特定のリソースを含める必要があります。たとえば、 en (ニュートラル英語)、 en-GB (英国で話されている英語)、 en-US (米国で話されている英語) のサテライトアセンブリを提供する場合、 en サテライトには一般的な用語が含まれ、 en-GB および en-US サテライトは、異なる用語についてのみオーバーライドを提供できます。
ランタイムは次に、現在実行中のアセンブリのディレクトリをチェックして、親ディレクトリが含まれているかどうかを確認します。親ディレクトリが存在する場合、ランタイムは、親カルチャの有効なサテライトアセンブリのディレクトリを検索します。アセンブリが見つかると、ランタイムは要求されたリソースをアセンブリで検索します。リソースが見つかると、リソースが使用されます。リソースが見つからない場合は、検索を続行します。
ランタイムは次に、Windows インストーラーに対してクエリを実行して、親サテライトアセンブリをオンデマンドでインストールするかどうかを判断します。その場合は、インストールを処理し、アセンブリを読み込み、そのアセンブリまたは要求されたリソースを検索します。アセンブリ内のリソースが見つかると、そのリソースが使用されます。リソースが見つからない場合は、検索を続行します。
ランタイムは AppDomain.AssemblyResolve イベントを発生させ、適切なフォールバックリソースが見つからないことを示します。イベントを処理することを選択した場合、イベントハンドラーは、参照にリソースが使用されるサテライトアセンブリへの参照を返すことができます。それ以外の場合、イベントハンドラーは null を返し、検索を続行します。
ランタイムは次に、前の 3 つの手順と同様に、多くの潜在的なレベルを通じて親アセンブリを検索します。各カルチャの親は 1 つだけで、CultureInfo.Parent プロパティによって定義されていますが、親がそれ自身の親を持つ可能性があります。カルチャの Parent プロパティが CultureInfo.InvariantCultureを返すと、親カルチャの検索は停止します。リソースフォールバックの場合、インバリアントカルチャは親カルチャまたはリソースを持つ可能性のあるカルチャとは見なされません。
最初に指定されたカルチャーとそのすべての親カルチャーを検索してもリソースが見つからない場合、既定（フォールバック）カルチャーのリソースが使用されます。通常、既定のカルチャのリソースはメインアプリケーションアセンブリに含まれます。ただし、Satellite 属性のLocation プロパティにNeutralResourcesLanguageAttributeの値を指定して、リソースの最終的なフォールバック位置がメインアセンブリではなくサテライトアセンブリであることを示すことができます。

注

既定のリソースは、メインアセンブリでコンパイルできる唯一のリソースです。 NeutralResourcesLanguageAttribute属性を使用してサテライトアセンブリを指定しない限り、最終的なフォールバック (最終親) になります。そのため、メインアセンブリには常に既定のリソースセットを含めるのが推奨されます。これは、例外がスローされるのを防ぐのに役立ちます。既定のリソースを含めることで、ファイルはすべてのリソースにフォールバックを提供し、カルチャに固有でない場合でも、少なくとも 1 つのリソースが常にユーザーに存在することを確認します。
最後に、ランタイムが既定の (フォールバック) カルチャのリソースを見つけられない場合は、リソースが見つからなかったことを示す MissingManifestResourceException または MissingSatelliteAssemblyException 例外がスローされます。

たとえば、アプリケーションがスペイン語 (メキシコ) ( es-MX カルチャ) 用にローカライズされたリソースを要求するとします。ランタイムは、最初にグローバルアセンブリキャッシュを検索して、 es-MXに一致するが見つからないアセンブリを検索します。ランタイムは、現在実行中のアセンブリのディレクトリで、 es-MX ディレクトリを検索します。これに失敗すると、ランタイムはグローバルアセンブリキャッシュを再度検索し、適切なフォールバックカルチャ (この場合は es (スペイン語) を反映する親アセンブリを検索します。親アセンブリが見つからない場合、ランタイムは、対応するリソースが見つかるまで、親アセンブリのすべての潜在的なレベルの es-MX カルチャを検索します。リソースが見つからない場合、ランタイムは既定のカルチャにリソースを使用します。

.NET Framework リソースフォールバックプロセスを最適化する

次の条件では、ランタイムがサテライトアセンブリ内のリソースを検索するプロセスを最適化できます。

サテライトアセンブリは、コードアセンブリと同じ場所に配置されます。コードアセンブリがグローバルアセンブリキャッシュにインストールされている場合、サテライトアセンブリもグローバルアセンブリキャッシュにインストールされます。コードアセンブリがディレクトリにインストールされている場合、サテライトアセンブリはそのディレクトリのカルチャ固有のフォルダーにインストールされます。
サテライトアセンブリは必要に応じてインストールされません。
アプリケーションコードは、 AppDomain.AssemblyResolve イベントを処理しません。

サテライトアセンブリのプローブを最適化するには、次の例に示すように、<relativeBindForResources> 要素を含め、そのenabled属性をアプリケーション構成ファイルでtrueに設定します。

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

サテライトアセンブリ用に最適化されたプローブはオプトイン機能です。つまり、> 要素がアプリケーションの構成ファイルに存在し、その属性がenabledに設定されていない限り、ランタイムはtrueに記載されている手順に従います。この場合、サテライトアセンブリのプローブプロセスは次のように変更されます。

ランタイムは、親コードアセンブリの場所を使用してサテライトアセンブリをプローブします。親アセンブリがグローバルアセンブリキャッシュにインストールされている場合、ランタイムはキャッシュ内をプローブしますが、アプリケーションのディレクトリにはプローブしません。親アセンブリがアプリケーションディレクトリにインストールされている場合、ランタイムはアプリケーションディレクトリにプローブしますが、グローバルアセンブリキャッシュにはプローブしません。
ランタイムは、サテライトアセンブリのオンデマンドインストールについて Windows インストーラーに対してクエリを実行しません。
特定のリソースアセンブリのプローブが失敗した場合、ランタイムは AppDomain.AssemblyResolve イベントを発生させません。

.NET Core リソースフォールバックプロセス

.NET Core リソースフォールバックプロセスには、次の手順が含まれます。

ランタイムは、指定されたカルチャのサテライトアセンブリを読み込もうとします。
- 現在実行中のアセンブリのディレクトリで、要求されたカルチャに一致するサブディレクトリを確認します。サブディレクトリが見つかると、そのサブディレクトリで要求されたカルチャの有効なサテライトアセンブリが検索され、読み込まれます。
  
  注
  
  大文字と小文字を区別するファイルシステムを持つオペレーティングシステム（LinuxやmacOS）では、文化名サブディレクトリの検索は大文字と小文字を区別します。サブディレクトリ名は、 CultureInfo.Name の大文字と小文字が完全に一致している必要があります (たとえば、 es や es-MX)。
  
  注
  
  プログラマが AssemblyLoadContextからカスタムアセンブリ読み込みコンテキストを派生させた場合、状況は複雑になります。実行中のアセンブリがカスタムコンテキストに読み込まれた場合、ランタイムはサテライトアセンブリをカスタムコンテキストに読み込みます。詳細については、このドキュメントの範囲外です。 AssemblyLoadContextを参照してください。
- サテライトアセンブリが見つからない場合、 AssemblyLoadContext は AssemblyLoadContext.Resolving イベントを発生させ、サテライトアセンブリが見つからないことを示します。イベントを処理する場合、イベントハンドラーはサテライトアセンブリへの参照を読み込んで返すことができます。
- サテライトアセンブリがまだ見つからない場合、AssemblyLoadContext によって AppDomain によって AppDomain.AssemblyResolve イベントがトリガーされ、サテライトアセンブリが見つからないことを示します。イベントを処理する場合、イベントハンドラーはサテライトアセンブリへの参照を読み込んで返すことができます。
サテライトアセンブリが見つかった場合、ランタイムは要求されたリソースを検索します。アセンブリ内のリソースが見つかると、そのリソースが使用されます。リソースが見つからない場合は、検索を続行します。

注

サテライトアセンブリ内のリソースを見つけるために、ランタイムでは現在の ResourceManager の CultureInfo.Name によって要求されたリソースファイルが検索されます。リソースファイル内で、要求されたリソース名を検索します。どちらかが見つからない場合、リソースは見つからないものとして扱われます。
ランタイムは次に、ステップ 1 と 2 を繰り返すたびに、多くの潜在的なレベルを通じて親カルチャアセンブリを検索します。

親カルチャは、適切なフォールバックカルチャとして定義されます。例外をスローするよりは何らかのリソースを提供する方がよいので、親をフォールバック候補として考えます。このプロセスでは、リソースを再利用することもできます。子カルチャで要求されたリソースをローカライズする必要がない場合にのみ、親レベルで特定のリソースを含める必要があります。たとえば、 en (ニュートラル英語)、 en-GB (英国で話されている英語)、 en-US (米国で話されている英語) のサテライトアセンブリを提供する場合、 en サテライトには一般的な用語が含まれ、 en-GB および en-US サテライトは、異なる用語についてのみオーバーライドを提供します。

各カルチャの親は 1 つだけで、CultureInfo.Parent プロパティによって定義されていますが、親がそれ自身の親を持つ可能性があります。カルチャの Parent プロパティが CultureInfo.InvariantCultureを返すと、親カルチャの検索は停止します。リソースフォールバックの場合、インバリアントカルチャは、親カルチャまたはリソースを持つ可能性のあるカルチャとは見なされません。
最初に指定されたカルチャーとそのすべての親カルチャーを検索してもリソースが見つからない場合、既定（フォールバック）カルチャーのリソースが使用されます。通常、既定のカルチャのリソースはメインアプリケーションアセンブリに含まれます。ただし、Satellite プロパティに Location の値を指定して、リソースの最終的なフォールバック場所がメインアセンブリではなくサテライトアセンブリであることを示すことができます。

注

既定のリソースは、メインアセンブリでコンパイルできる唯一のリソースです。 NeutralResourcesLanguageAttribute属性を使用してサテライトアセンブリを指定しない限り、最終的なフォールバック (最終親) になります。そのため、メインアセンブリには常に既定のリソースセットを含めるのが推奨されます。これは、例外がスローされるのを防ぐのに役立ちます。既定のリソースファイルを含めることで、すべてのリソースにフォールバックを提供し、カルチャに固有でない場合でも、少なくとも 1 つのリソースが常にユーザーに存在するようにします。
最後に、ランタイムで既定の (フォールバック) カルチャのリソースファイルが見つからない場合は、リソースが見つからなかったことを示す MissingManifestResourceException または MissingSatelliteAssemblyException 例外がスローされます。リソースファイルが見つかったが、要求されたリソースが存在しない場合、要求は null返します。

サテライトアセンブリへの最終的な復帰

必要に応じて、メインアセンブリからリソースを削除し、ランタイムが特定のカルチャに対応するサテライトアセンブリから最終的なフォールバックリソースを読み込む必要があることを指定できます。フォールバックプロセスを制御するには、 NeutralResourcesLanguageAttribute(String, UltimateResourceFallbackLocation) コンストラクターを使用し、Resource Manager がメインアセンブリまたはサテライトアセンブリからフォールバックリソースを抽出するかどうかを指定する UltimateResourceFallbackLocation パラメーターの値を指定します。

次の .NET Framework の例では、 NeutralResourcesLanguageAttribute 属性を使用して、フランス語 (fr) 言語のサテライトアセンブリにアプリケーションのフォールバックリソースを格納します。この例には、 Greetingという名前の単一の文字列リソースを定義する 2 つのテキストベースのリソースファイルがあります。 1 つ目の resources.fr.txtには、フランス語のリソースが含まれています。

Greeting=Bon jour!

2 つ目のリソース (ru.txt) には、ロシア語のリソースが含まれています。

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

これら 2 つのファイルは、コマンドラインからリソースファイルジェネレーター (resgen.exe) を実行して.resources ファイルにコンパイルされます。フランス語リソースの場合、コマンドは次のようになります。

resgen.exe resources.fr.txt

ロシア語リソースの場合、コマンドは次のようになります。

resgen.exe resources.ru.txt

.resources ファイルは、次のようにフランス語リソースのコマンドラインからアセンブリリンカー (al.exe) を実行してダイナミックリンクライブラリに埋め込まれます。

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

ロシア語リソースの場合は、次のようになります。

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

アプリケーションのソースコードは、Example1.csまたはExample1.vbという名前のファイルに存在します。既定のアプリケーションリソースが fr サブディレクトリにあることを示す NeutralResourcesLanguageAttribute 属性が含まれています。 Resource Manager がインスタンス化され、 Greeting リソースの値が取得され、コンソールに表示されます。

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

その後、次のようにコマンドラインから C# ソースコードをコンパイルできます。

csc Example1.cs

Visual Basic コンパイラのコマンドは非常によく似ています。

vbc Example1.vb

メインアセンブリにリソースが埋め込まれていないため、 /resource スイッチを使用してコンパイルする必要はありません。

言語がロシア語以外のシステムから例を実行すると、次の出力が表示されます。

Bon jour!

提案されたパッケージの代替案

時間または予算の制約により、アプリケーションがサポートするすべてのサブカルチャに対して一連のリソースを作成できなくなる可能性があります。代わりに、関連するすべてのサブカルチャで使用できる親カルチャ用の単一のサテライトアセンブリを作成できます。たとえば、リージョン固有の英語リソースを要求するユーザーによって取得される 1 つの英語サテライトアセンブリ (en) と、リージョン固有のドイツ語リソースを要求するユーザー用の単一のドイツサテライトアセンブリ (de) を提供できます。たとえば、ドイツ (de-DE)、オーストリア (de-AT)、スイス (de-CH) で話されているドイツ語の要求は、ドイツのサテライトアセンブリ (de) にフォールバックします。既定のリソースは最終的なフォールバックであるため、アプリケーションの大部分のユーザーから要求されるリソースである必要があるため、これらのリソースは慎重に選択してください。この方法では、カルチャに固有ではないリソースをデプロイしますが、アプリケーションのローカライズコストを大幅に削減できます。

次の方法で共有

.NET アプリでのリソースのパッケージ化とデプロイ

リソースの名前付け規則

リソース フォールバック プロセス

.NET Framework リソースフォールバック プロセス

.NET Framework リソース フォールバック プロセスを最適化する

.NET Core リソースフォールバック プロセス

サテライト アセンブリへの最終的な復帰