- Setting Up Local Development Environment
- Creating VSIX Packages for the Extension
- Updating the
Roslyn
Language Server Version
Setting up your local development environment for the vscode-csharp repository involves several steps. This guide will walk you through the process.
Before you start, make sure you have the following software installed on your machine:
- Node.js v18 (v18.17.0 LTS).
- Note - Building with higher major versions of Node.js is not advised - it may work but we do not test it.
- Npm (The version shipped with node is fine)
- .NET 8.0 SDK (dotnet should be on your path)
Once you have these installed, you can navigate to the cloned vscode-csharp repository to proceed with building, running, and testing the repository.
Follow these steps to build, run, and test the repository:
- Run
npm i
- This command installs the project dependencies. - Run
npm i -g gulp
- This command installs Gulp globally. - Run
gulp installDependencies
- This command downloads the various dependencies as specified by the version in the package.json file. - Run
code .
- This command opens the project in Visual Studio Code.
After completing the build steps:
- Run
npm run watch
(Optional) - This command watches for code changes. - Press Ctrl+Shift+D to open the Run view in VS Code and ensure
Launch Extension
is selected. - Start debugging by pressing F5.
To run tests:
- Execute
npm run test
or press F5 in VS Code with the "Launch Tests" debug configuration selected. - For integration tests, select either of the two 'current file' integration tests (one for roslyn and one for razor), from the drop-down and press F5 to start debugging:
- For Roslyn Server:
Launch Current File slnWithCsproj Integration Tests
- For Razor Server:
Launch Current File BasicRazorApp2_1 Integration Tests
These will allow you to actually debug the test, but the 'Razor integration tests' configuration does not.
This section shows how to set up local Razor or Roslyn language servers for debugging with the VSCode C# extension.
- Clone the Roslyn repository. This repository contains the Roslyn server implementation.
- Follow the build instructions provided in the repository.
The server DLL is typically at $roslynRepoRoot/artifacts/bin/Microsoft.CodeAnalysis.LanguageServer/Debug/net8.0/Microsoft.CodeAnalysis.LanguageServer.dll
, but this may vary based on the built configuration.
- Clone the Razor repository. This repository contains the Razor server implementation.
- Follow the build instructions provided in the repository.
The server DLL is typically at $razorRepoRoot/artifacts/bin/rzls/Debug/net8.0
.
Before running the language servers, familiarize yourself with the steps in the Configuring Local Language Servers section to configure either the Roslyn or Razor language servers for debugging .
Note: You would only need to configure this for the workspace you wish to debug, NOT for the repo root of vscode-csharp repo.
Follow these steps to enable debugging:
- Press
Ctrl+Shift+D
and thenF5
to launch the extension. This will open a new VS Code instance forvscode-csharp
repo. - In the new VS Code instance, open the project or solution you want to debug.
- Follow instructions in Configuring Local Language Servers to find and configure the workspace settings for the language server you want to debug.
- Ensure the language server is fully built in Debug mode.
- Meanwhile in a Visual Studio instance open the
.sln
solution file for the language server you want to debug. Keep this instance open for use in a later step. - Back on VS Code, press
Ctrl+Shift+P
and selectReload Window
. This ensures the changes made in step 3 are applied. - After reloading, a window will pop up prompting you to select or open a Visual Studio instance. Now, select the instance you opened in step 5.
- The language server will now trigger a breakpoint on
Debugger.Launch()
when it starts.
This section provides instructions on how to debug locally built Roslyn and Razor language servers. You can do this by either directly editing the settings.json
file of your workspace or through the VSCode settings interface.
- Open the Command Palette with
Ctrl+Shift+P
(orCmd+Shift+P
on macOS) - Type "Preferences: Open Workspace Settings"
- Select the option that appears.
- In the Workspace Settings tab, in the upper right corner, you'll see an icon that looks like a document with an arrow, which is the "Open Settings (JSON)" button.
- Click on this button to open the
settings.json
file.
In your workspace settings.json
file, add the following lines:
"dotnet.server.waitForDebugger": true,
"dotnet.server.path": "<roslynRepoRoot>/artifacts/bin/Microsoft.CodeAnalysis.LanguageServer/Debug/net8.0/Microsoft.CodeAnalysis.LanguageServer.dll"
Replace with the actual path to your Roslyn repository.
Or, in VSCode settings (Ctrl+,
):
- Search for
dotnet server
. - Set
dotnet.server.path
to the path of your Roslyn DLL. - Enable
dotnet.server.waitForDebugger
.
In your workspace settings.json file, add the following lines:
"razor.languageServer.debug": true,
"razor.languageServer.directory": "<razorRepoRoot>/artifacts/bin/rzls/Debug/net8.0",
"razor.server.trace": "Debug"
Replace $razorRepoRoot
with your actual values.
Or, in VSCode settings (Ctrl+,
):
- Search for
Razor
. - Set
razor.languageServer.directory
to the path of your Razor DLL. - Enable
razor.languageServer.debug
. - Set
razor.server.trace
toDebug
. This gives you more detailed log messages in the output window.
To package this extension, we need to create VSIX Packages. The VSIX packages can be created using the gulp command gulp vsix:release:package
. This will create all the platform specific VSIXs that you can then install manually in VSCode.
In order to pull in new packages from upstreams into the msft_consumption feed we use for restoring, you will need to be a member of the 'CSharp VS Code Extension contributors' group in the Azure Devops instance.
To update the version of the roslyn server used by the extension do the following:
- Find the the Roslyn signed build you want from here. Typically the latest successful build of main is fine.
- In the official build stage, look for the
Publish Assets
step. In there you will see it publishing theMicrosoft.CodeAnalysis.LanguageServer.neutral
package with some version, e.g.4.6.0-3.23158.4
. Take note of that version number. - In the package.json inside the
defaults
section update theroslyn
key to point to the version number you found above in step 2. - Ensure that version of the package is in the proper feeds by running
gulp updateRoslynVersion
. Note: you may need to install the Azure Artifacts NuGet Credential Provider to run interactive authentication. - Build and test the change. If everything looks good, submit a PR.