Case Status
Log In

Wiki

Options

 
Whole Tomato Software - Home
  • RSS Feed

Introduction to Source Links

Source Links connect comment substrings to external applications and websites, such as bug trackers, case managers, documentation, and source code control systems. Comment substrings that match user-defined patterns are automatically active links in the text editor.

Double-Click any link to open a defined target application or website. Hover over select links to open tooltips 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

Existing substrings in comments that follow consistent patterns do not need modification to become active links. Defining a pattern and resulting behavior activates existing substrings.

Access

Source Links are marked in the source editor by a rectangular edge and colored fill. Double-Click to open or hover over links defined via plug-in to display optional tooltips.

Enable

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 summarizes all links, which can be enabled/disabled individually.

Name

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

Simple Link Patterns

Substrings in comments that follow simple patterns can be made active Source Links using the keywords, suffixes, and value fields of a definition.

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.

Separate multiple keywords with semicolons. Keywords are not case sensitive. 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 an 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 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"

Complex Link Patterns

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:

(?:case|bug)\s*[:=]\s*(?<VALUE>\d+)

which matches the following comment substrings and extracts values as expected:

// bug:1234
// bug = 1234
// case 1234
// [case 1234]

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.

Keyword Expanded value
$(Keyword) Keyword of the activated link
$(Value) Value of the activated link
$(SolutionPath) Solution path
$(SolutionFileName) Solution file name without extension, from System.IO.Path.GetFileNameWithoutExtension
$(SolutionExt) Solution file extension, from System.IO.Path.GetExtension
$(ProjectDir) Project directory
$(ProjectPath) Project path
$(ProjectFileName) Project file name without extension
$(ProjectExt) Project file extension
$(FileDir) Current file directory
$(FilePath) Current file path
$(FileName) Current file name without extension
$(FileExt) Current file extension

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

Default Plug-ins

Plug-ins are available, and can be written, to handle more sophisticated activation of Source Links. Plug-ins can login to target applications or websites, maintain sessions, display hovering tooltips, access the user environment, and open dialogs to prompt for user input. After verifying or collecting needed information, plug-ins typically open URLs or execute shell commands.

Plug-ins provided with Visual Assist are:

  • None: Applicable when behavior is open URL or shell execute. No tooltip is shown when hovering over a link. Double-click of a link launches a browser or shell command without additional setup, i.e. login.

     
  • Default: Applicable when behavior is open URL or shell execute. Tooltips containing expanded URLs or shell commands appear when hovering. Double-click of a link launches a browser or shell command without additional setup.

     
  • FogBugzPlugin: Applicable when behavior is open URL and links are targeted to FogBugz case navigation. A tooltip containing information about the respective case appears when hovering.


    The FogBugz plug-in requires configuration before tooltips are displayed or the respective links become active.

     
  • GitHubPlugin: Applicable when behavior is open URL and links are targeted to GitHub issue navigation. A tooltip containing information about the respective issue appears when hovering.


    The GitHub plug-in requires configuration before tooltips are displayed or the respective links become active.

Custom Plug-Ins

Create a custom plug-in using the Source Links Example Plugin hosted at GitHub. Instructions can be found in Plugin.cs within the repository.

Default plug-ins are located in the installation directory of Visual Assist, but that directory changes every time you install a new build, or reinstall a build, of Visual Assist. Prior installation directories are deleted! Therefore, you should not install a custom plug-in to the installation directory of Visual Assist. Instead, specify a location of Source Links plug-ins by editing the registry.

Do not move PluginSDK.dll from its installation directory (as is true of all dlls installed by Visual Assist). Although required by custom plug-ins, the dll is also required by the default plug-ins and by Visual Assist. If a change to the dll requires recompiling of custom plug-ins, the need will be highlighted in the release notes for Visual Assist.

The current directory of any plug-in that launches is the directory of the file containing the activated Source Link.

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

Link Precedence

If a comment string matches multiple link definitions, the link defined earliest in the list of definitions is the active one. For example, separate definitions for URLs—the first with keywords http and https, and the second with keyword www—both may appear active in the editor but Double-Click activates only the first definition.

Drag and drop link definitions to change their order.

Export/Import

Settings associated with Source Links, including link definitions, are stored per version of Visual Studio. Visual Assist does not provide a UI for exporting and importing settings unique to the Source Links feature (of course, normal Visual Assist settings export includes Source Links settings). Use regedit to copy settings from one version of Visual Studio to another, or from one PC to another. Exit your IDEs and copy the SourceLinks sub-key for one IDE to that of another:

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

Account for settings that depend on paths or custom plug-ins.

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

Standalone Extension

Source Links integrated in Visual Assist is an enhanced version of the standalone extension 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 extension if you migrate to the integrated version.

Registry Settings

Value Name Meaning
EnableInPlainText Enable Source Links in text files
PluginPaths Specify a location of Source Links plug-ins

Visual Studio 2008 and older

Source Links are not available.