Bidrag och konfigurationer

Du kan exponera tilläggskomponenter för Visual Studio genom att härleda från vissa basklasser, och du kan konfigurera dem genom att definiera vissa egenskaper och använda olika attribut.

Visual Studio-bidrag

Syftet med ett Visual Studio-tillägg är att bidra nya funktioner i Visual Studio. Detta uppnås genom att utöka en av många klasser som Command, ToolWindoweller ExtensionPart och tillämpa attributet VisualStudioContribution.

Den här artikeln refererar till Command Parenting exempeltillägg för att förklara begreppen att bidra till och konfigurera tilläggskomponenter.

Varje VisualStudio.Extensibility-tillägg måste bidra med minst en Extension klass:

namespace CommandParentingSample;

[VisualStudioContribution]
public class CommandParentingSampleExtension : Extension
{
    /// <inheritdoc/>
    protected override void InitializeServices(IServiceCollection serviceCollection)
    {
        base.InitializeServices(serviceCollection);
    }
}

Klassen Extension är den första instansierade klassen i tillägget och gör att du kan lägga till dina egna tjänster i IServiceCollection som ska användas för beroendeinjektion.

Exemplet "Command Parenting" bidrar med en annan klass, Command, till Visual Studio.

[VisualStudioContribution]
internal class SampleCommand : Command
{
    public SampleCommand()
    {
    }
    ...

När du utökar en basklass som tillhandahålls av VisualStudio.Extensibility SDK kan du veta om du förväntas använda attributet VisualStudioContribution genom att kontrollera om basklassen implementerar IVisualStudioContributionClass (både Extension och Command gör).

Visual Studio-bidragsklasser är lättsinnigt instansierade singletons: endast en instans skapas och dess skapande fördröjs tills Visual Studio behöver interagera med den (till exempel när en Command först anropas av användaren).

Med VisualStudio.Extensibility-infrastrukturen kan du också ta emot tjänster via beroendeinmatning som konstruktorparametrar för Visual Studio-bidragsklasser (se Beroendeinmatning i VisualStudio.Extensibility-tillägg), inklusive alla tjänster som du har lagt till i IServiceCollection i Extension-klassens InitializeServices-metod.

Visual Studio kräver ofta att en unik identifierare associeras med bidrag. I de flesta fall använder VisualStudio.Extensibility-infrastrukturen det fullständiga namnet på Visual Studio-bidragsklassen som bidragsidentifierare. Till exempel skulle identifieraren för Extension-klassen ovan vara CommandParentingSample.CommandParentingSampleExtension. Du kanske vill välja typnamn och namnområde för dina Visual Studio-bidragsklasser, eftersom de kan visas i Visual Studio-loggar och felmeddelanden.

Konfigurering av Visual Studio-bidrag

De flesta Visual Studio-bidragsklasser kräver eller tillåter konfiguration. Till exempel kräver den Command abstrakta klassen implementeringen av en CommandConfiguration-egenskap som anger minst kommandots visningsnamn och, om du vill, andra egenskaper som dess placering.

[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 är en kompileringskonstant, vilket innebär att dess värde utvärderas när tillägget skapas och ingår i tilläggsmanifestet (extension.json). Visual Studio kan läsa tilläggsmanifestet utan att läsa in själva tillägget, vilket ger bättre prestanda.

kompileringstidskonstanter omfattas av ytterligare begränsningar jämfört med normala egenskaper, till exempel måste de vara skrivskyddade och deras initieringskod kan inte innehålla referenser till icke-statiska medlemmar eller imperativa kodblock med flera instruktioner. Dessa begränsningar tillämpas av visualstudio.extensibility build-verktygen och resulterar i felmeddelanden som följande:

Ett problem uppstod när kompileringskonstanten SampleCommand.CommandConfiguration utvärderades. Referenser till användardefinierade icke-statiska medlemmar stöds inte vid utvärdering av konstanta värden för kompileringstid.

I allmänhet bör tillägget vid körning inte referera till kompileringskonstantens konfigurationsinställningar.

Du kan enkelt identifiera kompileringskonstant konfigurationsegenskaper eftersom deras definition har attributet 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; }
    ...

I sällsynta fall kan konfigurationsegenskaper vara valfria. I vissa fall kan du behöva implementera flera konfigurationsegenskaper i samma klass. Detta är vanligt när du utökar ExtensionPart och implementerar flera gränssnitt, där var och en kräver en egen konfigurationsegenskap.

Fristående konfigurationsegenskaper

Som beskrivs ovan definierar Visual Studio-bidragsklasser en singleton-klass som vanligtvis exponerar en eller flera kompileringskonstant konfigurationsegenskaper. Konfigurationsegenskaperna sparas som tilläggsmetadata.

Vissa utökningsfunktioner kräver att du anger tilläggsmetadata som inte är kopplade till någon klass och som antingen är meningsfulla på egen hand eller så är det tänkt att refereras till av andra konfigurationer. Några exempel är definitioner av meny, verktygsfält och dokumenttyp. Detta uppnås genom att tillämpa attributet VisualStudioContribution på en statisk konfigurationsegenskap som är endast läsbar.

Visual Studio-bidragsegenskaper kan placeras i valfri klass.

Exemplet Kommandoparentes definierar ett verktygsfält genom att deklarera en statisk egenskap av typen ToolbarConfiguration och markera den som VisualStudioContribution.

namespace CommandParentingSample;

internal static class ExtensionCommandConfiguration
{
    [VisualStudioContribution]
    public static ToolbarConfiguration ToolBar => new("%CommandParentingSample.ToolBar.DisplayName%")
    {
        Children = new[]
        {
            ToolbarChild.Command<SampleCommand>(),
        },
    };
}

Egenskaper för Visual Studio-bidrag är också kompileringstidskonstanter och omfattas av samma begränsningar som beskrevs tidigare.

En Visual Studio-bidragsegenskap kan också referera till en annan konfigurationsegenskap. Till exempel:

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>(),
        },
    };
    ...

Typer som är avsedda att användas för att definiera Visual Studio-bidragsegenskaper implementerar IVisualStudioContributionProperty-gränssnittet och markeras med attributet CompileTimeEvaluation för att dokumentera att deras värden utvärderas när tillägget byggs.

[CompileTimeEvaluation]
public sealed class DocumentTypeConfiguration : IVisualStudioContributionProperty ...

Vägledningen om att inte referera till kompileringskonstant konfigurationsegenskaper vid körning gäller även för Visual Studio-kontributionsegenskaper.

Om en unik identifierare krävs för en Visual Studio-bidragsegenskap används dess fullständiga namn (som innehåller fullständigt namn och egenskapsnamn) av infrastrukturen VisualStudio.Extensibility som identifierare. Till exempel skulle den unika identifieraren för verktygsfältskonfigurationen som beskrivs här vara CommandParentingSample.ExtensionCommandConfiguration.ToolbarConfiguration.

Relaterat innehåll

  • Last updated on