Ajouter une extension du protocole de serveur de langage

Le protocole Language Server Protocol (LSP) est un protocole commun, sous forme de JSON RPC v2.0, utilisé pour fournir des fonctionnalités de service de langage à divers éditeurs de code. En utilisant ce protocole, les développeurs peuvent écrire un seul serveur de langage pour fournir des fonctionnalités de service de langage telles que IntelliSense, les diagnostics d’erreur, la recherche de toutes les références, etc., à divers éditeurs de code prenant en charge le LSP. Traditionnellement, les services de langage dans Visual Studio peuvent être ajoutés en utilisant des fichiers de grammaire TextMate pour fournir des fonctionnalités de base telles que la coloration syntaxique ou en écrivant des services de langage personnalisés qui utilisent l’ensemble complet d’API d’extensibilité de Visual Studio pour fournir des données plus riches. Avec le support de Visual Studio pour le LSP, il existe une troisième option.

Pour garantir la meilleure expérience utilisateur possible, envisagez également de mettre en œuvre la configuration de la langue, qui permet un traitement local de nombreuses opérations similaires et peut donc améliorer les performances de nombreuses opérations d’édition spécifiques à la langue prises en charge par le LSP.

Protocole de serveur de langage

Cet article décrit comment créer une extension Visual Studio qui utilise un serveur de langage basé sur le LSP. Il part du principe que vous avez déjà développé un serveur de langage basé sur le LSP et que vous souhaitez simplement l’intégrer dans Visual Studio.

Pour prendre en charge dans Visual Studio, les serveurs de langage peuvent communiquer avec le client (Visual Studio) via n’importe quel mécanisme de transmission basé sur un flux, par exemple:

• Flux d’entrée/sortie standard
• Canaux nommés
• Sockets (TCP uniquement)

L’objectif du LSP et de son support dans Visual Studio est d’intégrer des services de langage qui ne font pas partie du produit Visual Studio. Il n’est pas destiné à étendre les services de langage existants (comme C#) dans Visual Studio. Pour étendre les langages existants, référez-vous au guide d’extensibilité du service de langage (par exemple, la plateforme de compilateur .NET « Roslyn ») ou consultez Étendre l’éditeur et les services de langage.

Pour plus d’informations sur le protocole lui-même, consultez la documentation se trouvant ici.

Pour plus d’informations sur la création d’un serveur de langage d’exemple ou sur l’intégration d’un serveur de langage existant dans Visual Studio Code, consultez la documentation se trouvant ici.

Fonctionnalités prises en charge par le protocole Language Server Protocol

Les tables suivantes montrent quelles fonctionnalités du LSP sont prises en charge dans Visual Studio :

Bien démarrer

Créer un projet VSIX

Pour créer une extension de service de langage en utilisant un serveur de langage basé sur LSP, assurez-vous d’avoir la charge de travail développement d’extensions pour Visual Studio installée pour votre instance de VS.

Ensuite, créez un nouveau projet VSIX en naviguant vers Fichier>Nouveau projet>Visual C#>Extensibilité>Projet VSIX :

Installation du serveur de langage et de l’exécutable

Par défaut, les extensions créées pour prendre en charge les serveurs de langage basés sur LSP dans Visual Studio ne contiennent pas les serveurs de langage eux-mêmes ni les exécutables nécessaires à leur exécution. Les développeurs d’extensions sont responsables de la distribution des serveurs de langage et des exécutables nécessaires. Il existe plusieurs façons de le faire :

• Les serveurs de langage peuvent être intégrés dans le VSIX en tant que fichiers de contenu.
• Créez un MSI pour installer le serveur de langage et/ou les exécutables nécessaires.
• Fournissez des instructions sur la Place de marché informant les utilisateurs sur la manière d’obtenir les exécutables et les serveurs de langage.

Fichiers de grammaire TextMate

Le LSP n’inclut pas de spécification sur la manière de fournir une coloration de texte pour les langages. Pour fournir une coloration personnalisée pour les langues dans Visual Studio, les développeurs d’extensions peuvent utiliser un fichier de grammaire TextMate. Pour ajouter des fichiers de grammaire TextMate personnalisés ou des fichiers de thème, suivez ces étapes :

1. Créez un dossier nommé « Grammaires » à l’intérieur de votre extension (ou cela peut être n’importe quel nom que vous choisissez).

2. À l’intérieur du dossier Grammaires, incluez tout fichier *.tmlanguage, *.plist, *.tmtheme, ou *.json que vous souhaitez qui fournisse une colorisation personnalisée.

   Conseil

   Un fichier .tmtheme définit comment les scopes se mappent aux classifications Visual Studio (clés de couleur nommées). Pour obtenir des conseils, vous pouvez vous référer au fichier global .tmtheme dans le répertoire %ProgramFiles(x86)%\Microsoft Visual Studio<version>/<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg.

3. Créez un fichier .pkgdef et ajoutez une ligne similaire à celle-ci :

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

4. Faites un clic droit sur les fichiers et sélectionnez Propriétés. Changez l’action de Build en Contenu et changez la propriété Inclure dans le VSIX en true.

Après avoir effectué les étapes précédentes, un dossier Grammaires est ajouté au répertoire d’installation du package en tant que source de référentiel nommée « MyLang » (« MyLang » est juste un nom pour la désambiguïsation et peut être une chaîne unique quelconque). Toutes les grammaires (.tmlanguage fichiers) et les fichiers de thème (.tmtheme fichiers) dans ce répertoire sont récupérés comme des potentiels et ils supplantent les grammaires intégrées fournies avec TextMate. Si les extensions déclarées du fichier de grammaire correspondent à l’extension du fichier ouvert, TextMate interviendra.

Créez un client de langage simple

Interface principale - ILanguageClient

Après avoir créé votre projet VSIX, ajoutez le(s) paquet(s) NuGet suivant(s) à votre projet :

• Microsoft.VisualStudio.LanguageServer.Client

Vous pouvez ensuite créer une nouvelle classe qui implémente l’interface ILanguageClient, qui est l’interface principale nécessaire pour les clients de langage se connectant à un serveur de langage basé sur LSP.

Voici un exemple :

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;
        }
    }
}

