Registering error strings for custom HRESULTs

Summary

Historically, if you had a VS debugger extension (Concord or otherwise) that wanted to fail requests from the UI with custom message strings there wasn't a great way to get the UI to show these strings -- you could send message events, but there was no way to register custom error codes. Starting in 16.11, this is now possible.

Steps

Create a native resource dll that will compile your HRESULTs with the Message Compiler:

1. Add a new empty native project to your solution. Note that you want a native project even if the rest of your project is managed. If you already have a native resource dll you can reuse it.
2. Change your project to be a resource-only dll:
   • Change 'Configuration Type' to be 'Dynamic Library (.dll)'
   • In linker settings, disable generating debug information, and enable 'No Entry Point'
3. Add a '.mc' file to your project. There is no template for these, so you can just add a new .txt file and rename it. You can grab the example content below.
4. Unload your project and add build steps for compiling the .mc file. See example below.
5. Modify your .vsix project to ship this dll

Register the native resource dll

Open your .pkgdef file (or add one if you don't have one already in your .vsix project) and add something like the following:

[$RootKey$\Debugger\ErrorResources\123]
"ResourceDll"="$PackageFolder$\MyResources.dll"

Where:

• 123 is your HRESULT facility code from your .mc file.
• $PackageFolder$\MyResources.dll is the path to your resources dll. If your resources are localized and so you have multiple resource dlls, you can insert a * into the path that will be replaced with the locale id (ex: 1033 is EN-US). For example: $PackageFolder$\*\MyResources.dll

Example .mc file

MessageIdTypedef=HRESULT

SeverityNames=(Success=0x0
               CoError=0x2
              )

FacilityNames=(ExampleFacility=0x123:FACILITY_EXAMPLE
              )

;//
;//  Collection error codes
;//
;

MessageId=0x1 Facility=ExampleFacility SymbolicName=EXAMPLE_E_ONE
Severity=CoError
Language=English
Localized message text goes here.
.

See docs.microsoft.com for more information on the syntax of .mc files.

Example steps to compile Messages.mc

  <ItemGroup>
    <CustomBuild Include="Messages.mc">
      <FileType>Document</FileType>
      <Command>mc.exe -b Messages.mc -r $(IntermediateOutputPath) -h $(IntermediateOutputPath)</Command>
      <Outputs>$(IntermediateOutputPath)Messages.rc;$(IntermediateOutputPath)\Messages.h</Outputs>
    </CustomBuild>
  </ItemGroup>
  <ItemGroup>
    <ResourceCompile Include="$(IntermediateOutputPath)Messages.rc">
      <AutoGen>True</AutoGen>
      <DesignTime>False</DesignTime>
      <DependentUpon>Messages.mc</DependentUpon>
    </ResourceCompile>
  </ItemGroup>

See docs.microsoft.com for more information on the mc.exe command line arguments.