# RustHostingExtensions Methods

- Package: [Aspire.Hosting.Rust](/reference/api/csharp/aspire.hosting.rust.md)
- Type: [RustHostingExtensions](/reference/api/csharp/aspire.hosting.rust/rusthostingextensions.md)
- Kind: `Methods`
- Members: `13`

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

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

## AddRustApp(IDistributedApplicationBuilder, string, string)

- Name: `AddRustApp(IDistributedApplicationBuilder, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<RustAppResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L80-L173)

Adds a Rust application to the application model.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<RustAppResource> AddRustApp(
        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 working directory for cargo and the Docker build context used when publishing.

## Returns

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

## Remarks

The resource runs `cargo run` in `appDirectory`. Cargo discovers the manifest from that directory by default; use `WithCargoManifestPath` to select another manifest. Cargo requires the two kinds of argument to be separated by `--`, so they are configured separately: `WithCargoArgs` adds arguments for cargo itself (before the separator) and `WithArgs` adds arguments for the application (after it).

Debugging is wired up automatically. In VS Code the resource is built with `cargo build` and the resulting binary is launched under a native debugger, so the cargo arguments are applied to the build rather than to `cargo run`.

Aspire configures the OTLP endpoint and development certificate environment variables. The Rust application must still enable the transport and TLS features required by its OpenTelemetry SDK and load native trust roots when using the development certificate. Rust does not read a port from the environment on its own, so bind to the port named by `WithHttpEndpoint(env: ...)` rather than a hard-coded one.

When publishing, a multi-stage Dockerfile is generated that builds the crate inside the container; the crate is never compiled on the host. If the app directory already contains a `Dockerfile`, that file is used instead. Call `WithDockerfileBaseImage` once with both arguments to override the build and runtime base images together; each call replaces the previous image configuration.

## Examples

Add a Rust application to the AppHost and expose an HTTP endpoint:

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

builder.AddRustApp("api", "../rust-api")
       .WithHttpEndpoint(env: "PORT")
       .WithCargoReleaseBuild();

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

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

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

- Name: `WithCargoArgs(IResourceBuilder<T>, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L195-L204)

Adds command-line arguments to the cargo command used by a Rust application.

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

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `args` (`string[]`)
  The cargo arguments to append before `--`.

## Returns

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

## Remarks

Arguments are forwarded to cargo verbatim and are not interpreted. Publishing and debugging work out which file cargo produces from the `WithCargo*` options alone, so a target selection that has a dedicated method -- `WithCargoBinTarget`, `WithCargoExample`, `WithCargoPackage`, `WithCargoProfile`, `WithCargoReleaseBuild` and `WithCargoTarget` -- has to go through it rather than being passed here.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withcargoargs-iresourcebuilder-t-action-rustcargoargscallbackcontext"></a>

## WithCargoArgs(IResourceBuilder<T>, Action<RustCargoArgsCallbackContext>)

- Name: `WithCargoArgs(IResourceBuilder<T>, Action<RustCargoArgsCallbackContext>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs)

Adds command-line arguments to the cargo command used by a Rust application.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoArgs<T>(
        this IResourceBuilder<T> builder,
        Action<RustCargoArgsCallbackContext> callback)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `callback` (`Action<RustCargoArgsCallbackContext>`)
  A callback that computes cargo arguments at execution time.

## Returns

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

## Remarks

This method is not available in polyglot AppHosts. Use the string[] overload instead.

## ATS metadata

### Ignored by ATS

- Reason: Callback-based cargo arguments are not expressible in polyglot AppHosts.

<a id="withcargoargs-iresourcebuilder-t-func-rustcargoargscallbackcontext-task"></a>

## WithCargoArgs(IResourceBuilder<T>, Func<RustCargoArgsCallbackContext, Task>)

- Name: `WithCargoArgs(IResourceBuilder<T>, Func<RustCargoArgsCallbackContext, Task>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs)

Adds command-line arguments to the cargo command used by a Rust application.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoArgs<T>(
        this IResourceBuilder<T> builder,
        Func<RustCargoArgsCallbackContext, Task> callback)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `callback` (`Func<RustCargoArgsCallbackContext, Task>`)
  A callback that computes cargo arguments at execution time.

## Returns

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

## Remarks

This method is not available in polyglot AppHosts. Use the string[] overload instead.

## ATS metadata

### Ignored by ATS

- Reason: Callback-based cargo arguments are not expressible in polyglot AppHosts.

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

## WithCargoBinTarget(IResourceBuilder<T>, string)

- Name: `WithCargoBinTarget(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L335-L339)

Configures the binary target to run for Rust applications that declare more than one.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoBinTarget<T>(
        this IResourceBuilder<T> builder,
        string binName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `binName` (`string`)
  The binary target name, as declared by `[[bin]] name` in Cargo.toml.

## Returns

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

## Remarks

Passed to cargo as `--bin`. Debugging and publishing also use it to work out which file cargo produces, so a package with several binaries must select one here (or set `default-run` in Cargo.toml).

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

## WithCargoExample(IResourceBuilder<T>, string)

- Name: `WithCargoExample(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L358-L362)

