Team Foundation Core Services

The Team Foundation Core Services (TFCS) are a set of services, running on the application tier, which allow you access to different aspects of Team Foundation Server, including administration, security, and events. TFCS consists of five services:

• Classification service - Provides access to Team Project information.

• Eventing service - Provides access to events thrown by Team Foundation Server

• Linking service - Provides ability to link items together, such as work items and files that are version controlled

• Registration service - Points Team Foundation Server to the correct tools and services

• Security service - Provides ability to manage groups, users, and permissions

These services are implemented as Web services, and are used by Team Explorer and the different areas of Team Foundation Server. When utilizing the Team Foundation Core Services, you should not call the Web services directly. Instead, you should use the Team Foundation Object Model to interact with the Team Foundation Core Services. Microsoft will provide backward compatibility with the object model only, not the Web services, so you should use the object model to ensure your applications work with future versions of Team Foundation Server.

In the following sections, you will learn about each service and what it does. You can learn even more about the Team Foundation Core Services and the Team Foundation Object Model by downloading the Visual Studio 2005 SDK. This SDK contains documentation and examples of both the Team Foundation Core Services and the Team Foundation Object Model, as well as examples on how to extend Team Foundation Server in other ways. You can find it at http://affiliate.vsipmembers.com. Membership with the Visual Studio Industry Partner program is required, but membership is free. Just sign up and download the SDK.

Classification Service

The classification service provides access to Team Project information, including the Team Project name and URI, as well as access to the areas and iterations of a Team Project. Remember, the Area and Iterations section of a Team Project is essentially the structure of the project. This service allows you to view project information, and make changes to a project's structure. An example of using this service would be to populate a drop-down list box in your custom tool from which users could select a Team Project. They could then proceed to use your custom tool on the selected Team Project,

Using this service, you can create Team Projects, delete Team Projects, and access all the different properties of your Team Project.

The common pattern for accessing the object model is to first create a connection to the server. Once you have connected to the server, the next step is to ask for a service to use. You will see this in more detail later in this chapter. To access the classification service, you make use of the ICommonStructureService service type of the Team Foundation Object Model.

Eventing Service

Team Foundation Server uses events to enable its different services to be loosely coupled. The eventing service is a publish/subscribe system. Third parties can build tools that integrate with Team Foundation Server and register events related to their tools. Team Foundation Server also comes with several preregistered events, such as for work item tracking and version control. For example, Team Foundation Server throws a WorkItemChanged event every time a modification is made to a work item.

Users can subscribe to events. When a user subscribes to an event, he can choose to either receive an e-mail concerning that event, or trigger a Web service. When an event is raised, Team Foundation Server looks through its list of subscribed events and triggers the appropriate response.

The Visual Studio 2005 SDK includes a tool called bissubscribe.exe, which you can use to register a user for events. See the section entitled "Example: Subscribe to an Event" later in this chapter for details on using this tool.

To access the eventing service, you make use of the IEventService service type of the Team Foundation Object Model.

Linking Service

The linking service allows you to create loosely coupled tools that can offer lightweight data integration. Simply put, by using a standard way to identify the different items in a tool, such as work items used by work item tracking and version control items used by version control, you can link your work items and version control items together, without the different tools knowing the details of the stored data of the other tool.

The linking service does this using the concept of artifacts. Because of this loose coupling, the linking service provides you with a way to discover all the artifacts in Team Foundation Server. In addition, the extensibility of Team Foundation Server allows you to use the linking and registration services to create your own tools and artifacts, and link them with others already in the system. While you can still take the tightly coupled approach if you want, it is recommended you make use of the linking service, to make your tools as extensible. This allows your tools to be used by other tools you might not even know about, such as future parts of Team Foundation Server that have not even been developed yet.

So, what is an artifact? An artifact is a piece of information that a tool exposes and that other tools can refer to. For example, a work item is an artifact of the Work Item Tracking tool. An artifact has two required properties, an artifact identifier and an artifact type. To understand the concept of an artifact identifier, you need to understand about Uniform Resource Identifiers (URIs).

