Visor de la biblioteca de imágenes

La herramienta Visor de la biblioteca de imágenes de Visual Studio puede cargar y buscar manifiestos de imagen, lo que permite al usuario manipularlos de la misma manera que Lo haría Visual Studio. El usuario puede modificar el fondo, los tamaños, ppp, contraste alto y otras configuraciones. La herramienta también muestra información de carga para cada manifiesto de imagen y muestra información de origen para cada imagen en el manifiesto de imagen. Esta herramienta es útil para:

1. Diagnóstico de errores

2. Asegurarse de que los atributos se establecen correctamente en manifiestos de imagen personalizados

3. Búsqueda de imágenes en el catálogo de imágenes de Visual Studio para que una extensión de Visual Studio pueda usar imágenes que se ajusten al estilo de Visual Studio

Moniker de imagen

Un moniker de imagen (o moniker para abreviar) es un par GUID:ID que identifica de forma única un recurso de imagen o un recurso de lista de imágenes en la biblioteca de imágenes.

Archivos de manifiesto de imagen

Los archivos de manifiesto de imagen (.imagemanifest) son archivos XML que definen un conjunto de recursos de imagen, los monikers que representan esos recursos y la imagen o imágenes reales que representan cada recurso. Los manifiestos de imagen pueden definir imágenes independientes o listas de imágenes para la compatibilidad con la interfaz de usuario heredada. Además, hay atributos que se pueden establecer en el recurso o en las imágenes individuales detrás de cada recurso para cambiar cuándo y cómo se muestran esos recursos.

Esquema de manifiesto de imagen

Un manifiesto de imagen completo tiene este aspecto:

<ImageManifest>
      <!-- zero or one Symbols elements -->
      <Symbols>
        <!-- zero or more Guid, ID, or String elements -->
      </Symbols>
      <!-- zero or one Images elements -->
      <Images>
        <!-- zero or more Image elements -->
      </Images>
      <!-- zero or one ImageLists elements -->
      <ImageLists>
        <!-- zero or more ImageList elements -->
      </ImageLists>
</ImageManifest>

Symbols

Como ayuda de legibilidad y mantenimiento, el manifiesto de imagen puede usar símbolos para los valores de atributo. Los símbolos se definen de la siguiente manera:

<Symbols>
      <Import Manifest="manifest" />
      <Guid Name="ShellCommandGuid" Value="8ee4f65d-bab4-4cde-b8e7-ac412abbda8a" />
      <ID Name="cmdidSaveAll" Value="1000" />
      <String Name="AssemblyName" Value="Microsoft.VisualStudio.Shell.UI.Internal" />
      <!-- If your assembly is strongly named, you'll need the version and public key token as well -->
      <!-- <String Name="AssemblyName" Value="Microsoft.VisualStudio.Shell.UI.Internal;v17.0.0.0;b03f5f7f11d50a3a" /> -->
</Symbols>

Subelemento	Definición
Import	Importa los símbolos del archivo de manifiesto especificado para su uso en el manifiesto actual.
Guid	El símbolo representa un GUID y debe coincidir con el formato guid.
ID	El símbolo representa un identificador y debe ser un entero no negativo.
Cadena	El símbolo representa un valor arbitrario de cadena.

Los símbolos distinguen mayúsculas de minúsculas y se hace referencia a la sintaxis $(symbol-name):

<Image Guid="$(ShellCommandGuid)" ID="$(cmdidSaveAll)" >
      <Source Uri="/$(AssemblyName);Component/Resources/image.xaml" />
</Image>

Algunos símbolos están predefinidos para todos los manifiestos. Se pueden usar en el atributo URI del <elemento Source> o <Import> para hacer referencia a rutas de acceso en el equipo local.

Símbolo	Descripción
CommonProgramFiles	Valor de la variable de entorno %CommonProgramFiles%
LocalAppData	Valor de la variable de entorno %LocalAppData%
ManifestFolder	Carpeta que contiene el archivo de manifiesto
MyDocuments	Ruta de acceso completa de la carpeta Mis documentos del usuario actual
ProgramFiles	Valor de la variable de entorno %ProgramFiles%
Sistema	La carpeta Windows\System32
WinDir	Valor de la variable de entorno %WinDir%

Imagen

El <elemento Image> define una imagen a la que puede hacer referencia un moniker. El GUID y el identificador tomados juntos forman el moniker de imagen. El moniker de la imagen debe ser único en toda la biblioteca de imágenes. Si más de una imagen tiene un moniker determinado, el primero encontrado al compilar la biblioteca es el que se conserva.