Les principales méthodes qui doivent être implémentées sont OnLoadedAsync et ActivateAsync. OnLoadedAsync est appelée lorsque Visual Studio a chargé votre extension et que votre serveur de langage est prêt à démarrer. Dans cette méthode, vous pouvez invoquer immédiatement le délégué StartAsync pour signaler que le serveur de langage doit être démarré, ou vous pouvez effectuer une logique supplémentaire et invoquer StartAsync plus tard. Pour activer votre serveur de langage, vous devez appeler StartAsync à un moment donné.

ActivateAsync est la méthode finalement invoquée en appelant le délégué StartAsync. Il contient la logique pour démarrer le serveur de langage et établir une connexion avec lui. Un objet de connexion contenant des flux pour écrire vers le serveur et lire à partir du serveur doit être renvoyé. Toutes les exceptions levées ici sont capturées et affichées à l’utilisateur via un message InfoBar dans Visual Studio.

Activation

Une fois que votre classe de client de langage est implémentée, vous devrez définir deux attributs pour elle afin de définir comment elle sera chargée dans Visual Studio et activée :

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

MEF

Visual Studio utilise MEF (Managed Extensibility Framework) pour gérer ses points d’extensibilité. L’attribut Export indique à Visual Studio que cette classe doit être récupérée en tant que point d’extension et chargée au moment approprié.

Pour utiliser MEF, vous devez également définir MEF comme un actif dans le manifeste VSIX.

Ouvrez le concepteur du manifeste VSIX et accédez à l’onglet Actifs :

Cliquez sur Nouveau pour créer un nouvel actif :

• Type : Microsoft.VisualStudio.MefComponent
• Source : Un projet dans la solution actuelle
• Projet : [Votre projet]

Définition du type de contenu

Actuellement, la seule façon de charger votre extension de serveur de langage basé sur LSP est par type de contenu de fichier. C’est-à-dire que lors de la définition de votre classe de client de langage (qui implémente ILanguageClient), vous devrez définir les types de fichiers qui, lorsqu’ils sont ouverts, provoqueront le chargement de votre extension. Si aucun fichier correspondant à votre type de contenu défini n’est ouvert, alors votre extension ne sera pas chargée.

Cela se fait en définissant une ou plusieurs ContentTypeDefinition classes :

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

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

Dans l’exemple précédent, une définition de type de contenu est créée pour les fichiers se terminant par l’extension de fichier .bar. La définition de type de contenu est donnée le nom "bar" et doit dériver de CodeRemoteContentTypeName.

Après avoir ajouté une définition de type de contenu, vous pouvez ensuite définir quand charger votre extension de client de langage dans la classe de client de langage :

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

