Visual Studio Plugin Guide

Overview

This guide provides information about and instructions for installing and using the Sablime Visual Studio* Plugin with Sablime. The Sablime Visual Studio plugin is an interface between Sablime and Visual Studio or other supporting applications for Windows*. The supporting application is your Integrated Development Environment (IDE). The plugin allows you to perform Sablime source control operations (such as check in, check out) from within the IDE.

The Sablime plugin — “SabVSPlugin” — implements the Microsoft* Source Code Control API (SCC API) specification. The API allows IDEs to communicate with source code control providers like Sablime in common way. SabVSPlugin has been tested and is supported with following IDEs:

Other IDEs that comply with the Microsoft SCC API might also work with SabVSPlugin. Refer to your IDE’s documentation to determine whether or not it supports this interface.

Return to: Top of Page

Requirements

SabVSPlugin runs on a Windows XP Professional or later platform that has Internet Explorer 5.0 or higher installed. You do not need to use Internet Explorer, but the plugin uses some of the system libraries that come with IE 5.0 or higher, and these must be present.

You will need web access to an installed, licensed copy of Sablime to install and use the plugin.

Installation

SabVSPlugin is included in the Sablime package on the host machine. To use the Visual Studio plugin, first download the file setupSabVSPlugin.exe by selecting Visual Studio plugin on the Web Lifecycle page. Save the file to a convenient place on your PC.

(Select 'Visual Studio plugin' from the 'Downloads...' submenu of the 'Tools' menu on the page toolbar.)

When you install SabVSPlugin, it configures itself to be the Source Code Control (SCC) Provider.

If you need to change that setting, select Start > Programs > Sablime > Change SCC Provider.

Double-click on the saved file to install the plugin. The installation wizard will guide you through the installation process.

The next time you run the IDE (e.g. Visual Studio), the plugin will automatically be loaded and available for use.

To uninstall SabVSPlugin, launch the uninstall program by selecting Start > Programs > Sablime > Uninstall SabVSPlugin.

Return to: Top of Page

Upgrades

When you install updates to your host Sablime, you may need to upgrade your SabVSPlugin. To do so, just follow the same instructions as above for Installation. Even if no upgrade was really needed, doing so is harmless.

About the Plugin

In addition to the documentation provided here, you may also want to consult the documentation of your IDE. It may provide information on what SCC features are available and how they are presented to the user. The IDE (for example), not SabVSPlugin, lays out the SCC menu and the dialog boxes in its environment.

Plugin Environment

SabVSPlugin is based on the client/server architecture and uses the Apache* web server as a host. The Sablime database resides on the host while the files you work with reside in an IDE workspace on your local machine. You can place some or all of the files in your workspace under Sablime.

Return to: Top of PageAbout the Plugin

Terminology

The following terms are frequently used in the document:

Project
To help organize and perform common tasks on the items you are developing, the IDE usually defines a project as a container to logically manage, build and debug the items that comprise an application.
Product
Sablime terminology that most often corresponds to a single software application, though in some cases an application may be assembled from different “products”. Product is the top-level organizational unit in Sablime.
Generic
Sablime terminology usually representing a complete development cycle (release) of the product, from requirements through delivery and maintenance. A product may have one or more generics.
Source Node
A source node is a directory tree in Sablime database where Sablime stores source files associated with product and generic.
Mapped Project
Associates a selected project in the IDE with a specified Sablime product, generic and source node at a specified server location.

Return to: Top of PageAbout the Plugin

Available Sablime commands & SCC API features

The terminology used by the IDE to carry out tasks may differ from that used by Sablime. This table compares some terms:

Visual Studio Term or Operation Sablime Term or Command
CR - Change Request MR - Modification Request
Add to source control addisrc / addgsrc
Check Out edget
Check In edput
Undo Checkout unedget
Get Version sget / getversion
Rename a file source - rename
Remove from source control source - delete

The following table lists the Sablime commands available from the IDE using SabVSPlugin. Not all of the usual Sablime keywords for specific commands are available from the IDE; only those that makes most sense in an IDE environment.

