Visualizzatore della libreria di immagini

Lo strumento Visualizzatore libreria immagini di Visual Studio può caricare e cercare manifesti di immagini, consentendo all'utente di modificarli nello stesso modo in cui Visual Studio lo farebbe. L'utente può modificare sfondo, dimensioni, DPI, contrasto elevato e altre impostazioni. Lo strumento visualizza anche le informazioni di caricamento per ogni manifesto dell'immagine e visualizza le informazioni di origine per ogni immagine nel manifesto dell'immagine. Questo strumento è utile per:

1. Diagnostica degli errori

2. Verifica che gli attributi siano impostati correttamente nei manifesti delle immagini personalizzate

3. Ricerca di immagini nel catalogo immagini di Visual Studio in modo che un'estensione di Visual Studio possa usare immagini che si adattino allo stile di Visual Studio

Moniker immagine

Un moniker immagine (o moniker per brevità) è una coppia GUID:ID che identifica in modo univoco un asset di immagine o un asset elenco di immagini nella raccolta immagini.

File manifesto dell'immagine

I file manifesto dell'immagine (con estensione imagemanifest) sono file XML che definiscono un set di asset di immagine, i moniker che rappresentano tali asset e l'immagine o le immagini reali che rappresentano ogni asset. I manifesti delle immagini possono definire immagini autonome o elenchi di immagini per il supporto dell'interfaccia utente legacy. Sono inoltre disponibili attributi che possono essere impostati sull'asset o sulle singole immagini dietro ogni asset per cambiare quando e come vengono visualizzati tali asset.

Schema del manifesto dell'immagine

Un manifesto dell'immagine completo è simile al seguente:

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

Simboli

Come supporto per la leggibilità e la manutenzione, il manifesto dell'immagine può usare i simboli per i valori degli attributi. I simboli sono definiti come segue:

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

Sottoelemento	Definizione
Import	Importa i simboli del file manifesto specificato da usare nel manifesto corrente.
GUID	Il simbolo rappresenta un GUID e deve corrispondere alla formattazione GUID.
ID	Il simbolo rappresenta un ID e deve essere un intero non negativo.
String	Il simbolo rappresenta un valore stringa arbitrario.

I simboli fanno distinzione tra maiuscole e minuscole e fanno riferimento usando la sintassi $(symbol-name):

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

Alcuni simboli sono predefiniti per tutti i manifesti. Questi valori possono essere usati nell'attributo Uri dell'elemento <Source> o <Import> per fare riferimento ai percorsi nel computer locale.

Simbolo	Descrizione
CommonProgramFiles	Valore della variabile di ambiente %CommonProgramFiles%
Localappdata	Valore della variabile di ambiente %LocalAppData%
ManifestFolder	Cartella contenente il file manifesto
Mydocuments	Percorso completo della cartella Documenti dell'utente corrente
ProgramFiles	Valore della variabile di ambiente %ProgramFiles%
System	Cartella Windows\System32
Windir	Valore della variabile di ambiente %WinDir%

Image

L'elemento <Image> definisce un'immagine a cui può fare riferimento un moniker. Il GUID e l'ID combinati formano il moniker dell'immagine. Il moniker per l'immagine deve essere univoco nell'intera libreria di immagini. Se più di un'immagine ha un determinato moniker, il primo rilevato durante la compilazione della libreria è quello conservato.

Deve contenere almeno un'origine. Anche se le origini indipendenti dalle dimensioni offrono i risultati migliori in un'ampia gamma di dimensioni, non sono necessarie. Se viene richiesta un'immagine di una dimensione non definita nell'elemento <Image> e non esiste un'origine indipendente dalle dimensioni, il servizio sceglierà l'origine specifica delle dimensioni migliore e la ridimensiona alle dimensioni richieste.

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

Attributo	Definizione
GUID	[Obbligatorio] Parte GUID del moniker dell'immagine
ID	[Obbligatorio] Parte ID del moniker dell'immagine
AllowColorInversion	[Facoltativo, valore predefinito true] Indica se l'immagine può avere i colori invertibili a livello di codice quando viene usato in uno sfondo scuro.

Origine

