Diccionarios de recursos combinadosMerged Resource Dictionaries

Los recursos Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) admiten una característica de diccionario de recursos combinados.Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) resources support a merged resource dictionary feature. Esta característica proporciona una manera de definir la parte de recursos de una aplicación WPFWPF fuera de la aplicación XAMLXAML compilada.This feature provides a way to define the resources portion of a WPFWPF application outside of the compiled XAMLXAML application. Los recursos se pueden compartir entre aplicaciones y también se aíslan de forma más conveniente para la localización.Resources can then be shared across applications and are also more conveniently isolated for localization.

Introducir un diccionario de recursos combinadosIntroducing a Merged Resource Dictionary

En la marcación, se usa la sintaxis siguiente para introducir un diccionario de recursos combinados en una página:In markup, you use the following syntax to introduce a merged resource dictionary into a page:

<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 una Directiva x:Key, que normalmente es necesaria para todos los elementos de una colección de recursos.Note that the ResourceDictionary element does not have an x:Key Directive, which is generally required for all items in a resource collection. Pero otra referencia ResourceDictionary dentro de la colección MergedDictionaries es un caso especial, reservado para este escenario de Diccionario de recursos combinados.But another ResourceDictionary reference within the MergedDictionaries collection is a special case, reserved for this merged resource dictionary scenario. El ResourceDictionary que introduce un diccionario de recursos combinados no puede tener una Directiva x:Key.The ResourceDictionary that introduces a merged resource dictionary cannot have an x:Key Directive. Normalmente, cada ResourceDictionary dentro de la colección MergedDictionaries especifica un atributo Source.Typically, each ResourceDictionary within the MergedDictionaries collection specifies a Source attribute. El valor de Source debe ser un identificador uniforme de recursos (URI) que se resuelva en la ubicación del archivo de recursos que se va a combinar.The value of Source should be a uniform resource identifier (URI) that resolves to the location of the resources file to be merged. El destino de ese URI debe ser otro archivo de XAMLXAML, con ResourceDictionary como su elemento raíz.The destination of that URI must be another XAMLXAML file, with ResourceDictionary as its root element.

Nota

Es válido definir recursos dentro de una ResourceDictionary que se especifica como un diccionario combinado, como alternativa a especificar Source, o además de los recursos incluidos en el origen especificado.It is legal to define resources within a ResourceDictionary that is specified as a merged dictionary, either as an alternative to specifying Source, or in addition to whatever resources are included from the specified source. Sin embargo, esto no es un escenario común: el escenario principal para los diccionarios combinados es combinar recursos desde ubicaciones de archivo externas.However, this is not a common scenario; the main scenario for merged dictionaries is to merge resources from external file locations. Si desea especificar recursos dentro del marcado de una página, normalmente debe definirlos en el ResourceDictionary principal y no en los diccionarios combinados.If you want to specify resources within the markup for a page, you should typically define these in the main ResourceDictionary and not in the merged dictionaries.

Comportamiento del diccionario combinadoMerged Dictionary Behavior

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 en el que se combinan.Resources in a merged dictionary occupy a location in the resource lookup scope that is just after the scope of the main resource dictionary they are merged into. 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.Although a resource key must be unique within any individual dictionary, a key can exist multiple times in a set of merged dictionaries. En este caso, el recurso que se devuelve procederá del último diccionario encontrado secuencialmente en la colección de MergedDictionaries.In this case, the resource that is returned will come from the last dictionary found sequentially in the MergedDictionaries collection. Si la colección de MergedDictionaries se definió en XAMLXAML, el orden de los diccionarios combinados en la colección es el orden de los elementos que se proporcionan en el marcado.If the MergedDictionaries collection was defined in XAMLXAML, then the order of the merged dictionaries in the collection is the order of the elements as provided in the markup. Si se define una clave en el diccionario principal y también en un diccionario combinado, el recurso que se devuelve procederá del diccionario principal.If a key is defined in the primary dictionary and also in a dictionary that was merged, then the resource that is returned will come from the primary dictionary. Estas reglas de ámbito se aplican igualmente para referencias de recursos estáticos y dinámicos.These scoping rules apply equally for both static resource references and dynamic resource references.

Diccionarios combinados y códigoMerged Dictionaries and Code

Los diccionarios combinados se pueden agregar a un diccionario Resources mediante código.Merged dictionaries can be added to a Resources dictionary through code. El valor predeterminado, inicialmente vacío ResourceDictionary que existe para cualquier propiedad de Resources también tiene una propiedad de colección predeterminada, inicialmente MergedDictionaries vacía.The default, initially empty ResourceDictionary that exists for any Resources property also has a default, initially empty MergedDictionaries collection property. Para agregar un diccionario combinado a través de código, se obtiene una referencia al ResourceDictionaryprincipal deseado, se obtiene su valor de propiedad MergedDictionaries y se llama a Add en el Collection genérico que se incluye en MergedDictionaries.To add a merged dictionary through code, you obtain a reference to the desired primary ResourceDictionary, get its MergedDictionaries property value, and call Add on the generic Collection that is contained in MergedDictionaries. El objeto que agregue debe ser un nuevo ResourceDictionary.The object you add must be a new ResourceDictionary. En el código, no se establece la propiedad Source.In code, you do not set the Source property. En su lugar, debe obtener un objeto ResourceDictionary creando uno o cargando uno.Instead, you must obtain a ResourceDictionary object by either creating one or loading one. Una manera de cargar una ResourceDictionary existente para llamar a XamlReader.Load en una secuencia de archivo XAMLXAML existente que tiene una raíz ResourceDictionary y, a continuación, convertir el valor devuelto de XamlReader.Load en ResourceDictionary.One way to load an existing ResourceDictionary to call XamlReader.Load on an existing XAMLXAML file stream that has a ResourceDictionary root, then casting the XamlReader.Load return value to ResourceDictionary.