The Plugin Configurable values are as follows:
Yes [value]
The keyword can be configured from within the IDE using Project Settings dialog box. Default configuration of plugin uses value.
No [value]
The specified keyword is not configurable and takes the specified value.
Automatic
IDE/Plugin determines the value based on project configuration or command invocation.
Keyword Description Plugin Configurable
addisrc — Add files to Sablime
bfile Store As Binary Yes [auto-detect]
dir SDB Directory Location Automatic
g Generic Yes
initsrc Current File Location Automatic
mr MR Number Yes
owner File Owner No [No owner]
prompt Prompt for input No [n]
srf Source File Automatic
vct Version Control Tool Yes [SCCS]
addgsrc — Add files to Sablime
br Branch No [No value]
dir Directory Automatic
g Generic Yes
incldep Include Missing Depended-Upon MRs No [n]
initsrc Current File Location Automatic
mr MR Number Yes
mrs MRs for Specifying Version No [No value]
olddir Old Directory No [No value]
oldg Old Generic No [No value]
owner File Owner No [No owner]
prompt Prompt for input No [n]
srf Source Files Automatic
edget — Check out a file
dir Directory Automatic
g Generic Yes
mr MR Number Yes
prompt Prompt for input No [n]
reserve Reserve Yes [n]
rm Remove Files No [y]
srf Source Files Automatic
edput — Check in a change to a file.
adep Auto Dependency Yes
com Comments File Yes
dir Directory Automatic
extract Merge Extraction No [y]
g Generic Yes
lockout Merge Lockout No [n]
mr MR Number Yes
overwrite Merge Overwrite No [n]
prompt Prompt No [n]
reset Merge Reset No [n]
rm Remove Files No [n]
showdep Show Dependencies First No [n]
srf Source Files Automatic
sget — Get specified version of file
br Branch Yes [mr]
brdt Cutoff Date No [No value]
dir Directory Automatic
g Generic Yes
incldep Include Missing Depended-Upon MRs No [n]
kx Expand ID Keywords Yes [y]
mrs MR Numbers No [No value]
prompt Prompt for input No [n]
rm Remove Files No [y]
srf Source Files Automatic

SabVSPlugin also provides access to the fcreate command that allows you to create, accept and assign an MR to yourself from within the IDE. The available fields for the fcreate command are abstract and description, with the others being determined by Sablime defaults.

SabVSPlugin does not implement every feature available in the Microsoft SCC API. So for some IDEs that use the SabVSPlugin, certain source control menus (like history, for example) may not be available. The following lists the features that are available from within the IDE:

Available SCC API Feature Implemented in SabVSPlugin
Add project/files to Source Control Yes
Open project from Source Control Yes
Project Properties Yes
Checkout Yes
Check in Yes
Undo Checkout Yes
Get files Yes
File Diff Yes (No Visual Diff)
File History No
Add files to project from Source Control No
Remove files (delete from source control) No
Rename project/files No

Return to: Top of PageAbout the Plugin

Using the Plugin

Authenticating the User

SabVSPlugin uses the same authentication mechanism (Basic Authentication) as used by Sablime web interface. The first time you use the IDE to add project files to Sablime or open a project that is controlled by Sablime, you will be asked to authenticate:

The image shows the login dialogue for the Sablime host web server.

For the IDE projects that are already mapped with Sablime, the plugin will remember all the field values except for the password field. The password field value will be remembered only if Remember password is checked. Fields other than User Name, Password and Remember password are protected for already mapped projects.