L'elemento <Source> definisce un singolo asset di origine immagine (XAML e PNG).

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

Attributo	Definizione
URI	[Obbligatorio] URI che definisce la posizione da cui è possibile caricare l'immagine. I possibili valori sono i seguenti: - URI pack che usa l'autorità di application:/// - Informazioni di riferimento sulle risorse dei componenti assoluti - Percorso di un file contenente una risorsa nativa
Background	[Facoltativo] Indica il tipo di sfondo che l'origine deve essere usata. I possibili valori sono i seguenti: - Luce: la sorgente può essere utilizzata su uno sfondo chiaro. - Scuro: l'origine può essere usata su uno sfondo scuro. - HighContrast: l'origine può essere usata in qualsiasi sfondo in modalità contrasto elevato. - HighContrastLight: l'origine può essere usata su uno sfondo chiaro in modalità contrasto elevato. -HighContrastDark: l'origine può essere usata in uno sfondo scuro in modalità contrasto elevato. Se l'attributo Background viene omesso, l'origine può essere usata in qualsiasi background. Se Background è Chiaro, Scuro, HighContrastLight o HighContrastDark, i colori dell'origine non vengono mai invertiti. Se Background viene omesso o impostato su HighContrast, l'inversione dei colori dell'origine viene controllata dall'attributo AllowColorInversion dell'immagine.

Un <elemento Source> può avere esattamente uno dei sottoelementi facoltativi seguenti:

elemento	Attributi (tutti obbligatori)	Definizione
<Dimensione>	Valore	L'origine verrà usata per le immagini delle dimensioni specificate (in unità dispositivo). L'immagine sarà quadrata.
<SizeRange>	MinSize, MaxSize	L'origine verrà usata per le immagini da MinSize a MaxSize (in unità dispositivo) in modo inclusivo. L'immagine sarà quadrata.
<Dimensioni>	Larghezza, altezza	L'origine verrà usata per le immagini della larghezza e dell'altezza specificate (in unità dispositivo).
<DimensionRange>	MinWidth, MinHeight, MaxWidth, MaxHeight	L'origine verrà usata per le immagini dalla larghezza/altezza minima alla larghezza/altezza massima (in unità di dispositivo) inclusivamente.

Un <elemento Source> può anche avere un sottoelemento NativeResource> facoltativo<, che definisce un'origine <> caricata da un assembly nativo anziché da un assembly gestito.

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

Attributo	Definizione
Type	[Obbligatorio] Tipo della risorsa nativa, XAML o PNG
ID	[Obbligatorio] Parte ID intero della risorsa nativa

ImageList

L'elemento <ImageList> definisce una raccolta di immagini che possono essere restituite in un'unica striscia. La striscia è basata su richiesta, in base alle esigenze.

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

Attributo	Definizione
GUID	[Obbligatorio] Parte GUID del moniker dell'immagine
ID	[Obbligatorio] Parte ID del moniker dell'immagine
Esterna	[Facoltativo, impostazione predefinita false] Indica se il moniker dell'immagine fa riferimento a un'immagine nel manifesto corrente.

Il moniker per l'immagine contenuta non deve fare riferimento a un'immagine definita nel manifesto corrente. Se non è possibile trovare l'immagine contenuta nella raccolta immagini, verrà usata un'immagine segnaposto vuota al suo posto.

Procedura: utilizzare lo strumento

Convalida di un manifesto dell'immagine personalizzato

Per creare un manifesto personalizzato, è consigliabile usare lo strumento ManifestFromResources per generare automaticamente il manifesto. Per convalidare il manifesto personalizzato, avviare visualizzatore raccolta immagini e selezionare Percorsi set di file > ... per aprire la finestra di dialogo Directory di ricerca. Lo strumento userà le directory di ricerca per caricare i manifesti dell'immagine, ma li userà anche per trovare i file DLL che contengono le immagini in un manifesto, quindi assicurarsi di includere sia il manifesto che le directory DLL in questa finestra di dialogo.

Fare clic su Aggiungi per selezionare nuove directory di ricerca per cercare i manifesti e le DLL corrispondenti. Lo strumento memorizza queste directory di ricerca e può essere attivato o disattivato controllando o deselezionando una directory.

