图像库查看器

项目
10/10/2023

Visual Studio 图像库查看器工具可以加载和搜索图像清单，使用户能够以与 Visual Studio 相同的方式操作它们。用户可以更改背景、大小、DPI、高对比度和其他设置。该工具还显示每个图像清单的加载信息，并显示图像清单中每个图像的源信息。此工具适用于：

诊断错误
确保在自定义映像清单中正确设置属性
在 Visual Studio 图像目录中搜索图像，以便 Visual Studio 扩展可以使用适合 Visual Studio 样式的图像

Image Library Viewer Hero

图像名字对象

图像名字对象（或简称名字对象）是一个 GUID：ID 对，用于唯一标识图像库中的图像资产或图像列表资产。

映像清单文件

图像清单（.imagemanifest）文件是定义一组图像资产的 XML 文件、表示这些资产的名字对象，以及表示每个资产的真实图像或图像。映像清单可以为旧版 UI 支持定义独立映像或映像列表。此外，还可以在每个资产后面的单个图像上设置属性，以更改这些资产的显示时间和方式。

映像清单架构

完整的映像清单如下所示：

<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>
      <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" />
</Symbols>

子元素	定义
Import	导入给定清单文件的符号，以便在当前清单中使用。
Guid	符号表示 GUID，必须与 GUID 格式匹配。
ID	该符号表示 ID，必须是非负整数。
字符串	符号表示任意字符串值。

符号区分大小写，并使用 $（symbol-name）语法引用：

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

某些符号为所有清单预定义。可以在 Source> 或 <Import> 元素的 <Uri 属性中使用这些属性来引用本地计算机上的路径。

符号	描述
CommonProgramFiles	%CommonProgramFiles% 环境变量的值
LocalAppData	%LocalAppData% 环境变量的值
ManifestFolder	包含清单文件的文件夹
MyDocuments	当前用户的“我的文档”文件夹的完整路径
ProgramFiles	%ProgramFiles% 环境变量的值
系统	Windows\System32 文件夹
WinDir	%WinDir% 环境变量的值

Image

<Image> 元素定义可由名字对象引用的图像。 GUID 和 ID 共同构成图像名字对象。图像的名字对象在整个图像库中必须是唯一的。如果多个图像具有给定的名字对象，则生成库时遇到的第一个图像是保留的。

它必须至少包含一个源。尽管大小中性源将在整个大小范围内提供最佳结果，但不需要它们。如果要求服务提供未在 Image> 元素中<定义的大小的图像，并且没有非大小中性源，则服务将选择最佳大小特定的源并将其缩放为请求的大小。

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

Attribute	定义
Guid	[必需]图像名字对象的 GUID 部分
ID	[必需]图像名字对象的 ID 部分
AllowColorInversion	[可选，默认值为 true]指示图像在深色背景上使用时是否可以以编程方式反转其颜色。

Source

<Source> 元素定义单个图像源资产（XAML 和 PNG）。

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

Attribute	定义
Uri	[必需]一个 URI，用于定义可从中加载图像的位置。该参数可以是下列值之一： - 使用 application:/// 颁发机构的包 URI - 绝对组件资源参考 - 包含本机资源的文件的路径
背景	[可选]指示源要使用的背景类型。该参数可以是下列值之一： - 浅色：源可用于浅色背景。 - 深色：源可用于深色背景。 - HighContrast：源可在高对比度模式下的任何背景上使用。 - HighContrastLight：源可在高对比度模式下的浅色背景上使用。 -HighContrastDark：源可在高对比度模式下的深色背景上使用。如果省略 Background 属性，则可以在任何后台使用源。如果背景为浅色、深色、 HighContrastLight 或 HighContrastDark，则源的颜色永远不会反转。如果省略背景或设置为 HighContrast，则源颜色的反转由图像的 AllowColorInversion 属性控制。

Attribute

定义

Uri

[必需]一个 URI，用于定义可从中加载图像的位置。该参数可以是下列值之一：

- 使用 application:/// 颁发机构的包 URI

- 绝对组件资源参考

- 包含本机资源的文件的路径

背景

[可选]指示源要使用的背景类型。

该参数可以是下列值之一：

- 浅色：源可用于浅色背景。

- 深色：源可用于深色背景。

- HighContrast：源可在高对比度模式下的任何背景上使用。

- HighContrastLight：源可在高对比度模式下的浅色背景上使用。

-HighContrastDark：源可在高对比度模式下的深色背景上使用。

如果省略 Background 属性，则可以在任何后台使用源。

如果背景为浅色、深色、 HighContrastLight 或 HighContrastDark，则源的颜色永远不会反转。如果 省略背景 或设置为 HighContrast，则源颜色的反转由图像的 AllowColorInversion 属性控制。

<Source> 元素可以正好具有以下可选子元素之一：

