Přidání rozšíření protokolu LSP (Language Server Protocol)

Protokol LSP (Language Server Protocol) je běžný protokol ve formě JSON RPC verze 2.0, který slouží k poskytování funkcí služby jazyka různým editorům kódu. Pomocí protokolu můžou vývojáři napsat jeden server jazyka, který poskytuje funkce jazykových služeb, jako je IntelliSense, diagnostika chyb, vyhledání všech odkazů atd. pro různé editory kódu, které podporují LSP. Tradičně lze jazykové služby v sadě Visual Studio přidat pomocí gramatických souborů TextMate k poskytování základních funkcí, jako je zvýraznění syntaxe nebo psaní vlastních jazykových služeb, které používají úplnou sadu rozhraní API rozšiřitelnosti sady Visual Studio k poskytování bohatších dat. S podporou sady Visual Studio pro LSP je k dispozici třetí možnost.

Pokud chcete zajistit co nejlepší uživatelské prostředí, zvažte také implementaci konfigurace jazyka, která poskytuje místní zpracování mnoha stejných operací, a proto může zlepšit výkon mnoha operací editoru specifického pro jazyk, které LSP podporuje.

Protokol jazyka serveru

Tento článek popisuje, jak vytvořit rozšíření sady Visual Studio, které používá jazykový server založený na LSP. Předpokládá se, že jste už vyvinuli jazykový server založený na LSP a chcete ho jenom integrovat do sady Visual Studio.

Pro podporu v sadě Visual Studio můžou jazykové servery komunikovat s klientem (Visual Studio) prostřednictvím jakéhokoli mechanismu přenosu založeného na datových proudech, například:

• Standardní vstupní a výstupní datové proudy
• Pojmenované kanály
• Sokety (pouze TCP)

