Wiki

Options

Case Status
Log In

Wiki

Options

 
Whole Tomato Software - Home
  • RSS Feed

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. 

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
// 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 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:

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.

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.


     
  • URL Navigation: Applicable when substrings in comments match URL syntax. Behavior is typically set to open in an external browser, in which case links are opened using one's default browser, which may or may not be Internet Explorer.



    Configure the URL Navigation plug-in if you want to activate also website addresses written without a protocol, e.g. without http.



    In the configuration dialog, specify the prefixes of the addresses you want to activate. Listing the prefixes prevents Visual Assist from activating non-address substrings.

     

    Because Visual Studio also has the ability to open hyperlinks in comments, hyperlinks may appear marked by Visual Assist and by the IDE.



    Visual Studio 2017 15.3 and newer versions can open hyperlinks the IDE recognizes in an external browser, but all older versions of Visual Studio open hyperlinks in an internal browser only. To use only Source Links, disable URL navigation in the options dialog of the IDE.

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.

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

Custom Plug-Ins Location

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.

Specify the directory(ies) containing custom plug-in(s) in the options dialog for Visual Assist. One list of directories is searched to find all custom plug-ins.

Also, do not move PluginSDK.dll from its installation directory, as is true for all dlls installed by Visual Assist. Although required by custom plug-ins, the PluginSDK.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.

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.

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 SourceLinks extension if you migrate to the version integrated in Visual Assist.

Registry Settings

Value Name Meaning
EnableInPlainText Enable Source Links in text files

Visual Studio 2008 and older

Source Links are not available.