Improve messaging when trying to connect to an app in release mode

[johnpryan]

When an app is running in release mode, and I run the "Open DevTools in Web Browser" command, I get this warning:

Could we detect when the launch configuration's flutterMode is set to release and point users to the documentation?

[DanTup]

@johnpryan are you using current stable Flutter? I changed this message in 68cf41f but it requires flutter/flutter#106337 (in theory we might be able to check the mode another way, but since this is already I'm inclined to just wait for it to ship).

I will add a "More info" button that links to those docs though.

[DanTup]

@johnpryan can you confirm exactly where we should link to? The link above seems to be related to profile mode, but this issue is only about release mode?

[johnpryan]

That's a good point, the Flutter performance profiling page isn't quite right because it's also common to use DevTools in Debug mode. I'm not sure we have a place in our docs that says DevTools should only be run in Debug or Profile mode, not Release mode.

[DanTup]

Ah, in that case is there anything else to do here? The current message (when running on latest code) says:

DevTools is not available for an app running in this mode.

We could make this more specific (release/profile mode), however it requires making some assumptions in VS Code that I'd rather avoid (there are many ways the user could start the app in profile/release mode that are harder for us to detect).

[johnpryan]

I would prefer if it said "DevTools only supports Debug or Profile mode". The current gives two possible explanations, which can lead to confusion and doesn't tell the user how to resolve the issue.

Is there a way to detect that the debug session isn't ready yet so that we can disambiguate these two scenarios?

[DanTup]

I would prefer if it said "DevTools only supports Debug or Profile mode".

Isn't it the case that profile mode for Web doesn't support DevTools (it doesn't have a VM Service)? (see flutter/devtools#3969 (comment)). If so, could it be confusing to say it's only available in debug/profile mode if the user is running a profile (web) build?

Is there a way to detect that the debug session isn't ready yet so that we can disambiguate these two scenarios?

That's what the changes above do. With the latest code (if you're using Flutter master (or beta?)) we will show the new message posted above if we know the debug session has started, and otherwise show the old one (from your screenshot). In a future release, we could drop the "or does not support DevTools" part from that last message so that last message is less vague.

Dart-Code/src/extension/commands/debug.ts

Lines 137 to 147 in ecad283

	if (session.vmServiceUri) {
	return this.devTools.spawnForSession(session as DartDebugSessionInformation & { vmServiceUri: string }, { notify, page });
	} else if (session.session.configuration.noDebug) {
	vs.window.showInformationMessage("You must start your app with debugging in order to use DevTools.");
	} else if (session.hasStarted) {
	vs.window.showInformationMessage("DevTools is not available for an app running in this mode.");
	} else {
	// TODO: Remove the last part of this after the next Flutter release (after 3.0) when the appStarted event
	// is passed.
	vs.window.showInformationMessage("This debug session is not ready yet or does not support DevTools.");
	}

[johnpryan]

Isn't it the case that profile mode for Web doesn't support DevTools

That's a good point, maybe we could link to a compatibility table in the docs or something...

In a future release, we could drop the "or does not support DevTools"

Sounds good

[johnpryan]

Related to flutter/devtools#4050

[johnpryan]

I filed an issue to add a warning about web support flutter/website#7887

[DanTup]

That's a good point, maybe we could link to a compatibility table in the docs or something...

Is there an existing one I can link to? If not, if we can add one I can add a "more info" button here to link to it.

[johnpryan]

No, I don't think we have a compatibility table in the docs right now.

[github-actions]

This issue has been marked stale because it is tagged awaiting-info for 20 days with no activity. Remove the stale label or comment to prevent the issue being closed in 10 days.

[DanTup]

@johnpryan is there still work to do here? We can add a link to the message if there's somewhere appropriate to link to. The text has been tweaked slightly since the issue was originally reported:

Dart-Code/src/extension/commands/debug.ts

Lines 139 to 147 in 5a6e976

	} else if (session.session.configuration.noDebug) {
	vs.window.showInformationMessage("You must start your app with debugging in order to use DevTools.");
	} else if (session.hasStarted) {
	vs.window.showInformationMessage("DevTools is not available for an app running in this mode.");
	} else {
	vs.window.showInformationMessage("This debug session is not ready yet.");
	}
	}));

[johnpryan]

Here's the link to the docs on profile mode, which has a warning about web + profile mode: https://docs.flutter.dev/perf/ui-performance#run-in-profile-mode. It would be great to provide more info about why DevTools is unavailable if we can.

[DanTup]

It would be great to provide more info about why DevTools is unavailable if we can.

What sort of explanation would you like to see? I could update flutter_tools to tell us the mode (debug/profile/release) and we could show something like "DevTools is not available for [mode] mode on device [deviceId]" (edit: started here). We would be assuming (from VS Code) that if there is no VM Service that this message is accurate. I don't know if it adds a whole lot over the message above, but it would explicitly show the user what mode is running.

I found this page which lists which part of DevTools are available for each platform:

https://dart.dev/tools/dart-devtools

I wonder if including which modes in this chart would make sense too, and then it would be a good reference to link to?

[github-actions]

This issue has been marked stale because it is tagged awaiting-info for 20 days with no activity. Remove the stale label or comment to prevent the issue being closed in 10 days.

[johnpryan]

"DevTools is not available for [mode] mode on device [deviceId]" would definitely help here, the table at https://dart.dev/tools/dart-devtools is also handy, but doesn't contain any information about whether the user is in run/profile/release mode

[DanTup]

Ok, I've updated so it'll look like this:

It requires both flutter/flutter#121239 and a change here in the VS Code extension, so it'll still show the old message until you're using updated versions of each.

I haven't added a link to the page above for now, since it doesn't mention modes - however if it's reasonable for that page to be updated to mention modes, we could easily add a button here.