Visualizador da biblioteca de imagens

A ferramenta Visual Studio Image Library Viewer pode carregar e pesquisar manifestos de imagem, permitindo que o usuário manipule-os da mesma maneira que o Visual Studio. O usuário pode alterar plano de fundo, tamanhos, DPI, alto contraste e outras configurações. A ferramenta também exibe informações de carregamento para cada manifesto de imagem e exibe informações de origem para cada imagem no manifesto de imagem. Esta ferramenta é útil para:

1. Diagnóstico de erros

2. Garantindo que os atributos sejam definidos corretamente em manifestos de imagem personalizados

3. Procurando imagens no catálogo de imagens do Visual Studio para que uma extensão do Visual Studio possa usar imagens que se ajustam ao estilo do Visual Studio

Apelido da imagem

Um moniker de imagem (ou moniker para abreviar) é um par GUID:ID que identifica exclusivamente um ativo de imagem ou ativo de lista de imagens na Biblioteca de Imagens.

Arquivos de manifesto de imagem

Arquivos de manifesto de imagem (.imagemanifest) são arquivos XML que definem um conjunto de ativos de imagem, os apelidos que representam esses ativos e a imagem real ou imagens que representam cada ativo. Os manifestos de imagem podem definir imagens autônomas ou listas de imagens para suporte à interface do usuário herdada. Além disso, há atributos que podem ser definidos no ativo ou nas imagens individuais atrás de cada ativo para alterar quando e como esses ativos são exibidos.

Esquema de manifesto de imagem

Um manifesto de imagem completo tem esta aparência:

<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>

Símbolos

Como um auxílio de legibilidade e manutenção, o manifesto de imagem pode usar símbolos para valores de atributo. Os símbolos são definidos assim:

<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	Definição
Import	Importa os símbolos do arquivo de manifesto fornecido para uso no manifesto atual.
Guid	O símbolo representa um GUID e deve corresponder à formatação do GUID.
ID	O símbolo representa uma ID e deve ser um inteiro não negativo.
String	O símbolo representa um valor de cadeia de caracteres arbitrário.

Os símbolos diferenciam maiúsculas de minúsculas e são referenciados usando a sintaxe $(symbol-name):

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

Alguns símbolos são predefinidos para todos os manifestos. Eles podem ser usados no atributo Uri do <elemento Source> ou <Import> para fazer referência a caminhos na máquina local.

Símbolo	Descrição
CommonProgramFiles	O valor da variável de ambiente %CommonProgramFiles%
LocalAppData	O valor da variável de ambiente %LocalAppData%
Pasta Manifesto	A pasta que contém o arquivo de manifesto
Meus Documentos	O caminho completo da pasta Meus Documentos do usuário atual
ProgramFiles	O valor da variável de ambiente %ProgramFiles%
Sistema	A pasta Windows\System32
WinDir	O valor da variável de ambiente %WinDir%

Imagem

O <elemento Image> define uma imagem que pode ser referenciada por um moniker. O GUID e o ID juntos formam o apelido da imagem. O apelido da imagem deve ser exclusivo em toda a biblioteca de imagens. Se mais de uma imagem tiver um determinado apelido, a primeira encontrada durante a construção da biblioteca é a que é mantida.

Deve conter pelo menos uma fonte. Embora fontes de tamanho neutro forneçam os melhores resultados em uma ampla gama de tamanhos, elas não são necessárias. Se for solicitada ao serviço uma imagem de um tamanho não definido no <elemento Image> e não houver uma fonte de tamanho neutro, o serviço escolherá a melhor fonte específica de tamanho e a dimensionará para o tamanho solicitado.

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

Atributo	Definição
Guid	[obrigatório] A parte GUID do moniker de imagem
ID	[obrigatório] A parte ID do apelido de imagem
AllowColorInversion	[Opcional, padrão true] Indica se a imagem pode ter suas cores programaticamente invertidas quando usada em um plano de fundo escuro.

