IDE execution protocol: need a way to specify browser launch URL for projects

[karolz-ms]

Background and Motivation

The complete launch URL for Aspire dashboard requires an authentication token, which is not stored (for obvious reasons) in the launch profile. In the current implmentation both Visual Studio and Visual Studio Code special-case the Aspire project, combining the dashboard token generation and launch profile settings with the token to construct the final URL.

This is problematic for other tools that want to support the IDE execution protocol for Aspire, because they have to duplicate the same logic, or rely on error-prone app host log scanning. Instead, we should change the implementation so that the application host generates the token as part of the dashboard setup, and the final browse URL (if any) is passed from the app host, via DCP, to the IDE execution endpoint.

Proposed API

The IDE execution protocol https://github.com/dotnet/aspire/blob/main/docs/specs/IDE-execution.md should gain means to specify the browse URL for a debug session creation request. There are at least 3 ways we can go about it.

Option 1: add launch_url (optional) property to the existing project-type launch configuration:

{
    "launch_configurations": [
        {
            "type": "project",
            "project_path": "(Path to Visual Studio project file for the program)",
            "launch_url": "https://localhost:1234/login?t=4a996be5a766e64df6350423ea016cc2"
            // ... other project launch configuration properties
        }
    ]

    // Other session creation request properties
}

Pros: very simple addition to the protocol

Cons: it is a new property for existing launch configuration type (project), and even if it is specified as optional, some tools may report an error encountering a previously unknown property.

Option 2: add a new launch configuration type for data related to browser launch:

{
    "launch_configurations": [
        {
            "type": "project",
            "project_path": "(Path to Visual Studio project file for the program)",
            // ... other project launch configuration properties
        },
        {
            "type": "browser_launch",
            "url": "https://localhost:1234/login?t=4a996be5a766e64df6350423ea016cc2"
        },
    ]

    // Other session creation request properties
}

Pros: launch_configurations was designed from v1 as a collection specifically to separate different concerns associated with launching a program. This option provides clean separation between data associated with launching the dashboard, and the data associated with launching the dashboard client. No change to existing project-type launch configuration.

Cons: some pragmatists may say why employ another object if a single property suffices? But then again, maybe in future we might want more properties related to browser launch.

Option 3: add the browse URL information as a well-knwon "annotation" (requires adding the notion of "annotations" to project launch configuration):

{
    "launch_configurations": [
        {
            "type": "project",
            "project_path": "(Path to Visual Studio project file for the program)",
            "annotations": [
                "launch_url": "https://localhost:1234/login?t=4a996be5a766e64df6350423ea016cc2"
            ]
            // ... other project launch configuration properties
        }
    ]

    // Other session creation request properties
}

Pros: provides more separation between core project launch data and data related to browser launch than option 1 does. Annotations provide loose coupling between Aspire application host and IDE(s) and can be used for other scenarios beyond browser launch.

Cons: similartly to option 1, this introduces new property for existing launch configuration type. Option 2 seems to provide better concern separation AND allow for easier/more thorough request data verification.

Additional notes

• If the browser URL contains secrets (such as is the case with Aspire dashboard URL), it probably makes sense to only add it to the URL if the session with the IDE is secured  (described in https://github.com/dotnet/aspire/blob/main/docs/specs/IDE-execution.md#enabling-ide-execution)

[karolz-ms]

@DamianEdwards @tmat @danegsta @davidfowl FYI

Personally I like option 2 the best but can be convinced to go with any of them. Open to other suggestions.

[karolz-ms]

Also @rafaelldi please share your thoughts!

[rafaelldi]

Hello! Thanks for the mention! Now in our plugin we generate an environment variable DOTNET_DASHBOARD_FRONTEND_BROWSERTOKEN and run the host project with it. Then we use this token to open a browser. But I can change this behavior by using the DCP response instead.

In my opinion, options 1 and 3 can be confusing because the proposed launch_url refers to the entire solution running under a particular AspireHost and not to individual .NET projects within the solution (as far as I understand). Each individual project itself has an applicationUrl in the launchSettings.json file and these two URLs (launch_url and applicationUrl) can be mixed up. I like the second option better.

If the browser URL contains secrets (such as is the case with Aspire dashboard URL), it probably makes sense to only add it to the URL if the session with the IDE is secured

To be honest, I still don't use a certificate when connecting DCP in the plugin. Mainly because for some users (e.g. with different linux distributions), it can be challenging to configure everything. And we only support a local scenario, and if your local machine is compromised, the certificate probably won't help. So I would ask to add a token to the response even in an unsecured session. For example, if the author of the IDE toolkit fully understands the risks and thinks it's ok to use an insecure connection in their case.