Debugging a distributed application usually means moving between several tools.
You may start with the application dashboard, switch to a terminal to inspect a container, open another terminal for logs, and then return to the dashboard to check whether another service is failing.
.NET Aspire 13.6 improves this local development experience by adding a more capable terminal experience directly inside the Aspire Dashboard. The release includes a persistent, resizable terminal dock, detached terminal windows, and resource or AppHost-owned terminal sessions. It also adds database REPL support for several database and cache resources.
That matters because the dashboard already knows about the resources in your distributed application. Having terminal access alongside resource status, logs, metrics, and traces makes it easier to investigate a problem without constantly switching context.
This article explains how to use the capability, where it helps, and what developers should keep in mind when debugging containers.
What Changed in Aspire 13.6?
Aspire 13.6 adds a persistent terminal dock to the dashboard. The terminal can be resized, opened in tabs, or detached into its own window. The new terminal rendering system also improves copy and paste behavior and provides sizing controls.
The release also adds AppHost-owned interactive terminals, allowing an AppHost to create terminal processes that are not necessarily tied directly to a DCP-managed resource. These terminals can appear in the dashboard dock or in a separate dialog or window.
For developers, the practical difference is straightforward:
Before
Aspire Dashboard
|
+---- Logs
+---- Metrics
+---- Traces
Separate Terminal
|
+---- Container inspection
+---- Commands
+---- Database toolsWith the newer dashboard experience:
Aspire Dashboard
|
+---- Resources
+---- Logs
+---- Metrics
+---- Traces
|
+---- Terminal
|
+---- Commands
+---- Container inspection
+---- REPLThe goal is not to replace your normal terminal. It is to put runtime investigation closer to the application context.
Why Container Debugging Needs This Context
Consider a local application with several services:
Aspire
|
+---------------+---------------+
| | |
v v v
API PostgreSQL Redis
|
v
FrontendSuppose the API reports a database connection error.
You need to answer several questions:
Is PostgreSQL running?
Is the database accepting connections?
Is the API using the correct endpoint?
Is the expected database present?
Are the required environment variables available?
Is the problem inside the API or the database?
The dashboard can show resource state and telemetry.
The terminal gives you another level of inspection.
That combination is useful because you can move from:
Something is failing
|
v
Dashboard
|
v
Identify the resource
|
v
Terminal
|
v
Inspect the runtimeOpening the Terminal
Aspire 13.6 provides a terminal dock directly in the dashboard. The terminal can remain available while you move between dashboard views, and terminal sessions can also be detached into separate windows.
This is useful during a debugging session because you can keep the terminal open while checking resource logs.
For example:
+------------------------------------------------+
| Aspire Dashboard |
| |
| Resources | Logs | Traces | Metrics |
| |
|------------------------------------------------|
| Terminal |
| |
| $ pwd |
| $ ls -la |
| $ dotnet --info |
| |
+------------------------------------------------+The exact commands available depend on the resource and its environment.
Inspecting a Container
Suppose your AppHost includes a PostgreSQL resource.
A simplified AppHost might look like this:
var builder = DistributedApplication.CreateBuilder(args);
var postgres = builder
.AddPostgres("postgres")
.AddDatabase("appdb");
var api = builder
.AddProject<Projects.Api>("api")
.WithReference(postgres);
builder.Build().Run();When the application is running, Aspire understands that the API depends on PostgreSQL.
If the database behaves unexpectedly, the dashboard gives you the application-level view, while terminal access lets you inspect the runtime environment.
Depending on the resource, you may be able to run commands that inspect files, environment information, processes, or available tools.
For example:
pwdand:
ls -lacan help establish where you are and what files are available.
Checking the Runtime Environment
One of the first things to check when a container behaves differently from your local machine is the runtime environment.
For a .NET container:
dotnet --infocan show the installed .NET SDK and runtime information.
You can also inspect the operating system:
uname -aif the command is available.
The point is to replace assumptions with evidence.
Instead of assuming that the container has the runtime you expected, inspect it.
Checking Environment Variables Safely
Configuration is another common source of container problems.
You may need to determine whether a required variable exists.
For example:
if [ -n "$ASPNETCORE_ENVIRONMENT" ]; then
echo "Environment variable is configured"
else
echo "Environment variable is missing"
fiThis is safer than dumping the entire environment.
Avoid casually running:
envin an environment that contains secrets.
Environment variables may contain:
Connection strings
API keys
Access tokens
Passwords
Cloud credentials
The dashboard and terminal make investigation easier, but they do not remove the need for careful handling of sensitive information.
Debugging a Database Connection
Suppose the API cannot connect to PostgreSQL.
Start by checking whether the PostgreSQL resource is running.
Then inspect the application logs.
If the error looks like:
Connection refusedyou can investigate the database environment.
If the PostgreSQL client is available, you can check its version:
psql --versionYou can then use the appropriate connection information to test connectivity.
For example:
psql \
-h "$POSTGRES_HOST" \
-U "$POSTGRES_USER" \
-d "$POSTGRES_DB"The exact variables depend on how your application is configured.
Do not paste real passwords directly into commands or source files.
Database REPLs
Aspire 13.6 also adds opt-in REPL commands for database and cache integrations. The release includes bundled clients for PostgreSQL, MySQL, MongoDB, SQL Server, Redis, and Valkey.
This can make database troubleshooting more convenient.
For example, instead of manually finding the container and starting a client, the resource can expose an appropriate interactive database command through the Aspire development experience.
The workflow becomes:
Database Resource
|
v
Resource Command / REPL
|
v
Database Client
|
v
Inspect DataThis is particularly useful for local development and debugging.
It should not be interpreted as a reason to give developers unrestricted database access in production.
Join the conversation! Your thoughts help the community grow.