An application to fetch the release sources from Visual SouceSafe based on an Excel migration plan

• Download source - 28.2 Kb

Introduction

Some companies use a migration plan as the basis for a project release. Migration Plan (typically in Excel) contains the release file details such as release file name, path and the version number in the source control. Each worksheet in the migration plan contains the entries for one type of release source information (i.e. the C++ worksheet contains .cpp information and the EXEDLL worksheet contains the executable files information for the release). Please find a sample migration plan below:

Normally migration plans will be updated by the developers once the development phase is over. Based on this release migration plan, build engineers either fetch the sources from source control and build the sources to create the installation package, or fetch only the executables (if the source control contains the properly built executables) and create the installation package.

To automate the project release process in such scenarios, I tried to develop a Windows application that fetches the sources automatically from Visual SourceSafe based on an Excel based migration plan.

Here is the UI for this application:

The user will enter VSS details (such as user name, password and INI file), the Excel migration-file path and the destination folder (where the files from VSS would be copied). In this application, the user has the choice to fetch all the sources or those specified in chosen work sheets (under Extract Files group box).

Building the Application

Start by creating a new Windows Application project:

Design the user interface as shown below and name the controls appropriately:

On clicking the “Get Files” button:

1. The project will open the migration file (Excel file) and fetch the file details (file name, path and version number).
2. Copy the files to the destination folder from Visual SourceSafe.

We will create a class to handle the Excel operations such as opening the Excel file, closing the Excel file, and getting the file details (i.e. file path, name and version number in VSS) from the various worksheets.

We will create another class to handle VSS operations such as opening the VSS database, closing the VSS database and extracting the files from VSS to the local system.

We can prepare two separate components to handle the above cases. To make the application simple, I created both the classes in the application itself.

To extract the file details from the Excel migration file, create a new interface (IMigrationFile) with three methods: one method to open the migration file, a second method to close the migration file, and a third method to get the file details based on the worksheet name).

/// <summary>
/// Interface for Migration File
/// </summary>
interface IMigrationFile
{
    //Open the migration file
    string OpenMigrationFile(string strMigrationFile);
    //Close the migration file
    string CloseMigrationFile();
    // Get the file details(File Name,Path
    // and Version No) for the input work sheet
    ArrayList GetFileDetails(string strWorkSheet);
};

Add a new class (ExclMigrationFile.cs) to the project using Projects->Add New Item. This class will implement the IMigrationFile interface.

To access the Excel automation methods, we need to add a reference to the Excel object using Project->Add Reference under COM tab.

Each worksheet contains the file path, file name and version number. Create a structure to store these values while extracting the from the worksheet.

/// <summary>
/// Structure to hold file details (File Path,File Name and Version No)
/// </summary>
public struct FileDetails
{
    public string FilePath;
    public string FileName;
    public int VersionNo;
};

Now we need to provide the implementation for the IMigrationFile interface methods. Before implementing these interface methods, add the following private variables to the class.

private ExclVSS._Application exclVSSApp=null;
private ExclVSS.Sheets exclVSSWorkSheets=null;

Now provide the implementation for the OpenMigrationFile method.

/// <summary>
/// Open the Excel Migration File .
/// </summary>
/// <summary>
public string OpenMigrationFile(string strMigrationFile)
{
    try
    {
        //Create the Excel Application Class
        this.ExclApp= new Microsoft.Office.Interop.Excel.ApplicationClass();
        //Open the Excel file
        this.ExclApp.Workbooks.Open(strMigrationFile,vk_update_links, 
             vk_read_only, vk_format, vk_password,vk_write_res_password, 
             vk_ignore_read_only_recommend, vk_origin,vk_delimiter, 
             vk_editable, vk_notify, vk_converter, 
             vk_add_to_mru,vk_local, vk_corrupt_load);
        //Get the Excel work sheet
        this.ExclWorkSheets=this.ExclApp.Worksheets;
    }
    catch(Exception e)
    {
        return e.ToString();
    }
    return "";

}

Next we provide the implementation for the CloseMigrationFile method:

/// <summary>
/// Close the Excel Migration File .
/// </summary>
public string CloseMigrationFile()
{
    try
    {
        //Close the Work Books
        this.ExclApp.Workbooks.Close();
    }
    catch(Exception e)
    {
        return e.ToString();
    }
    return "";
}

The third interface method GetFileDetails needs to be implemented now. This method extracts the file details from the user choice worksheet. This method uses a helper function (GetFileDetails) to extract the file details.

/// <summary>
/// Get the file details for the given work sheet .
/// </summary>
public ArrayList GetFileDetails(string strWorkSheet)
{
    //Create an ArrayList to hold the File Details
    //(File Path,Name and Version NO)
    ArrayList alFileList=new ArrayList();
    //Iterate the Worksheets to get the C++ files Worksheet
    foreach(Excl.Worksheet exclWorkSheet in exclWorkSheets)
    {
        //Check if Worksheet name and the user choice are same
        if(strWorkSheet == exclWorkSheet.Name)
        {
            //Get File Details
            GetFileDetails(exclWorkSheet, ref alFileList);
            break;
        }
    }
    //Return the array list to the client
    return alFileList;
}

