DebugSupportExtensions Methods

ClassMethods3 members

Extension methods for inspecting whether a resource will be launched by an IDE or extension host for debugging rather than started as a plain process by Aspire.

CreateLaunchConfigurationAsync(IResource, string, CancellationToken)extensionTask<object>

Creates the launch configuration that this resource sends to the IDE for the given launch mode.

public static class DebugSupportExtensions
{
    public static Task<object> CreateLaunchConfigurationAsync(
        this IResource resource,
        string mode,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        // ...
    }
}

DebugSupportExtensions.cs#L131-L139

Parameters

resourceIResourceThe resource to inspect. It must carry a SupportsDebuggingAnnotation.

modestringThe launch mode, one of the values on ExecutableLaunchMode.

cancellationTokenCancellationTokenoptionalA token to cancel the operation.

Returns

Task<object>The launch configuration, typically an ExecutableLaunchConfiguration.

Exceptions

ArgumentNullExceptionresource or mode is null.

InvalidOperationExceptionThe resource does not declare debug launch support.

Remarks

Launch configuration is created by invoking the producer callback passed to a WithDebugSupport overload on ResourceBuilderExtensions, which owns the complete configuration; Aspire serializes the result as-is. The configuration is produced fresh on each call. Aspire may call the producer several times for the same resource.

This overload does not resolve the resource's environment variables. A context-based producer receives an empty environment. Aspire's executable creation path supplies the resolved environment through the context-aware overload.

This describes the launch configuration itself, not whether one is going to be used. Depending on how the application is started, or how a resource is configured, Aspire may or may not run the resource under a debugger. Use DebugSupportExtensions.SupportsDebugging to test for that.

HasLaunchToolArgsOwnedBy(IResource, SupportsDebuggingAnnotation)extensionbool

Determines whether the launch configuration performs the resource's tool invocation itself, meaning the resource's launch tool arguments must not also be passed to the launched program.

public static class DebugSupportExtensions
{
    public static bool HasLaunchToolArgsOwnedBy(
        this IResource resource,
        SupportsDebuggingAnnotation supportsDebuggingAnnotation)
    {
        // ...
    }
}

DebugSupportExtensions.cs#L90-L95

Parameters

resourceIResourceThe resource to inspect.

supportsDebuggingAnnotationSupportsDebuggingAnnotationThe launch configuration annotation to compare.

Returns

booltrue when the launch configuration supplies the tool invocation; otherwise, false.

Remarks

This is false for a resource whose launch tool arguments declare no owning launch configuration type, because such a prefix is always passed to the program.

SupportsDebugging(IResource, IConfiguration, SupportsDebuggingAnnotation?)extensionbool

Determines whether the resource will be launched by the IDE for debugging in the current session.

public static class DebugSupportExtensions
{
    public static bool SupportsDebugging(
        this IResource resource,
        IConfiguration configuration,
        out SupportsDebuggingAnnotation? supportsDebuggingAnnotation)
    {
        // ...
    }
}

DebugSupportExtensions.cs#L46-L73

Parameters

resourceIResourceThe resource to inspect.

configurationIConfigurationThe AppHost configuration, used to detect the active debug session and its capabilities.

supportsDebuggingAnnotationSupportsDebuggingAnnotation?When this method returns true, the annotation describing how the resource is launched.

Returns

booltrue when the IDE owns launching this resource; otherwise false.

Remarks

Integrations use this to decide whether to build a runnable command line for the resource. When the IDE launches the resource, arguments such as dotnet run --project … or go run … are supplied by the IDE instead and must not be produced by the integration.

A resource is only considered debuggable when it carries a SupportsDebuggingAnnotation, a debug session is active, the resource is not forced to process execution, it does not have a persistent lifetime, and the IDE advertised support for the annotation's launch configuration type.

Exception: when the active debug session did not provide a usable launch configuration capability list (for example Visual Studio, which does not send one), a non-file-based resource whose launch configuration type is KnownLaunchConfigurationTypes.Project is treated as implicitly supported. File-based C# apps require explicit IDE support because Visual Studio can only launch projects loaded in the solution.