Empaquetar e implementar recursos en aplicaciones .NET

Las aplicaciones se basan en el Administrador de recursos de .NET Framework, representado por la ResourceManager clase , para recuperar recursos localizados. El Administrador de recursos da por supuesto que se usa un modelo de concentrador y radio para empaquetar e implementar los recursos. El concentrador es el ensamblado principal que contiene el código ejecutable no localizable y los recursos de una sola referencia cultural, denominada referencia cultural neutra o predeterminada. La referencia cultural predeterminada es la referencia cultural de reserva para la aplicación; es la referencia cultural cuyos recursos se usan si no se encuentran los recursos localizados. Cada radio se conecta a un ensamblado satélite que contiene los recursos de una única referencia cultural, pero no contiene código.

Este modelo tiene varias ventajas:

• Puede agregar recursos de forma incremental para nuevas culturas después de desplegar una aplicación. Dado que el desarrollo posterior de recursos específicos de la referencia cultural puede requerir una cantidad significativa de tiempo, esto le permite publicar primero la aplicación principal y entregar recursos específicos de la referencia cultural en una fecha posterior.
• Puede actualizar y cambiar los ensamblados satélite de una aplicación sin volver a compilar la aplicación.
• Una aplicación debe cargar solo los ensamblados satélite que contienen los recursos necesarios para una referencia cultural determinada. Esto puede reducir significativamente el uso de recursos del sistema.

Sin embargo, también hay desventajas para este modelo:

• Debe administrar varios conjuntos de recursos.
• El costo inicial de probar una aplicación aumenta, ya que debe probar varias configuraciones. Tenga en cuenta que a largo plazo será más fácil y menos costoso probar una aplicación principal con varios satélites, que probar y mantener varias versiones internacionales paralelas.

Convenciones de nomenclatura de recursos

Al empaquetar los recursos de la aplicación, debe asignarles un nombre utilizando las convenciones de nomenclatura de recursos que el entorno de ejecución de lenguaje común (Common Language Runtime) espera. El tiempo de ejecución identifica un recurso por su nombre de cultura. A cada referencia cultural se le asigna un nombre único, que suele ser una combinación de un nombre de referencia cultural en minúsculas de dos letras asociado a un idioma y, si es necesario, un nombre de subcultura en mayúsculas de dos letras asociado a un país o región. El nombre de la referencia cultural secundaria va después del nombre de la referencia cultural, separado por un guion (-). Algunos ejemplos incluyen ja-JP para japonés como se habla en Japón, en-US para inglés como se habla en los Estados Unidos, de-DE para alemán como se habla en Alemania, o de-AT para alemán como se habla en Austria. Consulte la columna Etiqueta de idioma en la lista de nombres de idioma o región admitidos por Windows. Los nombres de referencia cultural siguen el estándar definido por BCP 47.

Para obtener más información, consulte Creación de archivos de recursos y Creación de ensamblados satélite.

Proceso de reserva de recursos

El modelo de concentrador y radio para empaquetar e implementar recursos usa un proceso de reserva para buscar los recursos apropiados. Si una aplicación solicita un recurso localizado que no está disponible, el Common Language Runtime busca en la jerarquía de culturas un recurso alternativo adecuado que coincida lo más estrechamente posible con la solicitud de la aplicación del usuario y genera una excepción solo como último recurso. En cada nivel de la jerarquía, si se encuentra un recurso adecuado, el tiempo de ejecución lo usa. Si no se encuentra el recurso, la búsqueda continúa en el siguiente nivel.

Para mejorar el rendimiento de la búsqueda, aplique el NeutralResourcesLanguageAttribute atributo al ensamblado principal y páselo el nombre del lenguaje neutro que funcionará con el ensamblado principal.

Proceso de reserva de recursos de .NET Framework

El proceso de reserva de recursos de .NET Framework conlleva los pasos siguientes:

1. El tiempo de ejecución busca primero en la caché global de ensamblados un ensamblado que coincida con la referencia cultural solicitada para la aplicación.

   La caché global de ensamblados puede almacenar ensamblados de recursos compartidos por muchas aplicaciones. Esto le libera de tener que incluir conjuntos específicos de recursos en la estructura de directorios de cada aplicación que cree. Si el tiempo de ejecución encuentra una referencia al ensamblado, busca en el ensamblado el recurso solicitado. Si encuentra la entrada en el ensamblado, usa el recurso solicitado. Si no encuentra la entrada, continúa la búsqueda.

