Introduction to Source Links

Source Links connect substrings in comment blocks to external applications and websites, such as bug trackers, case managers, documentation, and source code control systems. Source Links are active in the source files of all programming languages that have comment blocks, not just C/C++ and C#, and are optionally made active in text files.

When Source Links is enabled, comment substrings that match user-defined patterns become active links in the text editor.

Double-Click any link to open a defined target application or website. 

Open Quick Info (Ctrl+K, Ctrl+I) or hover over select links to open a tooltip containing basic information from the target.

Values from the comment substrings, e.g. case number, can be passed to target applications and websites.

Source Links can be defined to recognize many patterns in comments, including the following simple ones:

// bug:4567
// change = 89870
// topic 1554
// topic=1554
// doc 253
// http://www.wholetomato.com

Existing substrings in comment blocks that follow consistent patterns do not need modification to become active links. Defining a pattern and its associated behavior activates the existing substrings.

Access

Source Links are marked in the source editor by a rectangular edge and colored fill. Double-Click (by default) to open. Open Quick Info (Ctrl+K, Ctrl+I) or hover over links defined via plug-in to display optional tooltips.

Enable

Enable and define Source Links in the options dialog for Visual Assist. Default installation of Visual Assist includes example definitions, which you may modify, delete, or leave disabled. If you modify the examples or define new Source Links, installation of future builds of Visual Assist will not overwrite your definitions.

Define

The list of definitions identifies the types of links that Visual Assist might find in source comments. Visual Assist installs with several example definitions, although not all are enabled by default.

Name

Definition names are descriptive only. The names are not used outside of the options dialog.

Plug-In

The plug-in for a definition tells Visual Assist how to process the matching Source Links. The most basic plug-in, None, tells Visual Assist to simply launch a browser or shell command when a Source Link is double-clicked.

No tooltip is shown when hovering over a link.

The Default plug-in tells Visual Assist to show a hovering tooltip as well as support double-click.

All other plug-ins, whether built-in or custom, tell Visual Assist to process a Source Link to a greater extent.

Keywords: Simple Patterns

Keywords begin the patterns within comments that should be made into active Source Links.

Simple patterns match the expression:

<keyword>[<suffix>]<value>

where <keyword> and <suffix> can have multiple values, and where the three components can be separated optionally by whitespace.

Delimit multiple keywords with semicolons. Keywords are not case sensitive, and keywords cannot contain whitespace. For example, keywords "topic;topic-id;topic_id" match the following substrings:

// topic
// TOPIC
// topic-id
// Topic_ID

Suffixes are optional, whether or not any are specified, and whitespace surrounding a suffix is always matched. Specify multiple suffixes without separators. For example, suffixes ":=" match the following:

// topic: 
// TOPIC :
// topic-id =
// Topic_ID

Specify also the type of value that should follow the optional suffix. If type is number, a link becomes active only if the value begins with a digit, and the value terminates on the first non-digit character. For example, the following are all links to forums topic 1554:

// topic: 1554
// TOPIC : 1554foo
// topic-id = 1554
// Topic_ID 1554

If type is string, the value begins with the first non-whitespace character to follow a suffix and terminates on the next whitespace. If a string value in a comment includes whitespace, surround it with single or double quotes.

// author = "John Smith"

Keywords: Regular Expressions

Complex patterns can be described using Regular Expression Language, defined in documentation for the .NET Framework.

Specify a regex pattern by beginning the keyword field with "re=", and follow the prefix with your regex. When in regex mode, the keyword, suffixes, and value fields are replaced with one regex field.

If you intend to pass a value from a Source Link to an external application or website, your regex must include the named group VALUE, as in the example:

bug(?<VALUE>\d+)

which matches the following comment substring and extracts the value 1234 as expected:

// bug1234

If your regex is invalid, the regex field label appears red.

Behavior

Behavior defines the type of action to be taken when a Source Link is double-clicked. The open-URL types invoke a default Internet browser or an in-IDE browser. Shell Execute initiates actions supported by the Process class of the .NET Framework.

Open-URL is allowed for any link definition. Shell Execute is available only when Plug-in is None, Default or Custom (where Custom is a plug-in, unless the plug-in overrides URL, in which case Shell Execute is not available). 

Plug-ins may override execution of a link, in which case behavior is controlled by the plug-in.

URL / Exe

When behavior is open-URL, specify the URL to be invoked when a Source Link is double-clicked. Include $(Value) in the URL; the string will be replaced with a value extracted from a matching pattern. If your URL varies with the keyword matched in a multi-keyword definition, include also $(Keyword). URLs are encoded automatically.

When behavior is Shell Execute, specify the string to be passed to the Start() method of the Process class. Quotes around the string are optional, even if the string includes whitespace.

Exe Args

When behavior is Shell Execute, specify the arguments to be passed to the process. Separate multiple arguments with whitespace. Surround an argument that includes whitespace with quotes. Include any of the following keywords to pass expanded values to the process.

The current directory of an executed process is the directory of the file containing the active Source Link.

Mouse Action to Open

By default, a Source Link can be opened using Double-Click. Choose a different mouse action, and whether link tooltips should include available actions, using the drop-down and checkbox at the top of the options page for Source Links.

When enabled, available actions are displayed at the bottom of tooltips.

Color

Specify color of the rectangular edge and fill of Source Links by setting the foreground and background, respectively, of "VA Source Links Marker" in the options dialog of the IDE.

Default background, i.e. fill, differs slightly from background of plain text to make the link standout. If you wish to mark links with only an edge color, you must set background to a custom color--the background of plain text.

RGB values for plain text backgrounds of built-in themes are:

• Blue: 255 255 255
• Dark: 30 30 30
• Light: 255 255 255

Export/Import

Settings associated with Source Links, including link definitions, are stored per version of Visual Studio. The steps to transfer settings, i.e. copy or move settings of Visual Assist from one development environment to another, include those for Source Links.

If you want to export and import only the settings unique to the Source Links, exit your IDEs and copy the SourceLinks sub-key in the registry for one IDE to the sub-key of another IDE, or to the registry of a different development environment, e.g. different PC.

HKCU\Software\Whole Tomato\Visual Assist X\<IDE spec>\SourceLinks

In the resulting registry script, before import, account for settings that depend on paths or custom plug-ins.

NB. Link color is not stored in the SourceLinks sub-key so it will not be copied.

If copying to a different development environment, copy also the plug-in settings associated with the link definitions:

%APPDATA%\VisualAssist\SourceLinks

Standalone Extension

Source Links integrated in Visual Assist is an enhanced version of the standalone extension formerly available in the Visual Studio Marketplace. Definitions of links created in the standalone extension must be recreated manually in the integrated version. Export/import is not available.

Uninstall the standalone SourceLinks extension if you migrate to the version integrated in Visual Assist.

Registry Settings