Záměrem LSP a jeho podpory v sadě Visual Studio je onboardovat jazykové služby, které nejsou součástí produktu Visual Studio. V sadě Visual Studio není určeno rozšířit stávající jazykové služby (například C#). Pokud chcete rozšířit existující jazyky, projděte si průvodce rozšiřitelností jazykové služby (například "Roslyn" .NET Compiler Platform) nebo si přečtěte téma Rozšíření editoru a jazykových služeb.

Další informace o samotném protokolu najdete v této dokumentaci.

Další informace o tom, jak vytvořit server ukázkového jazyka nebo jak integrovat existující jazykový server do editoru Visual Studio Code, najdete v této dokumentaci.

Podporované funkce protokolu jazykového serveru

Následující tabulky ukazují, které funkce LSP jsou v sadě Visual Studio podporované:

Začínáme

Vytvoření projektu VSIX

Pokud chcete vytvořit rozšíření jazykové služby pomocí jazykového serveru založeného na LSP, nejprve se ujistěte, že máte nainstalovanou sadu Funkcí vývoje rozšíření sady Visual Studio pro vaši instanci sady VS.

Dále vytvořte nový projekt VSIX tak, že přejdete na Soubor>nový projekt>Visual C#>Rozšiřitelnost>projektu VSIX:

Instalace jazykového serveru a modulu runtime

Ve výchozím nastavení rozšíření vytvořená pro podporu jazykových serverů založených na LSP v sadě Visual Studio neobsahují samotné jazykové servery ani moduly runtime potřebné ke spuštění. Vývojáři rozšíření zodpovídají za distribuci jazykových serverů a potřebných modulů runtime. Existuje několik způsobů, jak to udělat:

• Jazykové servery mohou být vloženy do VSIX jako soubory obsahu.
• Vytvořte MSI pro instalaci jazykového serveru nebo potřebných modulů runtime.
• Uveďte pokyny pro Marketplace, které uživatele informují o tom, jak získat moduly runtime a jazykové servery.

Gramatické soubory TextMate

LSP neobsahuje specifikaci, jak poskytnout barevné zvýrazňování textu pro jazyky. Vývojáři rozšíření můžou k poskytování vlastních barev pro jazyky v sadě Visual Studio použít gramatický soubor TextMate. Pokud chcete přidat vlastní gramatické nebo motivové soubory TextMate, postupujte takto:

1. Ve svém rozšíření vytvořte složku s názvem Grammars (nebo může být jakýkoli název, který zvolíte).

2. Do složky Grammars (Gramatika) zahrňte všechny soubory *.tmlanguage, *.plist, *.tmtheme nebo *.json soubory, které chcete použít pro vlastní zabarvení.

   Tip

   Soubor .tmtheme definuje, jak se obory mapují na klasifikace sady Visual Studio (pojmenované barevné klíče). Pokyny najdete v globálním souboru .tmtheme v adresáři %ProgramFiles(x86)%\Microsoft Visual Studio\<version>\<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg .

3. Vytvořte soubor .pkgdef a přidejte řádek podobný tomuto:

   [$RootKey$\TextMate\Repositories]
   "MyLang"="$PackageFolder$\Grammars"
   

4. Klikněte pravým tlačítkem myši na soubory a vyberte Vlastnosti. Změňte akci Sestavení na Obsah a změňte vlastnost Include v VSIX na true.

Po dokončení předchozích kroků se složka Grammars přidá do instalačního adresáře balíčku jako zdroj úložiště s názvem MyLang (MyLang je jen název pro nejednoznačnost a může to být jakýkoli jedinečný řetězec). Všechny gramatické soubory (.tmlanguage ) a soubory motivu (soubory .tmtheme ) v tomto adresáři se vyberou jako potenciály a nahrazují předdefinované gramatiky poskytované textem TextMate. Pokud deklarované přípony gramatického souboru odpovídají příponě otevřeného souboru, textMate krokuje.

Vytvoření jednoduchého klienta jazyka

Hlavní rozhraní – ILanguageClient

Po vytvoření projektu VSIX přidejte do projektu následující balíčky NuGet:

• Microsoft.VisualStudio.LanguageServer.Client

Pak můžete vytvořit novou třídu, která implementuje rozhraní ILanguageClient , což je hlavní rozhraní potřebné pro klienty jazyků připojující se k serveru jazyka založenému na LSP.

Následuje ukázka:

namespace MockLanguageExtension
{
    [ContentType("bar")]
    [Export(typeof(ILanguageClient))]
    public class BarLanguageClient : ILanguageClient
    {
        public string Name => "Bar Language Extension";

        public IEnumerable<string> ConfigurationSections => null;

        public object InitializationOptions => null;

        public IEnumerable<string> FilesToWatch => null;

        public event AsyncEventHandler<EventArgs> StartAsync;
        public event AsyncEventHandler<EventArgs> StopAsync;

        public async Task<Connection> ActivateAsync(CancellationToken token)
        {
            await Task.Yield();

            ProcessStartInfo info = new ProcessStartInfo();
            info.FileName = Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "Server", @"MockLanguageServer.exe");
            info.Arguments = "bar";
            info.RedirectStandardInput = true;
            info.RedirectStandardOutput = true;
            info.UseShellExecute = false;
            info.CreateNoWindow = true;

            Process process = new Process();
            process.StartInfo = info;

            if (process.Start())
            {
                return new Connection(process.StandardOutput.BaseStream, process.StandardInput.BaseStream);
            }

            return null;
        }

        public async Task OnLoadedAsync()
        {
            await StartAsync.InvokeAsync(this, EventArgs.Empty);
        }

        public Task OnServerInitializeFailedAsync(Exception e)
        {
            return Task.CompletedTask;
        }

        public Task OnServerInitializedAsync()
        {
            return Task.CompletedTask;
        }
    }
}

Hlavní metody, které je potřeba implementovat, jsou OnLoadedAsync a ActivateAsync. OnLoadedAsync se volá, když Sada Visual Studio načetla vaše rozšíření a váš jazykový server je připravený ke spuštění. V této metodě můžete okamžitě vyvolat delegáta StartAsync , aby signalizoval, že se má spustit jazykový server, nebo můžete provést další logiku a vyvolat StartAsync později. Pokud chcete aktivovat jazykový server, musíte v určitém okamžiku volat Metodu StartAsync.

ActivateAsync je metoda, která se nakonec vyvolá voláním delegáta StartAsync . Obsahuje logiku pro spuštění jazykového serveru a navázání připojení k němu. Musí se vrátit objekt připojení, který obsahuje datové proudy pro zápis na server a čtení ze serveru. Všechny zde vyvolané výjimky jsou zachyceny a zobrazeny uživateli prostřednictvím zprávy informačního panelu v sadě Visual Studio.

Aktivace

Po implementaci třídy klienta jazyka budete muset definovat dva atributy, abyste mohli definovat, jak se načte do sady Visual Studio a jak se aktivuje:

  [Export(typeof(ILanguageClient))]
  [ContentType("bar")]

MEF

Visual Studio ke správě bodů rozšiřitelnosti používá MEF (Managed Extensibility Framework). Atribut Export označuje visual Studio, že tato třída by měla být vyzvednuta jako bod rozšíření a načtena v příslušné době.

Pokud chcete použít MEF, musíte také definovat MEF jako prostředek v manifestu VSIX.

