{"id":253374,"date":"2025-05-28T08:53:58","date_gmt":"2025-05-28T15:53:58","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/visualstudio\/?p=253374"},"modified":"2025-05-28T08:53:58","modified_gmt":"2025-05-28T15:53:58","slug":"improve-the-commands-in-your-extensions","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/visualstudio\/improve-the-commands-in-your-extensions\/","title":{"rendered":"Improve the commands in your extensions"},"content":{"rendered":"<p>As Visual Studio extension authors, our goal is to create tools that empower developers across diverse environments. A key part of this mission involves ensuring that your extension commands remain accessible and consistent across all Visual Studio locales. In your VSSDK extensions, by adding the <em>CanonicalName<\/em> property to your commands in the .vsct file, you can achieve greater resilience and user satisfaction for your extension.<\/p>\n<p>And with a few simple tricks, you can make your command names a lot prettier as well.<\/p>\n<h2>Why add the <em>CanonicalName<\/em> property?<\/h2>\n<p>When a Visual Studio extension supports multiple locales, the names of commands can vary based on localized resources. While this improves usability in specific languages, it can sometimes lead to inconsistencies or challenges in maintaining a stable reference to commands programmatically. For example, if a command\u2019s name changes between locales, automation scripts, or even third-party integrations referencing that command may break.<\/p>\n<p>The <em>CanonicalName<\/em> property solves this issue by providing a stable, locale-independent identifier for your commands. With this property:<\/p>\n<ul>\n<li><strong>Commands are more predictable<\/strong>: Developers referencing your extension programmatically can rely on a fixed name across all locales.<\/li>\n<li><strong>Better integration<\/strong>: Tools and integrations can seamlessly reference commands without needing locale-specific handling.<\/li>\n<li><strong>Enhanced user experience<\/strong>: End users benefit from consistent behavior and fewer issues caused by localization mismatches.<\/li>\n<\/ul>\n<h2>Step-by-step guide to adding <em>CanonicalName<\/em><\/h2>\n<p>Here\u2019s how you can add the <em>CanonicalName<\/em> property to your commands in the .vsct file of your Visual Studio extension:<\/p>\n<h3>1. Locate Your .vsct File<\/h3>\n<p>The .vsct (Visual Studio Command Table) file defines the commands for your extension. It\u2019s usually found in the root folder of your Visual Studio extension project.<\/p>\n<h3>2. Add the <em>CanonicalName<\/em> Attribute to Commands<\/h3>\n<p>Within the .vsct file, commands are defined using the <em>&lt;Button&gt;<\/em>, <em>&lt;Combo&gt;<\/em> or <em>&lt;Menu&gt;<\/em> elements. To add the <em>CanonicalName<\/em> property, include it as a child inside the <em>&lt;Strings&gt;<\/em> element. Here\u2019s an example:<\/p>\n<pre><code class=\"language-xml\">&lt;Button guid=\"guidMyExtensionCmdSet\" id=\"cmdidMyCommand\" priority=\"0x0100\" type=\"Button\"&gt;\r\n  &lt;Parent guid=\"guidMyExtensionCmdSet\" id=\"MyMenuGroup\" \/&gt;\r\n  &lt;Icon guid=\"guidImages\" id=\"bmpPic1\" \/&gt;\r\n  &lt;Strings&gt;\r\n    &lt;ButtonText&gt;My Command&lt;\/ButtonText&gt;\r\n    &lt;CanonicalName&gt;.MyExtension.MyCommandName&lt;\/CanonicalName&gt;\r\n  &lt;\/Strings&gt;\r\n&lt;\/Button&gt;\r\n<\/code><\/pre>\n<h3>3. Ensure uniqueness of <em>CanonicalName<\/em><\/h3>\n<p>The value you assign to <em>CanonicalName <\/em>must be unique across all commands in your extension. Use meaningful and descriptive identifiers that reflect the command\u2019s purpose.<\/p>\n<h2>Best practices for using CanonicalName<\/h2>\n<ul>\n<li><strong>Use PascalCase<\/strong>: Follow consistent naming conventions like PascalCase for the <em>CanonicalName<\/em> values.<\/li>\n<li><strong>Keep it descriptive<\/strong>: Make the names meaningful to help developers understand the purpose of the command without additional context.<\/li>\n<li><strong>Avoid localization<\/strong>: The <em>CanonicalName<\/em> should always remain in English and free from localization to ensure consistency.<\/li>\n<li><strong>Start with a period<\/strong>: This ensures that nothing is added in front of the command name. This is to avoid command names that look like <em>OtherContextMenus.MyExtension.MyCommandName<\/em>. The leading period is stripped automatically by VS, so it won\u2019t show up.<\/li>\n<li><strong>Lead with the extension name<\/strong>: This is to make it very clear that this command is provided by your extension. It also makes it easy for users to search for all commands provided by your extension.<\/li>\n<\/ul>\n<h2>We\u2019ve updated the XML Schema file<\/h2>\n<p>To reflect this best practice of providing the <a id=\"post-253374-_Int_FiBrOQXS\"><\/a>CanonicalName property with all commands, we\u2019ve updated the schema file to provide in-editor warnings when it is missing. It\u2019s just a warning and it doesn\u2019t affect the VSCT Compiler which will continue to compile the command table as it always has. This is simply a change to make it easier for you to remember to add the property. It will be included in a future update to Visual Studio.<\/p>\n<h3><strong>Conclusion<\/strong><\/h3>\n<p>Adding the <em>CanonicalName<\/em> property to your commands in the .vsct file is a small but impactful change that enhances the resilience and usability of your Visual Studio extensions. By ensuring consistent references across all locales, you\u2019ll provide a smoother experience for developers and maintain a higher-quality extension.<\/p>\n<p>Take a moment to review your extension\u2019s .vsct file and implement this property where necessary. It\u2019s a straightforward step toward making your tools even more powerful and user-friendly.<\/p>\n<p>Happy coding!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>As Visual Studio extension authors, our goal is to create tools that empower developers across diverse environments. A key part of this mission involves ensuring that your extension commands remain accessible and consistent across all Visual Studio locales. In your VSSDK extensions, by adding the CanonicalName property to your commands in the .vsct file, you [&hellip;]<\/p>\n","protected":false},"author":642,"featured_media":253376,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1388,6869,155],"tags":[294],"class_list":["post-253374","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-extensibility","category-reliability","category-visual-studio","tag-extensions"],"acf":[],"blog_post_summary":"<p>As Visual Studio extension authors, our goal is to create tools that empower developers across diverse environments. A key part of this mission involves ensuring that your extension commands remain accessible and consistent across all Visual Studio locales. In your VSSDK extensions, by adding the CanonicalName property to your commands in the .vsct file, you [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/posts\/253374","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/users\/642"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/comments?post=253374"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/posts\/253374\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/media\/253376"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/media?parent=253374"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/categories?post=253374"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/visualstudio\/wp-json\/wp\/v2\/tags?post=253374"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}