# AspireTerminal Methods

- Package: [Aspire.Hosting](/reference/api/csharp/aspire.hosting.md)
- Type: [AspireTerminal](/reference/api/csharp/aspire.hosting/aspireterminal.md)
- Kind: `Methods`
- Members: `7`

An Aspire-owned terminal handle for dashboard interaction and automation from AppHost code.

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

## DisposeAsync

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

Releases the handle, stopping the workload only when it is owned by the AppHost.

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

## Returns

`ValueTask` -- A task representing the terminal cleanup operation.

<a id="getscreentext"></a>

## GetScreenText

- Name: `GetScreenText`
- Returns: `string`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/AspireTerminal.cs#L142)

Gets the current contents of the terminal screen, with lines separated by newlines.

```csharp
public sealed class AspireTerminal
{
    public string GetScreenText()
    {
        // ...
    }
}
```

## Returns

`string` -- The current terminal screen text.

## Exceptions

- `InvalidOperationException` -- The AppHost-owned terminal has already stopped.

<a id="sendkeyasync"></a>
<a id="sendkeyasync-aspireterminalkey-cancellationtoken"></a>

## SendKeyAsync(AspireTerminalKey, CancellationToken)

- Name: `SendKeyAsync(AspireTerminalKey, CancellationToken)`
- Returns: `Task`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/AspireTerminal.cs#L120-L121)

Sends a single key, optionally combined with modifiers, to the terminal's workload.

```csharp
public sealed class AspireTerminal
{
    public Task SendKeyAsync(
        AspireTerminalKey key,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}
```

## Parameters

- `key` ([AspireTerminalKey](/reference/api/csharp/aspire.hosting/aspireterminalkey.md))
  The key to send.
- `cancellationToken` (`CancellationToken`) `optional`
  Cancellation token.

## Returns

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

## Exceptions

- `ArgumentException` -- `key` is an uninitialized value.
- `InvalidOperationException` -- The AppHost-owned terminal has already stopped.
- `OperationCanceledException` -- The input operation was canceled by `cancellationToken`.

## Remarks

Use the named values on [AspireTerminalKey](/reference/api/csharp/aspire.hosting/aspireterminalkey.md) and combine them with [AspireTerminalKey.Ctrl(AspireTerminalKey)](/reference/api/csharp/aspire.hosting/aspireterminalkey/methods.md#ctrl-aspireterminalkey), [AspireTerminalKey.Shift(AspireTerminalKey)](/reference/api/csharp/aspire.hosting/aspireterminalkey/methods.md#shift-aspireterminalkey), and [AspireTerminalKey.Alt(AspireTerminalKey)](/reference/api/csharp/aspire.hosting/aspireterminalkey/methods.md#alt-aspireterminalkey). For example, `AspireTerminalKey.Ctrl(AspireTerminalKey.R)` sends Control+R. Use [AspireTerminal.SendTextAsync(string, CancellationToken)](/reference/api/csharp/aspire.hosting/aspireterminal/methods.md#sendtextasync-string-cancellationtoken) for arbitrary text rather than individual keys. Key encoding follows the terminal's current input mode; a key does not represent a physical key-down or key-up event.

<a id="sendtextasync"></a>
<a id="sendtextasync-string-cancellationtoken"></a>

## SendTextAsync(string, CancellationToken)

- Name: `SendTextAsync(string, CancellationToken)`
- Returns: `Task`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/AspireTerminal.cs#L98)

Sends text to the terminal's workload as though it had been typed.

```csharp
public sealed class AspireTerminal
{
    public Task SendTextAsync(
        string text,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}
```

## Parameters

- `text` (`string`)
  The text to send.
- `cancellationToken` (`CancellationToken`) `optional`
  Cancellation token.

## Returns

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

## Exceptions

- `ArgumentNullException` -- `text` is `null`.
- `InvalidOperationException` -- The AppHost-owned terminal has already stopped.
- `OperationCanceledException` -- The input operation was canceled by `cancellationToken`.

<a id="show"></a>

## Show

- Name: `Show`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/AspireTerminal.cs#L86)

Reveals the terminal dock in every connected dashboard and switches to this terminal's tab.

```csharp
public sealed class AspireTerminal
{
    public void Show()
    {
        // ...
    }
}
```

## Remarks

Only meaningful for [TerminalPlacement.Dock](/reference/api/csharp/aspire.hosting/terminalplacement/fields.md) terminals. Terminals in a dialog are revealed by that dialog, so this is a no-op for them.

<a id="start"></a>

## Start

- Name: `Start`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/AspireTerminal.cs#L77)

Starts the terminal's workload if it is not already running.

```csharp
public sealed class AspireTerminal
{
    public void Start()
    {
        // ...
    }
}
```

## Exceptions

- `InvalidOperationException` -- The terminal has already stopped.

## Remarks

Starting is the caller's decision, not the dashboard's and not the interaction service's. Call this to have the workload running before anyone is looking at it -- a terminal that is already running when a dialog opens shows its scrollback immediately, and automation can drive a terminal that is never displayed at all.

This is idempotent and does not block: it schedules the workload rather than waiting for it to produce output. Use [AspireTerminal.WaitForTextAsync(string, TimeSpan?, CancellationToken)](/reference/api/csharp/aspire.hosting/aspireterminal/methods.md#waitfortextasync-string-timespan-cancellationtoken) to wait for the workload to reach a known state. It is also a no-op for [TerminalOwner.Resource](/reference/api/csharp/aspire.hosting/terminalowner/fields.md) terminals, whose workload is started by the resource.

<a id="waitfortextasync"></a>
<a id="waitfortextasync-string-timespan-cancellationtoken"></a>

## WaitForTextAsync(string, TimeSpan?, CancellationToken)

- Name: `WaitForTextAsync(string, TimeSpan?, CancellationToken)`
- Returns: `Task`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting/ApplicationModel/AspireTerminal.cs#L135)

Waits until `text` appears on the terminal screen.

```csharp
public sealed class AspireTerminal
{
    public Task WaitForTextAsync(
        string text,
        TimeSpan? timeout = null,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}
```

## Parameters

- `text` (`string`)
  The text to wait for.
- `timeout` (`TimeSpan?`) `optional`
  How long to wait before giving up. Defaults to 30 seconds.
- `cancellationToken` (`CancellationToken`) `optional`
  Cancellation token.

## Returns

`Task` -- A task that completes when the text appears on the terminal screen.

## Exceptions

- `ArgumentNullException` -- `text` is `null`.
- `TimeoutException` -- The text did not appear before `timeout` elapsed.
- `InvalidOperationException` -- The AppHost-owned terminal has already stopped.