Per impostazione predefinita, lo strumento tenterà di trovare la directory di installazione di Visual Studio e di aggiungere tali directory all'elenco delle directory di ricerca. È possibile aggiungere manualmente directory che lo strumento non trova.

Una volta caricati tutti i manifesti, lo strumento può essere usato per attivare o disattivare i colori di sfondo , DPI, contrasto elevato o gradazioni di grigio per le immagini in modo che un utente possa esaminare visivamente gli asset di immagine per verificare che il rendering venga eseguito correttamente per varie impostazioni.

Il colore di sfondo può essere impostato su Chiaro, Scuro o su un valore personalizzato. Selezionando "Colore personalizzato" si aprirà una finestra di dialogo di selezione dei colori e si aggiungerà tale colore personalizzato nella parte inferiore della casella combinata di sfondo per facilitare il richiamo in un secondo momento.

Selezionando un moniker immagine vengono visualizzate le informazioni per ogni immagine reale dietro tale moniker nel riquadro Dettagli immagine a destra. Il riquadro consente inoltre agli utenti di copiare un moniker in base al nome o al valore GUID:ID non elaborato.

Le informazioni visualizzate per ogni origine immagine includono il tipo di sfondo su cui visualizzarlo, se può essere sottoposto a tema o supporta contrasto elevato, quali dimensioni è valido o se è indipendente dalle dimensioni e se l'immagine proviene da un assembly nativo.

Quando si convalida un manifesto dell'immagine, è consigliabile distribuire il manifesto e la DLL dell'immagine nelle posizioni reali. In questo modo si verificherà che tutti i percorsi relativi funzionino correttamente e che la libreria di immagini possa trovare e caricare il manifesto e la DLL dell'immagine.

Ricerca di cataloghi di immagini KnownMonikers

Per trovare una corrispondenza migliore con gli stili di Visual Studio, un'estensione di Visual Studio può usare immagini nel catalogo immagini di Visual Studio anziché crearne e usarle autonomamente. Ciò ha il vantaggio di non dover gestire tali immagini e garantisce che l'immagine abbia un'immagine di supporto con valori DPI elevati in modo che abbia un aspetto corretto in tutte le impostazioni DPI supportate da Visual Studio.

Il visualizzatore della libreria di immagini consente di cercare un manifesto in modo che un utente possa trovare il moniker che rappresenta un asset di immagine e usare tale moniker nel codice. Per cercare immagini, immettere il termine di ricerca desiderato nella casella di ricerca e premere INVIO. La barra di stato nella parte inferiore visualizzerà il numero di corrispondenze rilevate delle immagini totali in tutti i manifesti.

Quando si cercano moniker di immagini in manifesti esistenti, è consigliabile cercare e usare solo i moniker del Catalogo immagini di Visual Studio, altri moniker intenzionalmente accessibili pubblicamente o i propri moniker personalizzati. Se si usano moniker non pubblici, l'interfaccia utente personalizzata potrebbe essere interrotta o modificarne le immagini in modi imprevisti se o quando tali moniker e immagini non pubblici vengono modificati o aggiornati.

Inoltre, la ricerca in base al GUID è possibile. Questo tipo di ricerca è utile per filtrare l'elenco in un singolo manifesto o una singola sottosezione di un manifesto se tale manifesto contiene più GUID.

Infine, anche la ricerca in base all'ID è possibile.

Note

• Per impostazione predefinita, lo strumento eseguirà il pull di diversi manifesti di immagini presenti nella directory di installazione di Visual Studio. L'unico che ha moniker di consumo pubblicamente è il manifesto Microsoft.VisualStudio.ImageCatalog . GUID: ae27a6b0-e345-4288-96df-5eaf394ee369 ( non eseguire l'override di questo GUID in un manifesto personalizzato) Tipo: KnownMonikers

• Lo strumento tenta all'avvio di caricare tutti i manifesti di immagine trovati, quindi potrebbe essere necessario alcuni secondi prima che l'applicazione venga effettivamente visualizzata. Potrebbe anche essere lento o non risponde durante il caricamento dei manifesti.

Output di esempio

Questo strumento non genera alcun output.