Origem

O <elemento Source> define um único ativo de origem de imagem (XAML e PNG).

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

Atributo	Definição
Uri	[obrigatório] Um URI que define de onde a imagem pode ser carregada. Pode ser um dos seguintes: - Um URI de pacote usando a autoridade application:/// - Uma referência absoluta de recursos de componentes - Um caminho para um arquivo que contém um recurso nativo
Tela de fundo	[Opcional] Indica em que tipo de plano de fundo a fonte deve ser usada. Pode ser um dos seguintes: - Luz: A fonte pode ser usada em um fundo claro. - Escuro: A fonte pode ser usada em um fundo escuro. - HighContrast: A fonte pode ser usada em qualquer plano de fundo no modo de Alto Contraste. - HighContrastLight: A fonte pode ser usada em um fundo claro no modo de alto contraste. -HighContrastDark: A fonte pode ser usada em um plano de fundo escuro no modo de Alto Contraste. Se o atributo Background for omitido, a origem poderá ser usada em qualquer plano de fundo. Se Plano de fundo for Claro, Escuro, HighContrastLight ou HighContrastDark, as cores da origem nunca serão invertidas. Se Background for omitido ou definido como HighContrast, a inversão das cores da origem será controlada pelo atributo AllowColorInversion da imagem.

Um <elemento Source> pode ter exatamente um dos seguintes subelementos opcionais:

Element	Atributos (todos obrigatórios)	Definição
<Tamanho>	Valor	A fonte será usada para imagens do tamanho determinado (em unidades de dispositivo). A imagem será quadrada.
<SizeRange>	MinSize, MaxSize	A fonte será usada para imagens de MinSize a MaxSize (em unidades de dispositivo) inclusive. A imagem será quadrada.
<Dimensões>	Largura, Altura	A fonte será usada para imagens da largura e altura dadas (em unidades de dispositivo).
<DimensionRange>	Largura mínima, Altura mínima, MaxWidth, MaxHeight	A fonte será usada para imagens da largura/altura mínima até a largura/altura máxima (em unidades de dispositivo) inclusive.

Um <elemento Source também pode ter um subelemento NativeResource> opcional<, que define um Source>> que é carregado de um assembly nativo em vez de um <assembly gerenciado.

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

Atributo	Definição
Tipo	[obrigatório] O tipo do recurso nativo, XAML ou PNG
ID	[obrigatório] A parte de ID inteiro do recurso nativo

ImageList

O <elemento ImageList> define uma coleção de imagens que podem ser retornadas em uma única faixa. A faixa é construída sob demanda, conforme a necessidade.

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

Atributo	Definição
Guid	[obrigatório] A parte GUID do moniker de imagem
ID	[obrigatório] A parte ID do apelido de imagem
Externos	[Opcional, falso padrão] Indica se o apelido de imagem faz referência a uma imagem no manifesto atual.

O apelido para a imagem contida não precisa fazer referência a uma imagem definida no manifesto atual. Se a imagem contida não puder ser encontrada na biblioteca de imagens, uma imagem de espaço reservado em branco será usada em seu lugar.

Como usar a ferramenta

Validando um manifesto de imagem personalizado

Para criar um manifesto personalizado, recomendamos que você use a ferramenta ManifestFromResources para gerar automaticamente o manifesto. Para validar o manifesto personalizado, inicie o Visualizador de Biblioteca de Imagens e selecione Caminhos do Conjunto de > Arquivos... para abrir a caixa de diálogo Diretórios de Pesquisa. A ferramenta usará os diretórios de pesquisa para carregar manifestos de imagem, mas também os usará para localizar os arquivos .dll que contêm as imagens em um manifesto, portanto, certifique-se de incluir os diretórios manifesto e DLL nessa caixa de diálogo.

Clique em Adicionar para selecionar novos diretórios de pesquisa para procurar manifestos e suas DLLs correspondentes. A ferramenta lembrará esses diretórios de pesquisa e eles podem ser ativados ou desativados marcando ou desmarcando um diretório.

