Cenni preliminari su menu e barre degli strumenti

Menu e barre degli strumenti sono il modo in cui gli utenti accedono ai comandi nell'estensione. Sono pratici modi grafici per presentare i comandi agli utenti. In genere, i comandi correlati sono raggruppati nello stesso menu o sulla stessa barra degli strumenti.

Usare menu e barre degli strumenti

Questa panoramica illustra questi scenari principali per l'uso di menu e barre degli strumenti:

• Creare un menu
• Inserisci voci in un menu
• Creare una barra degli strumenti
• Posizionare gli elementi su una barra degli strumenti
• Creare un gruppo
• Inserire elementi in un gruppo
• Posizionare i gruppi su un menu o una barra degli strumenti
• Ordinamento posizionamento (priorità)

Creare un menu

Per creare un menu con il nuovo modello di estendibilità, aggiungere una proprietà statica MenuConfiguration , adornando la classe con l'attributo VisualStudioContribution . Questa proprietà statica può essere inserita in qualsiasi classe nel progetto Extension. Nei nuovi esempi di modello di estendibilità sono disponibili nella Extension classe per semplicità. I menu senza elementi figlio visibili non saranno visibili nell'interfaccia utente.

[VisualStudioContribution]
public class ExtensionEntrypoint : Extension
{
  [VisualStudioContribution]
  public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%");
}

Classe MenuConfiguration

La MenuConfiguration classe ha alcuni parametri da acquisire familiarità con:

Parametro	Type	Obbligatorio	Descrizione
DisplayName	String	Sì	Nome visualizzato predefinito del menu. Racchiudere questa stringa con il carattere '%' per abilitare la localizzazione di questa stringa. Vedere la sezione Localizzare i metadati.
Tooltiptext	String	No	Testo da visualizzare come descrizione comando quando il menu viene posizionato o attivo. Racchiudere questa stringa con il carattere '%' per abilitare la localizzazione di questa stringa. Vedere la sezione Localizzare i metadati.
Posizionamenti	CommandPlacement[]	No	Specifica i gruppi esistenti all'interno di Visual Studio a cui il menu verrà padre. Vedere Inserire un menu nell'IDE.
Children	MenuChild[]	No	Descrive il set di comandi, menu e gruppi che devono essere padre di questo menu. L'ordine in cui questi elementi sono definiti nella matrice rappresentano l'ordine in cui verranno visualizzati visivamente nell'IDE. Vedere in Inserisci voci in un menu

Inserire un menu nell'IDE

I menu vengono inseriti nell'IDE nello stesso modo in cui i comandi sono. Vedere Inserire un comando nell'IDE.

public override MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Placements = new CommandPlacement[]
    {
        CommandPlacement.KnownPlacements.ToolsMenu
    },
};

Inserisci voci in un menu

L'inserimento della voce in un menu viene eseguito aggiungendo elementi alla Children matrice in MenuConfiguration. L'ordine in cui gli elementi vengono aggiunti a questa matrice determina il modo in cui questi elementi verranno visualizzati visivamente nell'IDE.

Inserimento di comandi in un menu

L'inserimento dei comandi in un menu viene eseguito usando il MenuChild.Command<T> metodo , sostituendo l'argomento modello con il nome della classe dell'oggetto Command.

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Command<MyCommand>(),
    },
};

Posizionamento di menu in un menu

L'inserimento di menu in un menu viene eseguito usando il MenuChild.Menu metodo , passando un altro MenuConfiguration come parametro.

[VisualStudioContribution]
public static MenuConfiguration MyChildMenu => new("My Child Menu!");

[VisualStudioContribution]
public static MenuConfiguration MyParentMenu => new("My Parent Menu!")
{
    Children = new[]
    {
        MenuChild.Menu(MyChildMenu),
    },
};

Separazione delle voci di menu in gruppi

Gli elementi all'interno di un menu possono essere raggruppati con un elemento MenuChild.Separator tra gli elementi. Visivamente, sarà simile a una linea sottile posizionata tra due elementi.

[VisualStudioContribution]
public static MenuConfiguration MyMenu1 => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        MenuChild.Menu(MyMenu2), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu2`
        MenuChild.Separator,
        MenuChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
        MenuChild.Menu(MyMenu3), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu3`
    },
};

Questa operazione può essere eseguita anche usando il MenuChild.Group metodo per definire un gruppo inline. Si userà quindi la GroupChild classe per aggiungere elementi padre al gruppo.