Configures an example target to run instead of a binary.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoExample<T>(
        this IResourceBuilder<T> builder,
        string exampleName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `exampleName` (`string`)
  The example name, as declared by a file or directory under `examples/`.

## Returns

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

## Remarks

Passed to cargo as `--example`. Cargo writes examples to `target/<profile>/examples/`, and debugging and publishing both follow that layout.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

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

- Name: `WithCargoFeatures(IResourceBuilder<T>, string[])`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L308-L315)

Adds cargo features for the Rust application.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoFeatures<T>(
        this IResourceBuilder<T> builder,
        params string[] features)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `features` (`string[]`)
  The features to enable.

## Returns

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

## Remarks

Repeated calls accumulate features in call order.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withcargolocked"></a>
<a id="withcargolocked-iresourcebuilder-t-bool"></a>

## WithCargoLocked(IResourceBuilder<T>, bool)

- Name: `WithCargoLocked(IResourceBuilder<T>, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L289-L292)

Configures the Rust application to build and run with the exact dependency versions recorded in `Cargo.lock`.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoLocked<T>(
        this IResourceBuilder<T> builder,
        bool locked = true)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `locked` (`bool`) `optional`
  `true` to add `--locked`; otherwise `false`.

## Returns

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

## Remarks

Passed to cargo as `--locked`, which fails the build rather than updating `Cargo.lock`. Publishing already adds this whenever the crate has a lock file, so a published image cannot silently pick up dependency versions that were never committed; pass `false` to opt out. See https://doc.rust-lang.org/cargo/commands/cargo-build.html#manifest-options

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

## WithCargoManifestPath(IResourceBuilder<T>, string)

- Name: `WithCargoManifestPath(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L450-L454)

Configures the `Cargo.toml` cargo builds from.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoManifestPath<T>(
        this IResourceBuilder<T> builder,
        string manifestPath)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `manifestPath` (`string`)
  The path to the manifest, absolute or relative to the app directory.

## Returns

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

## Remarks

Passed to cargo as `--manifest-path`. Cargo otherwise discovers the manifest by searching upwards from the app directory, which is what most apps want, so this is only needed to point at a manifest somewhere else -- for example the crate of one workspace member when the app directory is the workspace root.

Publishing copies the app directory into the container image and rewrites the manifest path to match, so the manifest has to live inside the app directory and the path has to be relative to it. An absolute path is accepted when running and rejected when publishing.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

## WithCargoPackage(IResourceBuilder<T>, string)

- Name: `WithCargoPackage(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L382-L386)

Configures the workspace package to build and run.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoPackage<T>(
        this IResourceBuilder<T> builder,
        string packageName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `packageName` (`string`)
  The cargo package name.

## Returns

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

## Remarks

Passed to cargo as `--package`. Required when the crate directory is a workspace whose default members include more than one package with a binary target, because the binary to run would otherwise be ambiguous. Library-only members are ignored, so an app crate beside library crates needs nothing.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

## WithCargoProfile(IResourceBuilder<T>, string)

- Name: `WithCargoProfile(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L473-L477)

Configures the named cargo profile to build with.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoProfile<T>(
        this IResourceBuilder<T> builder,
        string profileName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `profileName` (`string`)
  The profile name, for example `dev`, `release`, or a custom profile.

## Returns

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

## Remarks

Passed to cargo as `--profile`, which takes precedence over `WithCargoReleaseBuild` because cargo rejects `--profile` and `--release` together.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withcargoreleasebuild"></a>
<a id="withcargoreleasebuild-iresourcebuilder-t-bool"></a>

## WithCargoReleaseBuild(IResourceBuilder<T>, bool)

- Name: `WithCargoReleaseBuild(IResourceBuilder<T>, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L264-L267)

Configures the Rust application to run using release optimization.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoReleaseBuild<T>(
        this IResourceBuilder<T> builder,
        bool releaseBuild = true)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `releaseBuild` (`bool`) `optional`
  `true` to add `--release`; otherwise `false`.

## Returns

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

## Remarks

Publishing builds an optimized image by default, so pass `false` to opt a published image out of `--release`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

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

## WithCargoTarget(IResourceBuilder<T>, string)

- Name: `WithCargoTarget(IResourceBuilder<T>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Rust/RustHostingExtensions.cs#L420-L424)

Configures the target triple cargo builds for.

```csharp
public static class RustHostingExtensions
{
    public static IResourceBuilder<T> WithCargoTarget<T>(
        this IResourceBuilder<T> builder,
        string target)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The resource builder.
- `target` (`string`)
  The target triple, for example `x86_64-unknown-linux-musl`.

## Returns

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

## Remarks

Passed to cargo as `--target`. Cargo writes a cross-compiled binary to `target/<triple>/<profile>/`, and the generated Dockerfile follows that layout and adds the target's standard library to the build image with `rustup target add`.

Aspire-generated Dockerfiles map native Linux x86_64, aarch64, 32-bit ARM, and 32-bit x86 targets to Docker Linux platforms. Docker's `linux/arm` platform represents the ARMv7 variant. The default build and runtime images support x86_64 and aarch64 musl targets. A 32-bit musl target needs a custom build image but can use the default runtime image. Other ABIs require custom build and runtime images configured together in one `WithDockerfileBaseImage` call because later calls replace the previous image configuration.

Custom images opt out of default-image compatibility checks, but the target must still map to a supported native Docker Linux platform. A custom build image must already contain any linker or native dependencies the target needs; `WithDockerfileBaseImage` changes images but does not install cross-compilation tooling. Other targets require an authored Dockerfile for publishing.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.