Java integration

The Aspire Java hosting integration enables you to run Java applications, including Spring Boot applications, alongside your Aspire projects in the Aspire app host.

To get started with the Aspire Java hosting integration, install the CommunityToolkit.Aspire.Hosting.Java NuGet package in the app host project.

aspire add communitytoolkit-java

Select an integration to add:

> communitytoolkit-java (CommunityToolkit.Aspire.Hosting.Java)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.Java@*

<PackageReference Include="CommunityToolkit.Aspire.Hosting.Java" Version="*" />

To add a Spring Boot application to your app host, use the AddSpringApp extension method:

var builder = DistributedApplication.CreateBuilder(args);

var javaApp = builder.AddSpringApp(
    name: "spring-api",
    workingDirectory: "../spring-app",
    otelAgentPath: "../agents/opentelemetry-javaagent.jar")
    .WithHttpEndpoint(port: 8080);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(javaApp);

// After adding all resources, run the app...

The AddSpringApp method requires:

• name: The name of the resource in the Aspire dashboard
• workingDirectory: The path to the directory containing your Spring Boot application
• otelAgentPath: The path to the OpenTelemetry Java agent JAR file

For production scenarios, you can host Java applications in containers. Use JavaAppContainerResourceOptions to specify container-specific settings:

var builder = DistributedApplication.CreateBuilder(args);

var javaApp = builder.AddSpringApp(
    name: "spring-api",
    new JavaAppContainerResourceOptions
    {
        OtelAgentPath = "../agents/opentelemetry-javaagent.jar",
        ContainerImageName = "my-spring-app:latest",
        ContainerRegistry = "myregistry.azurecr.io"
    })
    .WithHttpEndpoint(port: 8080);

// After adding all resources, run the app...

For local development, you can run Java applications as executables using JavaAppExecutableResourceOptions:

var builder = DistributedApplication.CreateBuilder(args);

var javaApp = builder.AddSpringApp(
    name: "spring-api",
    new JavaAppExecutableResourceOptions
    {
        ApplicationName = "spring-app",
        OtelAgentPath = "../agents/opentelemetry-javaagent.jar",
        WorkingDirectory = "../spring-app"
    })
    .WithHttpEndpoint(port: 8080);

// After adding all resources, run the app...

On Linux and macOS, you may need to add additional configuration to trust the Aspire development certificates. Add the following to your Spring Boot application’s application.properties:

server.ssl.trust-store=/path/to/aspire/dev/certificate.p12
server.ssl.trust-store-password=your-password

For more information, see the Spring Boot SSL documentation.

Spring Boot applications typically use the server.port property to configure the port. Use WithHttpEndpoint to expose the endpoint:

var builder = DistributedApplication.CreateBuilder(args);

var javaApp = builder.AddSpringApp("spring-api", "../spring-app", "../agents/opentelemetry-javaagent.jar")
    .WithHttpEndpoint(port: 8080);

// After adding all resources, run the app...

The Java integration uses the OpenTelemetry Java agent to provide observability features. The agent automatically instruments your Java application and exports telemetry to the Aspire dashboard.

Make sure to download the OpenTelemetry Java agent and specify its path when calling AddSpringApp.

• Spring Boot documentation
• OpenTelemetry Java
• Aspire Community Toolkit
• Aspire integrations overview
• Aspire GitHub repo