TerminalService Methods

ClassMethods3 members

Manages terminals created and owned by the AppHost.

CreateTerminal(TerminalLaunchOptions)AspireTerminal

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

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

TerminalService.cs#L115-L117

Parameters

optionsTerminalLaunchOptionsDescribes the terminal to create.

Returns

AspireTerminal 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

ArgumentNullExceptionoptions or its TerminalLaunchOptions.Title is null.

ArgumentException The TerminalLaunchOptions.Title is empty or consists only of white-space characters.

ArgumentOutOfRangeException The placement in options is not TerminalPlacement.Dock, TerminalPlacement.Dialog, or TerminalPlacement.None.

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.

DisposeAsyncValueTask

Stops and awaits teardown of every terminal this service owns.

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

TerminalService.cs#L477-L506

Returns

ValueTaskA 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.

TryGetTerminal(string, AspireTerminal?)bool

Gets a terminal by id.

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

TerminalService.cs#L234-L249

Parameters

terminalIdstringThe AspireTerminal.Id of the terminal to find.

terminalAspireTerminal?The terminal, if one with that id exists.

Returns

booltrue 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.