Vytvoření jednoduchého rozšíření

Článek
2023-12-08

V části Vytvoření prvního rozšíření jste zjistili, jak pomocí šablony projektu VisualStudio.Extensibility vytvořit projekt rozšíření a jak ho sestavit a ladit v experimentální instanci sady Visual Studio.

V tomto kurzu se naučíte vytvořit rozšíření pomocí jednoduchého příkazu, který něco dělá v editoru sady Visual Studio. V tomto případě vloží nově vygenerovaný identifikátor GUID. Dozvíte se také, jak sadě Visual Studio sdělit, pro jaké typy souborů je přípona GUID povolená, a jak nastavit, aby se nový příkaz zobrazoval jako panel nástrojů nebo položka nabídky.

Dokončená ukázka pro tento kurz se může nacházet tady.

Tento kurz obsahuje následující kroky:

Konfigurace příkazu
Vytvoření metody provádění

Konfigurace příkazu

V tomto kroku se dozvíte o možnostech konfigurace a umístění příkazu. Účelem hostování příkazu je zveřejnit ho uživateli nějakým způsobem, například přidat položku nabídky nebo příkazového řádku.

Šablona projektu nebo ukázka, kterou jste vytvořili v kurzu Vytvoření prvního rozšíření , se skládá z jednoho souboru jazyka C#, který už obsahuje Command třídu. Můžete ho aktualizovat.

Command1.cs Přejmenujte soubor na InsertGuidCommand.cs, přejmenujte třídu InsertGuidCommand, aktualizujte CommandConfiguration vlastnost.
```
public override CommandConfiguration CommandConfiguration => new("%InsertGuidCommand.DisplayName%")
{
    Placements = new[] { CommandPlacement.KnownPlacements.ExtensionsMenu },
};
```
Placements určuje, kde se má příkaz v integrovaném vývojovém prostředí (IDE) objevit. V tomto případě se příkaz umístí do nabídky Rozšíření, což je jedna z nabídek nejvyšší úrovně v sadě Visual Studio.

Argumentem konstruktoru CommandConfiguration je zobrazovaný název příkazu, což je text nabídky. Zobrazovaný název je uzavřený % znaky, protože odkazuje na prostředek řetězce z .vsextension/string-resources.json důvodu podpory lokalizace.
Aktualizujte .vsextension/string-resources.json se zobrazovaným názvem InsertGuidCommand.
```
{
  "InsertGuidCommand.DisplayName": "Insert new guid"
}
```
Icon Přidejte vlastnost.
```
public override CommandConfiguration CommandConfiguration => new("%InsertGuidCommand.DisplayName%")
{
    Placements = new[] { CommandPlacement.KnownPlacements.ExtensionsMenu },
    Icon = new(ImageMoniker.KnownValues.OfficeWebExtension, IconSettings.IconAndText),
};
```
Můžete zadat známou integrovanou ikonu, v tomto případě OfficeWebExtensionnebo nahrát obrázky pro ikonu, jak je popsáno v části Přidat příkazy sady Visual Studio. Druhý argument je výčet, který určuje, jak se má příkaz objevit na panelech nástrojů (kromě jeho místa v nabídce). Tato možnost IconSettings.IconAndText znamená zobrazit ikonu a zobrazovaný název vedle sebe.

VisibleWhen Přidejte vlastnost, která určuje podmínky, které se musí pro položku zobrazit uživateli.

public override CommandConfiguration CommandConfiguration => new("%InsertGuidCommand.DisplayName%")
{
    Placements = new[] { CommandPlacement.KnownPlacements.ExtensionsMenu },
    Icon = new(ImageMoniker.KnownValues.OfficeWebExtension, IconSettings.IconAndText),
    VisibleWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveEditorContentType, ".+"),
};

Další informace najdete v tématu použití omezení aktivace na základě pravidel.

Vytvoření metody provádění

V tomto kroku implementujete metodu ExecuteCommandAsync příkazu, která definuje, co se stane, když uživatel vybere položku nabídky nebo stiskne položku na panelu nástrojů pro váš příkaz.

Zkopírujte následující kód pro implementaci metody.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        Requires.NotNull(context, nameof(context));
        var newGuidString = Guid.NewGuid().ToString("N", CultureInfo.CurrentCulture);

        using var textView = await context.GetActiveTextViewAsync(cancellationToken);
        if (textView is null)
        {
            this.logger.TraceInformation("There was no active text view when command is executed.");
            return;
        }

        await this.Extensibility.Editor().EditAsync(
            batch =>
            {
                textView.Document.AsEditable(batch).Replace(textView.Selection.Extent, newGuidString);
            },
            cancellationToken);
    }

První řádek ověří argumenty a pak vytvoříme nový Guid , který použijeme později.

Pak vytvoříme ITextViewSnapshot ( textView objekt zde) voláním asynchronní metody GetActiveTextViewAsync. Token zrušení se předává, aby se zachovala možnost zrušit asynchronní požadavek, ale tato část není v této ukázce ukázce ukázaná. Pokud se nám textové zobrazení úspěšně nezobrazí, zapíšeme do protokolu a ukončíme se bez nutnosti dělat nic jiného.

Teď jsme připraveni volat asynchronní metodu, která odešle požadavek na úpravy editoru sady Visual Studio. Metoda, kterou chceme, je EditAsync. To je člen EditorExtensibility třídy, který umožňuje interakci se spuštěným editorem sady Visual Studio v integrovaném vývojovém prostředí (IDE). Typ Command , který vlastní InsertGuidCommand třída dědí, má člen Extensibility , který poskytuje přístup k objektu EditorExtensibility EditorExtensibility , abychom se mohli dostat do třídy pomocí volání this.Extensibility.Editor().

Metoda EditAsync přebírá jako Action<IEditBatch> parametr. Tento parametr se nazývá editorSource,

Volání používá EditAsync výraz lambda. Pokud to chcete rozdělit trochu, můžete toto volání také napsat takto:

await this.Extensibility.Editor().EditAsync(
    batch =>
    {
        var editor = textView.Document.AsEditable(batch);
        // specify the desired changes here:
        editor.Replace(textView.Selection.Extent, newGuidString);
    },
    cancellationToken);

Toto volání si můžete představit jako zadání kódu, který chcete spustit v procesu editoru sady Visual Studio. Výraz lambda určuje, co chcete v editoru změnit. Je batch typu IEditBatch, což znamená, že výraz lambda definovaný zde provádí malou sadu změn, které by se měly provést jako jednotka, a nikoli přerušení jinými úpravami uživatelem nebo službou jazyka. Pokud se kód spustí příliš dlouho, může to vést k nereagování, takže je důležité zachovat změny v rámci tohoto výrazu lambda omezené a porozumět všemu, co by mohlo vést ke zpoždění.

AsEditable Pomocí metody v dokumentu získáte dočasný objekt editoru, který můžete použít k určení požadovaných změn. Všechno ve výrazu lambda si můžete představit jako požadavek na spuštění sady Visual Studio, nikoli jako skutečné spuštění, protože jak je popsáno v rozšiřitelnosti editoru Sady Visual Studio, existuje konkrétní protokol pro zpracování těchto asynchronních žádostí o úpravy z rozšíření a existuje možnost, že se změny nepřijímají, například pokud uživatel provádí změny ve stejnou dobu, kdy vytváří konflikt.

Vzor EditAsync lze použít k obecné úpravě textu zadáním změn po komentáři "zadejte požadované změny sem".

Sdílet prostřednictvím

Vytvoření jednoduchého rozšíření

Konfigurace příkazu

Vytvoření metody provádění

Další materiály