Introduction

This sample demonstrates how to create a source code control provider.

 

Quick Navigation

1 Requirements
2 Download and Install
3 Building and Running
4 Getting Started
4.1 Project Files
4.2 Unit Tests
4.3 Functional Tests
4.4 Status
4.5 History
4.6 Additional Resources


Requirements

Visual Studio 2010 and Visual Studio 2010 SDK

Download and Install

 

Building and Running

To build and execute the sample, press F5 after the sample is loaded. This will launch the experimental hive which will demonstrate the sample's function.

Getting Started

This sample has a package (SccProvider) and the source control service (SccProviderService). The sample exposes one tool window (SccProviderToolWindow) and one Options page (SccProviderOptions).

The source control provider can be selected in the Tools, Options, Source Control, Plug-In Selection page as "Managed Source Control Sample Provider". Selection will make it the active source control provider.

When the provider is selected as the active source control provider, the "Source control provider toolwindow" command will become visible on the View menu, the Tools, Options, Source Control, Sample Options Page page will become visible, the shortcut menus in Solution Explorer will become visible (with the AddToSourceControl, Checkin, Checkout, Offline commands) if you have a solution created, and the source control toolbar buttons will appear if you access View, Toolbars, Sample Source Control Toolbar. When the "View/Source control provider toolwindow" command is clicked, the tool window will be created. The visibility of menu commands, tool window, and Options page is controlled by the active state of the provider. All of the UI elements except the toolbar will be hidden automatically when the provider is deactivated.