[VisualStudioContribution]
public static MenuConfiguration MyMenu1 => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Group(
            GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
            GroupChild.Menu(MyMenu2)), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu2`
        MenuChild.Group(
            GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
            GroupChild.Menu(MyMenu3)), // Assuming there is a `MenuConfiguration` defined in the extension called `MyMenu3`
    },
};

Nei due esempi precedenti il menu risultante sarebbe identico nell'IDE. Il menu MyMenu1 sarà simile al menu nello screenshot seguente:

Creare una barra degli strumenti

Per creare una barra degli strumenti con il nuovo modello di estendibilità, aggiungere una proprietà statica ToolbarConfiguration , adornando la classe con l'attributo VisualStudioContribution . Questa proprietà statica può essere inserita in qualsiasi classe nel progetto Extension. Nei nuovi esempi di modello di estendibilità sono disponibili nella Extension classe per semplicità.

[VisualStudioContribution]
public class ExtensionEntrypoint : Extension
{
  [VisualStudioContribution]
  public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%");
}

Se si lascia la Placement proprietà di ToolbarConfiguration così come null si posiziona la barra degli strumenti sulla barra degli strumenti standard e può essere resa visibile selezionando la barra degli strumenti nel View -> Toolbars menu.

Classe ToolbarConfiguration

La ToolbarConfiguration classe ha alcune proprietà che è necessario acquisire familiarità con:

Proprietà	Type	Obbligatorio	Descrizione
DisplayName	String	Sì	Nome visualizzato predefinito della barra degli strumenti. Racchiudere questa stringa con il carattere '%' per abilitare la localizzazione di questa stringa. Vedere la sezione Localizzare i metadati.
Tooltiptext	String	No	Testo da visualizzare come descrizione comando quando la barra degli strumenti viene visualizzata con il puntatore del mouse o con lo stato attivo. Racchiudere questa stringa con il carattere '%' per abilitare la localizzazione di questa stringa. Vedere la sezione Localizzare i metadati.
Posizionamenti	CommandPlacement[]	No	Specifica i gruppi esistenti all'interno di Visual Studio a cui la barra degli strumenti sarà padre. Vedere Inserire un comando nell'IDE. Se si lascia questa proprietà, null la barra degli strumenti viene posizionata sulla barra degli strumenti standard e può essere resa visibile selezionando la barra degli strumenti nel View -> Toolbars menu
Children	ToolbarChild[]	No	Descrive il set di comandi, menu e gruppi che devono essere padre di questa barra degli strumenti. L'ordine in cui questi elementi sono definiti nella matrice rappresentano l'ordine in cui verranno visualizzati visivamente nell'IDE. Vedere In Inserire elementi su una barra degli strumenti

Posizionare gli elementi su una barra degli strumenti

L'inserimento dei comandi su una barra degli strumenti viene eseguito usando il ToolbarChild.Command<T> metodo , sostituendo l'argomento modello con il nome della classe dell'oggetto Command.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Command<MyCommand>(),
    },
};

Separazione degli elementi della barra degli strumenti in gruppi

Gli elementi all'interno di una barra degli strumenti possono essere raggruppati con un elemento ToolbarChild.Separator tra gli elementi. Visivamente, sarà simile a una linea sottile posizionata tra due elementi.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        ToolbarChild.Separator,
        ToolbarChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

Questa operazione può essere eseguita anche usando il ToolbarChild.Group metodo per definire un gruppo inline. Si userà quindi la ToolbarChild classe per aggiungere elementi padre al gruppo.

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Group(
            GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        ToolbarChild.Group(
            GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

Nei due esempi riportati di seguito, la barra degli strumenti risultante sarebbe identica nell'IDE. La barra degli strumenti sarà simile alla barra degli strumenti MyToolbar nello screenshot seguente:

Creare un gruppo

Un gruppo è un raggruppamento visivo di elementi in cui verrà inserito un separatore tra gli ultimi e i primi elementi dei gruppi adiacenti. Nelle sezioni precedenti viene descritto come creare gruppi all'interno del contesto della Children proprietà di un MenuConfiguration oggetto o ToolbarConfiguration. È anche possibile definire gruppi all'interno del proprio CommandGroupConfiguration. Ciò è utile quando si desidera aggiungere un gruppo a un menu o a una barra degli strumenti esistente in Visual Studio senza definire il proprio menu o barra degli strumenti. Può essere utile anche se si desidera formattare il codice in modo da separare le definizioni di gruppo dal menu e dalle definizioni della barra degli strumenti.

Per creare un gruppo con il nuovo modello di estendibilità, aggiungere una proprietà statica CommandGroupConfiguration . Questa proprietà statica può essere inserita in qualsiasi classe nel progetto Extension. Nei nuovi esempi di modello di estendibilità sono disponibili nella Extension classe per semplicità. Se un oggetto CommandGroupConfiguration specifica un Placementoggetto , deve anche essere adornato con l'attributo VisualStudioContribution .

public static CommandGroupConfiguration MyGroup => new();

[VisualStudioContribution]
private static CommandGroupConfiguration MyGroupWithPlacement => new(GroupPlacement.KnownPlacements.ToolsMenu);

Classe CommandGroupConfiguration

La CommandGroupConfiguration classe ha alcuni parametri da acquisire familiarità con:

Parametro	Type	Obbligatorio	Descrizione
Posizionamento	GroupPlacement	No	Specifica il menu o la barra degli strumenti esistente all'interno di Visual Studio a cui il gruppo sarà padre. Vedere Inserire un gruppo nell'IDE.
Children	GroupChild[]	No	Descrive il set di comandi e menu che devono essere padre di questo gruppo. L'ordine in cui questi elementi sono definiti nella matrice rappresentano l'ordine in cui verranno visualizzati visivamente nell'IDE. Vedere l'articolo Inserire elementi in un gruppo

Inserire un gruppo nell'IDE

In Visual Studio è disponibile un set di posizioni ben definite in cui è possibile posizionare i comandi. Questi posizionamenti sono definiti dalla proprietà CommandPlacement.KnownPlacements nella classe Commands.GroupPlacement. Il set corrente di KnownPlacements è:

• ToolsMenu - Il comando verrà inserito in un gruppo nel menu "Strumenti" di primo livello in Visual Studio.
• ViewOtherWindowsMenu - Il comando verrà inserito in un gruppo sotto il menu "Visualizza" di primo livello -> "Altre finestre" in Visual Studio.
• ExtensionsMenu - Il comando verrà inserito in un gruppo nel menu "Estensioni" di primo livello in Visual Studio.

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup1 => new(GroupPlacement.KnownPlacements.ToolsMenu);

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup2 => new(GroupPlacement.KnownPlacements.ExtensionsMenu.WithPriority(0x100));

Inserire elementi in un gruppo

I comandi e i menu possono essere inseriti in gruppi usando la Children proprietà matrice in CommandGroupConfiguration.

Posizionare i comandi in un gruppo

L'inserimento di comandi in un gruppo viene eseguito usando il GroupChild.Command<T> metodo , sostituendo l'argomento modello con il nome della classe .Command

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup => new(GroupPlacement.KnownPlacements.ToolsMenu)
{
    Children = new[]
    {
        GroupChild.Command<MyCommand>(),
    },
};

Posizionare i menu in un gruppo

L'inserimento di menu in un gruppo viene eseguito usando il GroupChild.Menu metodo , passando un oggetto MenuConfiguration come parametro.

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%");

[VisualStudioContribution]
public static CommandGroupConfiguration MyGroup => new(GroupPlacement.KnownPlacements.ToolsMenu)
{
    Children = new[]
    {
        GroupChild.Menu(MyMenu),
    },
};

Posizionare i gruppi su un menu o una barra degli strumenti

L'inserimento di un gruppo in un menu viene eseguito usando il MenuChild.Group metodo , passando un oggetto CommandGroupConfiguration come parametro. L'inserimento di un gruppo su una barra degli strumenti viene eseguito usando il ToolbarChild.Group metodo , passando un oggetto CommandGroupConfiguration come parametro. I gruppi padre a menu o barre degli strumenti in questo modo non possono avere la Placement proprietà dell'oggetto CommandGroupConfiguration impostato su alcun valore ad eccezione nulldi e non deve essere adornato con l'attributo VisualStudioContribution .

private static CommandGroupConfiguration MyGroup => new()
{
    Children = new[]
    {
        GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
};

[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
    Children = new[]
    {
        MenuChild.Group(MyGroup),
    },
};

private static CommandGroupConfiguration MyGroup => new()
{
    Children = new[]
    {
        GroupChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        GroupChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    },
}

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = new[]
    {
        ToolbarChild.Group(MyGroup),
    },
};

Ordinamento posizionamento (priorità)

I posizionamenti vengono ordinati in base al valore della proprietà Priority quando è padre di un controllo definito in VSCT, rispetto ad altri elementi padre dello stesso gruppo, menu o barra degli strumenti. La proprietà Priority è un oggettounsigned short. Il valore predefinito Priority di e CommandPlacementGroupPlacement è 0 e può essere modificato chiamando i CommandPlacement.WithPriority metodi o GroupPlacement.WithPriority passando il valore desiderato Priority . Può Priority anche essere impostato utilizzando i CommandPlacement.VsctParent metodi e GroupPlacement.VsctParent e passando direttamente l'oggetto desiderato Priority .

La Priority proprietà non è interessata quando gli elementi padre dei controlli definiti tramite oggetti di configurazione tramite il modello VisualStudio.Extensibility , ad esempio il gruppo, il menu o la barra degli strumenti padre di è stato definito tramite CommandGroupConfiguration, MenuConfigurationo ToolbarConfiguration.

GroupPlacement

GroupPlacement.KnownPlacements.ToolsMenu.WithPriority(0x0500);

// Parenting a group to the "Help" top level menu
GroupPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x0088, priority: 0x0500);

CommandPlacement

CommandPlacement.KnownPlacements.ToolsMenu.WithPriority(0x0500);

// Parenting a command to the "Help -> About" group
CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x016B, priority: 0x0801);