Otevřete návrháře manifestu VSIX a přejděte na kartu Prostředky :

Chcete-li vytvořit nový prostředek, klikněte na tlačítko Nový :

• Typ: Microsoft.VisualStudio.MefComponent
• Zdroj: Projekt v aktuálním řešení
• Projekt: [Váš projekt]

Definice typu obsahu

V současné době je jediným způsobem, jak načíst příponu jazykového serveru založeného na LSP, typ obsahu souboru. To znamená, že při definování třídy klienta jazyka (která implementuje ILanguageClient), budete muset definovat typy souborů, které při otevření způsobí načtení rozšíření. Pokud nejsou otevřeny žádné soubory odpovídající vašemu definovanému typu obsahu, rozšíření se nenačte.

To se provádí definováním jedné nebo více ContentTypeDefinition tříd:

namespace MockLanguageExtension
{
    public class BarContentDefinition
    {
        [Export]
        [Name("bar")]
        [BaseDefinition(CodeRemoteContentDefinition.CodeRemoteContentTypeName)]
        internal static ContentTypeDefinition BarContentTypeDefinition;

        [Export]
        [FileExtension(".bar")]
        [ContentType("bar")]
        internal static FileExtensionToContentTypeDefinition BarFileExtensionDefinition;
    }
}

V předchozím příkladu se vytvoří definice typu obsahu pro soubory, které končí příponou souboru .bar . Definice typu obsahu má název "bar" a musí být odvozena z CodeRemoteContentTypeName.

Po přidání definice typu obsahu můžete definovat, kdy se má načíst rozšíření jazykového klienta ve třídě klienta jazyka:

    [ContentType("bar")]
    [Export(typeof(ILanguageClient))]
    public class BarLanguageClient : ILanguageClient
    {
    }

Přidání podpory pro jazykové servery LSP nevyžaduje implementaci vlastního projektového systému v sadě Visual Studio. Zákazníci můžou otevřít jeden soubor nebo složku v sadě Visual Studio, aby mohli začít používat vaši jazykovou službu. Podpora jazykových serverů LSP je ve skutečnosti navržená tak, aby fungovala pouze ve scénářích s otevřenými složkami nebo soubory. Pokud je implementovaný vlastní projektový systém, některé funkce (například nastavení) nebudou fungovat.

Rozšířené funkce

Nastavení

K dispozici je podpora vlastních nastavení specifických pro jazyk a server, ale stále probíhá jeho vylepšení. Nastavení jsou specifické pro to, co jazykový server podporuje, a obvykle řídí, jak jazykový server generuje data. Například server jazyka může mít nastavení maximálního počtu nahlášených chyb. Autoři rozšíření by definovali výchozí hodnotu, kterou můžou změnit uživatelé pro konkrétní projekty.

Pomocí následujícího postupu přidejte podporu nastavení do rozšíření jazykové služby LSP:

1. Do projektu přidejte soubor JSON (například MockLanguageExtension Nastavení.json), který obsahuje nastavení a jejich výchozí hodnoty. Příklad:

   {
       "foo.maxNumberOfProblems": -1
   }
   

2. Klikněte pravým tlačítkem na soubor JSON a vyberte Vlastnosti. Změňte akci Sestavení na "Content" a "Include in VSIX' vlastnost na true.

3. Implementujte ConfigurationSections a vraťte seznam předpon pro nastavení definovaná v souboru JSON (V editoru Visual Studio Code by se to mapovalo na název oddílu konfigurace v package.json):

   public IEnumerable<string> ConfigurationSections
   {
       get
       {
           yield return "foo";
       }
   }
   

4. Přidejte do projektu soubor .pkgdef (přidejte nový textový soubor a změňte příponu souboru na .pkgdef). Soubor pkgdef by měl obsahovat tyto informace:

   [$RootKey$\OpenFolder\Settings\VSWorkspaceSettings\[settings-name]]
   @="$PackageFolder$\[settings-file-name].json"
   

   Ukázka:

   [$RootKey$\OpenFolder\Settings\VSWorkspaceSettings\MockLanguageExtension]
   @="$PackageFolder$\MockLanguageExtensionSettings.json"
   

5. Klikněte pravým tlačítkem na soubor .pkgdef a vyberte Vlastnosti. Změňte akci Sestavení na Obsah a Zahrnout do VSIX vlastnost true.

6. Otevřete soubor source.extension.vsixmanifest a přidejte prostředek na kartě Asset :

   

   • Typ: Microsoft.VisualStudio.VsPackage
   • Zdroj: Soubor v systému souborů
   • Cesta: [Cesta k vašemu souboru .pkgdef ]

