June 30, 2008

.NET CLI Wrapper

Surround SCM

Works with Surround SCM 2008 and Surround SCM 2009

For those users looking to access Surround SCM programatically, their only option is through the Command Line Interface (CLI). Many of the examples I have posted on this site show how you can access the command line interface using C#. For those that are looking for an easier and more reusable option, you may find using this .NET assembly helpful. [toc]

About the assembly

The assembly is simply a wrapper over the CLI. The advantage of the wrapper is that instead of having to build commands to pass the CLI, you can simple use methods and pass the parameters. Remember that this is still the CLI running in the background. This means that you still need to have the CLI installed and running. Currently, the CLI path is hard coded to C:Program FilesSeapineSurround SCMsscm.exe. The methods are subject to how the CLI works. Make sure you review the CLI user guide to make sure you are using the command properly. If you are not getting the results you expect, run the actual command on the command line. The assembly is written in C# using Visual Studio 2005. Note: The assembly is in its infancy at this time and it only supports a very limited number of commands. I do welcome anyone who wants to upload their own version with more methods. Simply register and you will be able to add your own section to this article and you can upload your own version. I do ask that if you upload your version, to create your own section in this article and provide a separate link to your version of the assembly.

Download

The current instance of the assembly is available for download here.

Setting the connection parameters

Instead of passing the connection parameters such as username, password, server address and port with each command, a method is provided to establish the parameters. The connection parameters are set as class fields.

SetConnectParams

Simply set the fields and then call this method before any of the commands. The method will concatenate and build the portion of the commands that contain the connection parameters:
TypeField NameDescription
stringscmUserNameSurround SCM username
stringscmPasswordPassword for the username above
stringscmServerAddressSurround SCM server address
stringscmServerPortSurround SCM server port
Example:
            SSCMCLASS  mySSCM = new SSCMCLASS();

            mySSCM.scmUserName = "Administrator";
            mySSCM.scmPassword = "password";
            mySSCM.scmServerAddress = "127.0.0.1";
            mySSCM.scmServerPort = "4900";

            mySSCM.SetConnectParams();

Current supported commands

Check Out

There are two check out methods:
  1. CheckOutFile
  2. CheckOutRepository
And each command has two different sets of overloads. The first set is for a 'simple check out'. The second set takes into account virtually all options for the command.

CheckOutFile

The first set of overloads are as follows:
TypeParameterDescription
stringscmFileThe file to check out
stringscmBranchThe branch to checkout from
stringscmRepositoryThe repository where the file is located
Default behavior is to skip writable or modified files in the working directory. The second set of overloads are as follows:
TypeParameterDescription
stringscmFileThe file to check out
stringscmBranchThe branch to checkout from
stringscmRepositoryThe repository where the file is located
boolexclusiveCheckOutWhether to make the check out exclusive
boolforceRetrievalWhether to force the file retrieval
stringtimeStampTimestamp to use for the file in the working directory. Options are "current", "modified" or "checkin"
stringfileVersionThe file version to check out
stringreplaceOptHow to handle replacing a modified or writable file in the working directory. Only specify "skip" or "replace". Currently there is no filtering for passing "prompt". If you pass "prompt" the application will stop and wait for the prompt to be answered and currently there is no way to answer the prompt.

CheckOutRepository

Checks out the repository passed as a parameter. Option included to do it recursively. Currently only one set of overloads available:
TypeParameterDescription
stringscmBranchthe branch to checkout from
stringscmRepositoryThe repository to check out
boolrecursiveCheck out child repositories as well

Get

