Language Server Extensions Handbook (2023)

As you saw inFeatures of the programming languagesubject, it is possible to implement language functions by direct usetalen.*API. However, the Language Server extension provides an alternative way to implement such language support.

Subjects:

• Explains the benefits of extending the language server.
• It guides you through the process of building a language server usingmicrosoft/vscode-language-server-nodelibrary. You can also go directly to the code inlsp example.

Why one language server?

A language server is a special type of Visual Studio Code extension that allows editing in many programming languages. Language servers allow you to implement auto-completion, error checking (diagnosis), jumping to definitions, and morelinguistic featuressupported in VS Code.

However, when implementing support for language features in VS Code, we found three common problems:

First, language servers are usually implemented in their own programming languages, which makes it challenging to integrate with VS Code that has a Node.js runtime.

Additionally, language features can be quite resource intensive. For example, to properly validate a file, the language server must parse a large number of files, build abstract syntax trees for them, and perform static program analysis. These operations can be CPU and memory intensive, so we need to make sure that VS code performance is intact.

Finally, integrating multiple language tools with multiple code editors can require significant effort. From a language tools perspective, they need to adapt to code editors with different APIs. From the perspective of code editors, they cannot expect a unified API from language tools. This allows implementation of language support forMLanguagesNcode editor workM*N.

To solve these problems, Microsoft gave upLanguage Server Protocol, which standardizes communication between language tools and code editors. In this way, language servers can be implemented in any language and run in their own process to avoid additional overhead when communicating with the code editor via the language server protocol. In addition, all LSP-compatible language tools integrate with many LSP-compatible code editors, and all LSP-compatible code editors can easily use many LSP-compatible language tools. LSP is a win-win for both language tool providers and code editor providers!

In this guide:

• Explain how to create a language server extension in VS Code using the attached fileNode SDK.
• Explain how to run, debug, register, and test a language server extension.
• List some advanced topics on language servers.

Language server implementation

Review

In VS Code, the language server consists of two parts:

• Language Client: A regular VS Code extension written in JavaScript/TypeScript. This extension has access to everyoneVS Code namespace API.
• Language Server: A language analysis tool that runs in a separate process.

As briefly mentioned above, there are two advantages to running the language server in a separate process:

• The analysis tool can be implemented in any language as long as it can communicate with the language client according to the language server protocol.
• Because language parsing tools are often CPU and memory intensive, running them in a separate process avoids performance overhead.

Here is an illustration from VS Code with two server language extensions. The HTML client and PHP client are regular VS Code extensions written in TypeScript. Each of them creates a corresponding language server and communicates with it via LSP. Although the PHP server is written in PHP, it can still communicate with the PHP client via LSP.

This tutorial will teach you how to build a language client/server using ourNode SDK. The rest of the document assumes you know VS codeExtension-API.

LSP example - a simple language server for plain text files

Let's make a simple language server extension that implements auto-completion and diagnostics for plain text files. We will also discuss configuration synchronization between the client and the server.

If you prefer to go directly to the code:

• lsp example: Richly documented source code for this guide.
• lsp-pattern-many-servers: A heavily documented advanced versionlsp examplewhich starts a second server instance per workspace map for maintenancemulti-root workspacefunction in VS code.

Clone the repositoryMicrosoft/vscode extension examplesand open the example:

> clone git https://github.com/microsoft/vscode-extension-samples.git>CDvscode-extension-samples/lsp-uzorak> install npm> npm run-build> the code.

The above installs all dependencies and opens the filelsp exampleworkspace with client and server code. Here is a rough outline of the structurelsp example:

.├── client // Language client│ ├── src│ │ ├── test // Comprehensive tests for Language client / server│ │ └── extension.ts // Language client entry point├── package. json // Extension manifest └── server // Language server └── src └── server.ts // Language server entry point

Explanation of "Language Client".

Let's see first/pakiet.jsonwhich describes the capabilities of the language client. There are two interesting sections:

Look firstconfigurationSection:

"configuration": { "tip":"object", "title":"Sample Configuration", "assets": { „languageServerExample.maxNumberOfProblems”: { "reach":"blush", "tip":"number", "standard":100, "description":"Controls the largest number of server-generated problems."}}}

