October 23, 2006

Bridging the Gap: Integrating SCM Tools with IDEs

Surround SCM
Software configuration management (SCM) is an essential part of the development lifecycle process. An SCM tool assists in the development process and increases individual and overall team productivity. Because most developers use some type of Integrated Development Environment (IDE), it greatly benefits the development team to have an SCM tool that integrates with the IDE of their choice. Developers generally prefer to stay within the boundaries of their IDE when developing and maintaining code. Switching between an SCM tool and the IDE slows down the development process and prevents developers from reaching a high level of efficiency. Convenience and ease of use are also important issues when working with an SCM tool, therefore the SCM tool must seamlessly integrate with the IDE. A number of SCM tools for the Windows platform support the Microsoft Source Code Control Interface (MSSCCI), which allows providers to integrate into Microsoft’s Visual Studio suite. This article provides a glimpse into the MSSCCI. Seapine’s Surround SCM is used to illustrate a sophisticated integration with Visual Studio .NET 2005. MSSCCI functionality overview The MSSCCI is an old API designed by Microsoft that dates back to the Visual Studio 6.0 days. It is strict in nature but includes a rich variety of options that a particular SCM provider can support. This interface has evolved over the years by offering additional functionality, better and faster communication between the provider and the IDE, as well as usability improvements.The MSSCCI sets up a communication bridge between the provider and the Visual Studio environment. A Source Control Adapter resides inside Visual Studio and acts as a proxy between the IDE and the provider. All Visual Studio components, such as the Solution Explorer, the editor, the projects and the source control UI, communicate directly with the Source Control Adapter. The Source Control Adapter passes information to and from those components via MSSCCI. The provider, while adhering to the strict interface guidelines, has the ability to be quite flexible in the way certain operations are implemented. For example, the provider can display its own UI elements. In fact, this behavior is encouraged in order to provide a tighter integration between Visual Studio and the SCM provider. The ability to display UI elements also provides a way for the integration library to support advanced features for a number of operations in the MSSCCI. Hurdles, potholes, and more As previously stated, the integration comes in a library form and implements the MSSCCI. The MSSCCI supports an advanced feature set, which allows the provider to support additional functionality. However, not all functionality of each provider can be implemented. While working on Surround’s integration, it quickly became apparent that it is next to impossible to implement direct support for branching in the integration library. Sure there are ways to do this, but they are neither clean nor desired since they may confuse users. MSSCCI does not directly provide support for branching in its current form. In Surround’s case, it is advised to perform any branch level operations using the Surround GUI client or the Surround CLI client. However, the beauty of the tight integration is the way a project works after it has been branched. The branched project, when opened from Visual Studio, behaves and functions as expected without any additional modifications or maintenance required from the user.In the early version of the MSSCCI documentation, it was difficult to really understand why certain calls were being made to the integration library. The documentation says one thing while Visual Studio acts differently and calls a different function in the integration library or calls the functions out of sequence. Trial and error techniques were generally used in the early stages of the development process because the behavior did not match the rules. One example of this was the expectation that the integration library would send a list of supported capabilities so Visual Studio’s Source Control Adapter could communicate with the library fittingly. We did just that with Surround SCM, sending back such a list to Visual Studio. However, even when certain operations were either supported or not supported by our library, calls to these functions were made incorrectly by Visual Studio. Over the years, this part of the MSSCCI has improved along with the documentation. Bug fixes in the interface and the Visual Studio IDE have improved functionality and performance in addition to resolving most problems. How does Surround SCM integrate with Visual Studio? To enable the integration library several Windows registry settings must be set prior to launching Visual Studio. The registry settings simply point to the location of the integration library, as follows: The key [HKEY_LOCAL_MACHINESoftwareSourceControlProvider] = “SoftwareSeapine SoftwareSurround SCMScci” The key [HKEY_LOCAL_MACHINESoftwareSeapine SoftwareSurround SCMScci] contains the following string values: SCCServerName = “Surround SCM” SCCServerPath = “C:Program FilesSeapineSurround SCMSurround SCM SCCI.dll” The Surround SCM installer takes care of this setting during the install process. After the integration library is registered, Visual Studio enables the Source Control in its main context menu (as seen in Figure 1) as well is in the File menu for the IDE.Adding existing Visual Studio Projects is a trivial task with Surround SCM integration into Visual Studio. Figure 1 Other operations including Check In, Check Out, Undo Check Out, Get, Diff, History, Remove, and Rename are similar in structure and should also be implemented with the same basic foundation as shown in the previous code snippet.After the “Add Solution to Source Control” option is selected, the Source Control Adapter communicates with the integration library to perform the desired task. The MSSCCI sends information to the library and the library performs the add operation after manipulating some of the data that is passed in.
 1longCMSSCCIController::AddFiles(constStringList&files, constString&advancedOptions, constlongflags) 2{ 3longrtn=OPERATION_OK; 4try 5{ 6// process list of files if needed 7// process flags if needed here 8// process advanced options here 9CMSSCCIAdvancedOptionsaddAdvancedOptions(advancedOptions);1011// perform add12rtn=m_pServer->ProcessAddFiles(files, &addAdvancedOptions);13}14catch()15{16rtn=OPERATION_UNKNOWN_ERROR;17}1819return(rtn);20}
Additional logic may be required for any advanced options or extra flags being passed into the integration library. It is a good practice to place all the operations inside a try/catch block since strange things may happen otherwise. A crash inside the library may yield erroneous dialogs from Visual Studio or, even worse, cause the whole IDE to crash.Additional flags or advanced options in the add operation may signal some additional useful information for the SCM provider. For example, if the files are all text files then a flag can be set to indicate this. The SCM provider can then save time by omitting its auto-detection scheme. The advanced options, driven by the integration library, can turn on options such as “Perform a Get after an Add” or “Check out files after Add” if so desired by the user. Other advanced options, such as change list usage, are also incorporated with Surround’s implementation. File detection and association Each provider uses different methods to determine if a file or a set of files have a specific status and whether or not they are in a controlled or a non-controlled state. Surround SCM uses local hidden files and server communication for determining this information. When a project is initialized and opened by the integration library, the logic to check for file status and state is comparable to the following:
 1longCMSSCCIController::GetFileInfo(constStringList&files, long*fileStatus) 2{ 3longrtn=OPERATION_OK; 4try 5{ 6if(m_pCacheObject!=NULL) 7{ 8// process file list if needed 9if(m_pCacheObject->IsCacheOutDated())10{11// if data is outdated, query the server12rtn=m_pServer->ProcessGetFileInfo(files, fileStatus);13}14else15{16// otherwise check cache for file status17rtn=m_pCacheObject->ProcessGetFileInfo(files, filestatus);18}19}20}21catch()22{23rtn=OPERATION_UNKNOWN_ERROR;24}25return(rtn);26}
The file status and state results are transferred to the Source Control Adapter, which then performs all the necessary updating inside Visual Studio based on the status flags it acquired from the integration library. Figure 2 illustrates how the results are posted to the Visual Studio shell. Figure 2 Each glyph, displayed next to the file icon, represents the file’s status in the Solution Explorer. The controlled elements are visually indicated by a padlock while checkmarks and other glyphs are used for additional status flags. Accessing the SCM tool from the IDE This operation is the most trivial to implement since the implementer has full control over the SCM tool that is launched. SCM providers that do not have a GUI client cannot truly take advantage of this feature. When the DLL is registered by Visual Studio and the Source Control menus are enabled, the “Launch provider” menu item is displayed and enabled (See Figure 3). Figure 3 he reason this implementation is trivial is because data manipulation does not take place. We simply look up the install root folder of Surround SCM from the Windows registry and start a new process. The ability to launch the Surround GUI client from inside Visual Studio allows the user to perform some advanced operations that are not included in the integration due to the strict interface guidelines imposed by MSSCCI. At the same time, the IDE allows the user to perform all operations from inside its shell, which includes the launching of the GUI client for advanced operations. Conclusion Seamless integration between an SCM tool and an IDE is a huge benefit to the developer, the development team, and the company. With all the SCM operations and actions available from the IDE’s shell, developers are more productive, giving them and the company the extra edge. The MSSCCI API is strict in nature but allows the opportunity for tight integration if the provider chooses to perform the implementation.Microsoft Source Code Control Interface information, documentation, and sample source code is available online: http://msdn.microsoft.com/vstudio/extend/.