Bijdragen en Configuraties
U kunt uitbreidingsonderdelen beschikbaar maken voor Visual Studio door te afgeleid van bepaalde basisklassen en u kunt ze configureren door bepaalde eigenschappen te definiëren en verschillende kenmerken te gebruiken.
Visual Studio-bijdragen
Het doel van een Visual Studio-extensie is om bijdragen nieuwe functies aan Visual Studio. Dit wordt bereikt door een van de vele klassen zoals Command, ToolWindowof ExtensionPart uit te breiden en het kenmerk VisualStudioContribution toe te passen.
In dit artikel wordt verwezen naar de Opdracht Parenting voorbeeldextensie om de concepten van het bijdragen aan en het configureren van extensiecomponenten uit te leggen.
Elke VisualStudio.Extensibility-extensie moet ten minste één Extension klasse bijdragen:
namespace CommandParentingSample;
[VisualStudioContribution]
public class CommandParentingSampleExtension : Extension
{
/// <inheritdoc/>
protected override void InitializeServices(IServiceCollection serviceCollection)
{
base.InitializeServices(serviceCollection);
}
}
De Extension klasse is de eerste geïnstantieerde klasse van de extensie en stelt u in staat om uw eigen services toe te voegen aan de IServiceCollection, welke gebruikt kunnen worden voor dependency injection.
Het Command Parenting-voorbeeld draagt een andere klasse, een Command, bij aan Visual Studio:
[VisualStudioContribution]
internal class SampleCommand : Command
{
public SampleCommand()
{
}
...
Wanneer u een basisklasse uitbreidt die wordt geleverd door de VisualStudio.Extensibility SDK, kunt u weten of u het kenmerk VisualStudioContribution wilt gebruiken door te controleren of de basisklasse IVisualStudioContributionClass implementeert (zowel Extension als Command wel).
Visual Studio-bijdrageklassen zijn enkelvoudige instanties die lui worden geïnstantieerd: er wordt slechts één instantie gecreëerd en de creatie hiervan wordt uitgesteld totdat Visual Studio ermee moet werken (bijvoorbeeld wanneer een Command voor het eerst door de gebruiker wordt opgeroepen).
Met de VisualStudio.Extensibility-infrastructuur kunt u ook services ontvangen via afhankelijkheidsinjectie als constructorparameters van Visual Studio-bijdrageklassen (zie Afhankelijkheidsinjectie in VisualStudio.Extensibility-extensies), inclusief alle services die u hebt toegevoegd aan de IServiceCollection in de Extension klasse InitializeServices methode.
Visual Studio vereist vaak een unieke id die is gekoppeld aan bijdragen. In de meeste gevallen gebruikt de VisualStudio.Extensibility-infrastructuur de volledige naam van de Visual Studio-bijdrageklasse als de bijdrage-id. De id van de bovenstaande Extension klasse zou bijvoorbeeld CommandParentingSample.CommandParentingSampleExtensionzijn. Mogelijk wilt u zorgvuldig de typenaam en naamruimte van uw Visual Studio-bijdrageklassen kiezen, omdat deze mogelijk worden weergegeven in Visual Studio-logboeken en foutberichten.
Visual Studio-bijdragen configureren
Voor de meeste Visual Studio-bijdrageklassen is configuratie vereist of toegestaan. De Command abstracte klasse vereist bijvoorbeeld de implementatie van een CommandConfiguration eigenschap die ten minste de weergavenaam van de opdracht opgeeft en, optioneel, andere eigenschappen, zoals de plaatsing ervan.
[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 is een compilatieconstante, wat betekent dat de waarde wordt geëvalueerd wanneer de extensie wordt gebouwd en wordt opgenomen in het extensiemanifest (extension.json). Visual Studio kan het extensiemanifest lezen zonder de extensie zelf te laden, wat betere prestaties mogelijk maakt.
Constanten tijdens compilatietijd zijn onderhevig aan extra beperkingen in vergelijking met normale eigenschappen. Zo moeten ze bijvoorbeeld alleen-lezen zijn en mag de initialisatiecode geen verwijzingen bevatten naar niet-statische leden of imperatieve codeblokken met meerdere opdrachten. Deze beperkingen worden afgedwongen door de bouwhulpprogramma's van VisualStudio.Extensibility en resulteren in foutberichten, zoals bijvoorbeeld de volgende:
Er is een probleem opgetreden bij het evalueren van de compilatieconstante SampleCommand.CommandConfiguration. Verwijzingen naar door de gebruiker gedefinieerde niet-statische leden worden niet ondersteund bij het evalueren van compilatietijdconstante waarden.
Over het algemeen moet de extensie niet verwijzen naar compilatieconstante configuratie-eigenschappen tijdens de runtijd.
U kunt eenvoudig compilatieconstante configuratie-eigenschappen identificeren, omdat de definitie het kenmerk CompileTimeEvaluation heeft.
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 zeldzame gevallen kunnen configuratie-eigenschappen optioneel zijn. In bepaalde gevallen moet u mogelijk meerdere configuratie-eigenschappen op dezelfde klasse implementeren. Dit is gebruikelijk bij het uitbreiden van ExtensionPart en het implementeren van meerdere interfaces, die elk een eigen configuratie-eigenschap vereisen.
Zelfstandige configuratie-eigenschappen
Zoals hierboven beschreven, definiëren Visual Studio-bijdrageklassen een singleton-klasse die meestal een of meer compilatieconstante configuratie-eigenschappen beschikbaar maakt. De waarden voor configuratie-eigenschappen worden opgeslagen als extensiemetagegevens.
Voor sommige uitbreidbaarheidsfuncties moet u extensiemetagegevens opgeven die niet aan een klasse zijn gekoppeld en die op zichzelf zinvol zijn of waarnaar moet worden verwezen door andere configuraties. Enkele voorbeelden zijn menu-, werkbalk- en documenttypedefinities. Dit wordt bereikt door het kenmerk VisualStudioContribution toe te passen op een statische alleen-lezen configuratie-eigenschap.
Visual Studio-bijdrage-eigenschappen kunnen in elke klasse worden geplaatst.
Het voorbeeld van het opdracht 'Parenting' definieert een werkbalk door een statische eigenschap van het type ToolbarConfiguration te declareren en deze als VisualStudioContributionaan te duiden.
namespace CommandParentingSample;
internal static class ExtensionCommandConfiguration
{
[VisualStudioContribution]
public static ToolbarConfiguration ToolBar => new("%CommandParentingSample.ToolBar.DisplayName%")
{
Children = new[]
{
ToolbarChild.Command<SampleCommand>(),
},
};
}
Visual Studio-bijdrage-eigenschappen zijn ook compilatieconstanten en zijn onderhevig aan dezelfde beperkingen die eerder zijn besproken.
Een visual Studio-bijdrage-eigenschap kan ook verwijzen naar een andere configuratie-eigenschap. Bijvoorbeeld:
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>(),
},
};
...
Typen die moeten worden gebruikt om eigenschappen van Visual Studio-bijdragen te definiëren, implementeren de IVisualStudioContributionProperty-interface en worden gemarkeerd met het kenmerk CompileTimeEvaluation om te documenteren dat hun waarden worden geëvalueerd wanneer de extensie wordt gebouwd.
[CompileTimeEvaluation]
public sealed class DocumentTypeConfiguration : IVisualStudioContributionProperty ...
De richtlijnen over het niet verwijzen naar compilatieconstante configuratie-eigenschappen tijdens uitvoeringstijd zijn ook van toepassing op de eigenschappen van Visual Studio bijdragen.
Als er een unieke ID vereist is voor een Visual Studio-eigenschap voor bijdragen, wordt de volledige naam, inclusief de volledige typenaam en eigenschapsnaam, door de VisualStudio.Extensibility-infrastructuur gebruikt als identifier. De unieke id van de hier besproken werkbalkconfiguratie zou bijvoorbeeld CommandParentingSample.ExtensionCommandConfiguration.ToolbarConfigurationzijn.