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 can achieve greater resilience and user satisfaction for your extension.
And with a few simple tricks, you can make your command names a lot prettier as well.
Why add the CanonicalName property?
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’s name changes between locales, automation scripts, or even third-party integrations referencing that command may break.
The CanonicalName property solves this issue by providing a stable, locale-independent identifier for your commands. With this property:
- Commands are more predictable: Developers referencing your extension programmatically can rely on a fixed name across all locales.
- Better integration: Tools and integrations can seamlessly reference commands without needing locale-specific handling.
- Enhanced user experience: End users benefit from consistent behavior and fewer issues caused by localization mismatches.
Step-by-step guide to adding CanonicalName
Here’s how you can add the CanonicalName property to your commands in the .vsct file of your Visual Studio extension:
1. Locate Your .vsct File
The .vsct (Visual Studio Command Table) file defines the commands for your extension. It’s usually found in the root folder of your Visual Studio extension project.
2. Add the CanonicalName Attribute to Commands
Within the .vsct file, commands are defined using the <Button>, <Combo> or <Menu> elements. To add the CanonicalName property, include it as a child inside the <Strings> element. Here’s an example:
<Button guid="guidMyExtensionCmdSet" id="cmdidMyCommand" priority="0x0100" type="Button">
<Parent guid="guidMyExtensionCmdSet" id="MyMenuGroup" />
<Icon guid="guidImages" id="bmpPic1" />
<Strings>
<ButtonText>My Command</ButtonText>
<CanonicalName>.MyExtension.MyCommandName</CanonicalName>
</Strings>
</Button>
3. Ensure uniqueness of CanonicalName
The value you assign to CanonicalName must be unique across all commands in your extension. Use meaningful and descriptive identifiers that reflect the command’s purpose.
Best practices for using CanonicalName
- Use PascalCase: Follow consistent naming conventions like PascalCase for the CanonicalName values.
- Keep it descriptive: Make the names meaningful to help developers understand the purpose of the command without additional context.
- Avoid localization: The CanonicalName should always remain in English and free from localization to ensure consistency.
- Start with a period: This ensures that nothing is added in front of the command name. This is to avoid command names that look like OtherContextMenus.MyExtension.MyCommandName. The leading period is stripped automatically by VS, so it won’t show up.
- Lead with the extension name: 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.
We’ve updated the XML Schema file
To reflect this best practice of providing the CanonicalName property with all commands, we’ve updated the schema file to provide in-editor warnings when it is missing. It’s just a warning and it doesn’t 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.
Conclusion
Adding the CanonicalName 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’ll provide a smoother experience for developers and maintain a higher-quality extension.
Take a moment to review your extension’s .vsct file and implement this property where necessary. It’s a straightforward step toward making your tools even more powerful and user-friendly.
Happy coding!
The post Improve the commands in your extensions appeared first on Visual Studio Blog.
