Regarding the `MenuCommand.Supported` property in the Visual Studio Extensibility SDK

[astrohart]

My issue is with xml/System.ComponentModel.Design/MenuCommand.xml, located at https://github.com/dotnet/dotnet-api-docs/blob/f5ba02279848e492aa825869ca1fb8d3ad46a5ae/xml/System.ComponentModel.Design/MenuCommand.xml.

The page referenced is the documentation for the MenuCommand.Supported property in the Visual Studio Extensibility toolkit.

When I set MenuCommand.Supported to false, it is not obvious what doing that means.

Nothing changed in the user experience by setting the Supported property to false; that I can see anyway, as a result. That does not mesh with my expectation.

This page is not helpful to me either, as it does not say what happens in Visual Studio's interface, or anywhere else in the user experience if the Supported property is set to false.

This documentation, as written, merely states:

• a) the property exists;
• b) it's a Boolean, and
• c) provides sample code setting the property to true.

But there is no discussion as to what the values true and false for the Supported property actually do, or what the default is.

All of these, I surmise, are essential pieces of information to know as a developer.

My use case is the following:

I am working on an extension that I have forked from someone else, and the author has set Supported to false for a particular MenuCommand they are adding.

Apparently, from my own experience, setting Supported to false does nothing.

The expected behavior from setting Supported to false is for the menu command to:

• a) Not be visible on Visual Studio menus and toolbars (according to where my .vsct has placed it); or,
• b) Showing the command, but graying it out.

Yet the command still appears in the VS menus, is selectable, and, when I, as a user, select the command, the specified handler is executed.

So what does setting Supported to false really even do?

If it does something, I'd like to know.

If it does not (perhaps it's deprecated), then I'd also like to know.

Therefore, I'd like to respectfully suggest augmenting the documentation on this property with a Remarks section that goes into more detail about the outcomes of setting the MenuCommand.Supported property to true versus false.

Thank you in advance for your consideration.

Regards,

Brian Hart

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[astrohart]

This is a bug.

Tagging subscribers to this area: @dotnet/area-system-componentmodel
See info in area-owners.md if you want to be subscribed.

Issue Details

---

My issue is with xml/System.ComponentModel.Design/MenuCommand.xml, located at https://github.com/dotnet/dotnet-api-docs/blob/f5ba02279848e492aa825869ca1fb8d3ad46a5ae/xml/System.ComponentModel.Design/MenuCommand.xml.

The page referenced is the documentation for the MenuCommand.Supported property in the Visual Studio Extensibility toolkit.

When I set MenuCommand.Supported to false, it is not obvious what doing that means.

Nothing changed in the user experience by setting the Supported property to false; that I can see anyway, as a result. That does not mesh with my expectation.

This page is not helpful to me either, as it does not say what happens in Visual Studio's interface, or anywhere else in the user experience if the Supported property is set to false.

This documentation, as written, merely states:

• a) the property exists;
• b) it's a Boolean, and
• c) provides sample code setting the property to true.

But there is no discussion as to what the values true and false for the Supported property actually do, or what the default is.

All of these, I surmise, are essential pieces of information to know as a developer.

My use case is the following:

I am working on an extension that I have forked from someone else, and the author has set Supported to false for a particular MenuCommand they are adding.

Apparently, from my own experience, setting Supported to false does nothing.

The expected behavior from setting Supported to false is for the menu command to:

• a) Not be visible on Visual Studio menus and toolbars (according to where my .vsct has placed it); or,
• b) Showing the command, but graying it out.

Yet the command still appears in the VS menus, is selectable, and, when I, as a user, select the command, the specified handler is executed.

So what does setting Supported to false really even do?

If it does something, I'd like to know.

If it does not (perhaps it's deprecated), then I'd also like to know.

Therefore, I'd like to respectfully suggest augmenting the documentation on this property with a Remarks section that goes into more detail about the outcomes of setting the MenuCommand.Supported property to true versus false.

Thank you in advance for your consideration.

Regards,

Brian Hart

Author:	astrohart
Assignees:	-
Labels:	Pri3, area-System.ComponentModel, :watch: Not Triaged
Milestone:	-

[tarekgh]

@astrohart thanks for reporting this issue.

From looking at the source https://github.com/dotnet/runtime/blob/e4851bcaa7e73d0f4346995c23f12ae7cb56e413/src/libraries/System.ComponentModel.TypeConverter/src/System/ComponentModel/Design/MenuCommand.cs#L38 it states the following:

        /// <summary>
        /// Indicates that the given command is supported. Marking a command
        /// as supported indicates that the shell will not look any further up
        /// the command target chain.
        /// </summary>
        private const int SUPPORTED = 0x01; // tagOLECMDF.OLECMDF_SUPPORTED

Also, Supported property mapped to the OLE OLECMDF_SUPPORTED property which is:

OLECMDF_SUPPORTED	The Automation object supports the command (but it may not be enabled).

Is it enough clarification what Supported property does? or do you have more questions? I agree with you that it would be better to clarify that in the docs. Feel free to submit a PR to update the doc if you like.

[astrohart]

First of all I want to thank you for the reachback.

Secondly, though, what you show is a constant not a property. Also, it strikes me as somewhat ambiguous, that particular XML doc comment.

The reason being is that it doesn't really say what the UI/UX outcomes are...which I think is crucial for a UI/UX component such as a MenuCommand.

I am a contributor to an extension that Mads Kristensen is working on, and he told me setting Supported to false makes the <VisibilityConstraints> tags in the .vsct file (of a VSIX) get respected.

[tarekgh]

First of all I want to thank you for the reachback.

You are welcome!

Secondly, though, what you show is a constant not a property. Also, it strikes me as somewhat ambiguous, that particular XML doc comment.

Right, I didn't mean pointing at that as a public documentation, The constant is what is used to set the property. https://github.com/dotnet/runtime/blob/5e38aec2ee04979c832c945e5a805dbb7c5ae346/src/libraries/System.ComponentModel.TypeConverter/src/System/ComponentModel/Design/MenuCommand.cs#L100 so you may think about it as both means same thing.

The reason being is that it doesn't really say what the UI/UX outcomes are...which I think is crucial for a UI/UX component such as a MenuCommand.

Agree.

I am a contributor to an extension that Mads Kristensen is working on, and he told me setting Supported to false makes the tags in the .vsct file (of a VSIX) get respected.

From reading the code, the Supported property is what is get mapped to OLE value OLECMDF_SUPPORTED and the comment I pasted before is what it does The Automation object supports the command (but it may not be enabled)..
CC @madskristensen here if he can add more details or suggest what need to add to the doc to clarify this Supported property.