Ajout de la prise en charge des serveurs de langage LSP ne nécessite pas d’implémenter votre propre système de projet dans Visual Studio. Les clients peuvent ouvrir un seul fichier ou un dossier dans Visual Studio pour commencer à utiliser votre service de langage. En fait, la prise en charge des serveurs de langage LSP est conçue pour fonctionner uniquement dans les scénarios de fichier/dossier ouverts. Si un système de projet personnalisé est implémenté, certaines fonctionnalités (comme les paramètres) ne fonctionneront pas.

Fonctionnalités avancées

Paramètres

La prise en charge des paramètres spécifiques au serveur de langage personnalisé est disponible, mais elle est encore en cours d’amélioration. Les paramètres sont spécifiques à ce que le serveur de langage prend en charge et contrôlent généralement la manière dont le serveur de langage émet des données. Par exemple, un serveur de langage peut avoir un paramètre pour le nombre maximal d’erreurs signalées. Les auteurs d’extensions définiraient une valeur par défaut, qui peut être modifiée par les utilisateurs pour des projets spécifiques.

Suivez les étapes ci-dessous pour ajouter la prise en charge des paramètres à votre extension de service de langage LSP :

1. Ajoutez un fichier JSON (par exemple, MockLanguageExtensionSettings.json) à votre projet qui contient les paramètres et leurs valeurs par défaut. Par exemple :

   {
       "foo.maxNumberOfProblems": -1
   }
   

2. Faites un clic droit sur le fichier JSON et sélectionnez Propriétés. Changez l’action de Build en « Content » et la propriété « Include in VSIX » en true.

3. Implémentez ConfigurationSections et retournez la liste des préfixes pour les paramètres définis dans le fichier JSON (Dans Visual Studio Code, cela correspondrait au nom de section de configuration dans package.json) :

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

4. Ajoutez un fichier .pkgdef au projet (ajoutez un nouveau fichier texte et changez l’extension de fichier en .pkgdef). Le fichier pkgdef devrait contenir ces informations :

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

   Exemple :

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

5. Faites un clic droit sur le fichier .pkgdef et sélectionnez Propriétés. Changez l’action de Build en Content et la propriété Include in VSIX en true.

6. Ouvrez le fichier source.extension.vsixmanifest et ajoutez un actif dans l’onglet Actif :

   

   • Type: Microsoft.VisualStudio.VsPackage
   • Source : Fichier sur le système de fichiers
   • Chemin : [Chemin vers votre fichier .pkgdef]

Modification des paramètres par l’utilisateur pour un espace de travail

1. L’utilisateur ouvre un espace de travail contenant des fichiers que votre serveur possède.

2. L’utilisateur ajoute un fichier dans le dossier .vs appelé VSWorkspaceSettings.json.

3. L’utilisateur ajoute une ligne au fichier VSWorkspaceSettings.json pour un paramètre fourni par le serveur. Par exemple :

   {
       "foo.maxNumberOfProblems": 10
   }
   

Activation de la trace des diagnostics

La trace des diagnostics peut être activée pour produire toutes les messages entre le client et le serveur, ce qui peut être utile lors du débogage des problèmes. Pour activer le suivi des diagnostics, suivez la procédure ci-dessous :

1. Ouvrez ou créez le fichier de paramètres de l’espace de travail VSWorkspaceSettings.json (voir « Modification des paramètres par l’utilisateur pour un espace de travail »).
2. Ajoutez la ligne suivante dans le fichier json de paramètres :

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

Il existe trois valeurs possibles pour la verbosité de la trace :

• «Off » : la trace est complètement désactivée.
• « Messages » : la trace est activée mais seuls le nom de la méthode et l’identifiant de la réponse sont tracés.
• « Verbose » : la trace est activée ; le message rpc complet est tracé.

Lorsque la trace est activée, le contenu est écrit dans un fichier du répertoire %temp%\VisualStudio\LSP. Le journal suit le format de nommage [NomDuClientDeLangage]-[Horodatage].log. Actuellement, la trace ne peut être activée que pour les scénarios de dossier ouvert. L’ouverture d’un seul fichier pour activer un serveur de langage n’a pas de prise en charge de la trace des diagnostics.

Messages personnalisés

Il existe des API pour faciliter le passage des messages vers et depuis le serveur de langage qui ne font pas partie du protocole standard du serveur de langage. Pour gérer les messages personnalisés, implémentez l’interface ILanguageClientCustomMessage2 dans votre classe de client de langage. La bibliothèque VS-StreamJsonRpc est utilisée pour transmettre des messages personnalisés entre votre client de langage et votre serveur de langage. Étant donné que votre extension de client de langage LSP est comme n’importe quelle autre extension de Visual Studio, vous pouvez décider d’ajouter des fonctionnalités supplémentaires (qui ne sont pas prises en charge par le LSP) à Visual Studio (en utilisant d’autres API de Visual Studio) dans votre extension grâce à des messages personnalisés.