/// <summary>
/// This is a helper function to extract the file names
/// and their paths based on the input work sheet
/// </summary>
private void GetFileDetails(Excl.Worksheet exclWorkSheet, 
                             ref ArrayList alFileDetails)
{
    //Activate the work sheet
    exclWorkSheet.Activate();
    //Get the number of rows 
    int nRowCount=exclWorkSheet.UsedRange.EntireRow.Count;
    for(int i=2;i<=nRowCount;i++)
    {
        //Get the file names and their paths from the sheet
        // Column : A contains File Path
        //Column : B contains File Name
        Excl.Range rangeCPP=exclWorkSheet.get_Range("A"+i.ToString(), 
                                                 "C" + i.ToString());
        //Get the file path and names for the row
        System.Array array = (System.Array)rangeCPP.Cells.Value2;
        //Create File Details object

        FileDetails fileDetails=new FileDetails();
        //Get the File Path
        fileDetails.FilePath=(string)array.GetValue(1,1).ToString();
        //Get the File Name
        fileDetails.FileName=(string)array.GetValue(1,2).ToString();
        //Get the Version No
        fileDetails.VersionNo=
          Convert.ToInt32(array.GetValue(1,3).ToString());
        //Add to the ArrayList
        alFileDetails.Add(fileDetails);
    }
}

To get the files from VSS, create a new interface (ISourceControl) with three methods to open the VSS database, to close the VSS database, and to get the specified file from VSS.

/// <summary>
/// Interface for Source Control
/// </summary>
interface ISourceControl
{
    //Open the SourceSafe
    string OpenSourceControl(string UserName, 
           string Password, string INIPath);
    //Close the SourceSafe
    string CloseSourceControl();
    //Get the specified version file
    string GetFileFromSourceControl(string FilePath, 
           string DestinationPath, int VersionNo,int Flags);
};

Add a new class (VSS.cs) to the project using Projects->Add New Item. This class will implement the ISourceControl interface.

To access the Visual SourceSafe automation methods, we need to add a reference to the VSS object using Project->Add Reference under COM tab.

Now provide the implementation for the ISourceControl interface methods:

//Open the SourceSafe
public string OpenSourceControl(string UserName, 
                                string Password, string INIPath)
{
    //Create VSS Database object
    vssDatabase = new SourceSafeTypeLib.VSSDatabase();
    try
    {
        //Open the VSS Database based on User Name,
        //Passwor and INI file name
        vssDatabase.Open (INIPath, UserName, Password);
    }
    catch(Exception e)
    {
        return e.ToString();
    }
    return "";
}
//Close the SourceSafe
public string CloseSourceControl()
{
    try
    {
        //Set VSSDatabase object to null
        vssDatabase = null;
    }
    catch(Exception e)
    {
        return e.ToString();
    }

    return "";
}
//Get the specified version file
public string GetFileFromSourceControl(string FilePath, 
       string DestinationPath,int VersionNo,int Flags)
{
    SourceSafeTypeLib.VSSItem vssItem;
    SourceSafeTypeLib.VSSItem  vssVersionItem;
    try
    {
        /// Get the VSS Item
        vssItem = vssDatabase.get_VSSItem(FilePath, false);    
        //Get the specified verison
        vssVersionItem=vssItem.get_Version(VersionNo);
        //Extract the file to the destination folder
        vssVersionItem.Get(ref DestinationPath, Flags);
    }
    catch(Exception e)
    {
        return e.ToString();
    }
    return "";
}

We have done with the IMigrationFile and ISourceControl implementation.

Now provide the implementation for the UI control handlers.

Implementation for OnClick of the Get Files button:

/// <summary>
/// Get file details from migration file
/// and extract the corresponding files from VSS.
/// </summary>
private void btnGetFiles_Click(object sender, System.EventArgs e)
{
    //Initialize Excel and VSS Objects and 
    //Open the Excel and VSS Database
    Initialize_OpenExcelVSS();

    //Extract Files
    ExtractFiles();
        
    //Close Excel and VSS Database
    Close_ExcelVSS();
}

Here are the operations that this method will perform:

Step 1:

Open the Excel file and the VSS database using IMigrationFile and ISourceControl interface methods.