Por padrão, a ferramenta tentará localizar o diretório de instalação do Visual Studio e adicionar esses diretórios à lista de diretórios de pesquisa. Você pode adicionar manualmente diretórios que a ferramenta não encontra.

Depois que todos os manifestos são carregados, a ferramenta pode ser usada para alternar cores de plano de fundo, DPI, alto contraste ou escala de cinza para as imagens, para que um usuário possa inspecionar visualmente os ativos de imagem para verificar se eles estão sendo renderizados corretamente para várias configurações.

A cor do plano de fundo pode ser definida como Claro, Escuro ou um valor personalizado. Selecionar "Cor personalizada" abrirá uma caixa de diálogo de seleção de cores e adicionará essa cor personalizada à parte inferior da caixa de combinação de plano de fundo para facilitar a recuperação mais tarde.

A seleção de um moniker de imagem exibe as informações de cada imagem real por trás desse apelido no painel Detalhes da imagem à direita. O painel também permite que os usuários copiem um apelido por nome ou por valor bruto GUID:ID.

As informações exibidas para cada fonte de imagem incluem em que tipo de plano de fundo exibi-la, se ela pode ser temática ou suporta Alto Contraste, para quais tamanhos ela é válida ou se é neutra em termos de tamanho e se a imagem vem de um assembly nativo.

Ao validar um manifesto de imagem, recomendamos que você implante o manifesto e a DLL de imagem em seus locais do mundo real. Isso verificará se todos os caminhos relativos estão funcionando corretamente e se a biblioteca de imagens pode localizar e carregar a DLL de manifesto e imagem.

Procurando por catálogo de imagens KnownMonikers

Para corresponder melhor ao estilo do Visual Studio, uma extensão do Visual Studio pode usar imagens no Catálogo de Imagens do Visual Studio em vez de criar e usar suas próprias. Isso tem o benefício de não precisar manter essas imagens e garante que a imagem terá uma imagem de suporte de DPI alto, portanto, ela deve parecer correta em todas as configurações de DPI que o Visual Studio suporta.

O visualizador da biblioteca de imagens permite que um manifesto seja pesquisado para que um usuário possa encontrar o apelido que representa um ativo de imagem e usar esse apelido no código. Para procurar imagens, digite o termo de pesquisa desejado na caixa de pesquisa e pressione Enter. A barra de status na parte inferior exibirá quantas correspondências foram encontradas do total de imagens em todos os manifestos.

Ao procurar apelidos de imagem em manifestos existentes, recomendamos que você pesquise e use apenas os apelidos do Catálogo de Imagens do Visual Studio, outros apelidos intencionalmente acessíveis publicamente ou seus próprios apelidos personalizados. Se você usar apelidos não públicos, a interface do usuário personalizada poderá ser interrompida ou ter suas imagens alteradas de maneiras inesperadas se ou quando esses apelidos e imagens não públicos forem alterados ou atualizados.

Além disso, a pesquisa por GUID é possível. Esse tipo de pesquisa é útil para filtrar a lista para um único manifesto ou uma única subseção de um manifesto se esse manifesto contiver vários GUIDs.

Por fim, a pesquisa por ID também é possível.

Observações

• Por padrão, a ferramenta puxará vários manifestos de imagem presentes no diretório de instalação do Visual Studio. O único que tem apelidos de consumo público é o manifesto Microsoft.VisualStudio.ImageCatalog . GUID: ae27a6b0-e345-4288-96df-5eaf394ee369 ( não substitua este GUID em um manifesto personalizado) Tipo: KnownMonikers

• A ferramenta tenta ao iniciar carregar todos os manifestos de imagem encontrados, portanto, pode levar vários segundos para que o aplicativo realmente apareça. Ele também pode estar lento ou não responder durante o carregamento dos manifestos.

Saída de exemplo

Esta ferramenta não gera nenhuma saída.