Web Sablime URL
Enter the URL you use for Web Sablime access (i.e. http://server_name:port_number/docs/wsab.html, where the port_number part is optional depending on how your web server was configured).
Use HTTP Proxy Server
Check this if you are using a proxy server for communicating with the Sablime web server. This will enable the Proxy Server and Port fields on the form.
Proxy Server
Enter the host name of your proxy server. The field is enabled only if Use HTTP Proxy Server is checked.
Port
Enter the port number of your proxy server. The field is enabled only if Use HTTP Proxy Server is checked.
User Name
Enter the same user name as you use for the Sablime web interface.
Password
Enter the same password as you use for the Sablime web interface.
Remember password
Check this if you want the plugin to remember your password for your next log-in.

Return to: Top of PageUsing the Plugin

Changing Sablime Settings

The first time you add project files to Sablime using the IDE, you will be asked to configure Sablime settings for the project. For an already-mapped project, the project settings can be accessed from the Sablime Properties source control menu (may vary depending on IDE).

The Sablime Setting dialogue has two tabs General and Command options:

General

The General tab has project specific options that map the local project to a Sablime database. The options are stored in the project preference file on the local machine. Each mapped project/user has its own project preference file named ProjectName_user.sabscc.

Web Sablime URL
A read-only field, identifies the web server the plugin is communicating with.
Product
A drop-down list of available products on the Sablime server. This (mandatory) field is read-only for already mapped projects.
Generic
A drop-down list of available generics for the specified product. This (mandatory) field is read-only for already mapped projects.
MR Number
A drop-down list of assigned MRs for the selected generic. The field is mandatory under certain scenarios like Adding project to Sablime. If left unspecified, certain source operations (check out, check in) will not be available.
New
This button allows you to fcreate an MR by specifying an abstract and description. The new MR will be added to the MR Number dropdown list.
Local Path
Specifies a directory on the local machine for the root of the project directory tree. This (mandatory) is set by clicking Browse.

Select Project
This list-box contains the project files currently in the Sablime database. The field is only present when you are trying to open a project from Sablime, or are trying to map a local project with one that already exists in Sablime.

The determination of project files by Sablime is based on the file extension matching. If your IDE specifies a particular file extension for a startup project file then you should append that extension to the $VSEXTN variable in the wsab.conf file in your web Sablime installation. $VSEXTN comes initialized with Visual Studio extensions as follows:

$VSEXTN=".sln,.vbproj,.vbdproj,.vbp,.csproj,.csdproj,.vjsproj,.vcproj,
.dsp,.mdp,.mak,.vfpproj,.vdp,.vdproj,.dbp,.vsmproj,.vsmacros,.hwproj,
.etp,.etpproxy,.actproj,.atp,.dmp,.mdmp,.dsw";

Command Options

The Command Options tab has Sablime command-specific options stored for all mapped projects in plug-in global preference file on the local machine. Because the options are stored centrally, any change in command specific options will impact the command options of all mapped projects on local machine.

The options can be overridden at command runtime in IDEs where the Advanced menu is available for commands (e.g. check out, check in, get).

Auto-Dependency
This corresponds to adep keyword of the edput command and has values “line-level”, “file-level” and “none”. Pre-configured with “line-level” selected.
Checkin Unchanged Files
When initiating a check-in, if the new version is not different than the one stored in the database, the plugin can either check in the unchanged file anyway (the traditional Sablime action), or can undo the checkout (preventing null deltas from being added to the file). Pre-configured with Undo Checkout selected.
Version Control Tool
This corresponds to vct keyword of the addisrc command and has selections “SCCS” and “SBCS”. Pre-configured with “SCCS” selected.
Store As Binary
This corresponds to the bfile keyword of the addisrc command and has selections “auto-detect”, “yes” and “no”. Pre-configured with “auto-detect” selected.
Reserve Checkout
This corresponds to the reserve keyword of the edget command. Pre-configured with “n” selected. Ignored if the Sablime product does not have Temporary Branching enabled.
Replace Writable Files
If the file being checked-out or gotten exists and is writable on local machine, this field specifies the plugin action. The selections are “Ask”, “Replace”, and “Skip”. Pre-configured with “Ask” selected.
With “Ask” selected, the plugin will prompt the user whether to overwrite the local copy with the one from Sablime. With “Replace” selected, the plugin will always replace a local copy with the one from Sablime; while for “Skip”, the plugin will never replace a local writable copy.
Branch
This corresponds to br keyword of the sget command and has selections “mr” and “ofc”. Pre-configured with “mr” selected. The option is only visible in IDEs where the Advanced option is available for the get command.

Return to: Top of PageUsing the Plugin

Synchronize Project Files with Sablime

The plugin does not provide an automated action to synchronize the local copy of files with the one stored in Sablime. Some IDEs like Visual Studio do provide a menu selection that triggers a Get Latest Version action for all files in the project when opening the project to synchronize it. If such a menu is not available one has to manually trigger the Get Latest Version of all files in the project to synchronize the local files those in Sablime as required.

Return to: Top of PageUsing the Plugin

When to go Outside of the IDE

You will need to use Web Sablime directly to perform any Sablime tasks that are not defined in the tables above. You also may want to go outside of the IDE if you want to use non-configurable keywords for the Sablime commands.

The Sablime web interface can be invoked from most IDEs by selecting Lucent Sablime from the source control menu. If you do perform Sablime source control tasks outside the IDE, be sure to refresh the IDE display afterwards, to ensure that file status is updated and displayed correctly.

Return to: Top of PageUsing the Plugin

Sablime Mapping IDE Project Files to its Source Node

Projects managed in Sablime via the plugin are stored in a directory named for the project, and at the root of the Sablime product source node. For example, a project with name “foo” that has files under C:\com\src and C:\com\src\doc will have a source node populated in Sablime with directories foo, foo/src and foo/src/doc.

In order to manage an already existing Sablime project using the plugin, you may need to rearrange the source files so they are under the root in a directory named for the project.

Return to: Top of PageUsing the Plugin

Choosing Which Project Files to Put in Sablime

Usually, the IDE determines which project files need to be in Sablime for a given project. However, if you decide for yourself which project files to store in Sablime, you should not put any IDE-generated files (e.g. .ncb, .clw or .opt files for Visual Studio) in your Sablime database. If you put certain build or view related files in Sablime the files are usually marked as read-only on local machine. That may result in build errors or view display errors when the IDE is unable them.

Return to: Top of PageUsing the Plugin

Using the plug-in with Visual Studio .NET

Overview

This section guides you through common development tasks such as how to add a project/solution to Sablime, how to retrieve a project/solution from Sablime, and how to check files in and out on a regular basis. You can quickly get up to speed on the essential tasks by going though this section. Though the procedure is specifically targeted for Visual Studio .NET IDE, other SabVSPlugin compatible IDEs usually use similar procedures.

Adding a project/solution to Sablime

In this scenario, you want to create a new project/solution and then add the project/solution to Sablime or after you use Visual Studio .NET to create a new project/solution file, and some initial development, you want to add the project/solution to Sablime. The steps to add a project/solution to Sablime are:

  1. Start Visual Studio .NET and create new project/solution or open the solution that you are already working with and want to add it to Sablime.
  2. On the File menu, point to Source Control, and then click Add project/solution to Source Control.
  3. You will be prompted with SabVSPlugin authentication dialog box. Fill out the form and click OK on the dialog box.
  4. The plugin will display the Project Settings dialog box: select the appropriate product, generic and MR number to map your project in Sablime and click OK on the final dialog box. Though usually not needed, you can also modify source command options on command options tab before clicking OK.

Your project/solution with its associated source files are now placed under Sablime. The files are locked within Sablime as indicated by the lock symbol next to all the files in the Solution Explorer. The local working copy of files is assigned the read-only attribute to prevent you from inadvertantly changing them unless you check out the files from Sablime.

Opening a project/solution from Sablime

In this scenario, another team member has created a project/solution and added it to Sablime. You would like to obtain the copy of project/solution for the first time to start working on it. The steps to open a project/solution from Sablime are:

  1. Start Visual Studio .NET
  2. On the File menu, point to Source Control, and then click Open From Source Control.
  3. You will be prompted with the authentication dialog box. Fill out the form and click OK.
  4. The plugin will display the Project Settings dialog box: select the appropriate product, generic and MR number. Then locate the local path where you want to download your project on local machine. Select the project that you want to work on from select project list box and click OK. Though usually not needed, you can also modify source command options on the Command Options tab before clicking OK.
  5. You will prompted with the Open Solution dialog box that has your solution/project pre-selected, click OK.

The complete solution/project with all associated source files will be downloaded to your local machine. The files are locked in Sablime as indicated by lock symbol next to them in Solution Explorer.

Note: To work on an already mapped solution/project with Sablime that also already exists on your local machine, you should open the local solution file. This approach is easy and less error prone. Do not use Open From Source Control menu in this scenario. When you open the project/solution using the local file, to ensure you have the most updated version of project files, you can select the project/solution in Solution Explorer; right-click it, and click Get Latest Version (Recursive).

Check Out a File

When you start to edit a locked file, Visual Studio .NET has an automatic check-out-on-edit feature that prompts you with Check Out For Edit dialog box to check out the file. Click the Check Out button and the file will be checked out for you. To check out more than one file at the same time, right-click on solution/project file in the solution explorer and select Check Out, select all the files that need to be checked out in the Check Out For Edit dialog box and click Check Out.

Check In a File

To check in the edited file, right-click the file within the Solution Explorer and select Check In. To check in more than one file at the same time, right-click on the solution/project file in Solution Explorer and select Check In, select all the files that need to be checked in on the Check In dialog box and click Check In.

If there is a merge conflict for a file that is being checked in, Sablime will detect it and set up a merge on the local machine with an appropriate message. You will need to go outside of the IDE to merge files. The merge set-up files (LD, CA and BK) are not deleted by the subsequent successful merge/check in.

Undo Checkout

To undo a checkout on a file, right-click on the file in the Solution Explorer and click Undo Checkout. To Undo Checkout on more than one file at the same time, right-click on solution/project file in the Solution Explorer and select Undo Checkout; select all the files that need to have their check-out undone and click Undo Checkout.

Get a file

The plugin can get one of the two different versions of a file from Sablime: latest version (mr branch) or latest approved version (ofc branch). Defaults to “mr” branch version.

To get the latest mr branch version of a file, right-click on the file within Solution Explorer and click Get Latest Version. To get the latest version on more than one file at the same time, select all the files in Solution Explorer that need to be retrieved, right-click and select Get Latest Version.

The complete project/solution will all related files can be retrieved by right-clicking the project/solution file and selecting Get Latest Version (Recursive).

To get the latest official branch version of a file, select the project/solution file in the Solution Explorer. On the File menu, point to Source Control and then click Get&. On the resulting dialog box, check all the files that need to be retrieved and click the Options toolbar menu. On Command Options dialog box, select Branch “ofc” and click OK. Then again click OK on the Get dialog.

Compare Versions

To determine if a local version of a file differs from the latest mr branch version stored in Sablime, select the file in Solution Explorer. On the File menu, point to Source Control and then click Compare Versions;. This will tell you if the file differs from the one stored in Sablime. The plugin does not support visual diffs and file history.

Renaming and Deleting files

Once the project/solution and its associated files are in source control, the project/solution name and its associated file names cannot be renamed using Visual Studio menu. The plugin does not support this operation. Users are on their own for renaming project/solution and its associated files.

Also, deleting individual files or folders with Visual Studio is not automatically propagated to Sablime and vice-versa. As a result, deleting files from the Visual Studio project/solution that are in Sablime requires a corresponding action in Sablime using its source command, and deleting files from Sablime that are part of Visual Studio project/solution requires a corresponging action in Visual Studio.

Return to: Top of PageUsing the Plugin

Known Problems and Limitations

Authentication dialog box appears more than once for some projects Some IDEs support a workspace view (solution view) where more than one project can be opened together. In such a case, if each project is stored at a separate source node for a specified product and generic in Sablime then your IDE will prompt for separate authentication dialog box for each such project being opened.

Entering comments in check out, undo check out dialog box does not work The plugin supports comments for the check-in command only. However, certain IDEs (like Visual Studio) provide a comment field for almost all the source commands (like checkout, undo checkout). The plugin will ignore the comment field the source commands other than check in.

Installing the plug-in leaves some files like mfc70.dll, msvcp70.dll, msvcr70.dll on other driveIn some cases, for an unknown reason, when installing the plugin it has been observed that the plugin installs certain files on a drive other than the destination drive if more than one drive is available on the machine. However, the files installed are harmless and if not modified will automatically be uninstalled when the plugin is uninstalled.

The plugin does not delete BK, CA and LD files when file is checked in When checking in files and a merge is required, the plugin will set up the merge, extracting LD and CA files. However, these files will not be deleted by the plugin after merge and subsequent check in. This is limitation of SabVSPlugin.

The plugin does not support bind or rebind option if available from within the IDE The current version of the plugin does not support bind or rebind operation. In order to rebind the project you need to do one of the following

  • If the IDE has an Open from Source Control menu, then select that menu and specify the same location where the current project exists. For Overwrite and Replace Writable Files dialog boxes that pop up during this operation, you can accept defaults and click OK to overwrite files with those from Sablime.
  • If the IDE does not have an Open from Source Control menu, then using the Sablime web interface: do a getversion of the complete project node onto the local machine. Then in the IDE open the project on local machine. It will prompt you to map the local project with the one stored in Sablime. Select appropriate project from Sablime in project settings dialog box and the project will rebind.

When using the plugin with Visual Studio, many times Reload / Ignore dialog box pops up Visual Studio detects file changes that happen outside of the IDE and prompts the user to reload or ignore the outside changes. In some cases the plugin does manipulate the file outside of the IDE, so Visual Studio prompts the with the Reload / Ignore dialog box. You can select either of the option in such a case, as the file has not actually been changed.

Using the plugin with Visual Studio, sometime an odd “unedget” error comes up when adding project to Sablime When adding some projects to Sablime, Visual Studio sometime triggers the plug-in to unedget the file that was never added/checked-out in first place displaying unedget error dialog box. The file name is typically Project/Solution Name.vsscc. The cause of the problem is unknown and ignoring the message seems to work fine.

Return to: Top of Page


* Microsoft, Visual Studio, and Windows are trademarks or registered trademarks of Microsoft Corporation in the United States and other countries.
UNIX is a registered trademark of The Open Group.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.
Apache is a trademark of the Apache Software Foundation.

Sablime is a registered trademark of Alcatel-Lucent Inc.
Contents copyright © 2010-2015 Alcatel-Lucent. Permission to photocopy in support of a licensed installation of Sablime is hereby granted.