The provider demonstrates basic source control functionality:

  1. The sample does not implement a real source control store. To track which files in a project are controlled, the sample will create a projectname.storage text file on the hard drive that contains the list of controlled files in that project. To simplify things, if a project is added to the solution after the solution was added to source control, that project will not be automatically controlled. The user must explicitly use the AddToSourceControl command to add it to source control. (Exceptions are solution folders, which are controlled automatically after closing and reopening the solution.
  2. Controlled solutions may be opened from disk.
  3. Controlled files can be checked out and checked in, but these actions only toggle the read-write attribute of the files. Source control status of files will be inferred from the file attributes on local disk.


The SccProvider class derives from the IVsPersistSolutionProps interface to persist properties in the solution file. The following property names are used: SolutionIsControlled, which indicates the controlled status of the solution, and SolutionBindings, which shows the solution location in the source control database.

The SccProvider class derives from IVsPersistSolutionProps interface to persist user options in the .suo file. The "Use Scc Offline" command will be visible in shortcut menus in Solution Explorer and will act like a toggle that allows projects to be taken online or offline. The offline status for the projects is persisted in the .suo file through the SampleSourceControlProvider options key. The status of other source control commands is not affected by the offline status of a project.

The sample implements basic QueryEditQuerySave service functionality in the SccProviderService class. OnEdit will prompt the user to check out the file, edit in memory, or cancel the edit. OnSave will prompt the user to check out the file, skip the save, or cancel the operation. The OnSave code will trigger only if files have been edited in memory or if the user forces the file to be saved when it is checked in.

SccProviderService implements the IVsTrackProjectDocumentsEvents2 interface to intercept project-change events in the integrated development environment (IDE). The following functions are implemented:
OnAfterRenameFiles to rename files in source control when they are renamed in projects and OnQueryRemoveFiles to warn the user when they are deleting files under source control.

Project Files

File Name Description
SccProvider This file contains the Package implementation. It also is responsible for handling the enabling and execution of source control commands.
SccProviderService This file contains the source control service implementation. The class implements the the IVsSccProvider interface that enables source control provider activation and switching.
SccProviderStorage This file contains the implementation of a pseudo-source control storage. The class creates a *.storage text file for each controlled project in the solution and stores in it the list of the controlled files. The checked in and checked out status of controlled files is inferred from the their attributes on disk..
SccProviderOptions This class derives from MsVsShell.DialogPage and provides the Options page. It is responsible for handling Option page events such as activation, apply, and close. It hosts the SccProviderOptionsControl.
SccProviderOptionsControl This class is a UserControl that will be hosted in the Options page. It has a label to demonstrate display of controls on the page.
SccProviderToolWindow This class derives from ToolWindowPane, which provides the IVsWindowPane implementation. It is responsible for defining window frame properties such as caption and bitmap. It hosts the SccProviderToolWindowControl.
SccProviderToolWindowControl This class is a UserControl that will be hosted in the tool window. It has a label to demonstrate display of controls in the window.
DataStreamFromComStream This class implements a Stream object that wraps an IStream COM object. It is used to facilitate the read/write of solution user options from an IStream by using a BinaryFormatter object that can serialize data to and from Stream objects
DlgQueryEditCheckedInFile This class is a Form that will be displayed when a checked in file is edited. The user can choose to check out the file, continue editing the file in memory, or cancel the edit
DlgQuerySaveCheckedInFile This class is a Form that will be displayed when a checked in file is saved. The user can choose to checkout the file, discard the in-memory changes and skip saving it, save the file with a different name, or cancel the operation.
CommandId This is a list of GUIDs specific to this sample, especially the package GUID and the commands group GUID. It also includes GUIDs of other elements used by the sample.
Guids This is the list of command IDs that the sample defines.
PkgCmd.vsct This file describes the menu structure and commands for this sample. It also is where the toolbar is defined.
Resources (.cs/.resx/.Designer.cs) These files are used to support localized strings.
Resources\Images_24bit.bmp This bitmap defines the icons that are used for tool windows.
Resources\Images_32bit.bmp This bitmap defines the icons that are used for toolbars and menu commands.
Resources\Product.ico This file defines the icon to be used for the product.
ProvideSourceControlProvider This file contains the implementation of a custom registration attribute that registers a source control provider. It is used to make the source control provider visible on the Tools, Options, SourceControl, Plugins page.
ProvideToolsOptionsPageVisibility This file contains the implementation of a custom registration attribute that defines the visibility of a tool window. It is used to make the tool window implemented by the provider visible only when the provider is active (that is, when the provider context UI has been asserted).
ProvideSolutionProps This file contains the implementation of a custom registration attribute that declares the key used by the package to persist solution properties. When encountering a solution containing this key, the IDE will know which package it has to call to read that block of solution properties.


Unit Tests

Description
Verify that the package can be created and sited and that it implements IVsPackage
Verify that the source control provider service can be ceated, activated, and deactivated
Test the "Scc Command" command on the Tools menu by toggling it twice
Test the Activate, Deactivate, Apply, and Close events on the Options page
Test that the tool window can be displayed and that the toolbar command can be executed
Test that source control storage can be created, and read and write storage files. Test that files can be added to the storage, checked out, checked in, and renamed. Test that correct source control status is returned for files in storage


Functional Tests

Description
Verify sample builds in all configurations.
Verify that the sample was registered. The About box should list the product as installed.
Verify that the provider is can be selected in Tools, Options, SourceControl.
Verify that menu commands are visible when the provider is active.
Verify that the toolbar can be displayed.
Verify that toolbar buttons are enabled only when the provider is active.
Verify that the tool window is visible only when the provider is active, after it was displayed once.
Verify that the Options page is visible only when the provider is active.
Verify that a solution can be added to source control entirely by using the AddToSourceControl command on a newly created solution when the solution node is selected in Solution Explorer. Everything should be checked in.
Verify that a project can be added to source control separately from a solution by using AddToSourceControl command on a newly created solution when the project node is selected in Solution Explorer. Only project files should be checked in.
Verify that checked in files in a controlled solution can be checked out.
Verify that checked out files in a controlled solution can be checked in.
Verify that solution items are added to source control when a solution is added to source control.
Verify that adding a new project to a controlled solution prompts QueryEdit to check out the solution file and open it for editing.
Verify that adding a new project to a controlled solution does not make the project controlled.
Verify that adding a new solution item to a controlled solution makes the new file a pending addition. Pending additions display a checkout glyph in Solution Explorer, but have a different tooltip.
Verify that adding a new item to a controlled project prompts QueryEdit to check out the project file and open it for editing.
Verify that adding a new item to a controlled project makes the new file a pending addition. Pending additions display a checkout glyph in Solution Explorer, but have a different tooltip.
Verify that pending addition files can be checked in.
Verify that closing and reopening from disk a controlled solution preserves the controlled status for all of the projects controlled in that solution.
Verify that any controlled project or solution can be taken offline.
Verify that closing and reopening from disk a controlled solution in which some projects were taking offline preserves the offline status.
Verify that the user is warned when attempting to delete a controlled item from a controlled project.
Verify that renaming a controlled item in a controlled project renames the item in the store and keeps the renamed file controlled.
Verify that renaming a controlled project in a solution renames the project in the store and in the storage file, and that the project files remain controlled.
Verify source control glyphs in Solution Explorer for controlled files (checked in and checked out), pending addition files (uncontrolled files in controlled projects), and uncontrolled files.
Verify source tooltips in Solution Explorer for controlled files (checked in and checked out), pending addition files (uncontrolled files in controlled projects), and uncontrolled files.


Status

Function Status
Demonstrates Accessibility Yes
Includes Architecture Diagram Yes
Demonstrates Error Handling Yes
Follows SDK Coding Standards No
Demonstrates Localization Yes
Implements Functional Tests No
Samples supported by Microsoft Yes
Implements Unit Tests Yes


History

Date Activity
2005-10-01 Created this sample for the Visual Studio 2005 SDK
2010-03-05 Ported this sample to work in Visual Studio 2010


Additional Resources

SCC Provider Integration