Diccionarios de recursos combinados (WPF .NET)

Los recursos de Windows Presentation Foundation (WPF) admiten una característica de diccionario de recursos combinado. Esta característica proporciona una manera de definir la parte de recursos de una aplicación WPF fuera de la aplicación XAML compilada. Los recursos se pueden compartir entre aplicaciones y también se aíslan de forma más conveniente para la localización.

Importante

La documentación de la Guía de escritorio para .NET 6 y .NET 5 (incluido .NET Core 3.1) está en elaboración.

Creación de un diccionario combinado

En la marcación, se usa la sintaxis siguiente para introducir un diccionario de recursos combinados en una página:

<Page.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
      <ResourceDictionary Source="myresourcedictionary.xaml"/>
      <ResourceDictionary Source="myresourcedictionary2.xaml"/>
    </ResourceDictionary.MergedDictionaries>
  </ResourceDictionary>
</Page.Resources>

Tenga en cuenta que el elemento ResourceDictionary no tiene ninguna directiva x:Key,, que generalmente se necesita para todos los elementos de una colección de recursos. Pero otra referencia ResourceDictionary dentro de la colección MergedDictionaries es un caso especial, reservado para este escenario de diccionario de recursos combinados. Además, el ResourceDictionary que introduce un diccionario de recursos combinado no puede tener una directiva x:Key.

Normalmente, cada ResourceDictionary de la colección MergedDictionaries especifica un atributo Source. El valor de Source debe ser un identificador uniforme recursos (URI) que se resuelva en la ubicación del archivo de recursos con el que se va a combinar. El destino de ese URI debe ser otro archivo XAML que tenga ResourceDictionary como elemento raíz.

Nota:

Es legal definir recursos dentro de un ResourceDictionary que se especifica como un diccionario combinado, ya sea como alternativa a especificar Source, o agregado a los recursos que se incluyen desde el origen especificado. Sin embargo, este no es un escenario común. El escenario principal para los diccionarios combinados es combinar recursos desde ubicaciones de archivo externas. Si desea especificar recursos dentro del marcado de una página, debe definirlos en el ResourceDictionary principal y no en los diccionarios combinados.

Comportamiento del diccionario combinado

Los recursos de un diccionario combinado ocupan una ubicación en el ámbito de búsqueda de recursos que está justo después del ámbito del diccionario de recursos principal con el que se fusionan. Aunque una clave de recurso debe ser única dentro de un diccionario individual, una clave puede existir varias veces en un conjunto de diccionarios combinados. En este caso, el recurso devuelto procederá del último diccionario encontrado secuencialmente en la colección MergedDictionaries. Si se la colección MergedDictionaries se ha definido en XAML, el orden de los diccionarios combinados de la colección es el orden de los elementos tal y como se proporcionan en la marcación. Si se define una clave en el diccionario principal y también el diccionario con el que se combina, el recurso que se devuelve procederá del diccionario principal. Estas reglas de ámbito se aplican igualmente para referencias de recursos estáticos y dinámicos.

Diccionarios combinados y código

Los diccionarios combinados se pueden agregar a un diccionario Resources mediante código. El valor predeterminado ResourceDictionary inicialmente vacío que existe para cualquier propiedad Resources, también tiene una propiedad de colección predeterminada MergedDictionaries inicialmente vacía. Para agregar un diccionario combinado mediante código, obtenga una referencia al ResourceDictionary principal deseado, obtenga su valor de propiedad MergedDictionaries y llame a Add en el genérico Collection contenido en MergedDictionaries. El objeto que agregue debe ser un nuevo ResourceDictionary.

En el código no se establece la propiedad Source. En su lugar, debe obtener un objeto ResourceDictionary, sea creando uno, o cargando uno. Una manera de cargar un ResourceDictionary existente es llamar a XamlReader.Load en una secuencia de archivos XAML existente que tiene una raíz ResourceDictionary y, a continuación, convertir el valor devuelto en ResourceDictionary.

URI de diccionarios combinados

Existen varias técnicas para incluir un diccionario de recursos combinados, que se indican mediante el formato del identificador uniforme de recursos (URI) que se use. En términos generales estas técnicas pueden dividirse en dos categorías: recursos que se compilan como parte del proyecto y recursos que no se compilan como parte del proyecto.

Para los recursos que se compilan como parte del proyecto, puede usar una ruta de acceso relativa que haga referencia a la ubicación del recurso. La ruta de acceso relativa se evalúa durante la compilación. El recurso debe definirse como parte del proyecto como una acción de compilación de Recurso. Si incluye un archivo .xaml de recursos en el proyecto como Recurso, no tendrá que copiar el archivo de recursos en el directorio de salida, dado que el recurso ya está incluido en la aplicación compilada. También puede usar la acción de compilación de Contenido, pero entonces debe copiar los archivos en el directorio de salida y también implementar los archivos de recursos en la misma relación de ruta de acceso que el ejecutable.

Nota:

No use la acción de compilación de Recurso incrustado. La propia acción de compilación es compatible con las aplicaciones WPF, pero la resolución de Source no incorpora ResourceManager y, por tanto, no puede separar el recurso individual de la secuencia. Todavía podría usar los Recursos incrustados para otros propósitos siempre que usara ResourceManager para obtener acceso a los recursos.

Una técnica relacionada es usar un Pack URI en un archivo XAML y hacer referencia a él como Origen. Un Pack URI habilita las referencias a componentes de ensamblados de referencia y otras técnicas. Para obtener más información sobre Pack URI, consulte Archivos de recursos, contenido y datos de aplicaciones de WPF.

Para los recursos que no se compilan como parte del proyecto, el URI se evalúa en tiempo de ejecución. Puede usar un transporte URI común, como file: o http:, para hacer referencia al archivo de recursos. La desventaja de usar el enfoque de recursos no compilados es que el acceso file: requiere pasos de implementación adicionales y el acceso http: implica la zona de seguridad de Internet.

Reutilizar diccionarios combinados

Puede reutilizar o compartir los diccionarios de recursos combinados entre aplicaciones, ya que se puede hacer referencia al diccionario de recursos que va a combinar mediante cualquier identificador uniforme de recursos (URI) válido. Cómo hacerlo exactamente dependerá de la estrategia de implementación de la aplicación y de qué modelo de aplicación siga. La estrategia de Pack URI mencionada anteriormente proporciona una forma de obtener normalmente un recurso combinado entre varios proyectos durante el desarrollo mediante el uso compartido de una referencia de ensamblado. En este escenario, el cliente distribuye los recursos y al menos una de las aplicaciones debe implementar el ensamblado de referencia. También es posible hacer referencia a recursos combinados mediante un URI distribuido que usa el protocolo http:.

Escribir diccionarios combinados como archivos de aplicación locales o en almacenamiento compartido local es otro escenario posible de implementación de diccionarios combinados y aplicaciones.

Localización

Si los recursos que deben localizarse están aislados en diccionarios que se combinan en diccionarios principales y se mantienen como XAML dinámico, estos archivos se pueden localizar por separado. Esta técnica es una alternativa ligera a la localización de los ensamblados de recursos satélite. Para obtener más información, consulte Información general sobre la globalización y la localización de WPF.

Vea también