VSSDK003 flags toolwindows using ToolWindowCreationContext.Unspecified

[jasonmalinowski]

Bug description

VSSDK003 (use async tool windows) still fires if you're using ToolWindowCreationContext.Unspecified, and doesn't hint at what you should do to make it go away then.

• Version of the vssdk-analyzers: 15.7.7 I think (great is the mystery of NuGet!)
• Analyzer rule: VSSDK003
• Error (exception message, type, and callstack where applicable): n/a

To Reproduce

We had an existing class that defined a tool window, and we moved to the newer analyzers which (correctly) suggested to move to an async tool window. I did my first pass overriding the methods of AsyncPackage, but I couldn't get the diagnostic to go away. I was using ToolWindowCreationContext.Unspecified in InitializeToolWindowAsync to specify that my tool window constructor didn't need to get anything -- at least initially while I was trying to get everything else to work -- but the analyzer was still complaining.

I was able to figure out what was going on by finding the analyzer code and reading it, which quickly revealed the problem. But hey, I work on Roslyn, so that's "easy" for me. 😄

Expected behavior

Once I had overridden the methods in AsyncPackage, the diagnostic would go away. I kept assuming that because I was still getting the diagnostic, I had missed some overload.

Actual behavior

The analyzer is actually looking entirely at the constructor of the ToolWindow to see if there's a non-default constructor. Although the presence of one does indicate it's an async tool window, the absence doesn't necessarily. In any case, I ran around in circles trying to figure out what I was doing wrong.

Suggested behavior

In a perfect world the analyzer could see what was happening and realized it was fine, but that's hard. A good heuristic might be that default constructors are OK if InitializeToolWindowAsync somewhere has a reference to ToolWindowCreationContext.Unspecified. Or, if the analyzer sees a reference to Unspecified, consider reporting a different message that tells you it might be OK, and you should just use a constructor to ensure it's safe.

Or, absent of code changes, just update the docs that if you use Unspecified, the analyzer will still be "wrong". That at least wouldn't have sent me down a path of assuming I'm doing something wrong.

[AArnott]

Thanks for the great write-up of the problem you found and suggestions for the resolution.
Async tool windows are indeed one of the more complicated things both to test for (which is why I took shortcuts that I thought were heuristically sufficient) and IIRC we don't offer a code fix for it.
I suspect we can take your suggestions though.

[jasonmalinowski]

@AArnott Happy to do so! And in my case, even just a small doc update or something would have been useful. Honestly, what was the trickiest part was actually finding any docs saying what should be done; if there was simple step-by-step that was "override these methods, do this", you could easily have a note there which is "you need a non-default constructor to make the analyzer happy", and I wouldn't have given it much of a second thought.

[reduckted]

I think I've come across a similar bug, so rather than opening a new issue, I'll add to this one.

The Community.VisualStudio.Toolkit is about to introduce helper classes for creating async tool windows: madskristensen/Community.VisualStudio.Toolkit#25

The only downside to those helper classes is that the VSSDK003 analyzer warning is produced, even though the tool windows are being created asynchronously.

The PR I linked above contains the full sample code, but the two key parts are:

1. You inherit from ToolkitPackage instead of AsyncPackage.
2. The tool window has a parameterless constructor.

Under the hood, the ToolkitPackage class creates the tool windows asynchronously. Any asynchronously resolved services that are needed by the tool window are resolved during the InitializeToolWindowAsync method and the helper class implementation uses those services to create the tool window's Content property value rather than passing those services to the tool window's constructor.