This guide provides detailed instructions on how to configure your Liberty project to use the Liberty Tools for Visual Studio Code extension.
- Before you begin
- Open the Liberty dashboard
- Run your application on Liberty using dev mode
- Run your application tests
- View your application test reports
- Stop your application
- Debug your application
- Manually add your liberty project to the dashboard
- Configure a Liberty server
- Develop with Jakarta EE and MicroProfile APIs
- Java 17 is required by Liberty Tools for Visual Studio Code.
-
Define a Liberty
server.xmlconfiguration file in thesrc/main/liberty/configlocation. -
Configure the Liberty Maven Plugin or Liberty Gradle Plugin. We recommend using recent versions of the plugins as they include several important bug fixes.
The following versions are recommended at minimum:
- Liberty Maven Plugin -> 3.7.1
- Liberty Gradle Plugin -> 3.5.1
To ensure that the Liberty Config Language Server starts properly, define the xml.java.home property in your VS Code settings or set the system JAVA_HOME environment variable to point to Java 17 .
By default, the Liberty dashboard appears in the Project Explorer side bar. Optionally, you can drag the Liberty dashboard into the Activity Bar.
| Side Bar view | Activity Bar view |
|---|---|
 |
 |
Projects that are already properly configured to run on Liberty and use Liberty dev mode are automatically added the Liberty dashboard when it opens. If your Liberty project does not show up in the Liberty dashboard automatically and you have the Liberty Maven or Liberty Gradle plugin configured, check out how to manually add your project to the Liberty dashboard.
If you add new projects or make changes, use the refresh icon in the Liberty dashboard toolbar to refresh the dashboard view.
The following three menu actions are available to start your Liberty application in dev mode through the Liberty dashboard or the Visual Studio Code command palette:
- Start your application in dev mode
- Start your application in dev mode with configuration
- Start your application in dev mode in a container
The Liberty dashboard provides a context menu for Liberty projects. You can choose different commands from the menu to speed up application development.
The Liberty Tools plugin provides a set of commands to the command palette. The command palette is accessible a number of ways. Additionally, the Shift + Alt + L shortcut shows a similar menu with only Liberty commands.
All Liberty Tools commands that are described in the following sections are also available from the command palette.
To start your application in dev mode, select the Start command for your application in the Liberty dashboard.
A new terminal tab opens to run the application in dev mode.
To start your application in dev mode with custom configuration, select the Start... command for your application in the Liberty dashboard. The command opens an edit dialog where you can specify parameters for the Liberty Maven dev goal or Liberty Gradle dev task.
A new terminal tab opens to run the application in dev mode.
The next time you choose to start dev mode with configuration, the menu provides a history of previously used configurations.
To use dev mode for containers, select the Start in container command for your application in the Liberty dashboard.
For more information on dev mode for containers, check out the Liberty Maven devc goal or the Liberty Gradle libertyDevc task.
After your application is running on Liberty using dev mode, you can easily run the tests provided by your application.
To run tests, select the Run tests command for your application in the Liberty dashboard.
The tests are run in the corresponding terminal.
After you finish running your application tests, you can access the produced test reports.
To view the integration test report for Maven-built applications, select the View integration test report command for your application in the Liberty dashboard.
This command looks for the integration test report at the /target/site/failsafe-report.html default location.
To view the unit test report for Maven-built applications, select the View unit test report command for your application in the Liberty dashboard.
This command looks for the unit test report at the/target/site/surefire-report.html default location.
To view the test report for Gradle-built applications, select the View test report command for your application in the Liberty dashboard.
This command looks for the test report at the build/reports/tests/test/index.html default location.
To stop your application, select the Stop command for your application in the Liberty dashboard.
To attach the debugger, you must have a running server. Once the server is running, click the Attach debugger command or select the Liberty: Attach debugger command in the command palette, followed by your application.
When the debugger is attached, the Visual Studio Code debug options become available.
In the event that your Liberty project is not automatically detected by the Liberty dashboard, you can manually add your Liberty project to the Liberty dashboard. To manually add your Liberty project to the Liberty dashboard, right-click into an empty space in the project explorer and select Add project to Liberty Dashboard or select the Liberty: Add project to the tool window command in the command palette, followed by your application.
You are prompted with a list of projects that are not already displayed in the in the Liberty dashboard.
To remove manually added Liberty projects from the Liberty dashboard, right-click in an empty space in the project explorer and select Remove project from Liberty Dashboard or select the Liberty: Remove project from the tool window command in the command palette, followed by your application.
Liberty configuration assistance provides editing assistance, such as code completion, diagnostics, and quick-fixes, in Liberty server.xml, server.env, and bootstrap.properties files.
- Start the project in dev mode by using one of the previously described Liberty dashboard or command palette commands. Dev mode installs the Liberty features that are required for your application.
- Open any of the supported Liberty configuration files.
- To use Liberty-specific code completion, press Ctrl + Space / Cmd + Space anywhere within the document. A drop-down list of completion suggestions appears.
Liberty configuration assistance is offered through the Liberty Config Language Server. For more information, see the project documentation in GitHub.
Liberty Tools editing assistance provides code completion, diagnostics, and quick-fixes in configuration and application files for Jakarta EE and MicroProfile APIs.
- Open a Java or microprofile-config.properties file.
- To use Jakarta EE-specific and MicroProfile-specific code completion, press Ctrl + Space / Cmd + Space anywhere within the document. A drop-down list of completion suggestions appears.
Jakarta EE API configuration assistance is offered through Eclipse LSP4Jakarta, the Language Server for Jakarta EE. For more information, see the project documentation in GitHub.
MicroProfile EE API configuration assistance is offered through Eclipse LSP4MP, the Language Server for MicroProfile. For more information, see the project documentation in GitHub.