# JavaHostingExtensions Methods

- Package: [Aspire.Hosting.Java](/reference/api/csharp/aspire.hosting.java.md)
- Type: [JavaHostingExtensions](/reference/api/csharp/aspire.hosting.java/javahostingextensions.md)
- Kind: `Methods`
- Members: `15`

Provides extension methods for adding Java applications to an `Hosting.IDistributedApplicationBuilder`.

<a id="addjavaapp"></a>
<a id="addjavaapp-idistributedapplicationbuilder-string-string"></a>

## AddJavaApp(IDistributedApplicationBuilder, string, string)

- Name: `AddJavaApp(IDistributedApplicationBuilder, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<JavaAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L88-L162)

Adds a Java application to the application model, launched with `java`.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<JavaAppResource> AddJavaApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The application directory. Relative paths are resolved against the AppHost directory.

## Returns

`IResourceBuilder<JavaAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `name` or `appDirectory` is `null`, empty, or whitespace.
- `InvalidOperationException` -- No launch mode was configured. Raised when the resource starts, not when this is called.

## Remarks

Combine with [JavaHostingExtensions.WithMavenGoal(IResourceBuilder<T>, string, string[])](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withmavengoal-iresourcebuilder-t-string-string) or [JavaHostingExtensions.WithGradleTask(IResourceBuilder<T>, string, string[])](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withgradletask-iresourcebuilder-t-string-string) to run the application through a build tool, or use the overload that accepts a `jarPath` to run a prebuilt JAR with `java -jar`. Exactly one of those three launch modes must be configured.

## Examples

Run a Spring Boot application through the Maven wrapper:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

builder.AddJavaApp("catalog", "../catalog")
       .WithMavenGoal("spring-boot:run")
       .WithHttpEndpoint(env: "SERVER_PORT")
       .WithHttpHealthCheck("/actuator/health");

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="addjavaapp-idistributedapplicationbuilder-string-string-string-string"></a>

## AddJavaApp(IDistributedApplicationBuilder, string, string, string, string[])

- Name: `AddJavaApp(IDistributedApplicationBuilder, string, string, string, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<JavaAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L191-L211)

Adds a Java application that runs a prebuilt JAR with `java -jar`.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<JavaAppResource> AddJavaApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory,
        string jarPath,
        params string[] args)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The application directory. Relative paths are resolved against the AppHost directory.
- `jarPath` (`string`)
  The path to the JAR file to execute. Relative paths are resolved against `appDirectory`.
- `args` (`string[]`)
  Arguments passed to the Java application after the JAR path.

## Returns

`IResourceBuilder<JavaAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` or `args` is `null`.
- `ArgumentException` -- `name`, `appDirectory`, or `jarPath` is `null`, empty, or whitespace.

## Examples

Build the JAR with Maven, then run it:

```csharp
builder.AddJavaApp("worker", "../worker", "target/worker.jar")
       .WithMavenBuild();
```

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting.Java/addJavaAppWithJar`

<a id="addjavacontainer"></a>
<a id="addjavacontainer-idistributedapplicationbuilder-string-string-string"></a>

## AddJavaContainer(IDistributedApplicationBuilder, string, string, string?)

- Name: `AddJavaContainer(IDistributedApplicationBuilder, string, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<JavaContainerResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L258-L271)

Adds a Java application that runs from an existing container image.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<JavaContainerResource> AddJavaContainer(
        this IDistributedApplicationBuilder builder,
        string name,
        string image,
        string? tag = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `image` (`string`)
  The container image that runs the application, for example `mycompany/catalog`.
- `tag` (`string?`) `optional`
  The image tag. Defaults to the image's `latest` tag.

## Returns

`IResourceBuilder<JavaContainerResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `name` or `image` is `null`, empty, or whitespace.

## Remarks

