# DockerfileBuildAnnotation Methods

- Package: [Aspire.Hosting](/reference/api/csharp/aspire.hosting.md)
- Type: [DockerfileBuildAnnotation](/reference/api/csharp/aspire.hosting/dockerfilebuildannotation.md)
- Kind: `Methods`
- Members: `2`

Represents an annotation for customizing a Dockerfile build.

## EmitDockerfileArtifactsAsync(DockerfileFactoryContext, string?)

- Name: `EmitDockerfileArtifactsAsync(DockerfileFactoryContext, string?)`
- Returns: `Task`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting/ApplicationModel/DockerfileBuildAnnotation.cs#L139-L162)

Emits all generated Dockerfile artifacts for this annotation.

```csharp
public class DockerfileBuildAnnotation
{
    public Task EmitDockerfileArtifactsAsync(
        DockerfileFactoryContext context,
        string? dockerfilePath = null)
    {
        // ...
    }
}
```

## Parameters

- `context` ([DockerfileFactoryContext](/reference/api/csharp/aspire.hosting/dockerfilefactorycontext.md))
  The context containing services and resource information.
- `dockerfilePath` (`string?`) `optional`
  The optional Dockerfile path to emit to. When specified, the materialized Dockerfile is copied to this path and any generated sibling files are emitted next to it. When omitted, artifacts are emitted next to [DockerfileBuildAnnotation.DockerfilePath](/reference/api/csharp/aspire.hosting/dockerfilebuildannotation/properties.md#dockerfilepath).

## Returns

`Task` -- A task representing the asynchronous operation.

## Remarks

This method materializes a Dockerfile from [DockerfileBuildAnnotation.DockerfileFactory](/reference/api/csharp/aspire.hosting/dockerfilebuildannotation/properties.md#dockerfilefactory) when present, then emits generated companion files such as BuildKit's per-Dockerfile `.dockerignore` sibling. Use this instead of calling [DockerfileBuildAnnotation.MaterializeDockerfileAsync(DockerfileFactoryContext, CancellationToken)](/reference/api/csharp/aspire.hosting/dockerfilebuildannotation/methods.md#materializedockerfileasync-dockerfilefactorycontext-cancellationtoken) directly when the caller intends to pass the resulting Dockerfile path to a Docker/BuildKit-compatible builder.

## MaterializeDockerfileAsync(DockerfileFactoryContext, CancellationToken)

- Name: `MaterializeDockerfileAsync(DockerfileFactoryContext, CancellationToken)`
- Returns: `Task`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/a3766e994fd2cba86c8ac60b8a80268cab7e6383/src/Aspire.Hosting/ApplicationModel/DockerfileBuildAnnotation.cs#L91-L119)

Materializes the Dockerfile from the factory if it hasn't been materialized yet. This method is thread-safe and ensures the Dockerfile is only written once.

```csharp
public class DockerfileBuildAnnotation
{
    public Task MaterializeDockerfileAsync(
        DockerfileFactoryContext context,
        CancellationToken cancellationToken)
    {
        // ...
    }
}
```

## Parameters

- `context` ([DockerfileFactoryContext](/reference/api/csharp/aspire.hosting/dockerfilefactorycontext.md))
  The context containing services and resource information.
- `cancellationToken` (`CancellationToken`)
  The cancellation token.

## Returns

`Task` -- A task representing the asynchronous operation.