# TerminalService Methods

- Package: [Aspire.Hosting](/reference/api/csharp/aspire.hosting.md)
- Type: [TerminalService](/reference/api/csharp/aspire.hosting/terminalservice.md)
- Kind: `Methods`
- Members: `3`

Manages terminals created and owned by the AppHost.

<a id="createterminal"></a>
<a id="createterminal-terminallaunchoptions"></a>

## CreateTerminal(TerminalLaunchOptions)

- Name: `CreateTerminal(TerminalLaunchOptions)`
- Returns: [AspireTerminal](/reference/api/csharp/aspire.hosting/aspireterminal.md)
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/TerminalService.cs#L115-L117)

Creates a terminal. The workload does not start until something needs it: the first viewer attaching, or the first automation call.

```csharp
public sealed class TerminalService
{
    public AspireTerminal CreateTerminal(
        TerminalLaunchOptions options)
    {
        // ...
    }
}
```

## Parameters

- `options` ([TerminalLaunchOptions](/reference/api/csharp/aspire.hosting/terminallaunchoptions.md))
  Describes the terminal to create.

## Returns

[AspireTerminal](/reference/api/csharp/aspire.hosting/aspireterminal.md) -- The terminal. Disposing it cancels the workload and removes the terminal from the dashboard; a dock terminal that is meant to outlive the call that created it should be left undisposed, and is torn down when the AppHost shuts down.

## Exceptions

- `ArgumentNullException` -- `options` or its [TerminalLaunchOptions.Title](/reference/api/csharp/aspire.hosting/terminallaunchoptions/properties.md#title) is `null`.
- `ArgumentException` -- The [TerminalLaunchOptions.Title](/reference/api/csharp/aspire.hosting/terminallaunchoptions/properties.md#title) is empty or consists only of white-space characters.
- `ArgumentOutOfRangeException` -- The placement in `options` is not [TerminalPlacement.Dock](/reference/api/csharp/aspire.hosting/terminalplacement/fields.md), [TerminalPlacement.Dialog](/reference/api/csharp/aspire.hosting/terminalplacement/fields.md), or [TerminalPlacement.None](/reference/api/csharp/aspire.hosting/terminalplacement/fields.md).
- `IOException` -- On Windows, the PTY socket directory does not use a supported Aspire layout or cannot be created.
- `UnauthorizedAccessException` -- On Windows, the PTY socket directory permissions cannot be applied.
- `InvalidOperationException` -- On Windows, no user profile directory is available for the default PTY socket directory.

## Remarks

The options, including the argument and environment variable collections, are captured during this call. Changing or reusing `options` afterward does not affect the created terminal. The process still inherits the AppHost's environment when it starts.

<a id="disposeasync"></a>

## DisposeAsync

- Name: `DisposeAsync`
- Returns: `ValueTask`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/TerminalService.cs#L477-L506)

Stops and awaits teardown of every terminal this service owns.

```csharp
public sealed class TerminalService
{
    public ValueTask DisposeAsync()
    {
        // ...
    }
}
```

## Returns

`ValueTask` -- A task that completes when all terminal workloads and transports have been disposed.

## Remarks

Teardown starts concurrently for all terminals. Repeated calls await the same cleanup operation.

<a id="trygetterminal"></a>
<a id="trygetterminal-string-aspireterminal"></a>

## TryGetTerminal(string, AspireTerminal?)

- Name: `TryGetTerminal(string, AspireTerminal?)`
- Returns: `bool`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/TerminalService.cs#L234-L249)

Gets a terminal by id.

```csharp
public sealed class TerminalService
{
    public bool TryGetTerminal(
        string terminalId,
        out AspireTerminal? terminal)
    {
        // ...
    }
}
```

## Parameters

- `terminalId` (`string`)
  The [AspireTerminal.Id](/reference/api/csharp/aspire.hosting/aspireterminal/properties.md#id) of the terminal to find.
- `terminal` ([AspireTerminal?](/reference/api/csharp/aspire.hosting/aspireterminal.md))
  The terminal, if one with that id exists.

## Returns

`bool` -- `true` if the terminal was found.

## Remarks

Resolves terminals the AppHost owns as well as those belonging to resources, so automation code can drive either kind through the same handle without knowing which it has.