Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
È possibile esporre i componenti delle estensioni a Visual Studio derivando da determinate classi di base ed è possibile configurarli definendo determinate proprietà e usando vari attributi.
Contributi di Visual Studio
Lo scopo di un'estensione di Visual Studio è contribuire nuove funzionalità a Visual Studio. Questa operazione viene ottenuta estendendo una di molte classi come Command, ToolWindowo ExtensionPart e applicando l'attributo VisualStudioContribution.
Questo articolo fa riferimento all'estensione di esempio Command Parenting per spiegare i concetti di contributo e configurazione dei componenti di estensione.
Ogni estensione VisualStudio.Extensibility deve contribuire almeno a una classe Extension:
namespace CommandParentingSample;
[VisualStudioContribution]
public class CommandParentingSampleExtension : Extension
{
/// <inheritdoc/>
protected override void InitializeServices(IServiceCollection serviceCollection)
{
base.InitializeServices(serviceCollection);
}
}
La classe Extension è la prima classe dell'estensione a essere istanziata e permette di aggiungere servizi personalizzati al IServiceCollection per utilizzarli nell'inserimento delle dipendenze .
L'esempio Command Parenting contribuisce con un'ulteriore classe, un Command, a Visual Studio.
[VisualStudioContribution]
internal class SampleCommand : Command
{
public SampleCommand()
{
}
...
Quando si estende una classe di base fornita da VisualStudio.Extensibility SDK, è possibile sapere se si prevede di usare l'attributo VisualStudioContribution verificando se la classe di base implementa IVisualStudioContributionClass (sia Extension che Command fare).
Le classi di contributo di Visual Studio sono singleton istanziati pigramente: viene creata una sola istanza e la loro creazione viene ritardata fino a quando Visual Studio non deve interagirci, ad esempio quando un Command viene richiamato per la prima volta dall'utente.
L'infrastruttura VisualStudio.Extensibility consente anche di ricevere servizi tramite l'iniezione delle dipendenze come parametri del costruttore delle classi contributive di Visual Studio, incluso qualsiasi servizio aggiunto al IServiceCollection nel metodo InitializeServices della classe Extension (vedere iniezione delle dipendenze nelle estensioni di VisualStudio.Extensibility).
Visual Studio richiede spesso un identificatore univoco da associare ai contributi. Nella maggior parte dei casi, l'infrastruttura VisualStudio.Extensibility usa il nome completo della classe di contributo di Visual Studio come identificatore del contributo. Ad esempio, l'identificatore della classe Extension precedente sarà CommandParentingSample.CommandParentingSampleExtension. È consigliabile scegliere con attenzione il nome del tipo e lo spazio dei nomi delle classi di contributo di Visual Studio, perché potrebbero essere visualizzati nei log di Visual Studio e nei messaggi di errore.
Configurazione dei contributi di Visual Studio
La maggior parte delle classi di contributi di Visual Studio richiede o consente la configurazione. Ad esempio, la classe astratta Command richiede l'implementazione di una proprietà CommandConfiguration specificando almeno il nome visualizzato del comando e, facoltativamente, altre proprietà come la relativa posizione.
[VisualStudioContribution]
internal class SampleCommand : Command
{
/// <inheritdoc />
public override CommandConfiguration CommandConfiguration => new("%CommandParentingSample.SampleCommand.DisplayName%")
{
Placements = new[]
{
// File in project context menu
CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 1072, priority: 0),
// Project context menu
CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 1026, priority: 0),
// Solution context menu
CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 1043, priority: 0),
},
};
...
CommandConfiguration è una costante in fase di compilazione , il cui valore viene valutato quando viene compilata l'estensione ed è inclusa nel manifesto dell'estensione (extension.json). Visual Studio può leggere il manifesto dell'estensione senza caricare l'estensione stessa, consentendo prestazioni migliori.
costanti in fase di compilazione sono soggette a limitazioni aggiuntive rispetto alle proprietà normali, ad esempio devono essere di sola lettura e il codice di inizializzazione non può includere riferimenti a membri non statici o blocchi di codice imperativi con più istruzioni. Queste restrizioni vengono applicate dagli strumenti di compilazione VisualStudio.Extensibility e genera messaggi di errore simili ai seguenti:
Si è verificato un problema durante la valutazione della costante in fase di compilazione SampleCommand.CommandConfiguration. I riferimenti ai membri non statici definiti dall'utente non sono supportati durante la valutazione dei valori costanti in fase di compilazione.
In generale, l'estensione non dovrebbe fare riferimento alla costante per la compilazione o alle proprietà di configurazione durante l'esecuzione.
È possibile identificare facilmente costante in fase di compilazione proprietà di configurazione perché la definizione ha l'attributo CompileTimeEvaluation.
public abstract class Command : ExecutableCommandHandler, IVisualStudioContributionClass
{
...
/// <summary>
/// Gets the configuration for this command. The value of this property is evaluated at compile time
/// when building the Visual Studio extension.
/// </summary>
[CompileTimeEvaluation]
public abstract CommandConfiguration CommandConfiguration { get; }
...
In rari casi, le proprietà di configurazione possono essere facoltative. In alcuni casi, potrebbe essere necessario implementare più proprietà di configurazione nella stessa classe. Ciò è comune quando si estendono ExtensionPart e si implementano più interfacce, ognuna delle quali richiede la propria proprietà di configurazione.
Proprietà di configurazione autonome
Come descritto in precedenza, le classi di contributo di Visual Studio definiscono una classe singleton che in genere espone una o più proprietà di configurazione costanti di compilazione . I valori delle proprietà di configurazione vengono salvati come metadati dell'estensione.
Alcune caratteristiche di estensibilità richiedono di specificare i metadati dell'estensione che non sono collegati a nessuna classe e sono significativi da soli o devono essere riferiti da altre configurazioni. Alcuni esempi sono le definizioni di menu, barra degli strumenti e tipo di documento. A tale scopo, applicare l'attributo VisualStudioContribution a una proprietà di configurazione statica di sola lettura.
Le proprietà dei contributi di Visual Studio possono essere inserite in qualsiasi classe.
L'esempio di command parenting definisce una barra degli strumenti dichiarando una proprietà statica di tipo ToolbarConfiguration e contrassegnandola come VisualStudioContribution.
namespace CommandParentingSample;
internal static class ExtensionCommandConfiguration
{
[VisualStudioContribution]
public static ToolbarConfiguration ToolBar => new("%CommandParentingSample.ToolBar.DisplayName%")
{
Children = new[]
{
ToolbarChild.Command<SampleCommand>(),
},
};
}
Le proprietà dei contributi di Visual Studio sono anche costanti in fase di compilazione e sono soggette alle stesse limitazioni descritte in precedenza.
Una proprietà di contributo di Visual Studio può anche fare riferimento a un'altra proprietà di configurazione. Per esempio:
public static class MenuConfigurations
{
[VisualStudioContribution]
public static CommandGroupConfiguration MyCommandGroup => new(GroupPlacement.KnownPlacements.ExtensionsMenu)
{
Children = new GroupChild[]
{
GroupChild.Menu(MyMenu),
},
};
[VisualStudioContribution]
public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
{
Children = new[]
{
MenuChild.Command<MyCommand>(),
},
};
...
I tipi destinati a essere usati per definire le proprietà dei contributi di Visual Studio implementano l'interfaccia IVisualStudioContributionProperty e sono contrassegnati con l'attributo CompileTimeEvaluation per documentare che i relativi valori vengono valutati quando viene compilata l'estensione.
[CompileTimeEvaluation]
public sealed class DocumentTypeConfiguration : IVisualStudioContributionProperty ...
Le linee guida per non fare riferimento alla costante di compilazione e alle proprietà di configurazione in fase di esecuzione si applicano anche alle proprietà di contributo di Visual Studio.
Se per una proprietà di contributo di Visual Studio è necessario un identificatore univoco, il nome completo (contenente il nome completo del tipo e il nome della proprietà) viene usato dall'infrastruttura VisualStudio.Extensibility come identificatore. Ad esempio, l'identificatore univoco della configurazione della barra degli strumenti descritta qui sarà CommandParentingSample.ExtensionCommandConfiguration.ToolbarConfiguration.