🔗 API reference link helper

This handy-dandy extension helps content developers quickly insert and edit cross-reference ("xref") links to the official Microsoft API reference documentation for .NET types and members. It uses the Microsoft Learn API Browser to search for a requested type or member. The extension:

• Exposes the ability to insert a Markdown link in the Markdown or XML file that's open in the active editor.
• Supports different link text variations: display only the type or member name, the member name with its type, the fully qualified name, or custom text.

Requirements

• Visual Studio Code

Example usage

1. With your cursor positioned where you want the link to be inserted in your document, open the command palette F1 and search for Insert XREF Link.

2. Select the command, and when prompted, enter the type or member name you want to link to.

   

3. After a valid search term is entered, the extension searches for the configured API and displays the most relevant results.

   

4. Once you select a result, you're prompted to choose the format of the link you want to insert.

   

   The extension inserts the selected link format into the active editor.

Get started

To install the extension, download the latest xref-helper.vsix file from the .dist/ folder, and from Visual Studio Code, right-click the file and select Install Extension VSIX.

Alternatively, to install the VSIX extension, open the command palette F1 and select Extensions: Install from VSIX.... Then, browse to the downloaded xref-helper.vsix file and select it.

Features

The following URL formats are supported, given the example System.String.Format method when selecting the overloads option and Method overloads search result:

Command pallette commands:

• Insert XREF Link: Inserts a markdown (<xref:uid>) link to the official Microsoft API reference documentation for the selected type or member.
• Insert API Reference Link: Inserts a markdown ([Name](URL link)) link to the official Microsoft API reference documentation for the selected type or member.
• Transform XREF to Other: Convert XREF link between [](xref:) and <xref:>.

Auto-completions:

• XREF Link Completion: When typing <xref:, the extension will suggest the Insert XREF Link as a completion.
• XREF Display Property Completion: When typing <xref:uid?, the extension will suggest the possible display properties as completions.

Code actions:

• XREF Display Property Switch: The quick-edit code action (💡) is displayed when your cursor is on a line that contains an xref link with an existing display property, allowing you to quickly change the display property.

Context menu commands:

• Convert XREF Link: When a full xref link is selected, a context menu command is available to convert the link between [](xref:) and <xref:>.

Search validations

After you start typing, if you delete the text, there's a validation error that will appear. The extension doesn't allow you to insert an empty search term:

The search term cannot contain spaces:

If an opening bracket is specified (i.e. if you're looking for a generic API), the search term must also include the closing bracket:

Extension settings

In Visual Studio Code settings, search for "XREF Helper" (or paste this filter into the search bar @ext:ievangelist.xref-helper). You can configure the following settings:

[
   {
      "name": ".NET",
      "enabled": true,
      "url": "https://learn.microsoft.com/api/apibrowser/dotnet/search",
      "queryStringParameters": [
         {
         "name": "api-version",
         "value": "0.2"
         },
         {
         "name": "locale",
         "value": "en-us"
         }
      ]
   },
   {
      "name": "Java",
      "enabled": false,
      "url": "https://learn.microsoft.com/api/apibrowser/java/search",
      "queryStringParameters": [
         {
         "name": "api-version",
         "value": "0.2"
         },
         {
         "name": "locale",
         "value": "en-us"
         }
      ]
   },
   {
      "name": "JavaScript",
      "enabled": false,
      "url": "https://learn.microsoft.com/api/apibrowser/javascript/search",
      "queryStringParameters": [
         {
         "name": "api-version",
         "value": "0.2"
         },
         {
         "name": "locale",
         "value": "en-us"
         }
      ]
   },
   {
      "name": "Python",
      "enabled": false,
      "url": "https://learn.microsoft.com/api/apibrowser/python/search",
      "queryStringParameters": [
         {
         "name": "api-version",
         "value": "0.2"
         },
         {
         "name": "locale",
         "value": "en-us"
         }
      ]
   },
   {
      "name": "PowerShell",
      "enabled": false,
      "url": "https://learn.microsoft.com/api/apibrowser/powershell/search",
      "queryStringParameters": [
         {
         "name": "api-version",
         "value": "0.2"
         },
         {
         "name": "locale",
         "value": "en-us"
         }
      ]
   }
]