Úpravy nastavení pracovního prostoru uživatelem

1. Uživatel otevře pracovní prostor obsahující soubory, které vlastní váš server.

2. Uživatel přidá soubor do složky .vs s názvem VSWorkspace Nastavení.json.

3. Uživatel přidá řádek do souboru VSWorkspace Nastavení.json pro nastavení, které server poskytuje. Příklad:

   {
       "foo.maxNumberOfProblems": 10
   }
   

Povolení trasování diagnostiky

Trasování diagnostiky je možné povolit pro výstup všech zpráv mezi klientem a serverem, což může být užitečné při ladění problémů. Pokud chcete povolit trasování diagnostiky, postupujte takto:

1. Otevřete nebo vytvořte soubor nastavení pracovního prostoru VSWorkspace Nastavení.json (viz "Úpravy nastavení pro pracovní prostor uživatele").
2. Do souboru JSON nastavení přidejte následující řádek:

{
    "foo.trace.server": "Off"
}

Existují tři možné hodnoty pro úroveň podrobností trasování:

• "Vypnuto": trasování bylo zcela vypnuto.
• Zprávy: Trasování je zapnuté, ale trasování je sledováno pouze název metody a ID odpovědi.
• "Podrobné": trasování je zapnuté; Celá zpráva rpc je trasována.

Pokud je trasování zapnuté, obsah se zapíše do souboru v adresáři %temp%\VisualStudio\LSP . Protokol se řídí formátem pojmenování [LanguageClientName]-[Datetime Stamp].log. Trasování je v současné době možné povolit pouze pro scénáře s otevřenými složkami. Otevření jednoho souboru pro aktivaci jazykového serveru nemá podporu trasování diagnostiky.

Vlastní zprávy

Existují rozhraní API, která usnadňují předávání zpráv a přijímání zpráv ze serveru jazyka, které nejsou součástí standardního protokolu jazykového serveru. Pokud chcete zpracovávat vlastní zprávy, implementujte rozhraní ILanguageClientCustomMessage2 ve vaší třídě klienta jazyka. Knihovna VS-StreamJsonRpc slouží k přenosu vlastních zpráv mezi vaším jazykovým klientem a jazykovým serverem. Vzhledem k tomu, že rozšíření jazyka LSP je stejně jako jakékoli jiné rozšíření sady Visual Studio, můžete se rozhodnout přidat do sady Visual Studio další funkce (které LSP nepodporuje) (pomocí jiných rozhraní API sady Visual Studio) ve vašem rozšíření prostřednictvím vlastních zpráv.

Příjem vlastních zpráv