2. Después, el tiempo de ejecución busca en el directorio del ensamblado actualmente en ejecución un subdirectorio que coincida con la referencia cultural solicitada. Si encuentra el subdirectorio, busca en ese subdirectorio un ensamblado satélite válido para la referencia cultural solicitada. A continuación, el tiempo de ejecución busca en el ensamblaje satélite el recurso solicitado. Si encuentra el recurso en el ensamblado, lo usa. Si no encuentra el recurso, continúa la búsqueda.

3. El entorno de ejecución siguiente consulta a Windows Installer para determinar si el ensamblado satélite se va a instalar a petición. Si es así, controla la instalación, carga el ensamblado y busca en él el recurso solicitado. Si encuentra el recurso en el ensamblado, lo usa. Si no encuentra el recurso, continúa la búsqueda.

4. El tiempo de ejecución genera el evento AppDomain.AssemblyResolve para indicar que no ha podido encontrar el ensamblado satélite. Si decide controlar el evento, el controlador de eventos puede devolver una referencia al ensamblado satélite cuyos recursos se usarán para la búsqueda. De lo contrario, el controlador de eventos devuelve null y la búsqueda continúa.

5. Luego, el tiempo de ejecución busca de nuevo en la caché global de ensamblados el ensamblado principal de la referencia cultural solicitada. Si el ensamblado primario existe en la caché global de ensamblados, el tiempo de ejecución busca el ensamblado para el recurso solicitado.

   La cultura principal se define como la cultura de respaldo adecuada. Considere a los padres como candidatos de reserva, porque proporcionar cualquier recurso es preferible a lanzar una excepción. Este proceso también permite reutilizar los recursos. Debe incluir un recurso determinado en el nivel principal solo si la referencia cultural secundaria no necesita localizar el recurso solicitado. Por ejemplo, si proporciona ensamblajes satélite para en (inglés neutro), en-GB (inglés hablado en el Reino Unido) y en-US (inglés como se habla en los Estados Unidos), el satélite en contendrá la terminología común y los satélites en-GB y en-US podrían proporcionar sobrescrituras solo para los términos que difieren.

6. El entorno de ejecución comprueba el directorio del ensamblado que se está ejecutando actualmente para ver si contiene un directorio primario. Si existe un directorio principal, el tiempo de ejecución busca en el directorio un ensamblado satélite válido para la cultura principal. Si encuentra el ensamblado, el tiempo de ejecución busca el ensamblado para el recurso solicitado. Si encuentra el recurso, lo usa. Si no encuentra el recurso, continúa la búsqueda.

7. El entorno de ejecución siguiente consulta a Windows Installer para determinar si el ensamblado satélite primario se va a instalar a petición. Si es así, controla la instalación, carga el ensamblado y busca en él el recurso solicitado. Si encuentra el recurso en el ensamblado, lo usa. Si no encuentra el recurso, continúa la búsqueda.

8. El entorno de ejecución lanza el evento AppDomain.AssemblyResolve para indicar que no puede encontrar un recurso alternativo adecuado. Si decide controlar el evento, el controlador de eventos puede devolver una referencia al ensamblado satélite cuyos recursos se usarán para la búsqueda. De lo contrario, el controlador de eventos devuelve null y la búsqueda continúa.

9. Después, el tiempo de ejecución busca ensamblados principales, como en los tres pasos anteriores, en varios niveles posibles. Cada cultura tiene solo un progenitor, que se define mediante la CultureInfo.Parent propiedad, pero un progenitor podría tener su propio progenitor. La búsqueda de referencias culturales principales se detiene cuando la propiedad Parent de una referencia cultural devuelve CultureInfo.InvariantCulture. Para la reserva de recursos, la referencia cultural invariable no se considera una referencia cultural principal ni una referencia cultural que pueda tener recursos.

