Team Foundation Linking Basics
The Linking Service lets you associate artifacts from various sources. This topic explains how artifacts are referenced and linked.
Team Foundation Server URIs
The identifier for an artifact consists of a well-formed Team Foundation Server URI. Each URI is formed by the artifact provider. The following discussion identifies each element of the URI and explains how its value is derived.
The following example shows a prototype of a well-formed Team Foundation Server URI.
vstfs:///<tooltype>/<artifacttype>/<tool-specific id>
Vstfs A constant that may be used as a custom protocol. In version 1.0, it is converted to a URL and made widely available that way.
**<tooltype> **Identifies the tool interface supported by the tool responsible for maintaining and answering questions about the artifact—in other words, the artifact provider. This enables a calling tool (one holding a link) to decide how to handle an artifact based on the interface offered by the tool. For example: vsbug, vsversionstore, and so on. Tooltype identifies the API and is specified by the tool.
**<artifactttype> **The type of artifact that the tool maintains. A tool only supplies an artifact type if the type is immutable. Artifact types are registered by the tool at installation time.
<tool-specific id> An immutable reference to the artifact instance. The tool creates the tool-specific ID and maintains it.
Examples
A URI pointing to a file stored in source control.
vstfs:///vsversionstore/file/b4e3216
A URI pointing to requirement record in work item tracking.
vstfs:///vstfArtifact/vsworkitems/req/345
Encoding and Decoding Artifact URIs
In order to encourage consistent formatting of URIs, Team Foundation Core Services offers a pair of utility functions to encode and decode them based on a structure. These functions, DecodeUri, and EncodeUri are available in the Microsoft.TeamFoundation.Server assembly and namespace through the static LinkingUtilities class.
Loose Coupling vs. Tight Coupling
In the Team Foundation linking environment, tools use links to enable loosely-coupled behavior. Tools can also provide specialized interfaces and interactions that provide a higher-level of specialized integration through tightly-coupled behavior. Each approach is valid in the correct context.
Loose coupling offers these advantages:
You can add new artifact types into a Web of artifacts without disturbing pre-existing applications. This is especially useful for third-party integration.
You can aggregate results to provide a complete "where-used" picture for artifacts of varying types.
Artifact handlers, both providers and consumers, can change behavior drastically. As long as they continue to use the generic linking interfaces, all loosely-coupled behavior will continue to work.
Tools that offer tightly-coupled behavior exploit links that conform to the linking service, but they do not use generic linking interfaces. Instead, an artifact consumer takes advantage of specific interfaces offered by the artifact provider. This behavior can provide cross-tool behavior that is specific to the participating tools.
Loose coupling should be used when:
- A pointer to a referenced artifact can be present in a referring artifact unknown to the referenced artifact’s provider.
For example, a third-party test management tool is introduced into the suite. The tool is Team Foundation -enabled. Therefore, it provides a mechanism to build links to Visual Studio Team System defects. The Visual Studio Team System defect does not have to know about this new type of referring artifact to show return information about it in an inversion query.
A referring artifact can point to a referenced artifact type that the referring artifact does not know about. This mechanism requires a generic artifact picker that is not implemented in version 1.0.
The behavior available for a referenced artifact is not influenced by the referring artifact.
For example, when a user wants to see what work items are associated with a build inside the Visual Studio IDE, the user views the list of work items returned by the inversion query UI for the build. Similarly, when a user wants to see the work items that were affected by a specific changeset, the inversion query UI for the changeset returns a list of work items. In either case, the user should be able to double-click any one of the work items to display a Work Item Tracking document window for that window.
Loosely-coupled interactions are enabled through artifact providers and consumers by:
Following Team Foundation conventions.
Implementing standard interfaces.
How Tools Participate in Linking
Each tool that offers artifacts is an artifact provider. An artifact provider must register its artifact types. It must implement a set of interfaces that enable a loosely-coupled tool to read those artifacts. Artifact provider responsibilities are described in Artifact Provider Obligations.
An artifact provider that also contains links to other artifacts is an artifact consumer. An artifact consumer has some additional obligations beyond those of a provider. An artifact consumer must register link types. Also, it must offer standard methods to answer queries and inversion queries. Responsibilities of an artifact consumer are described in Artifact Consumer Obligations.
Finally, Team Foundation Server provides many facilities for registration, discoverability, and cross-service link query.