Pokud chcete přijímat vlastní zprávy z jazykového serveru, implementujte vlastnost [CustomMessageTarget]((/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage.custommessagetarget) v ILanguageClientCustomMessage2 a vraťte objekt, který ví, jak zpracovat vlastní zprávy. Příklad:

Vlastnost (/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage.custommessagetarget) v ILanguageClientCustomMessage2 a vrátí objekt, který ví, jak zpracovat vlastní zprávy. Příklad:

internal class MockCustomLanguageClient : MockLanguageClient, ILanguageClientCustomMessage2
{
    private JsonRpc customMessageRpc;

    public MockCustomLanguageClient() : base()
    {
        CustomMessageTarget = new CustomTarget();
    }

    public object CustomMessageTarget
    {
        get;
        set;
    }

    public class CustomTarget
    {
        public void OnCustomNotification(JToken arg)
        {
            // Provide logic on what happens OnCustomNotification is called from the language server
        }

        public string OnCustomRequest(string test)
        {
            // Provide logic on what happens OnCustomRequest is called from the language server
        }
    }
}

Odesílání vlastních zpráv

Pokud chcete odesílat vlastní zprávy na jazykový server, implementujte metodu AttachForCustomMessageAsync na ILanguageClientCustomMessage2. Tato metoda se vyvolá, když je váš jazykový server spuštěný a připravený přijímat zprávy. Objekt JsonRpc se předává jako parametr, který pak můžete zachovat k odesílání zpráv na jazykový server pomocí rozhraní API VS-StreamJsonRpc . Příklad:

internal class MockCustomLanguageClient : MockLanguageClient, ILanguageClientCustomMessage2
{
    private JsonRpc customMessageRpc;

    public MockCustomLanguageClient() : base()
    {
        CustomMessageTarget = new CustomTarget();
    }

    public async Task AttachForCustomMessageAsync(JsonRpc rpc)
    {
        await Task.Yield();

        this.customMessageRpc = rpc;
    }

    public async Task SendServerCustomNotification(object arg)
    {
        await this.customMessageRpc.NotifyWithParameterObjectAsync("OnCustomNotification", arg);
    }

    public async Task<string> SendServerCustomMessage(string test)
    {
        return await this.customMessageRpc.InvokeAsync<string>("OnCustomRequest", test);
    }
}

Střední vrstva

Vývojář rozšíření někdy může chtít zachytit zprávy LSP odeslané a přijaté ze serveru jazyků. Vývojář rozšíření může například chtít změnit parametr zprávy odeslaný pro konkrétní zprávu LSP nebo upravit výsledky vrácené z jazykového serveru pro funkci LSP (například dokončení). V případě potřeby můžou vývojáři rozšíření použít rozhraní API MiddleLayer k zachycení zpráv LSP.

Chcete-li zachytit konkrétní zprávu, vytvořte třídu, která implementuje ILanguageClientMiddleLayer rozhraní. Pak implementujte rozhraní ILanguageClientCustomMessage2 ve vaší třídě klienta jazyka a vraťte instanci objektu v MiddleLayer vlastnost. Příklad:

public class MockLanguageClient : ILanguageClient, ILanguageClientCustomMessage2
{
  public object MiddleLayer => DiagnosticsFilterMiddleLayer.Instance;

  private class DiagnosticsFilterMiddleLayer : ILanguageClientMiddleLayer
  {
    internal readonly static DiagnosticsFilterMiddleLayer Instance = new DiagnosticsFilterMiddleLayer();

    private DiagnosticsFilterMiddleLayer() { }

    public bool CanHandle(string methodName)
    {
      return methodName == "textDocument/publishDiagnostics";
    }

    public async Task HandleNotificationAsync(string methodName, JToken methodParam, Func<JToken, Task> sendNotification)
    {
      if (methodName == "textDocument/publishDiagnostics")
      {
        var diagnosticsToFilter = (JArray)methodParam["diagnostics"];
        // ony show diagnostics of severity 1 (error)
        methodParam["diagnostics"] = new JArray(diagnosticsToFilter.Where(diagnostic => diagnostic.Value<int?>("severity") == 1));

      }
      await sendNotification(methodParam);
    }

    public async Task<JToken> HandleRequestAsync(string methodName, JToken methodParam, Func<JToken, Task<JToken>> sendRequest)
    {
      return await sendRequest(methodParam);
    }
  }
}

Funkce střední vrstvy je stále ve vývoji a ještě není komplexní.

Ukázkové rozšíření jazykového serveru LSP

Pokud chcete zobrazit zdrojový kód ukázkového rozšíření pomocí klientského rozhraní API LSP v sadě Visual Studio, podívejte se na ukázku LSP VSSDK-Extensibility-Samples.

Často kladené dotazy

Chci vytvořit vlastní projektový systém, který doplní jazykový server LSP, aby poskytoval bohatší podporu funkcí v sadě Visual Studio, jak to mám udělat?

Podpora jazykových serverů založených na LSP v sadě Visual Studio spoléhá na funkci open folder a je navržená tak, aby nevyžaduje vlastní systém projektů. Vlastní systém projektů můžete vytvořit podle těchto pokynů, ale některé funkce, například nastavení, nemusí fungovat. Výchozí logikou inicializace pro jazykové servery LSP je předání umístění kořenové složky aktuálně otevřené složky, takže pokud používáte vlastní projektový systém, možná budete muset během inicializace zadat vlastní logiku, aby se zajistilo, že váš jazykový server může začít správně.

Návody přidat podporu ladicího programu?

V budoucí verzi budeme poskytovat podporu pro společný protokol ladění .

Pokud už je nainstalovaná jazyková služba podporovaná v sadě VS (například JavaScript), můžu stále nainstalovat rozšíření jazykového serveru LSP, které nabízí další funkce (například linting)?

Ano, ale ne všechny funkce budou správně fungovat. Konečným cílem rozšíření jazykových serverů LSP je povolit jazykové služby, které visual Studio nativně nepodporuje. Můžete vytvořit rozšíření, která nabízejí další podporu pomocí jazykových serverů LSP, ale některé funkce (například IntelliSense) nebudou bezproblémové. Obecně se doporučuje, aby se pro poskytování nových jazykových prostředí používala rozšíření jazyka LSP, a ne rozšíření stávajících jazykových serverů.

Kde publikuji dokončený jazykový server LSP VSIX?

Pokyny k Marketplace najdete tady.

Související obsah

• Přidání podpory editoru sady Visual Studio pro jiné jazyky

• Přizpůsobení chování editoru pomocí konfigurace jazyka