10. Si se ha buscado en la referencia cultural especificada inicialmente y en todos los elementos principales y el recurso sigue sin encontrarse, se usa el recurso de la referencia cultural predeterminada (de reserva). Normalmente, los recursos de la cultura predeterminada se incluyen en el ensamblado de aplicación principal. Sin embargo, puede especificar un valor de Satellite para la propiedad Location del atributo NeutralResourcesLanguageAttribute para indicar que la ubicación de reserva definitiva para los recursos es un ensamblado satélite, en lugar del ensamblado principal.

    Nota:

    El recurso predeterminado es el único recurso que se puede compilar con el ensamblado principal. A menos que especifique un ensamblado satélite mediante el atributo NeutralResourcesLanguageAttribute, es la reserva definitiva (elemento principal final). Por lo tanto, se recomienda incluir siempre un conjunto predeterminado de recursos en el ensamblado principal. Esto ayuda a evitar que se produzcan excepciones. Al incluir un archivo de recursos predeterminado, se proporciona una reserva para todos los recursos y se garantiza que al menos un recurso esté siempre presente para el usuario, incluso si no es específico de la referencia cultural.

11. Por último, si el tiempo de ejecución no encuentra un recurso para una referencia cultural predeterminada (de reserva), se produce una excepción MissingManifestResourceException o MissingSatelliteAssemblyException para indicar que no se pudo encontrar el recurso.

Por ejemplo, supongamos que la aplicación solicita un recurso localizado para español (México) (la es-MX cultura). El tiempo de ejecución busca primero en la caché global de ensamblados el ensamblado que coincida con es-MX, pero no lo encuentra. Después, el tiempo de ejecución busca un directorio es-MX en el directorio del ensamblado actualmente en ejecución. Si esto no funciona, el tiempo de ejecución busca de nuevo en la caché global de ensamblados un ensamblado principal que refleje la referencia cultural de reserva adecuada, en este caso, es (español). Si no se encuentra el ensamblado principal, el tiempo de ejecución busca en todos los posibles niveles de ensamblados principales la referencia cultural es-MX hasta que encuentra un recurso correspondiente. Si no se encuentra un recurso, el tiempo de ejecución usa el recurso para la cultura predeterminada.

Optimización del proceso de reemplazo de recursos de .NET Framework

En las siguientes condiciones, puede optimizar el proceso por el que el tiempo de ejecución busca recursos en ensamblados satélite.

• Los ensamblados satélite se implementan en la misma ubicación que el ensamblado de código. Si el ensamblado de código está instalado en la caché global de ensamblados, los ensamblados satélite también se instalan en la caché global de ensamblados. Si el ensamblado de código está instalado en un directorio, los ensamblados satélite se instalan en carpetas específicas de referencias culturales de ese directorio.

• Los ensamblados satélite no están instalados a petición.

• El código de la aplicación no controla el AppDomain.AssemblyResolve evento.

Para optimizar el sondeo para los ensamblados satélite, incluya el <elemento relativeBindForResources> y configure su atributo enabled a true en el archivo de configuración de la aplicación, como se muestra en el ejemplo siguiente.

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

El sondeo optimizado para ensamblados satélite es una función opcional. Es decir, el tiempo de ejecución sigue los pasos documentados en El proceso de reserva de recursos a menos que el <elemento relativeBindForResources> esté presente en el archivo de configuración de la aplicación y su enabled atributo esté establecido trueen . Si este es el caso, el proceso de sondeo para un ensamblado satélite se modifica de la siguiente manera:

• El tiempo de ejecución usa la ubicación del ensamblado de código principal para sondear el ensamblado satélite. Si el ensamblado principal está instalado en la caché global de ensamblados, el tiempo de ejecución sondea la memoria caché, pero no el directorio de la aplicación. Si el ensamblado primario está instalado en un directorio de aplicación, el entorno de ejecución sondea en el directorio de la aplicación, pero no en la caché global de ensamblados.

• El entorno de ejecución no consulta al Windows Installer para la instalación bajo demanda de ensamblados satélite.

• Si se produce un error en el sondeo de un ensamblado de recurso en particular, el tiempo de ejecución no genera el evento AppDomain.AssemblyResolve.

Proceso de reserva de recursos de .NET Core

El proceso de reserva de recursos de .NET Core conlleva los pasos siguientes:

1. El entorno de ejecución intenta cargar un ensamblado satélite para la referencia cultural solicitada.

   • Busca en el directorio del ensamblado actualmente en ejecución un directorio que coincida con la referencia cultural solicitada. Si encuentra el subdirectorio, busca en ese subdirectorio un ensamblado satélite válido para la referencia cultural solicitada y lo carga.

     Nota:

     En sistemas operativos con sistemas de archivos que distinguen mayúsculas de minúsculas (es decir, Linux y macOS), la búsqueda del subdirectorio de nombres de referencias culturales distingue mayúsculas de minúsculas. El nombre del subdirectorio debe coincidir exactamente con el caso de CultureInfo.Name (por ejemplo, es o es-MX).

     Nota:

     Si el programador ha derivado un contexto de carga de ensamblado personalizado de AssemblyLoadContext, la situación es complicada. Si el ensamblaje en ejecución se cargó en el contexto personalizado, el runtime carga el ensamblaje satélite en el contexto personalizado. Los detalles están fuera del ámbito de este documento. Consulte AssemblyLoadContext.

   • Si no se encuentra un ensamblado satélite, AssemblyLoadContext genera el AssemblyLoadContext.Resolving evento para indicar que no puede encontrar el ensamblado satélite. Si decide manejar el evento, su controlador de eventos puede cargar y devolver una referencia al ensamblado satélite.

   • Si aún no se encuentra un ensamblado satélite, AssemblyLoadContext hace que AppDomain desencadene un AppDomain.AssemblyResolve evento para indicar que no puede encontrar el ensamblado satélite. Si decide manejar el evento, su controlador de eventos puede cargar y devolver una referencia al ensamblado satélite.

2. Si se encuentra un ensamblado satélite, el tiempo de ejecución busca en él el recurso solicitado. Si encuentra el recurso en el ensamblado, lo usa. Si no encuentra el recurso, continúa la búsqueda.

   Nota:

   Para buscar un recurso dentro del ensamblado satélite, el entorno de ejecución busca el archivo de recursos solicitado por ResourceManager para el CultureInfo.Name actual. Dentro del archivo de recursos, busca el nombre del recurso solicitado. Si no se encuentra alguno, el recurso se considera no encontrado.

3. Luego, el entorno de ejecución busca los ensamblados de referencias culturales primarias a través de muchos niveles potenciales, y cada vez repite los pasos 1 y 2.

   La referencia cultural principal se define como una referencia cultural de reserva adecuada. Considere a los padres como candidatos de reserva, porque proporcionar cualquier recurso es preferible a lanzar una excepción. Este proceso también permite reutilizar los recursos. Debe incluir un recurso determinado en el nivel principal solo si la referencia cultural secundaria no necesita localizar el recurso solicitado. Por ejemplo, si proporciona ensamblados satélite para en (inglés neutro), en-GB (inglés hablado en el Reino Unido) y en-US (inglés como se habla en los Estados Unidos), el satélite en contiene la terminología común, y los satélites en-GB y en-US proporcionan sustituciones solo para los términos que difieren.

   Cada cultura tiene solo un progenitor, que se define mediante la CultureInfo.Parent propiedad, pero un progenitor podría tener su propio progenitor. La búsqueda de las referencias culturales principales se detiene cuando la propiedad Parent de una referencia cultural devuelve CultureInfo.InvariantCulture. En el caso del reemplazo de recursos, la cultura invariable no se considera una cultura principal o una cultura que puede tener recursos.

4. Si se ha buscado en la referencia cultural especificada inicialmente y en todos los elementos principales y el recurso sigue sin encontrarse, se usa el recurso de la referencia cultural predeterminada (de reserva). Normalmente, los recursos de la cultura predeterminada se incluyen en el ensamblado de aplicación principal. Sin embargo, puede especificar un valor de Satellite para la propiedad Location para indicar que la ubicación de respaldo final de los recursos es un ensamblado satélite en lugar del ensamblado principal.

   Nota:

   El recurso predeterminado es el único recurso que se puede compilar con el ensamblado principal. A menos que especifique un ensamblado satélite mediante el atributo NeutralResourcesLanguageAttribute, es la reserva definitiva (elemento principal final). Por lo tanto, se recomienda incluir siempre un conjunto predeterminado de recursos en el ensamblado principal. Esto ayuda a evitar que se produzcan excepciones. Al incluir un archivo de recursos predeterminado, se proporciona una reserva para todos los recursos y se garantiza que al menos un recurso siempre está presente para el usuario, aunque no sea culturalmente específico.