/// <summary>
/// Initialize and Open Excel and VSS Database.
/// </summary>
private void Initialize_OpenExcelVSS()
{
    //Get the user options
    strUserName=txtUserName.Text;
    strPwd=txtPwd.Text;
    strINIPath=txtIniName.Text;
    strExcelPath=txtExcel.Text;
    strDestPath=txtDest.Text;

    //Create objects
    this.iExcel=new AutoMigration.ExcelMigrationFile();
    this.iVSS=new AutoMigration.VSS();

    //Open Excel file
    this.iExcel.OpenMigrationFile(strExcelPath);
    //Open VSS Database
    this.iVSS.OpenSourceControl(strUserName,strPwd,strINIPath);

}

Step 2:

Get the file details (file path, file name and version number) from the Excel worksheet.

/// <summary>
/// Extract File details from Excel Migration Plan.
/// </summary>
private void ExtractFiles()
{
    //C++
    if(true==chkCPP.Checked)
    {
        ArrayList al=null;
        //Get the file details from Excel work sheet
        al=this.iExcel.GetFileDetails(strCPP);
        //Extract the file from VSS to the destination folder
        GetVSSFiles(al);
    }
    //VB
    if(true==chkVB.Checked)
    {
        ArrayList al=null;
        //Get the file details from Excel work sheet
        al=this.iExcel.GetFileDetails(strVB);
        //Extract the file from VSS to the destination folder
        GetVSSFiles(al);
    }
    //XML
    if(true==chkXML.Checked)
    {
        ArrayList al=null;
        //Get the file details from Excel work sheet
        al=this.iExcel.GetFileDetails(strXML);
        //Extract the file from VSS to the destination folder
        GetVSSFiles(al);
    }
    //EXE
    if(true==chkEXE.Checked)
    {
        ArrayList al=null;
        //Get the file details from Excel work sheet
        al=this.iExcel.GetFileDetails(strEXE);
        //Extract the file from VSS to the destination folder
        GetVSSFiles(al);
    }
    //ASP
    if(true==chkASP.Checked)
    {
        ArrayList al=null;
        //Get the file details from Excel work sheet
        al=this.iExcel.GetFileDetails(strASP);
        //Extract the file from VSS to the destination folder
        GetVSSFiles(al);
    }
}

Step 3:

Extract the files from VSS based on the file path, name and version number (which we got in the above step).

/// <summary>
/// Get specified verion file from VSS  .
/// </summary>
private string GetVSSFiles(ArrayList alFiles)
{
    string strFilePath;
    try
    {
        //Get the Enumerator for ArrayList
        System.Collections.IEnumerator myEnumerator = alFiles.GetEnumerator();
        while ( myEnumerator.MoveNext() )
        {
            //Extract the FileDetails
            FileDetails fileDetails=(FileDetails) myEnumerator.Current;
            //Get the File Path
            strFilePath=fileDetails.FilePath+fileDetails.FileName;
            //Get files from VSS
            this.iVSS.GetFileFromSourceControl(strFilePath,strDestPath,
                                          fileDetails.VersionNo,Flags);

        }
    }
    catch(Exception e)
    {
        return e.ToString();
    }
    return "";

}

Step 4:

Close the Excel file and the VSS database.

/// <summary>
/// Close Excel and VSS Database.
/// </summary>
private void Close_ExcelVSS()
{
    //Close Excel
    this.iExcel.CloseMigrationFile();
    //Close VSS Database
    this.iVSS.CloseSourceControl();

    this.iExcel=null;
    this.iVSS=null;    

}

Implementation for browse buttons:

/// <summary>
/// Browse INI Files.
/// </summary>
private void btnINI_Click(object sender, System.EventArgs e)
{
    //Use Open File Dialog
    OpenFileDialog openINIFile = new OpenFileDialog();
    //Set the default text as ini, so that 
    //file open dialog displays only ini files
    openINIFile.DefaultExt = "ini";
    // The Filter property requires a search string after the pipe ( | )
    openINIFile.Filter = "INI Files (*.ini)|*.ini";
    openINIFile.ShowDialog();
    //Get the INI file
    txtExcel.Text=openINIFile.FileName;

}
/// <summary>
/// Browse XLS Files.
/// </summary>
private void btnExcel_Click(object sender, System.EventArgs e)
{
    //Use Open File Dialog
    OpenFileDialog openExcelFile = new OpenFileDialog();
    //Set the default text as xls, so that 
    //file open dialog displays only Excel files
    openExcelFile.DefaultExt = "xls";
    // The Filter property requires a search string after the pipe ( | )
    openExcelFile.Filter = "Excel sheets (*.xls)|*.xls";
    openExcelFile.ShowDialog();
    //Get the Excel File
    txtExcel.Text=openExcelFile.FileName;

}

This is the first step of automating the migration plan release process. Next step would be automatically building the fetched sources (I’ll cover this topic in the next article).

Before testing the application, make sure that the user has the proper rights to connect to Visual SourceSafe and to fetch the sources.

Reference and Further Reading

Documents in MSDN:

1. Tim Winter. Visual SourceSafe 6.0 Automation. September 1998.