This section contributesconfigurationsettings for VS code. The example explains how these settings are sent to the language server at startup and when the settings are changed.

Remark: If your extension is compatible with VS Code versions older than 1.74.0, you must check thisonLanguage: clear textwactivation eventsSometimes/pakiet.jsontell VS Code to activate the extension as soon as a plain text file is opened (for example, a file with a.text):

"Activation Events": []

The actual source code of the language client and associatedpacked.jsonare in/Clientfile. Interesting piece inside/client/pakket.jsonthe file it points toeverywhere, everywhereextension of host-API viamotorfield and adds a dependency to the filevscode-taalclientlibrary:

"motor": { „vscode”:„^ 1,52,0”},"addiction": { "vscode-taalclient":„^7.0.0”}

As mentioned, the client is implemented as a regular VS Code extension and has access to all VS Code namespace APIs.

Below is the content of the corresponding extension.ts file, which is the file entrylsp exampleextension:

import * How pad z 'substrate';import{field,Extension context}z „vscode”;import{ LanguageClient, LanguageClientOptions, Server Options, Type of transport}z „vscode-taalclient/čvor”;allow Client:LanguageClient;export function Activate(context:Extension context) { // The server is implemented in the node allow server module=context.as an absolute path(pad.taking part('server','vani',"server.js")); // Server debugging options // --inspect=6009: Start the server in Node Inspector mode to allow VS Code to connect to the server for debugging allow debugging capabilities= {execArgv:['--his','--inspection=6009']}; // If the extension is running in debug mode, the debug server options are used // Otherwise the boot options are used allow Server Options:Server Options= { start:{module: server module,transport: Type of transport.ipc}, debug:{ module: server module, transport: Type of transport.ipc, options: debugging capabilities}}; // Language client control options allow customer options:LanguageClientOptions= { // Register the text document server Documentkiezer:[{diagram: 'duration',Tong: "plain text"}], synchronization:{ // Notify the server about changes to the ".clientrc" files in the workspace event file: field.Create a file system watcher('**/.clientrc')}}; // Create the language client and start the client. Client=novi LanguageClient( "languageServerExample", "Language server example", Server Options, customer options); // Starting the client. This will also start the server Client.start();}export function deactivate():That is possible<vacuum> |indefinite{ I(!Client) { yield indefinite;} yield Client.Stop();}

Explanation of "Language server"

Remark:The "Server" implementation cloned from the GitHub repository has the final tutorial implementation. To follow the instructions, you can create a new oneserver.tsor change the content of the cloned version.

In the example, the server is also implemented in TypeScript and works with Node.js. Since VS Code already ships with the Node.js runtime, you don't need to ship your own version unless you have specific runtime requirements.

The language server source code can be found at/server. Interesting part on the serverpacked.jsonthe file is:

"addiction": { "vscode language server":„^7.0.0”, "vscode-language-server-textdocument":"^1.0.1"}

It's bullshitvscode language serverlibraries.

Below is a server implementation that uses the included text document manager that synchronizes text documents, always sending incremental differences from the VS code to the server.

import{ make a connection, Text documents, Diagnostic, Diagnostic validity, Suggested features, Initialize the parameters, DidChangeConfigurationNotification, Rounding off the article, Type of completion item, TextDocumentPositionParams, A text document of the synchronization type, Initialize the result}z "vscode-languageserver/čvor";import{text document}z 'vscode-taalserver-textdocument';// Connect to the server using the node's IPC as the transport.// Also includes all preview/proposed LSP functions.allow connection=make a connection(Suggested features.already);// Create a simple text document manager.allow documents:Text documents<text document> =novi Text documents(text document);allow has configuration options:logically=LIE;allow heeftWorkspaceFolderCapability:logically=LIE;allow maDiagnosticRelatedInformationCapability:logically=LIE;connection.click Initialize((parameters:Initialize the parameters)=>{ allow possibilities=parameters.possibilities; // Does the client support the `workspace/configuration` request? // If not, we revert to the global settings. has configuration options= !!( possibilities.field&&!!possibilities.field.configuration); heeftWorkspaceFolderCapability= !!( possibilities.field&&!!possibilities.field.Workspace maps); maDiagnosticRelatedInformationCapability= !!( possibilities.text document&& possibilities.text document.postDiagnose&& possibilities.text document.postDiagnose.related information); art result:Initialize the result= { options:{ tekstDocumentSync: A text document of the synchronization type.Increasing, // Tell the client that this server supports code completion. completion Supplier:{ resolve vendor: WHERE}}}; I(heeftWorkspaceFolderCapability) { result.possibilities.field= { workspace folders:{ maintain: WHERE}};} yield result;});connection.uninitialized(()=>{ I(has configuration options) { // Register for all configuration changes. connection.Client.Register(DidChangeConfigurationNotification.tip,indefinite);} I(heeftWorkspaceFolderCapability) { connection.field.onDidChangeWorkspaceFoldery(_an event =>{ connection.console.log("Received workspace map change event.");});}});// View settingskoppel Example settings{ maxNumberIssues:number;}// General settings used when the `workspace/configuration` request is not supported by the client.// Note that this is not the case when using this server with the client in this example// but this can happen with other clients.art Standard items:Example settings= {maximum number of problems: 1000};allow General settings:Example settings=Standard items;// Settings cache of all open documentsallow document items:Card<series,That is possible<Example settings>> =novi Card();connection.onDidChangeConfiguration(To change =>{ I(has configuration options) { // Clear all cached document settings document items.clear();}Anders{ General settings= <Example settings>((To change.institution.languageServerExample||Standard items));} // Recheck all open text documents documents.already().for everyone(Confirm the text document);});function getDocumentSettings(blush:series):That is possible<Example settings> { I(!has configuration options) { yield Promise.arrange(General settings);} allow result=document items.get(blush); I(!result) { result=connection.field.getConfiguration({ achieves: blush, Section: "languageServerExample"}); document items.set(blush,result);} yield result;}// Keep settings for open documents onlydocuments.detention(mi =>{ document items.delete(mi.document.vas);});// The content of the text document has been changed. This event is being broadcast// when the text document is first opened or its contents changed.documents.opDidChangeContent(To change =>{ Confirm the text document(To change.document);});asynchronous function Confirm the text document(text document:text document):Promise<vacuum> { // In this simple example, we get the settings for each validation run. allow institution=to wait getDocumentSettings(text document.vas); // The validator performs diagnostics for all capitalized words of length 2 and more allow text=text document.downloadText(); allow insert=/\B[A-Z]{2,}\B/G; allow M:RegExpExecArray|nula; allow questions=0; allow diagnostic:Diagnostic[] = []; one second((M=insert.performer(text)) &&questions<institution.maxNumberIssues) { questions++; allow diagnostic:Diagnostic= { Ernst: Diagnostic validity.Warning, reach:{ start: text document.positieAt(M.Content), end: text document.positieAt(M.Content+M[0].lenght)}, message: `${M[0]}is written in capital letters.`, bron: 'were'}; I(maDiagnosticRelatedInformationCapability) { diagnostic.related information= [{ Place:{ Address: text document.vas, reach: Object.assign({},diagnostic.reach)}, message: "Spelling is important"},{ Place:{ Address: text document.vas, reach: Object.assign({},diagnostic.reach)}, message: "Especially for Namur"}];} diagnostic.Press(diagnostic);} // Send the calculated diagnostics to VS Code. connection.send diagnostics({Address: text document.vas,diagnostic});}connection.opDidChangeWatchedFiles(_To change =>{ // Watched files are changed to VS code connection.console.log("We received a file change event");});// This handler returns the initial list of completed items.connection.already((_textDocumentPosition:TextDocumentPositionParams):Rounding off the article[]=>{ // The pass parameter contains the position of the text document w // which code is complete as requested. For example, we ignore it // info and always have the same additional items. yield[{ ticket: 'Typscript', Decent: Type of completion item.Text, deen: 1},{ ticket: „JavaScript”, Decent: Type of completion item.Text, deen: 2}];});// This handler resolves additional information for the selected item// completion list.connection.onCompletionResolve((article:Rounding off the article):Rounding off the article =>{ I(article.deen===1) { article.Detail="TypeScript Details"; article.documentation="TypeScript Documentation";}Anders I(article.deen===2) { article.Detail="JavaScript-Details"; article.documentation="JavaScript Documentation";} yield article;});// Make the text document manager listen for a connection// for opening, modifying and closing text documentsdocuments.Listen(connection);// Listen onlineconnection.Listen();

Add simple validation

To add document validation to the server, we add a listener to the text document manager that is called when the content of the text document changes. The server then decides when it is best to validate the document. In the example implementation, the server validates the plain text document and selects all words that use CAPITAL LETTERS. The relevant code snippet looks like this:

// The content of the text document has been changed. This event is being broadcast// when the text document is first opened or its contents changed.documents.opDidChangeContent(asynchronous To change =>{ allow text document=To change.document; // In this simple example, we get the settings for each validation run. allow institution=to wait getDocumentSettings(text document.vas); // The validator performs diagnostics for all capitalized words of length 2 and more allow text=text document.downloadText(); allow insert=/\B[A-Z]{2,}\B/G; allow M:RegExpExecArray|nula; allow questions=0; allow diagnostic:Diagnostic[] = []; one second((M=insert.performer(text)) &&questions<institution.maxNumberIssues) { questions++; allow diagnostic:Diagnostic= { Ernst: Diagnostic validity.Warning, reach:{ start: text document.positieAt(M.Content), end: text document.positieAt(M.Content+M[0].lenght)}, message: `${M[0]}is written in capital letters.`, bron: 'were'}; I(maDiagnosticRelatedInformationCapability) { diagnostic.related information= [{ Place:{ Address: text document.vas, reach: Object.assign({},diagnostic.reach)}, message: "Spelling is important"},{ Place:{ Address: text document.vas, reach: Object.assign({},diagnostic.reach)}, message: "Especially for Namur"}];} diagnostic.Press(diagnostic);} // Send the calculated diagnostics to VS Code. connection.send diagnostics({Address: text document.vas,diagnostic});});

Diagnostic tips and tricks

• If the start and end positions are the same, VS Code will underline the word at that position.
• To wrap the underscore to the end of the line, set the end position character to Number.MAX_VALUE.

Follow these steps to start the language server:

• Press⇧⌘B(Windows, LinuxCtrl+Shift+B)to start construction. The job builds both the client and the server.
• openStartview, selectionStart the clientrun the setting and pressStart debuggingbutton to perform additionalExtension development hostinstance of VS code that executes the extension code.
• to createtest.txtfile in the root folder and paste the following content:

TypeScript lets you write JavaScript the way you want. TypeScript is a typed superset of JavaScript that can be translated into plain JavaScript. ANY browser. ANY host. ANY operating system. open source.

FromExtension development hostthe instance will then look like this:

Debugging both client and server

Debugging client code is as easy as debugging a regular extension. Set a breakpoint in the client code and debug the extension by pressingF5.

Since the server leadsLanguageClientrunning in the extension (client), we need to attach the debugger to the running server. Go to for thisRun and debugview and select a startup configurationJoin the serverand pressF5. This will connect the debugger to the server.

Language server login support

If you usevscode-taalclientfor a client implementation, you can specify a setting[langId].tracking.serverwhich directs the client to record language client/server communication on the language client channelTo do.

Forlsp example, you can set this setting:"languageServerExample.trace.server": "pełny". Now go to the "Language Server Example" channel. You should see the logs:

Use the configuration settings on the server

When writing the client part of the extension, we already defined a setting that controls the highest number of reported problems. We also wrote server-side code to read these settings from the client:

function getDocumentSettings(blush:series):That is possible<Example settings> { I(!has configuration options) { yield Promise.arrange(General settings);} allow result=document items.get(blush); I(!result) { result=connection.field.getConfiguration({ achieves: blush, Section: "languageServerExample"}); document items.set(blush,result);} yield result;}

All we need to do now is listen for server-side configuration changes and, if the setting changes, reauthenticate the open text documents. To reuse the validation logic to handle the document change event, we extract the code to a fileConfirm the text documentfunction and change the code to amaxNumberIssueschangeable:

asynchronous function Confirm the text document(text document:text document):Promise<vacuum> { // In this simple example, we get the settings for each validation run. allow institution=to wait getDocumentSettings(text document.vas); // The validator performs diagnostics for all capitalized words of length 2 and more allow text=text document.downloadText(); allow insert=/\B[A-Z]{2,}\B/G; allow M:RegExpExecArray|nula; allow questions=0; allow diagnostic:Diagnostic[] = []; one second((M=insert.performer(text)) &&questions<institution.maxNumberIssues) { questions++; allow diagnostic:Diagnostic= { Ernst: Diagnostic validity.Warning, reach:{ start: text document.positieAt(M.Content), end: text document.positieAt(M.Content+M[0].lenght)}, message: `${M[0]}is written in capital letters.`, bron: 'were'}; I(maDiagnosticRelatedInformationCapability) { diagnostic.related information= [{ Place:{ Address: text document.vas, reach: Object.assign({},diagnostic.reach)}, message: "Spelling is important"},{ Place:{ Address: text document.vas, reach: Object.assign({},diagnostic.reach)}, message: "Especially for Namur"}];} diagnostic.Press(diagnostic);} // Send the calculated diagnostics to VS Code. connection.send diagnostics({Address: text document.vas,diagnostic});}

Configuration change handling is done by adding a configuration change notification handler to the connection. The relevant code looks like this:

connection.onDidChangeConfiguration(To change =>{ I(has configuration options) { // Clear all cached document settings document items.clear();}Anders{ General settings= <Example settings>((To change.institution.languageServerExample||Standard items));} // Recheck all open text documents documents.already().for everyone(Confirm the text document);});

Restarting the client and changing the setting to maximum report 1 problem results in the following check:

Add additional language features

The first interesting feature that a language server usually implements is document validation. In this sense, even a linter counts as a language server, and in VS Code linters are usually implemented as language servers (seeeslintandjshintfor example). But language servers are more than that. They can enable code completion, find all references, or jump to definitions. The following code example adds code completion to the server. It suggests two words "TypeScript" and "JavaScript".

// This handler returns the initial list of completed items.connection.already((_textDocumentPosition:TextDocumentPositionParams):Rounding off the article[]=>{ // The pass parameter contains the position of the text document w // which code is complete as requested. For example, we ignore it // info and always have the same additional items. yield[{ ticket: 'Typscript', Decent: Type of completion item.Text, deen: 1},{ ticket: „JavaScript”, Decent: Type of completion item.Text, deen: 2}];});// This handler resolves additional information for the selected item// completion list.connection.onCompletionResolve((article:Rounding off the article):Rounding off the article =>{ I(article.deen===1) { article.Detail="TypeScript Details"; article.documentation="TypeScript Documentation";}Anders I(article.deen===2) { article.Detail="JavaScript-Details"; article.documentation="JavaScript Documentation";} yield article;});

Fromdeenfields are used to uniquely identify the completion element in the solution handler. The data property is transparent to the protocol. Since the underlying messaging protocol is based on JSON, the data field should only contain data that can be serialized to and from JSON.

The only thing missing is telling VS Code that the server is handling code completion requests. To do this, check the corresponding option in the initialization handler:

connection.click Initialize((parameters):Initialize the result =>{... yield{ options:{... // Tell the client that the server supports code completion termination provider: { resolve vendor: WHERE}}};});

The screenshot below shows the finished code running in a plain text file:

Language server testing

To create a high-quality language server, we need to build a proper test suite that covers its features. There are two common ways to test language servers:

• Unit Test: This is useful if you want to test certain features on the language servers by simulating all the information being sent to them. VS codesHTML/CSS/JSONLanguage servers use this approach to testing. The npm LSP modules also use this approach. SeeHerefor some unit tests written using the npm protocol module.
• Extensive test: It is similarVS Code Extensie Test. The advantage of this approach is that the test is run by creating an instance of VS Code with a workspace, opening the file, activating the language client/server, andVS code commands. This approach is better if you have files, settings, or dependencies (such asnode_modules) which is difficult or impossible to mock. PopularPythonextension follows this testing approach.

It is possible to run a unit test in any testing framework of your choice. Here we describe how to perform extensive testing of language server extensions.

open.vscode/launch.json, and can be foundE2Eexam objective:

{ "to do":"E2E server language test", "tip":"host extension", "Application":"start", "executable file":"${execPath}", "arguments": [ "--extensionDevelopmentPath=${workspaceRoot}", "--extensionTestsPath=${workspaceRoot}/client/out/test/index", "${workspaceRoot}/client/testFixture"], "output files": ["${workspaceRoot}/client/out/test/**/*.js"]}

Running this debug target will launch an instance of VS Code fromclient/test deviceas an active workspace. VS Code will then continue to run all testsclient/source/test. As a debugging tip, you can set breakpoints in typescript filesclient/source/testand they will be affected.

Let's seecompletion.test.tsduration:

import * How everywhere, everywhere z „vscode”;import * How under condition z 'under condition';import{download DocUri,Activate}z './aide';set("need to finish", ()=>{ art a horse=download DocUri("completed.txt"); test("JS/TS ends in txt file",asynchronous()=>{ to wait End of trial(a horse,novi everywhere, everywhere.Position(0,0), { things:[{ticket: „JavaScript”,Decent: everywhere, everywhere.Type of completion item.Text},{ticket: 'Typscript',Decent: everywhere, everywhere.Type of completion item.Text}]});});});asynchronous function End of trial( a horse:everywhere, everywhere.Uri, position:everywhere, everywhere.Position, list of expected completion:everywhere, everywhere.Completion list) { to wait Activate(a horse); // Run `vscode.executeCompletionItemProvider` to simulate trigger completion art the actual list of endings= (to wait everywhere, everywhere.commandos.execute the command( "vscode.executeCompletionItemProvider", a horse, position))How everywhere, everywhere.Completion list; under condition.Alright(the actual list of endings.things.lenght>=2); list of expected completion.things.for everyone((expected item,and)=>{ art Actually=the actual list of endings.things[and]; under condition.equivalent(Actually.ticket,expected item.ticket); under condition.equivalent(Actually.Decent,expected item.Decent);});}

In this test:

• Activate the extension.
• Run the commandvscode.executeCompletionItemProviderwith the URI and position to simulate the interrupt trigger.
• Confirm returned shipping items with our expected shipping items.

Let's dive a little deeper into itactivation (docURI)function. It is stated inclient/source/test/helper.ts:

import * How everywhere, everywhere z „vscode”;import * How pad z 'substrate';export allow of art:everywhere, everywhere.text document;export allow editor:everywhere, everywhere.text editor;export allow documentEol:series;export allow platformaEol:series;/*** Activates the vscode.lsp sample extension*/export asynchronous function Activate(a horse:everywhere, everywhere.Uri) { // Extension ID is `name.publisher` from package.json file art int=everywhere, everywhere.extensions.download the extension('vscode-examples.lsp-przyklad')!; to wait int.Activate(); to attempt{ of art=to wait everywhere, everywhere.field.open a text document(a horse); editor=to wait everywhere, everywhere.window.display text document(of art); to wait sleep(in 2000);// Wait for server activation}to catch(mi) { console.wrong(mi);}}asynchronous function sleep(SM:number) { yield novi Promise(arrange => Set a time limit(arrange,SM));}

In the activation section:

• Download the extension from{publisher.name}.{extensionId}as stated inpacked.json.
• Open the specified document and display it in the active text editor.
• Idle for 2 seconds to make sure the language server is created.

When we are ready, we can runVS code commandscorresponding to each language function and validate the returned result.

There is another test that contains a diagnostic function that has just been implemented. Check out atclient/source/test/diagnostics.test.ts.

Advanced themes

So far this guide covers:

• A brief overview of the language server and the language server protocol.
• Language Server Extension Architecture in VS Code
• Fromlsp exampleextension and how to develop/debug/verify/test it.

There are some more advanced topics that we couldn't fit into this guide. We will include links to these resources for further study of language server development.

Additional language server functions

The following language features are currently supported on the language server with code completion:

• Main features of the document: Highlights all "equals" symbols in a text document.
• Conduct: Provides information about hovering over the selected symbol in a text document.
• signature help: Provides subtitle help for the symbol selected in the text document.
• Definition: takes you to the definition of the selected symbol in the text document.
• Go to type definition: jumps to the type/interface definition for the selected symbol in the text document.
• Go to implementation: Allows you to switch to implementation definition support for the selected symbol in the text document.
• Find references: Finds all project-wide references for the selected symbol in the text document.
• List of document symbols: Contains a list of all symbols defined in the text document.
• List the workspace symbols: Lists all symbols in the entire project.
• Code actions: calculates the commands to be performed (usually beautification/refactoring) for the given text document and range.
• CodeLens: Calculates CodeLens statistics for the given text document.
• Formatting of documents: This includes formatting entire documents, ranges of documents, and formatting by type.
• Rename: rename the symbol through the project.
• Links to documents: Calculate and resolve links in a document.
• Colors of documents: Calculate and resolve the colors in the document to enable color selection in the editor.

FromFeatures of the programming languagetopic describes each of the above language features and provides guidance on how to implement them through the language server protocol or using the extensibility API directly from your extension.

Incremental synchronization of text documents

The example uses a simple text document manager provided by the packagevscode language servera module for synchronizing documents between VS Code and the language server.

This has two drawbacks:

• A lot of data is transferred because the entire content of the text document is repeatedly sent to the server.
• If an existing language library is used, such libraries typically support incremental document updates to avoid unnecessary parsing and syntax tree abstraction.

Therefore, the protocol also supports incremental document synchronization.

To take advantage of incremental document synchronization, the server must install three notification handlers:

• opDidOpenTextDocument: called when a text document is opened in VS Code.
• opDidChangeTextDocument: called when the content of a text document is changed in VS code.
• onDidCloseTextDocument: called when a text document is closed in VS code.

Below is a code snippet that illustrates how to bind these notification handlers to a connection and return the correct capability during initialization:

connection.click Initialize((parameters):Initialize the result =>{... yield{ options:{ // Enable incremental document synchronization tekstDocumentSync: A text document of the synchronization type.Increasing,...}};});connection.opDidOpenTextDocument((parameters)=>{ // A text document is opened in VS Code. // params.uri uniquely identifies the document. For documents stored on disk, this is the URI of the file. // params.text initial full text of the document.});connection.opDidChangeTextDocument((parameters)=>{ // The content of the text document has been changed to VS code. // params.uri uniquely identifies the document. // params.contentChanges describes changes in the content of the document.});connection.onDidCloseTextDocument((parameters)=>{ // Text document is closed in VS code. // params.uri uniquely identifies the document.});/*Make the text document manager listen for the connectionfor opening, changing and closing text documents.Comment out this line to enable `connection.onDidOpenTextDocument`,`connection.onDidChangeTextDocument` and `connection.onDidCloseTextDocument` for event handling*/// documents.listen(connection);

Use the VS Code API directly to implement language features

Although language servers have many advantages, they are not the only option for extending the editing capabilities of VS Code. In cases where you want to add some simple language features for a document type, consider usingvscode.languages.register[LANGUAGE_FEATURE]Dostavaas an option.

here it isexample of restorationdoorvscode.languages.registerCompletionItemProviderto add some snippets to plain text files.

More examples illustrating the use of the VS Code API can be found athttps://github.com/microsoft/vscode-extension-samples.

An error-tolerant language server parser

In most cases, the code in the editor is incomplete and syntactically incorrect, but developers still expect auto-completion and other language features to work. Therefore, the language server needs an error-tolerant parser: the parser generates meaningful ASTs from partially complete code, and the language server provides language functions based on the AST.

As we've been improving PHP support in VS Code, we've realized that the official PHP parser is not error-proof and cannot be reused directly on the language server. That's why we kept workingMicrosoft/tolerante-php-parserand on the left in detailnoteswhich can help language server authors who need to implement a fault-tolerant parser.

Frequently asked questions

When I try to connect to the server I get the message "unable to connect during runtime (timeout after 5000ms)"?

You will get this timeout error if the server is down when you try to mount the debugger. The client runs the language server, so make sure you run the client to have a running server. You may also need to disable client breakpoints if they interfere with starting the server.

I have read this manual andLSP specificationbut I still have unsolved questions. Where can I get help?

Please open an issuehttps://github.com/microsoft/language-server-protocol.

5.03.2023