Debe contener al menos un origen. Aunque los orígenes neutros de tamaño proporcionarán los mejores resultados en una amplia gama de tamaños, no son necesarios. Si se solicita al servicio una imagen de un tamaño no definido en el <elemento Image> y no hay ningún origen independiente del tamaño, el servicio elegirá el mejor origen específico del tamaño y lo escalará al tamaño solicitado.

<Image Guid="guid" ID="int" AllowColorInversion="true/false">
      <Source ... />
      <!-- optional additional Source elements -->
</Image>

Atributo	Definición
Guid	[Obligatorio] Parte GUID del moniker de imagen
ID	[Obligatorio] Parte del identificador del moniker de imagen
AllowColorInversion	[Opcional, valor predeterminado true] Indica si la imagen puede invertir sus colores mediante programación cuando se usa en un fondo oscuro.

Origen

El <elemento Source> define un único recurso de origen de imagen (XAML y PNG).

<Source Uri="uri" Background="background">
      <!-- optional NativeResource element -->
 </Source>

Atributo	Definición
Uri	[Obligatorio] Un URI que define dónde se puede cargar la imagen. Puede tener uno de los valores siguientes: - Un URI de paquete mediante la autoridad de application:/// - Referencia de recursos de componente absoluto : ruta de acceso a un archivo que contiene un recurso nativo
Fondo	[Opcional] Indica qué tipo de fondo está diseñado para usarse el origen. Puede tener uno de los valores siguientes: - Luz: la fuente se puede usar en un fondo claro. - Oscuro: el origen se puede usar en un fondo oscuro. - HighContrast: el origen se puede usar en cualquier fondo en modo contraste alto. - HighContrastLight: el origen se puede usar en un fondo claro en modo contraste alto. -HighContrastDark: el origen se puede usar en un fondo oscuro en modo contraste alto. Si se omite el atributo Background , el origen se puede usar en cualquier fondo. Si El fondo es Claro, Oscuro, AltoContrastLight o HighContrastDark, los colores de la fuente nunca se invierten. Si se omite background o se establece en HighContrast, la inversión de los colores del origen se controla mediante el atributo AllowColorInversion de la imagen.

Un <elemento Source> puede tener exactamente uno de los siguientes subelementos opcionales:

Element	Atributos (todos necesarios)	Definición
<Tamaño>	Value	El origen se usará para las imágenes del tamaño especificado (en unidades de dispositivo). La imagen será cuadrada.
<SizeRange>	MinSize, MaxSize	El origen se usará para imágenes de MinSize a MaxSize (en unidades de dispositivo) de forma inclusiva. La imagen será cuadrada.
<Dimensiones>	Ancho, alto	El origen se usará para las imágenes del ancho y alto especificados (en unidades de dispositivo).
<DimensionRange>	MinWidth, MinHeight, MaxWidth, MaxHeight	El origen se usará para las imágenes desde el ancho o alto mínimo hasta el ancho o alto máximo (en unidades de dispositivo) de forma inclusiva.

Un <elemento Source> también puede tener un subelemento NativeResource> opcional<, que define un <> origen que se carga desde un ensamblado nativo en lugar de un ensamblado administrado.

<NativeResource Type="type" ID="int" />

Atributo	Definición
Tipo	[Obligatorio] Tipo del recurso nativo, ya sea XAML o PNG.
ID	[Obligatorio] Parte del identificador entero del recurso nativo

ImageList

El <elemento ImageList> define una colección de imágenes que se pueden devolver en una sola franja. La tira se basa en la demanda, según sea necesario.

<ImageList>
      <ContainedImage Guid="guid" ID="int" External="true/false" />
      <!-- optional additional ContainedImage elements -->
 </ImageList>

Atributo	Definición
Guid	[Obligatorio] Parte GUID del moniker de imagen
ID	[Obligatorio] Parte del identificador del moniker de imagen
Externos	[Opcional, valor predeterminado false] Indica si el moniker de imagen hace referencia a una imagen en el manifiesto actual.

El moniker de la imagen independiente no tiene que hacer referencia a una imagen definida en el manifiesto actual. Si no se encuentra la imagen contenida en la biblioteca de imágenes, se usará una imagen de marcador de posición en blanco en su lugar.

Uso de la herramienta

Validación de un manifiesto de imagen personalizado