元素	属性（全部必需）	定义
<大小>	值	源将用于给定大小的图像（以设备单位为单位）。图像将为正方形。
<SizeRange>	MinSize、MaxSize	源将用于从 MinSize 到 MaxSize（以设备单位为单位）的图像（含设备单位）。图像将为正方形。
<Dimensions>	Width, Height	源将用于给定宽度和高度的图像（以设备单位为单位）。
<DimensionRange>	MinWidth、MinHeight、 MaxWidth、MaxHeight	源将用于从最小宽度/高度到最大宽度/高度（以设备单位为单位）的图像。

<Source> 元素还可以具有可选的 <NativeResource> 子元素，该子元素定义<从本机程序集而不是托管程序集加载的源>。

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

Attribute	定义
类型	[必需]本机资源的类型，即 XAML 或 PNG
ID	[必需]本机资源的整数 ID 部分

ImageList

<ImageList> 元素定义可在单个条带中返回的图像集合。条带按需构建。

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

Attribute	定义
Guid	[必需]图像名字对象的 GUID 部分
ID	[必需]图像名字对象的 ID 部分
外部	[可选，默认值 false]指示图像名字对象是否引用当前清单中的图像。

包含映像的名字对象不必引用当前清单中定义的映像。如果在图像库中找不到包含的图像，则会在其位置使用空白占位符图像。

如何使用该工具

验证自定义映像清单

若要创建自定义清单，建议使用 ManifestFromResources 工具自动生成清单。若要验证自定义清单，请启动图像库查看器并选择“文件 > 集路径...”打开“搜索目录”对话框。该工具将使用搜索目录加载图像清单，但它也将使用它来查找包含清单中的图像的 .dll 文件，因此请确保在此对话框中同时包含清单目录和 DLL 目录。

单击“ 添加...” 以选择要搜索清单及其相应 DLL 的新搜索目录。该工具将记住这些搜索目录，可以通过检查或取消检查目录来打开或关闭它们。

默认情况下，该工具将尝试查找 Visual Studio 安装目录，并将这些目录添加到搜索目录列表中。可以手动添加工具找不到的目录。

加载所有清单后，该工具可用于切换 图像的背景 色、 DPI、 高对比度或 灰度缩放 ，以便用户可以直观地检查图像资产，以验证它们是否为各种设置正确呈现。

Image Library Viewer Background

背景色可以设置为浅色、深色或自定义值。选择“自定义颜色”将打开颜色选择对话框，并将该自定义颜色添加到背景组合框底部，以便稍后轻松召回。

Image Library Viewer Custom Color

选择图像名字对象会在右侧的“图像详细信息”窗格中显示该名字对象背后的每个真实图像的信息。该窗格还允许用户按名称或原始 GUID：ID 值复制名字对象。

Image Library Viewer Image Details

为每个图像源显示的信息包括要显示它的背景类型、是主题还是支持高对比度、有效大小还是大小不中性，以及图像是否来自本机程序集。

Image Library Viewer Can Theme

验证映像清单时，建议在实际位置部署清单和映像 DLL。这将验证任何相对路径是否正常工作，以及图像库能否找到并加载清单和映像 DLL。

搜索图像目录 KnownMonikers

为了更好地匹配 Visual Studio 样式，Visual Studio 扩展可以使用 Visual Studio 映像目录中的图像，而不是创建和使用自己的图像。这样做的好处是不必维护这些图像，并保证图像具有高 DPI 支持的图像，因此它应该在 Visual Studio 支持的所有 DPI 设置中看起来正确。

图像库查看器允许搜索清单，以便用户可以找到表示图像资产的名字对象并在代码中使用该名字对象。若要搜索图像，请在搜索框中输入所需的搜索词，然后按 Enter。底部的状态栏将显示所有清单中所有图像中发现多少个匹配项。

Image Library Viewer Filter

在现有清单中搜索图像名字对象时，建议仅搜索和使用 Visual Studio 图像目录的名字对象、其他有意公开访问的名字对象或你自己的自定义名字对象。如果使用非公共名字对象，则自定义 UI 可能会中断，或者如果更改或更新这些非公共名字对象和图像，则自定义 UI 可能会以意外的方式更改或更改其图像。

此外，还可以通过 GUID 进行搜索。这种类型的搜索对于将列表筛选到单个清单或清单的单个子部分（如果该清单包含多个 GUID）非常有用。

Image Library Viewer Filter GUID

最后，也可以按 ID 进行搜索。

Image Library Viewer Filter ID

说明

默认情况下，该工具将拉取 Visual Studio 安装目录中存在的多个映像清单。唯一具有公开易耗品名字对象的人是 Microsoft.VisualStudio.ImageCatalog 清单。 GUID：ae27a6b0-e345-4288-96df-5eaf394ee369（请勿在自定义清单中重写此 GUID）类型：KnownMonikers
该工具在启动时尝试加载它找到的所有映像清单，因此应用程序实际显示可能需要几秒钟时间。加载清单时也可能很慢或无响应。

示例输出

此工具不生成任何输出。

通过

图像库查看器

如何使用该工具

说明

示例输出

其他资源