URI de diccionarios de recursos combinadosMerged Resource Dictionary URIs

Hay varias técnicas para incluir un diccionario de recursos combinados, que se indica mediante el formato de identificador uniforme de recursos (URI) que se va a usar.There are several techniques for how to include a merged resource dictionary, which are indicated by the uniform resource identifier (URI) format that you will 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.Broadly speaking, these techniques can be divided into two categories: resources that are compiled as part of the project, and resources that are not compiled as part of the project.

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.For resources that are compiled as part of the project, you can use a relative path that refers to the resource location. La ruta de acceso relativa se evalúa durante la compilación.The relative path is evaluated during compilation. El recurso debe definirse como parte del proyecto como una acción de compilación de recursos.Your resource must be defined as part of the project as a Resource build action. 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.If you include a resource .xaml file in the project as Resource, you do not need to copy the resource file to the output directory, the resource is already included within the compiled application. También puede usar la acción de compilación de contenido, pero debe copiar los archivos en el directorio de salida e implementar los archivos de recursos en la misma relación de ruta de acceso que el ejecutable.You can also use Content build action, but you must then copy the files to the output directory and also deploy the resource files in the same path relationship to the executable.

Nota

No use la acción de compilación de recurso incrustado.Do not use the Embedded Resource build action. La propia acción de compilación es compatible con las aplicaciones WPFWPF, pero la resolución de Source no incorpora ResourceManagery, por tanto, no puede separar el recurso individual de la secuencia.The build action itself is supported for WPFWPF applications, but the resolution of Source does not incorporate ResourceManager, and thus cannot separate the individual resource out of the stream. Puede seguir usando el recurso incrustado para otros propósitos, siempre y cuando use también ResourceManager para tener acceso a los recursos.You could still use Embedded Resource for other purposes so long as you also used ResourceManager to access the resources.

Una técnica relacionada es usar un Pack URI en un archivo XAMLXAML y hacer referencia a él como origen.A related technique is to use a Pack URI to a XAMLXAML file, and refer to it as Source. Pack URI habilita las referencias a componentes de ensamblados de referencia y otras técnicas.Pack URI enables references to components of referenced assemblies and other techniques. Para obtener más información sobre Pack URI, consulte Archivos de recursos, contenido y datos de aplicaciones de WPF.For more information on Pack URIs, see WPF Application Resource, Content, and Data Files.

Para los recursos que no se compilan como parte del proyecto, el URI se evalúa en tiempo de ejecución.For resources that are not compiled as part of the project, the URI is evaluated at run time. Puede usar un transporte URI común, como file: o http:, para hacer referencia al archivo de recursos.You can use a common URI transport such as file: or http: to refer to the resource file. 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.The disadvantage of using the noncompiled resource approach is that file: access requires additional deployment steps, and http: access implies the Internet security zone.

Reutilizar diccionarios combinadosReusing Merged Dictionaries

Puede reutilizar o compartir diccionarios de recursos combinados entre aplicaciones, ya que se puede hacer referencia al Diccionario de recursos para combinar a través de un identificador uniforme de recursos (URI) válido.You can reuse or share merged resource dictionaries between applications, because the resource dictionary to merge can be referenced through any valid uniform resource identifier (URI). Cómo hacerlo exactamente dependerá de la estrategia de implementación de aplicaciones y de qué modelo de aplicación siga.Exactly how you do this will depend on your application deployment strategy and which application model you follow. La estrategia 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.The aforementioned Pack URI strategy provides a way to commonly source a merged resource across multiple projects during development by sharing an assembly reference. En este escenario, el cliente distribuye los recursos y al menos una de las aplicaciones debe implementar el ensamblado de referencia.In this scenario the resources are still distributed by the client, and at least one of the applications must deploy the referenced assembly. También es posible hacer referencia a recursos combinados mediante un URI distribuido que usa el protocolo http.It is also possible to reference merged resources through a distributed URI that uses the http protocol.

Escribir diccionarios combinados como archivos de aplicación locales o en almacenamiento compartido local es otro escenario posible de diccionario combinado o implementación de aplicación.Writing merged dictionaries as local application files or to local shared storage is another possible merged dictionary / application deployment scenario.

LocalizaciónLocalization

Si los recursos que deben localizarse están aislados en diccionarios que se combinan en diccionarios principales y se mantienen como XAMLXAML separados, estos archivos se pueden localizar por separado.If resources that need to be localized are isolated to dictionaries that are merged into primary dictionaries, and kept as loose XAMLXAML, these files can be localized separately. Esta técnica es una alternativa ligera a la localización de los ensamblados de recursos satélite.This technique is a lightweight alternative to localizing the satellite resource assemblies. Para obtener más información, consulte Información general sobre la globalización y la localización de WPF.For details, see WPF Globalization and Localization Overview.

Vea tambiénSee also