The artifact identifier is simply the URI for that artifact. Here is the general syntax for a URI:

 vstfs:///<tooltype>/<artifacttype>/<tool id> 

The syntax can be parsed as follows:

• vstfs is a custom protocol used by Team Foundation Server. It is converted to a URL and used in that way.

• <tooltype> is the interface of the tool that is responsible for answering questions about the artifact. For example, for a work item, the tooltype is WorkItemTracking.

• <artifacttype> is the specific artifact type for that tool. A tool can handle requests for multiple artifact types. For the Work Item Tracking tool, the artifact type is WorkItem.

• <tool id> is the unique ID to a particular artifact identifiable by your tool. For example, you might have a work item that has been assigned a number of 50. In this case, the specific tool ID would be 50.

Given the previous example, a URI for work item 52 would be:

 vstfs:///WorkItemTracking/WorkItem/52 

For detailed documentation on the linking service, refer to the documentation included with the Visual Studio 2005 SDK.

To access the linking service, you make use of the ILinking service type of the Team Foundation Object Model.

Registration Service

The registration service is used to help direct calls to Team Foundation Server to the correct services and tools. Using tools provided with Team Foundation Server, located on the application tier server at C:\Program Files\Microsoft Visual Studio 2005 Team Foundation Server\Tools, you can register your tools, artifacts, events, and link types that you have created with Team Foundation Server. You can then use the Team Foundation Object Model to query this registered information for all the tools in Team Foundation Server.

To access the registration service, you make use of the IRegistration service type of the Team Foundation Object Model.

Security Service

The security service gives you the ability to manage all the groups, users, and access permissions in Team Foundation Server. There are two primary areas of the security service, Group Security and Authorization.

The Group Security area allows you to manage all the different Team Foundation Server application groups and membership to those groups. The Authorization area allows you to manage the access control lists for the Team Foundation Server.

To access the security service, you make use of the IGroupSecurityService and IAuthorizationService service types of the Team Foundation Object Model.

Subscribing to an Event

As mentioned earlier when talking about the Eventing Service of the Team Foundation Core Services, there is a tool included with the Visual Studio 2005 SDK which allows you to use the eventing service to subscribe to events. This tool is called bissubscribe.exe.

To download the SDK, point your browser to http://affiliate.vsipmembers.com. To download the SDK, you must register with the Visual Studio Industry Partner's program. Registration is free and quick.

Once you have downloaded and installed the SDK, look for a folder in the installation directory named VisualStudioTeamSystemIntegration. It contains a Utilities directory, and in that folder is a ZIP file called Event Subscription Tool. This zip file contains the bissubscribe utility. Look at the read-me file included in the ZIP file, to determine the correct spot to copy the utility on your machine.

The general syntax for the bissubscribe utility is:

 Bissubscribe /eventType <MyEvent> /userId <MyDomain\MyId> /address <MyEmailOrSoapAddress> /deliveryType <EmailHtml|EmailPlainText|Soap> /domain <MyDomain> /filter <MyFilterString /tag <MyTag> 

The syntax can be parsed as follows:

• eventType - The name (case-sensitive) of the event to which you want to subscribe

• filter - A filter expression, if needed

• userId - The domain and username for the subscriber

• address - The e-mail address or Web service URL for the subscriber

• tag - A name that can be used to later identify this subscription

• domain - The name of the Team Foundation Server

Let's say you wanted to subscribe to the ProjectCreatedEvent. Every time a new Team Project is created, you want to receive an e-mail. Here is the syntax for subscribing a user named User1 located in Domain1:

 Bissubscribe /eventType ProjectCreatedEvent /userId Domain1\User1 /address [e-mail] /deliveryType EmailPlainText /domain mytfs /tag User1EmailSubscription1 

Any time a new team project is created, a ProjectCreatedEvent will fire. Team Foundation Server looks through its list of subscribers, finds where User1 subscribed to the ProjectCreatedEvent, and sends an e-mail with the creation details to User1.