There is only one get command, called GetFile. There are three sets of overloads for GetFile. The first set of overloads gets the file or repository to the working directory. There is no recursive option at this time with this set of overloads.
TypeParameterDescription
stringscmFilethe file or repository to get. Use "/" if you want to get the repository passed with the scmRepository parameter
stringscmBranchthe branch to get the file or repository from
stringscmRepositorythe repository where the file or repository is located or the repository to get
The second set of overloads takes a parameter to specify a destination directory other than the working directory:
TypeParameterDescription
stringscmFileThe file or repository to get. Use "/" if you want to get the repository passed with the scmRepository parameter
stringscmBranchThe branch to get the file or repository from
stringscmRepositoryThe repository where the file or repository is located or the repository to get
stringdestinationDirThe destination directory to place the files.
Default behavior for the first to set of overloads is to skip writable or modified files in the working directory. The third set of overlads are as follows:
TypeParameterDescription
stringscmFileThe file or repository to get. Use "/" if you want to get the repository passed with the scmRepository parameter
stringscmBranchThe branch to get the file or repository from
stringscmRepositoryThe repository where the file or repository is located or the repository to get
stringdestinationDirThe destination directory to place the files.
stringfileLabelGet based on this label
boolfileWritableSet files to not read-only in destination
boolforceFileForce file retrieval from server.
stringtimeStampGet based on this timestamp. Timestamp format is yyyymmddhh:mm:ss

CheckIn

There are two sets of overloads for the CheckIn command. The first one is a simple check in command, while the second one supports attaching the check in to a TestTrack defect.
TypeParameterDescription
stringscmFileThe file or repository to check in. Use "/" if you want to check in the repository passed with the scmRepository parameter
stringscmBranchThe branch to check in the file(s).
stringscmRepositoryThe repository to check in the file(s).
stringcommentThe check in comment. This is required.
The second set of overloads that support attaching to a TestTrack defect are as follows:
TypeParameterDescription
stringscmFileThe file or repository to check in. Use "/" if you want to check in the repository passed with the scmRepository parameter
stringscmBranchThe branch to check in the file(s).
stringscmRepositoryThe repository to check in the file(s).
stringttConnectionThe name of the TestTrack connection to use.
stringttUserThe TestTrack username to use with the TestTrack connection.
stringttUserThe password of the TestTrack username to use with the TestTrack connection.
stringdefectNumThe defect number to attach the check-in.

LsMainline

There are two lsmainline commands:
  1. LsMainline
  2. LsMainlineArray
The only difference is in what they return. LsMainline returns a long string with a list of all the mainlines. This is the raw output from the CLI, carriage and new line returns included. LsMainlineArray returns an ArrayList object and each item in the array is a mainline branch name. This method parses through the CLI output and removes all of the carriage and new line returns. Both methods take the same parameter:
TypeParameterDescription
boolinclRemovedInclude removed mainline branches in the output
Example:
     ArrayList mainlineArray = mySSCM.lsMainlineArray(true);
     for (int i = 0; i < mainlineArray.Count; i++)
     {
         if (!(mainlineArray[i] == null))
         {
             Console.WriteLine("Mainline branch name is {0}", mainlineArray[i].ToString());
         }
     }

Version

Probably the simplest of the commands. It does not require any parameters. This was the first command implemented and it is an easy one to get started or to do minor tests.

GenCommand

This is command that allows you to pass any of the commands that are-yet-to-be-added as methods to the assembly. It takes only one parameter, and it is the command itself and its paramenters. Example:
mySSCM.GenCommand("get / -bWysiCorp -pWysiCorp -r");
Note: Be mindful of commands that will give you a prompt to confirm the action or a comment. If you do not handle these properly, the sscm.exe process will be left running in the background waiting for a response. The command will not complete and you will have to manually end the process.

Disclaimers

This is provided as an example only. While this does work in my environment, it may not work in yours. This is outside of the scope of what is covered and supported by Seapine Software. While all the methods worked with my examples, there may still be a need for some adjustments. I have not taken into account every possible situation and every single option for every command. This is not provided as an add-on to Surround SCM. You are welcomed to use it in your environment, but it is your responsibility to make any changes for this to work in your environment. Please test this thoroughly before implenting this in a production environment as it is your sole responsability the results caused by the use of this assembly.

Improvements/enhancements

This is in its infancy so there are plenty of possible enhancements. Mainly just creating methods for the rest of the commands, or adjusting current methods to handle certain situations.

Comments/Suggestions

Feel free to drop me an e-mail if you have any comments or suggestions. Just keep in mind the disclaimer. If you have any issues I may be able to help you, but only if it is something minor. If you would like to implement a similar application but require it to be customized or rewritten for your environment (maybe your are in Linux, or use a differnt SCC tool), feel free to contact our services department, which I am a member of. We have the knowledge and skills to deliver a solution that will meet your needs.