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.

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"

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.

Only the open-URL behaviors are allowed when a definition employs a 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.

Plug-ins

Plug-ins can 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.

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

By default, plug-ins must re-installed to the default installation directory of Visual Assist every time you install a new build of Visual Assist. You can specify an alternate location of plug-ins by editing the registry.

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

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 Setting

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

Visual Studio 2008 and older

Source Links are not available.