Why this exists

If you are trying to run a Maven project inside Visual Studio and not cry, this guide is for you. It walks through installing Java and Maven or using the Maven Wrapper, wiring up pom.xml, running builds and tests, and attaching a debugger so breakpoints actually stop something. Expect practical tips and a few sarcastic asides to keep you awake.

Install Java and Maven or use the Maven Wrapper

First rule of dependency club, talk about JAVA_HOME. Make sure a Java Development Kit is installed and the JAVA_HOME environment variable points to it. If you do not want to rely on whatever is on a teammate's laptop use the Maven Wrapper which keeps your build reproducible.

java -version
mvn -v
# or use the wrapper in the repo
./mvnw -v

Create or import the Maven project

Either start with an archetype or import an existing pom.xml. Visual Studio may need a Java or Maven extension so the IDE recognizes the project layout and dependency management. Install the extension and restart the editor like a sensible person.

What to check in pom.xml

• groupId, artifactId and version are set
• dependencies are declared with appropriate scope
• plugins for compilation, testing and packaging are configured

If transitive dependencies are acting up run the dependency tree to find the noisy child.

mvn dependency:tree

Build run and test

Use the standard Maven commands to produce artifacts and run tests. The integrated terminal in Visual Studio keeps you in one tragicomedy of an environment.

mvn clean package
mvn test

If you want a quicker feedback loop skip packaging with a goal that only compiles and tests, or use -DskipTests when packaging is irrelevant for the moment.

Set up debugging so breakpoints mean something

Either configure a debug profile in your application plugin or attach the debugger to a running JVM. For services run with remote debug flags so the IDE can connect and actually stop at breakpoints. If your app is started by a plugin set MAVEN_OPTS or add JVM args to the exec plugin.

# example JVM debug flags for a remote attach
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005

Then attach Visual Studio debugger to port 5005. Logging plus breakpoints make a competent detective team.

Troubleshooting quick hits

• Build fails with missing classes, check dependency scopes and run mvn dependency:tree
• Tests behave differently in IDE, run mvn -Dtest=YourTest test to match CI
• Plugin or lifecycle issues, try mvn -X for verbose output and read the stack like a pirate reads treasure maps

Recap and smart shortcuts

Install JDK and Maven or use the Maven Wrapper. Set JAVA_HOME. Import or create your Maven project and configure pom.xml with dependencies and plugins. Use mvn clean package and mvn test for reliable builds. Attach the debugger with standard JVM debug flags for an honest debugging session. When things go sideways inspect the dependency tree and use verbose Maven output to find the villain.

Pro tip

Commit the Maven Wrapper to the repo and your future self will send you a thank you note in the form of fewer angry emails.