Use this when the image is built elsewhere -- by a separate CI pipeline, or by a team that ships the application as a container. Aspire runs the image as-is and never rebuilds it, so the JAR, the JDK, and any OpenTelemetry agent all come from the image. Use [JavaHostingExtensions.AddJavaApp(IDistributedApplicationBuilder, string, string)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#addjavaapp-idistributedapplicationbuilder-string-string) instead when Aspire should build and run the application from source.

No endpoint is declared, because the port the image listens on is a property of the image. Add one with `WithHttpEndpoint(targetPort: 8080)`, using whichever port the application binds -- 8080 for a default Spring Boot or Quarkus image.

## Examples

Run a published Spring Boot image and give it a database:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddPostgres("pg").AddDatabase("catalogdb");

builder.AddJavaContainer("catalog", "mycompany/catalog", "1.4.0")
       .WithHttpEndpoint(targetPort: 8080)
       .WithReference(db)
       .WithJvmArgs("-Xmx512m");

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="addquarkusapp"></a>
<a id="addquarkusapp-idistributedapplicationbuilder-string-string"></a>

## AddQuarkusApp(IDistributedApplicationBuilder, string, string)

- Name: `AddQuarkusApp(IDistributedApplicationBuilder, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<JavaAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L410-L504)

Adds a Quarkus application to the application model, built and launched with its own Maven or Gradle wrapper.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<JavaAppResource> AddQuarkusApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The application directory, containing `pom.xml`, `build.gradle`, `build.gradle.kts`, `settings.gradle`, or `settings.gradle.kts`. Relative paths are resolved against the AppHost directory.

## Returns

`IResourceBuilder<JavaAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `name` or `appDirectory` is `null`, empty, or whitespace.
- `InvalidOperationException` -- The directory contains neither a Maven nor a Gradle build file, or contains both.

## Remarks

The build tool is detected when the resource starts, the application runs in Quarkus dev mode ( `quarkus:dev` or `quarkusDev`) so live coding works, and an HTTP endpoint is declared through `QUARKUS_HTTP_PORT`, the environment variable Quarkus reads for its listening port. Everything else behaves like [JavaHostingExtensions.AddJavaApp(IDistributedApplicationBuilder, string, string)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#addjavaapp-idistributedapplicationbuilder-string-string). The dev-mode goal compiles the application itself, so Aspire does not add a separate build resource before it. There are two exceptions. [JavaHostingExtensions.WithOtelAgent(IResourceBuilder<T>)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withotelagent-iresourcebuilder-t) with a build-produced agent cannot be loaded until a build has written it, and a debug session launches the packaged fast JAR rather than the dev-mode wrapper, which no build has written on a clean checkout.

Quarkus Dev Services are left enabled but do not activate for anything Aspire supplies: Dev Services only start a container when the corresponding configuration is missing, and a `WithReference` to a database or broker provides it. That means Aspire's resources are used rather than a second set started underneath.

`QUARKUS_PROFILE` is set to `dev` in run mode. Dev mode already selects that profile; setting it explicitly means a debugger, which launches the packaged application rather than the dev-mode wrapper, resolves the same `%dev.` configuration the application would see when run normally.

In run mode the application is bound to all interfaces. Quarkus enables Host header validation whenever it binds a localhost name, and that filter rejects the hostname Aspire publishes, which makes the endpoint link in the dashboard return `400`. Published output is left alone, where the application already binds all interfaces.

No health check is added. `/q/health` only exists when the application depends on `quarkus-smallrye-health`, and adding it unconditionally would leave applications without that extension permanently unhealthy and silently stall every `WaitFor` on them. Add `WithHttpHealthCheck("/q/health")` when the extension is present.

## Examples

A Quarkus service backed by a database Aspire provides:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddPostgres("pg").AddDatabase("inventorydb");

builder.AddQuarkusApp("inventory", "../inventory")
       .WithReference(db)
       .WaitFor(db);

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="addspringbootapp"></a>
<a id="addspringbootapp-idistributedapplicationbuilder-string-string"></a>

## AddSpringBootApp(IDistributedApplicationBuilder, string, string)

- Name: `AddSpringBootApp(IDistributedApplicationBuilder, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<JavaAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L330-L345)

Adds a Spring Boot application to the application model, built and launched with its own Maven or Gradle wrapper.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<JavaAppResource> AddSpringBootApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string appDirectory)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The `Hosting.IDistributedApplicationBuilder` to add the resource to.
- `name` (`string`)
  The name of the resource.
- `appDirectory` (`string`)
  The application directory, containing `pom.xml`, `build.gradle`, `build.gradle.kts`, `settings.gradle`, or `settings.gradle.kts`. Relative paths are resolved against the AppHost directory.

## Returns

`IResourceBuilder<JavaAppResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `name` or `appDirectory` is `null`, empty, or whitespace.
- `InvalidOperationException` -- The directory contains neither a Maven nor a Gradle build file, or contains both.

## Remarks

This is [JavaHostingExtensions.AddJavaApp(IDistributedApplicationBuilder, string, string)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#addjavaapp-idistributedapplicationbuilder-string-string) with the common Spring Boot configuration already applied: the build tool is detected when the resource starts, the application is launched through that tool's Spring Boot plugin ( `spring-boot:run` or `bootRun`), and an HTTP endpoint is declared through `SERVER_PORT`, which is the environment variable Spring Boot reads for its listening port. Everything else is the same, so any `With...` method that works on [JavaHostingExtensions.AddJavaApp(IDistributedApplicationBuilder, string, string)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#addjavaapp-idistributedapplicationbuilder-string-string) works here too.

The launch goal compiles the application itself, so Aspire does not add a separate build resource before it. Publishing still packages the application with tests skipped ( `-DskipTests` for Maven, `-x test` for Gradle). Call [JavaHostingExtensions.WithMavenBuild(IResourceBuilder<T>, string[])](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withmavenbuild-iresourcebuilder-t-string) or [JavaHostingExtensions.WithGradleBuild(IResourceBuilder<T>, string[])](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withgradlebuild-iresourcebuilder-t-string) afterwards to customize those package arguments. The one thing that does add a build resource is [JavaHostingExtensions.WithOtelAgent(IResourceBuilder<T>)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withotelagent-iresourcebuilder-t) with a build-produced agent, which cannot be loaded until a build has written it.

No health check is added. `/actuator/health` only exists when the application depends on `spring-boot-starter-actuator`, and adding it unconditionally would leave applications without that dependency permanently unhealthy and silently stall every `WaitFor` on them. Add `WithHttpHealthCheck("/actuator/health")` when the actuator is present.

## Examples

Two Spring Boot services and a database:

```csharp
var builder = DistributedApplication.CreateBuilder(args);

var db = builder.AddPostgres("pg").AddDatabase("catalogdb");

var catalog = builder.AddSpringBootApp("catalog", "../catalog")
                     .WithReference(db);

builder.AddSpringBootApp("orders", "../orders")
       .WithReference(catalog)
       .WaitFor(catalog);

builder.Build().Run();
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withgradlebuild"></a>
<a id="withgradlebuild-iresourcebuilder-t-string"></a>

## WithGradleBuild(IResourceBuilder<T>, string[])

- Name: `WithGradleBuild(IResourceBuilder<T>, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L790-L796)

Runs a Gradle build before the Java application starts.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithGradleBuild<T>(
        this IResourceBuilder<T> builder,
        params string[] args)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder for the Java application.
- `args` (`string[]`)
  Arguments passed to the Gradle wrapper. Defaults to `clean build`.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` or `args` is `null`.
- `InvalidOperationException` -- The application is already configured to build with Maven.

## Remarks

When the application launches with [JavaHostingExtensions.WithGradleTask(IResourceBuilder<T>, string, string[])](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withgradletask-iresourcebuilder-t-string-string), that task performs the local compilation, so these arguments normally configure publishing without adding a second run-mode build. Otherwise, the build step is a child resource that the application waits for. No child is created when publishing because the generated container image performs the build.

This runs a build before the application starts. To launch the application through Gradle, use [JavaHostingExtensions.WithGradleTask(IResourceBuilder<T>, string, string[])](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withgradletask-iresourcebuilder-t-string-string) instead.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withgradletask"></a>
<a id="withgradletask-iresourcebuilder-t-string-string"></a>

## WithGradleTask(IResourceBuilder<T>, string, string[])

- Name: `WithGradleTask(IResourceBuilder<T>, string, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L674-L678)

Launches the Java application through a Gradle task instead of `java`, for example `bootRun`.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithGradleTask<T>(
        this IResourceBuilder<T> builder,
        string task,
        params string[] args)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder for the Java application.
- `task` (`string`)
  The Gradle task to execute.
- `args` (`string[]`)
  Additional arguments passed to the Gradle wrapper after the task.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` or `args` is `null`.
- `ArgumentException` -- `task` is `null`, empty, or whitespace.
- `InvalidOperationException` -- The application is already configured to run a prebuilt JAR or a Maven goal.

## Remarks

The wrapper defaults to `gradlew` ( `gradlew.bat` on Windows) in the resource's working directory and can be overridden with [JavaHostingExtensions.WithWrapperPath(IResourceBuilder<T>, string)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withwrapperpath-iresourcebuilder-t-string).

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withjarartifact"></a>
<a id="withjarartifact-iresourcebuilder-t-string"></a>

## WithJarArtifact(IResourceBuilder<T>, string)

- Name: `WithJarArtifact(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L1039-L1042)

Selects the JAR the generated container image runs, for projects whose build produces more than one.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithJarArtifact<T>(
        this IResourceBuilder<T> builder,
        string jarPath)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder for the Java application.
- `jarPath` (`string`)
  The path to the JAR produced by the build, relative to the application directory, for example `target/app.jar`.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `jarPath` is `null`, empty, or whitespace.

## Remarks

Only affects publishing, and only when the application is built in the image. Without it the container build selects the single JAR that is not a `-plain`, `-sources`, or `-javadoc` artifact, and fails the build if that is ambiguous.

This takes precedence over the JAR named by the `jarPath` overload of [JavaHostingExtensions.AddJavaApp(IDistributedApplicationBuilder, string, string)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#addjavaapp-idistributedapplicationbuilder-string-string), so a resource can run one JAR locally and publish another. It has no effect on an application published from a prebuilt JAR, because nothing is built in the image for it to select from.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withjvmargs"></a>
<a id="withjvmargs-iresourcebuilder-t-string"></a>

## WithJvmArgs(IResourceBuilder<T>, string[])

- Name: `WithJvmArgs(IResourceBuilder<T>, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L1070-L1084)

Adds arguments to the Java Virtual Machine that runs the application.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithJvmArgs<T>(
        this IResourceBuilder<T> builder,
        params string[] args)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `args` (`string[]`)
  The JVM arguments, for example `-Xmx512m`.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` or `args` is `null`.

## Remarks

Arguments are passed through the `JAVA_TOOL_OPTIONS` environment variable, which the JVM reads however it was started -- `java -jar`, a Maven goal, a Gradle task, or a container image's own entrypoint, including the JVM those build tools fork. Values containing spaces are quoted, because the JVM splits this variable on whitespace.

This is also how a container image that already carries the OpenTelemetry Java agent turns it on, since [JavaHostingExtensions.WithOtelAgent(IResourceBuilder<T>)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withotelagent-iresourcebuilder-t) copies an agent from the build context and so applies only to applications Aspire itself launches or builds: `WithJvmArgs("-javaagent:/app/opentelemetry-javaagent.jar")`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withmainclass"></a>
<a id="withmainclass-iresourcebuilder-t-string"></a>

## WithMainClass(IResourceBuilder<T>, string)

- Name: `WithMainClass(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L1008-L1011)

Sets the main class an IDE launches when running or debugging this application. Has no effect on how Aspire starts the process, which is decided by the JAR path, Maven goal, or Gradle task.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithMainClass<T>(
        this IResourceBuilder<T> builder,
        string mainClass)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder for the Java application.
- `mainClass` (`string`)
  The fully qualified name of the class declaring `main`, for example `com.example.Application`.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `mainClass` is `null`, empty, or whitespace.

## Remarks

Only affects IDE execution. When omitted, the IDE resolves the main class from the project's build files; set it explicitly when a project declares more than one class with a `main` method.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withmavenbuild"></a>
<a id="withmavenbuild-iresourcebuilder-t-string"></a>

## WithMavenBuild(IResourceBuilder<T>, string[])

- Name: `WithMavenBuild(IResourceBuilder<T>, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L757-L763)

Runs a Maven build before the Java application starts.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithMavenBuild<T>(
        this IResourceBuilder<T> builder,
        params string[] args)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder for the Java application.
- `args` (`string[]`)
  Arguments passed to the Maven wrapper. Defaults to `clean package`.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` or `args` is `null`.
- `InvalidOperationException` -- The application is already configured to build with Gradle.

## Remarks

When the application launches with [JavaHostingExtensions.WithMavenGoal(IResourceBuilder<T>, string, string[])](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withmavengoal-iresourcebuilder-t-string-string), that goal performs the local compilation, so these arguments normally configure publishing without adding a second run-mode build. Otherwise, the build step is a child resource that the application waits for. No child is created when publishing because the generated container image performs the build.

This runs a build before the application starts. To launch the application through Maven, use [JavaHostingExtensions.WithMavenGoal(IResourceBuilder<T>, string, string[])](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withmavengoal-iresourcebuilder-t-string-string) instead.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withmavengoal"></a>
<a id="withmavengoal-iresourcebuilder-t-string-string"></a>

## WithMavenGoal(IResourceBuilder<T>, string, string[])

- Name: `WithMavenGoal(IResourceBuilder<T>, string, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L646-L650)

Launches the Java application through a Maven goal instead of `java`, for example `spring-boot:run`.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithMavenGoal<T>(
        this IResourceBuilder<T> builder,
        string goal,
        params string[] args)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder for the Java application.
- `goal` (`string`)
  The Maven goal to execute.
- `args` (`string[]`)
  Additional arguments passed to the Maven wrapper after the goal.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` or `args` is `null`.
- `ArgumentException` -- `goal` is `null`, empty, or whitespace.
- `InvalidOperationException` -- The application is already configured to run a prebuilt JAR or a Gradle task.

## Remarks

The wrapper defaults to `mvnw` ( `mvnw.cmd` on Windows) in the resource's working directory and can be overridden with [JavaHostingExtensions.WithWrapperPath(IResourceBuilder<T>, string)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withwrapperpath-iresourcebuilder-t-string).

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withotelagent"></a>
<a id="withotelagent-iresourcebuilder-t"></a>

## WithOtelAgent(IResourceBuilder<T>)

- Name: `WithOtelAgent(IResourceBuilder<T>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L1122-L1127)

Runs the application with the OpenTelemetry Java agent from the location the build tool writes it to.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithOtelAgent<T>(
        this IResourceBuilder<T> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `InvalidOperationException` -- The resource has no Maven or Gradle build configured, so the agent location cannot be inferred. Raised when the application model is built, not when this is called.

## Remarks

The agent is expected at `target/agent/opentelemetry-javaagent.jar` for Maven and `build/agent/opentelemetry-javaagent.jar` for Gradle -- the conventional output directory of each tool with an `agent` subdirectory. The build has to put it there; nothing is downloaded. With Maven, copy it with `maven-dependency-plugin` 's `copy` goal bound to `process-resources`; with Gradle, declare the agent in its own configuration and add a `Copy` task that `compileJava` depends on.

May be called before or after the build tool is configured: which directory the agent is read from is decided when the application model is built, so the result does not depend on the order of builder calls.

Because the build writes the agent, Aspire runs that build as its own resource in run mode and holds the application until it finishes -- including for Spring Boot and Quarkus, whose launch goals would otherwise be the only build. This is required rather than an optimization: `JAVA_TOOL_OPTIONS` is read by every JVM started beneath the resource, and the first of those is the wrapper's own, so an agent the build has not written yet kills that JVM during VM initialization with "Error opening zip file or JAR manifest missing" before the launch goal runs.

Use [JavaHostingExtensions.WithOtelAgent(IResourceBuilder<T>)](/reference/api/csharp/aspire.hosting.java/javahostingextensions/methods.md#withotelagent-iresourcebuilder-t) when the agent lives anywhere else, including when it is committed to the repository or supplied by the container base image.

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting.Java/withOtelAgentDefaultPath`

<a id="withotelagent-iresourcebuilder-t-string"></a>

## WithOtelAgent(IResourceBuilder<T>, string)

- Name: `WithOtelAgent(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L1206-L1209)

Runs the application with the OpenTelemetry Java agent so it exports traces, metrics, and logs to Aspire.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithOtelAgent<T>(
        this IResourceBuilder<T> builder,
        string agentPath)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `agentPath` (`string`)
  The path to the `opentelemetry-javaagent.jar` file.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `agentPath` is `null`, empty, or whitespace.

## Remarks

The agent is not downloaded. Obtain it as a build dependency, or from https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases, and point this at the resulting file. The OTLP exporter is configured by `AddJavaApp` regardless of whether an agent is used, so call this only when you want the agent's automatic instrumentation.

A relative `agentPath` is resolved against the application directory and made absolute when running locally. This is required, not cosmetic: `JAVA_TOOL_OPTIONS` is inherited by every JVM started beneath the resource, and build tools start JVMs whose working directory is not the application directory. The Gradle daemon, for example, starts from its own distribution directory, so a relative `-javaagent:` path fails to resolve and the daemon dies during VM initialization with "Error opening zip file or JAR manifest missing".

A relative path names a file the build produces, so Aspire runs that build as its own resource in run mode and holds the application until it finishes. An absolute path names a file that exists independently of the build, so no build resource is added.

In publish mode a relative path is rewritten to the location the generated Dockerfile copies the agent to, because the path has to be interpreted inside the container rather than on the build machine. An absolute path is emitted unchanged, since it cannot have come from the build context and must be supplied by the base image or a mount.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withwrapperpath"></a>
<a id="withwrapperpath-iresourcebuilder-t-string"></a>

## WithWrapperPath(IResourceBuilder<T>, string)

- Name: `WithWrapperPath(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Java/JavaHostingExtensions.cs#L952-L986)

Overrides the build tool wrapper script path, for repositories whose wrapper is not in the default location or does not use the default name.

```csharp
public static class JavaHostingExtensions
{
    public static IResourceBuilder<T> WithWrapperPath<T>(
        this IResourceBuilder<T> builder,
        string wrapperPath)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The `ApplicationModel.IResourceBuilder`1` to configure.
- `wrapperPath` (`string`)
  The path to the wrapper script, absolute or relative to the resource's working directory.

## Returns

`IResourceBuilder<T>` -- A reference to the `ApplicationModel.IResourceBuilder`1`.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `wrapperPath` is `null`, empty, or whitespace.

## Remarks

May be called before or after the build tool is configured. A later call re-points anything that already resolved the default wrapper, so the result does not depend on the order of builder calls.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.