5. Por último, si el tiempo de ejecución no encuentra un archivo de recursos para una referencia cultural predeterminada (de reserva), se produce una excepción MissingManifestResourceException o MissingSatelliteAssemblyException para indicar que no se pudo encontrar el recurso. Si se encuentra el archivo de recursos, pero el recurso solicitado no está presente, la solicitud devuelve null.

Reserva definitiva en ensamblado satélite

Opcionalmente, puede quitar recursos del ensamblado principal y especificar que el entorno de ejecución debe cargar los recursos de reserva finales de un ensamblado satélite que corresponda a una referencia cultural específica. Para controlar el proceso de reserva, use el NeutralResourcesLanguageAttribute(String, UltimateResourceFallbackLocation) constructor y proporcione un valor para el UltimateResourceFallbackLocation parámetro que especifica si Resource Manager debe extraer los recursos de reserva del ensamblado principal o de un ensamblado satélite.

En el ejemplo siguiente de .NET Framework se usa el atributo NeutralResourcesLanguageAttribute para almacenar los recursos de reserva de una aplicación en un ensamblado satélite para el idioma francés (fr). El ejemplo tiene dos archivos de recursos basados en texto que definen un único recurso de cadena denominado Greeting. La primera, resources.fr.txt, contiene un recurso de idioma francés.

Greeting=Bon jour!

El segundo, resources.ru.txt, contiene un recurso de idioma ruso.

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

Estos dos archivos se compilan en archivos .resources mediante la ejecución del Generador de archivos de recursos (resgen.exe) desde la línea de comandos. Para el recurso de idioma francés, el comando es:

resgen.exe resources.fr.txt

Para el recurso de idioma ruso, el comando es:

resgen.exe resources.ru.txt

Los archivos .resources se insertan en bibliotecas de vínculos dinámicos mediante la ejecución de Assembly Linker (al.exe) desde la línea de comandos para el recurso de idioma francés de la siguiente manera:

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

y para el recurso de idioma ruso de la manera siguiente:

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

El código fuente de la aplicación reside en un archivo denominado Example1.cs o Example1.vb. Incluye el NeutralResourcesLanguageAttribute atributo para indicar que el recurso de aplicación predeterminado está en el subdirectorio fr. Crea una instancia del Administrador de recursos, recupera el valor del Greeting recurso y lo muestra en la consola.

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

A continuación, puede compilar código fuente de C# desde la línea de comandos de la manera siguiente:

csc Example1.cs

El comando del compilador de Visual Basic es muy similar:

vbc Example1.vb

Dado que no hay recursos insertados en el ensamblado principal, no es necesario compilar mediante la opción /resource.

Al ejecutar el ejemplo desde un sistema cuyo idioma no sea ruso, muestra la siguiente salida:

Bon jour!

Alternativa de empaquetado sugerida

Las restricciones de tiempo o presupuesto pueden impedir que cree un conjunto de recursos para cada subcultura que admita la aplicación. En su lugar, puede crear un único ensamblaje satélite para una cultura principal que todas las subculturas relacionadas puedan usar. Por ejemplo, puede proporcionar un único ensamblado satélite inglés (en) recuperado por los usuarios que solicitan recursos en inglés específicos de la región y un único ensamblado satélite alemán (de) para los usuarios que solicitan recursos alemanes específicos de la región. Por ejemplo, las solicitudes de alemán de Alemania (de-DE), Austria (de-AT) y Suiza (de-CH) recurrirán al ensamblado satélite en alemán (de). Los recursos predeterminados son el último recurso y, por lo tanto, deben ser los recursos solicitados por la mayoría de los usuarios de la aplicación, así que elija estos recursos con cuidado. Este enfoque implementa recursos menos específicos culturalmente, pero puede reducir significativamente los costos de localización de la aplicación.

Consulte también

• Recursos en aplicaciones .NET
• Caché global de ensamblados
• Creación de archivos de recursos
• Creación de ensamblados satélite