Recevoir des messages personnalisés

Pour recevoir des messages personnalisés du serveur de langage, implémentez la propriété [CustomMessageTarget]((/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage.custommessagetarget) sur ILanguageClientCustomMessage2 et renvoyez un objet qui sait comment gérer vos messages personnalisés. Voici un exemple ci-dessous :

(/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage.custommessagetarget) sur ILanguageClientCustomMessage2 et renvoyez un objet qui sait comment gérer vos messages personnalisés. Voici un exemple ci-dessous :

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
        }
    }
}

Envoyer des messages personnalisés

Pour envoyer des messages personnalisés au serveur de langage, implémentez la méthode AttachForCustomMessageAsync sur ILanguageClientCustomMessage2. Cette méthode est invoquée lorsque votre serveur de langage est démarré et prêt à recevoir des messages. Un objet JsonRpc est passé en tant que paramètre, que vous pouvez ensuite conserver pour envoyer des messages au serveur de langage en utilisant les API de VS-StreamJsonRpc. Voici un exemple ci-dessous :

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);
    }
}

Couche intermédiaire

Parfois, un développeur d’extension peut vouloir intercepter les messages LSP envoyés et reçus du serveur de langage. Par exemple, un développeur d’extension peut vouloir modifier le paramètre de message envoyé pour un message LSP particulier, ou modifier les résultats renvoyés par le serveur de langage pour une fonctionnalité LSP (par exemple les complétions). Lorsque cela est nécessaire, les développeurs d’extension peuvent utiliser l’API MiddleLayer pour intercepter les messages LSP.

Pour intercepter un message particulier, créez une classe qui implémente l’interface ILanguageClientMiddleLayer. Ensuite, implémentez l’interface ILanguageClientCustomMessage2 dans votre classe de client de langage et renvoyez une instance de votre objet dans la propriété MiddleLayer. Voici un exemple ci-dessous :

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);
    }
  }
}

La fonctionnalité de la couche intermédiaire est encore en cours de développement et n’est pas encore exhaustive.

Extension de serveur de langage LSP d’exemple

Pour voir le code source d’une extension d’exemple utilisant l’API client LSP dans Visual Studio, veuillez consulter l’échantillon LSP de VSSDK-Extensibility-Samples.

FAQ

Je voudrais créer un système de projet personnalisé pour compléter mon serveur de langage LSP afin de fournir un support de fonctionnalités plus riche dans Visual Studio, comment puis-je procéder ?

La prise en charge des serveurs de langage basés sur LSP dans Visual Studio repose sur la fonctionnalité de dossier ouvert et est conçue pour ne pas nécessiter de système de projet personnalisé. Vous pouvez créer votre propre système de projet personnalisé en suivant les instructions se trouvant ici, mais certaines fonctionnalités, telles que les paramètres, peuvent ne pas fonctionner. La logique d’initialisation par défaut des serveurs de langage LSP consiste à transmettre l’emplacement du dossier racine du dossier actuellement ouvert, donc si vous utilisez un système de projet personnalisé, vous devrez peut-être fournir une logique personnalisée lors de l’initialisation pour garantir que votre serveur de langage peut démarrer correctement.

Comment ajouter la prise en charge du débogueur ?

Nous fournirons une prise en charge du protocole de débogage commun dans une future version.

Si un service de langage pris en charge par VS est déjà installé (par exemple, JavaScript), puis-je toujours installer une extension de serveur de langage LSP qui offre des fonctionnalités supplémentaires (comme le linting) ?

Oui, mais toutes les fonctionnalités ne fonctionneront pas correctement. L’objectif ultime des extensions de serveur de langage LSP est de permettre les services de langage non pris en charge nativement par Visual Studio. Vous pouvez créer des extensions qui offrent un support supplémentaire en utilisant des serveurs de langage LSP, mais certaines fonctionnalités (telles que IntelliSense) ne seront pas une expérience fluide. En général, il est conseillé d’utiliser les extensions de serveur de langage LSP pour fournir de nouvelles expériences linguistiques, plutôt que d’étendre les existantes.

Où puis-je publier mon VSIX de serveur de langage LSP terminé ?

Consultez les instructions du Marketplace ici.

Contenu connexe

• Ajouter la prise en charge de l’éditeur Visual Studio pour d’autres langages

• Personnalisation du comportement de l’éditeur en utilisant la Configuration de langage