Para crear un manifiesto personalizado, se recomienda usar la herramienta ManifestFromResources para generar automáticamente el manifiesto. Para validar el manifiesto personalizado, inicie el Visor de bibliotecas de imágenes y seleccione Rutas de acceso > del conjunto de archivos... para abrir el cuadro de diálogo Directorios de búsqueda. La herramienta usará los directorios de búsqueda para cargar manifiestos de imagen, pero también los usará para buscar los archivos .dll que contienen las imágenes de un manifiesto, por lo que asegúrese de incluir los directorios de manifiesto y DLL en este cuadro de diálogo.

Haga clic en Agregar... para seleccionar nuevos directorios de búsqueda para buscar manifiestos y sus archivos DLL correspondientes. La herramienta recordará estos directorios de búsqueda y se pueden activar o desactivar mediante la comprobación o desactivación de un directorio.

De forma predeterminada, la herramienta intentará encontrar el directorio de instalación de Visual Studio y agregará esos directorios a la lista de directorios de búsqueda. Puede agregar manualmente directorios que la herramienta no encuentra.

Una vez cargados todos los manifiestos, la herramienta se puede usar para alternar colores de fondo , PPP, contraste alto o escalado gris para las imágenes para que un usuario pueda inspeccionar visualmente los recursos de imagen para comprobar que se están representando correctamente para varias configuraciones.

El color de fondo se puede establecer en Claro, Oscuro o un valor personalizado. Al seleccionar "Color personalizado" se abrirá un cuadro de diálogo de selección de colores y se agregará ese color personalizado a la parte inferior del cuadro combinado de fondo para facilitar la recuperación más adelante.

Al seleccionar un moniker de imagen se muestra la información de cada imagen real detrás de ese moniker en el panel Detalles de la imagen de la derecha. El panel también permite a los usuarios copiar un moniker por nombre o por valor GUID:ID sin formato.

La información que se muestra para cada origen de imagen incluye el tipo de fondo en el que se va a mostrar, tanto si se pueden incluir temas como si admiten contraste alto, qué tamaño es válido para o si es de tamaño neutro y si la imagen procede de un ensamblado nativo.

Al validar un manifiesto de imagen, se recomienda implementar el manifiesto y el archivo DLL de imagen en sus ubicaciones reales. Esto comprobará que las rutas de acceso relativas funcionan correctamente y que la biblioteca de imágenes puede encontrar y cargar el manifiesto y el archivo DLL de imagen.

Búsqueda de knownMonikers del catálogo de imágenes

Para que coincida mejor con el estilo de Visual Studio, una extensión de Visual Studio puede usar imágenes en el Catálogo de imágenes de Visual Studio en lugar de crear y usar sus propias. Esto tiene la ventaja de no tener que mantener esas imágenes y garantiza que la imagen tendrá una imagen de respaldo de valores altos de PPP, por lo que debe ser correcta en todas las configuraciones de PPP que admite Visual Studio.

El visor de la biblioteca de imágenes permite buscar un manifiesto para que un usuario pueda encontrar el moniker que representa un recurso de imagen y usar ese moniker en el código. Para buscar imágenes, escriba el término de búsqueda deseado en el cuadro de búsqueda y presione Entrar. La barra de estado de la parte inferior mostrará cuántas coincidencias se encontraron de las imágenes totales en todos los manifiestos.

Al buscar monikers de imágenes en manifiestos existentes, se recomienda buscar y usar solo los monikers del Catálogo de imágenes de Visual Studio, otros monikers accesibles públicamente intencionadamente o sus propios monikers personalizados. Si usa monikers no públicos, es posible que se rompa la interfaz de usuario personalizada o que sus imágenes cambien de maneras inesperadas si o cuando esos monikers e imágenes no públicos se cambian o actualizan.

Además, es posible realizar búsquedas por GUID. Este tipo de búsqueda es útil para filtrar la lista a un único manifiesto o a una sola subsección de un manifiesto si ese manifiesto contiene varios GUID.

Por último, también es posible realizar búsquedas por identificador.

Notas

• De forma predeterminada, la herramienta extraerá varios manifiestos de imagen presentes en el directorio de instalación de Visual Studio. El único que tiene monikers consumibles públicamente es el manifiesto Microsoft.VisualStudio.ImageCatalog . GUID: ae27a6b0-e345-4288-96df-5eaf394ee369 ( no invalide este GUID en un manifiesto personalizado) Tipo: KnownMonikers

• La herramienta intenta iniciarse para cargar todos los manifiestos de imagen que encuentra, por lo que la aplicación puede tardar varios segundos en aparecer realmente. También puede ser lento o no responde al cargar los manifiestos.

Salida de ejemplo

Esta herramienta no genera ninguna salida.