Team Development with Visual Studio.NET and Visual SourceSafe

 

Michael Monteiro
Sapient Corporation

February 2003

Summary: BuildIt is a Microsoft® .NET console application that automates the build process outlined in the patterns & practices article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN® Library. BuildIt is designed, developed, and tested by Sapient Corporation and it is reviewed by Microsoft, including team members of the Microsoft patterns & practices and Visual Studio® .NET development system. (28 printed pages)

Using BuildIt:

  • Eliminates the time required to create, test, and maintain a custom build script.
  • Makes a team's build process more repeatable and consistent.

BuildIt is designed to jump-start the build process used for development of .NET distributed applications. The downloadable program provides full source code and comprehensive documentation for Microsoft Visual C#® development tool and Microsoft Visual Basic® .NET development system.

Note   BuildIt currently supports building solutions that contain setup projects developed with Visual Basic .NET, Visual C#, and Visual Studio .NET. It has not been tested with projects written in other .NET languages or with other setup projects (for example, setup projects from Wise or InstallShield).

While BuildIt has undergone testing and reviews and is considered a robust code set, the code and documentation is provided "as-is" for you to use and extend.

This document includes the following sections:

Downloading and Installing BuildIt

Testing Your Installation

User's Guide

Deployment and Operations

Known Issues

Design and Implementation

Class Reference

Frequently Asked Questions

Summary

Downloading and Installing BuildIt

Click here to download BuildIt.

The installation process creates a Microsoft Application Blocks for .NET submenu on your Programs menu. On the Microsoft Application Blocks for .NET submenu, there is a Sapient BuildIt submenu that includes options to launch the BuildIt Visual Studio .NET solution.

Testing Your Installation

The following steps to build two sample solutions found in Program Files\BuildIt\Code\BuildItTest help verify that BuildIt is working properly.

To add items to source control

  1. In Visual SourceSafe® (VSS) version control system, create a new project named BuildItTest.
  2. Set the working folder on $/BuildItTest to Program Files\BuildIt\Code\BuildItTest.
  3. Add assembly version files to VSS:
    1. Add Program Files\BuildIt\Code\BuildItTest\AssemblyVersionInfo.cs to $/BuildItTest.
    2. Repeat for AssemblyVersionInfo.vb.
  4. Create a virtual directory for the Web project (Project2):
    1. Browse to Program Files\BuildIt\Code\BuildItTest\Solution2\Project2.
    2. Right-click Project2, and then click Properties.
    3. Click the Web Sharing tab, and then click Share this folder.
    4. Accept the default alias, and then click OK to close the Edit Alias dialog box.
    5. Click OK to close the Properties dialog box.
  5. Add solutions to VSS:
    1. Open Program Files\BuildIt\Code\BuildItTest\Solution1\Solution1.sln.
    2. In Solution Explorer, right-click Solution1, and then click Add Solution to Source Control.
    3. Browse to $/BuildItTest, and then click OK (click Yes to create the VSS project).
    4. If prompted to specify the location for Project1, browse to $/BuildItTest/Solution1, and then click OK.
    5. Repeat Steps a–d for Solution2.
  6. Share assembly version files in VSS:
    1. Share $/BuildItTest/AssemblyVersionInfo.cs to $/BuildItTest/Solution1/Project1.
    2. Share $/BuildItTest/AssemblyVersionInfo.vb to $/BuildItTest/Solution2/Project2.

To add assembly version files to projects

  1. Add AssemblyVersionInfo.cs to Project1 found in Solution1:
    1. Open Program Files\BuildIt\Code\BuildItTest\Solution1\Solution1.sln.
    2. In Solution Explorer, right-click Project1, point to Add, and then click Add Existing Item.
    3. Browse to Program Files\BuildIt\Code\BuildItTest\Solution1\Project1\AssemblyVersionInfo.cs, and then click Open.
    4. In the Check Out for Edit dialog box, click Check Out to check out Project1.csproj.
    5. Open AssemblyVersionInfo.cs and note the version number (1.0.0.*).
    6. Press CTRL+SHIFT+B to build the solution.
    7. In Solution Explorer, right-click Project1, and then click Check In Now (Recursive).
    8. Repeat Steps a–g to add AssemblyVersionInfo.vb to Project2 found in Solution2.
  2. Update configuration settings:
    1. Open Program Files\BuildIt\Code\BuildItTest\BuildIt.exe.config.
    2. Update the sourceControl settings.
  3. Deploy BuildIt:
    1. Open Program Files\BuildIt\Code\BuildIt.sln.
    2. Press CTRL+SHIFT+B to build the solution (make sure you build a Release version).
    3. Copy the .exe file and all .dll files from Program Files\BuildIt\Code\BuildIt\bin\Release to Program Files\BuildIt\Code\BuildItTest.
  4. Execute BuildIt and verify:
    1. Open Program Files\BuildIt\Code\BuildItTest\BuildNumber.xml and note that the next build number is 1.
    2. Open Program Files\BuildIt\Code\BuildItTest\BuildIt.bat to review the BuildIt command line.
    3. Run BuildIt.bat to build the solutions.
    4. Open Program Files\BuildIt\Code\BuildItTest\BuildIt.log to check for errors.
    5. Open Program Files\BuildIt\Code\BuildItTest\BuildReport.log to review results of the build.
    6. Open BuildNumber.xml and note that the next build number was incremented to 2.
    7. Open AssemblyVersionInfo.cs and AssemblyVersionInfo.vb and note that the version numbers were updated from 1.0.0.* to 1.0.1.*.
    8. Browse to Program Files\BuildIt\Code\BuildItTest\Archive\1 to see that the generated assemblies were archived to a folder named after the build number.
    9. Browse to Program Files\BuildIt\Code\BuildItTest\Latest to see that the generated assemblies were copied to the latest folder.
    10. Show history on $/BuildItTest to see that the VSS project was labeled with the build number.

User's Guide

The following topics provide more information about using BuildIt:

Maintaining Build Numbers

Building Solutions

Reviewing the Build Report

Rebuilding a Solution

Archiving Builds

Emailing Build Results

Versioning Assemblies

Maintaining Build Numbers

BuildIt uses build numbers to label solutions that are source controlled in VSS and to update assembly version numbers (if the appropriate build option is enabled). At the end of each successful build, BuildIt generates a new build number by incrementing the current build number by one (if the build fails, the build number is not incremented). The new build number is then saved to an XML file whose name and location is defined by the buildNumberFilePath attribute contained in the BuildIt.exe.config file.

The following example shows the contents of a build number XML file called BuildNumber.xml.

<buildNumber>1000</buildNumber>
  
Note   The build number XML file must be created and initialized with a starting build number before running BuildIt. Also note that build numbers must be positive integers.

Building Solutions

BuildIt can be configured to build a single solution or multiple solutions. For multi-solution systems that include cross-solution file references, the solutions must be listed in the correct order. For example, if Solution2 depends on Solution1, make sure that Solution1 gets built first by listing it before Solution2.

The following sample from BuildIt.exe.config shows how to configure the build tool to build a multi-solution system:

<solutions latestRootFolderFullName="c:\System"
 buildNumberFilePath="c:\System\BuildNumber.xml">
  <solution path="c:\System\Solution1\Solution1.sln"/>
  <solution path="c:\System\Solution2\Solution2.sln"/>
</solutions>
  

Reviewing the Build Report

BuildIt generates a build report called BuildReport.log in the working folder at the end of each build. The build report can be viewed with any text editor. The build report contains summary information along with a list of solutions that succeeded and a list of those that failed. If any solutions fail to build, Visual Studio .NET can be used to manually build those solutions to find out exactly why they failed.

=============================================
Build Report Generated by BuildIt
=============================================
Build Number:    8016
Build Start:    9/12/2002 6:50:09 PM
Build End:    9/12/2002 6:50:43 PM
Build Duration:  1 minute(s)
Archive Folder:  c:\System\Archive\8016\
Latest Folder:    c:\System\Latest\
Build Results:    1 succeeded, 0 failed

=============================================
Succeeded
=============================================
c:\System\Solution1\Solution1.sln

=============================================
Failed
=============================================
  

Rebuilding a Solution

A rebuild is required if a build break occurs during a build. You must complete the following steps before rebuilding the solution.

To rebuild after a build break

  1. If the fix requires a code change, manually check out the necessary files from VSS to the build computer.
    Note   Use the same VSS credentials specified in the build tool configuration file when checking out files. This helps identify the files that were modified to fix a break.
  2. Make the code change, recompile using Visual Studio .NET, and then test the recompiled files.
  3. After the problem is resolved, check in the modified files.
  4. Manually update the label on each checked-in file with the label that was generated by the previous build, as follows:
    1. Right-click the file name, and then click Show History.
    2. In the History Options dialog box, click OK.
    3. Click the version of the file whose label you want to update, and then click Details.
    4. Update the Label field with the label used during the build (for example, "Build 100").
  5. Manually run BuildIt with the /rebuild option.

Archiving Builds

BuildIt can be configured to archive previous builds to a specified location, as described in the "Consider Maintaining Previous Builds" section of the "Team Development with Visual Studio .NET and Visual SourceSafe" article in the MSDN Library.

When the archiveBuild build option is enabled, the build tool copies generated assemblies to a folder named after the current build number located beneath the archive root folder specified by the archiveRootFolderFullName attribute in the configuration file.

By default, BuildIt archives output generated from only Visual C# and Visual Basic .NET projects. To archive output from other projects such as Visual Studio .NET setup projects, add folder elements to the additionalFoldersToArchive element.

The following sample from BuildIt.exe.config shows how to enable this option.

<options>
  <archiveBuild mode="on" archiveRootFolderFullName="c:\System\Archive">
    <additionalFoldersToArchive>
      <folder fullName=" c:\System\Solution1\Setup1\Debug" 
       destFolderName="Debug\Setup1" />
      <folder fullName=" c:\System\Solution1\Setup1\Release" 
       destFolderName="Release\Setup1" />
    </additionalFoldersToArchive>
  </archiveBuild>
</options>
  

Emailing Build Results

BuildIt can be configured to send the build results, by way of an e-mail message, to a specified e-mail address, as described in the "Emailing Build Results" section of the "Team Development with Visual Studio .NET and Visual SourceSafe" article.

When the sendBuildReport build option is enabled, the build tool sends a generated e-mail message that contains a build report called BuildReport.log to an e-mail address specified by the toAddress attribute.

The following sample from BuildIt.exe.config shows how to enable this option:

<options>
  <sendBuildReport mode="on" smtpServer="255.255.255.255"
   toAddress="you@yourcompany.com"/>
</options>
  

Versioning Assemblies

BuildIt can be configured to update an assembly's version with the current build number stored in an XML file specified by the buildNumberFilePath attribute as follows:

<solutions buildNumberFilePath="c:\System\BuildNumber.xml">
  

An assembly's version is typically specified in the AssemblyVersion attribute (which is defined within the AssemblyInfo.cs or AssemblyInfo.vb file). However, when the build tool is configured to update an assembly's version, the AssemblyVersion attribute should be defined in a separate file (for example, AssemblyVersionInfo.cs or AssemblyVersionInfo.vb) that is shared in VSS across all of the .NET projects in the solution. This allows BuildIt to update one file and have the change propagate to all of the projects in the solution. For more information, see the "Consider Centralizing Assembly Version Numbers" section of the "Team Development with Visual Studio .NET and Visual SourceSafe" article.

Note   Two example files called AssemblyVersionInfo.cs and AssemblyVersionInfo.vb are copied to the BuildItTest directory when BuildIt is installed.

The version number is physically represented as a four part number separated with periods, as shown in the following code sample.

<major version>.<minor version>.<build number>.<revision>
  

When the updateAssemblyVersion build option is enabled, the build tool updates the build number segment of the AssemblyVersion attribute with the current build number.

The following sample from BuildIt.exe.config shows how to enable this option.

<options>
  <updateAssemblyVersion mode="on" 
   csAssemblyVersionVSSPath="$/System/AssemblyVersionInfo.cs"  
   vbAssemblyVersionVSSPath="$/System/AssemblyVersionInfo.vb" />
</options>
  

Deployment and Operations

This section includes the following administrative topics:

Deploying BuildIt

Configuring BuildIt

Securing BuildIt

Troubleshooting BuildIt

Deploying BuildIt

When deploying any application, it's important to identify any dependencies that exist. BuildIt, which is implemented as a single assembly named BuildIt.exe, has the following dependencies:

  • BuildIt.exe.config for configuration settings
  • BuildNumber.xml for maintaining the next build number
    Note   The name and location of the build number XML file is defined by the buildNumberFilePath attribute in the BuildIt.exe.config file. Also note that the build number XML file must be created and initialized with the starting build number before running BuildIt. For more information, see the "Maintaining Build Numbers" section.
  • Microsoft.ApplicationBlocks.ExceptionManagent.dll and Microsoft.ApplicationBlock.ExceptionManagent.Interfaces.dll for exception management
  • Interop.SourceSafeTypeLib.dll for interoperating with the VSS API (SSAPI.dll)
  • Visual SourceSafe 6.0c client programs for accessing a remote VSS database
  • Visual Studio .NET for building .NET solutions

Armed with this information, a deployment method can be chosen based on the needs of the development team. For BuildIt, there are two deployment methods to consider: XCOPY or Windows Installer deployment. The following sections describe these options in more detail.

Deploying with XCOPY

Deploying BuildIt with the XCOPY command is the easiest method; however, it requires more knowledge from the person deploying the tool. To deploy with this method, use XCOPY to copy the required assemblies, along with the application configuration file (BuildIt.exe.config), to a directory on the target computer. Next, invoke the ExceptionManagerInstaller class using the Installutil.exe system utility to create the event sources required by the default exception publisher when it writes to the Windows Event Log. For example, use the following command-line:

Installutil.exe Microsoft.ApplicationBlocks.ExceptionManagement.dll
  
For   more information about the Exception Management Application Block, see "Microsoft Application Blocks for .NET" in the MSDN library.

Deploying with Windows Installer

Deploying BuildIt with Windows Installer requires more work up front than XCOPY, but it requires little knowledge from the person deploying the tool. To deploy using a Visual Studio.NET Setup and Deployment project, add the BuildIt, Exception Management, and Exception Management Interfaces project output to the application folder along with the BuildIt.exe.config file. Next, add the Exception Management project output as a custom action to ensure the ExceptionManagerInstaller class is instantiated at installation time.

Configuring BuildIt

The behavior of the build tool is controlled using an application configuration file. Application configuration files are XML-based documents stored in the root directory of the application folder hierarchy. The application configuration file name takes the form applicationname.applicationextension.config. For the build tool, the application configuration file is called BuildIt.exe.config.

This section includes the following topics about configuring BuildIt:

Setting Build Options

Configuring Tracing

Configuring Exception Management

Running with Multiple Versions of Visual Studio .NET

Note   When the configuration file is modified, the changes do not take effect until BuildIt is executed again.

Setting Build Options

You can enable or disable any build option by setting its mode attribute to on/off, as shown in the following code sample:

<options>
  <sendBuildReport mode="on" smtpServer="255.255.255.255"
   toAddress="you@company.com"/>
</options>
  
Note   If the mode attribute is omitted or has any value other than on/off, an exception is raised. Also note that the mode attribute values are not case sensitive.

Configuring Tracing

BuildIt uses the Trace class in the System.Diagnostics namespace to generate trace output to the console and to a file called BuildIt.log in the working directory. The following is an example of the trace output.

Validating command-line arguments
Reading BuildIt settings from configuration file
Starting build 100 at 11/1/2002 1:57:53 PM
Updating assembly version file $/System/AssemblyVersionInfo.cs
Labelling source
Getting source from label
Backing up latest folder
Building Debug version of solution C:\System\Solution1\Solution1.sln
Building Release version of solution C:\System\Solution1\Solution1.sln
Building Debug version of solution C:\System\Solution2\Solution2.sln
Building Release version of solution C:\System\Solution2\Solution2.sln
2 solution(s) succeeded, 0 failed
Deleting latest backup folder
Archiving additional folders
Generating build report
Not sending build report because the option was not enabled
Ending build at 11/1/2002 1:58:40 PM - 0 minute(s) to complete
  

Tracing can be enabled and disabled using a TraceSwitch named traceLevel defined in the BuildIt.exe.config file. Tracing is disabled by setting the TraceSwitch to 0 and enabled by setting the switch to 3. Setting the TraceSwitch to 4 enables more detailed trace output (verbose mode).

The following code sample shows how to enable tracing.

<system.diagnostics> 
  <switches>
    <add name="traceLevel" value="3"/>
  </switches>
</system.diagnostics>
  

In addition, BuildIt can be configured to append trace output to the trace file (if one already exists) or it can be configured to overwrite the trace file. The recommended setting is to overwrite the trace file to prevent it from becoming too large. The following code sample shows how to do this.

<appSettings>
  <add key="appendTraceOutput" value="off" />
</appSettings>
  
Note   If the appendTraceOutput key is omitted, BuildIt overwrites the trace file by default.

Configuring Exception Management

BuildIt uses Microsoft's Exception Management Application Block, which can be configured with XML settings in the configuration file. If the settings are omitted, the Exception Management Application Block publishes exceptions to the application log by default. However, additional publishers can be specified.

At the time of this writing, the configuration file does not contain Exception Management settings. Therefore, all exceptions are published to the application log, which can then be view using the Event Viewer. For more information, see "Exception Management Application Block Overview" in the MSDN Library.

Running withMultiple Versions of Visual Studio .NET

By default, BuildIt uses the latest installed version of Visual Studio .NET to build solutions. However, if multiple versions are installed on the same computer, developers may want BuildIt to use a specific version. To force BuildIt to use a specific version of Visual Studio .NET, include a visualStudioProgID key in the appSettings section of the configuration file. The following code sample shows how to do this.

<appSettings>
  <add key="visualStudioProgID" value="VisualStudio.Solution.7" />
</appSettings>
  
Note   If the visualStudioProgID key is omitted, BuildIt uses the latest installed version of Visual Studio .NET by default.

Securing BuildIt

As with any application, you must ensure that all sensitive data and resources are protected from unauthorized access. With respect to BuildIt, there are two main areas to consider:

Preventing Unauthorized Access to Application Configuration Files

Access Permissions Required by BuildIt

Preventing Unauthorized Access to Configuration Files

Because the build tool configuration file contains sensitive data such as the VSS user name and password, you should ensure that only authorized users can view or change those settings. You can secure the configuration file by using Windows NTFS file permissions.

Access Permissions Required by BuildIt

BuildIt uses Microsoft's Exception Management Application Block to publish exceptions to the event log. In addition, the BuildIt reads/writes to the file system. Therefore, you need to ensure that the security principal used by BuildIt has appropriate permissions to conduct these operations.

Troubleshooting BuildIt

There are two mechanisms available to help developers troubleshoot the build tool: tracing and exception management. When tracing is enabled, BuildIt generates a trace file in the working folder called BuildIt.log that can be used to determine which steps were performed by the build tool. This is useful when trying to determine why the build tool is not behaving as expected.

When an exception occurs, BuildIt uses Microsoft's Exception Management Application Block to publish exceptions to the application log. Developers can then use the Event Viewer to view detailed information about the exception.

When used together, the two mechanisms provide information that can be used to troubleshoot the build tool.

Known Issues

BuildIt is very effective in most cases- but there are a few situations in which it has some known issues. Table 1 lists known issues with BuildIt.

Table 1: Known issues with BuildIt

IssueDescriptionResolution
BuildIt throws an error when building two or more solutions that have projects with the same name.An error occurs when BuildIt tries to copy project output to the latest folder if that output already exists. This can happen if BuildIt encounters two projects with the same name, even though they reside in different solutions. It can also happen if BuildIt encounters the same solution a second time during a single run of the tool.Make sure all projects are uniquely named across your system and make sure the App.config file does not contain duplicate solution entries.
Set Project Location dialog box appears during build.The Set Project Location dialog box appears during the build, prompting the user to set the location for the working copy of a Web project. This happens when trying to load a Web project that is not mapped to a corresponding virtual directory.To prevent the dialog box from appearing while BuildIt is running, make sure all Web projects are mapped to virtual directories before running BuildIt. One easy way to check is to manually open each solution in Visual Studio .NET before running BuildIt.
If the dialog box does appear while BuildIt is running, simply respond to the dialog box by setting the location for the working copy of the Web project. Visual Studio .NET then creates the virtual directory automatically.

Design and Implementation

This section includes the following design and implementation topics:

Problem Description

Design Goals

Solution Description

Enhancements

Problem Description

BuildIt is designed to solve the following problems:

  • Developers lose precious development time creating, testing, and maintaining custom build scripts that are often not reusable from one project to the next.
  • Developers are often under tight timeframes, leaving little time for thorough testing and documentation of their build scripts.

Design Goals

The design goals of BuildIt are:

  • The solution must adhere to the steps outlined in the article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library.
  • The solution must be well-documented, maintainable, and easy to use.
  • The solution must be flexible; it should be configurable without needing to re-code and re-compile.
  • The solution must be robust; it must handle any exceptions that occur during the build process.

Solution Description

BuildIt is a console application that consists of a number of classes that work together to automate the build process. For example:

  • . Validates command-line options, retrieves build tool settings by way of the BuildItSectionHandler and initiates the build process by way of the BuildManager.
  • . Retrieves settings from the tool's configuration file. These settings are used to alter runtime behavior.
  • . Orchestrates the build process.
  • . Exposes VSS operations (for example, Check-in and Checkout) used during the build process.
  • . Provides type-safe access to error messages stored in a resource file.
  • . Encapsulates the command-line arguments supported by BuildIt.

Figure 1 illustrates how these classes work together.

***Missing graphic tdlg17.gif

Figure 1. Build process flow diagram

The flow of logic is as follows:

  1. BuildIt is launched with the appropriate command-line arguments.
  2. The Main1 class calls the Start method of the BuildInitializer class.
  3. The BuildInitializer class validates the command-line arguments and then uses the BuildItSectionHandler class to retrieve settings from the tool's configuration file. The BuildItSectionHandler returns the settings by way of a type-safe structure called BuildItSettings.
  4. The BuildInitializer creates an instance of the BuildManager, passing the BuildItSettings structure to the Constructor.
  5. The BuildInitializer then calls Build on the BuildManager to initiate either a build or a rebuild, dictated by the command-line arguments.

Configuration File Settings

The BuildIt configuration file, called BuildIt.exe.config, contains settings that are read at runtime. This allows the tool's behavior to be modified without the need to recompile the solution.

Settings in the file indicate:

  • The solutions being built.
  • Information needed to connect to a specified VSS database.
  • Whether to update assembly versions with the build number.
  • Whether to archive previously built assemblies to a specified location.
  • Whether to send the build results in an e-mail message to a specified e-mail address.
Note   BuildIt throws an exception if any of the settings are missing or specified incorrectly, unless stated otherwise in this document.

The following code sample shows the format of the configuration file settings.

<configuration>
  <configSections>
    <section name="BuildIt" 
     type="Sapient.Framework.Tools.BuildIt.BuildItSectionHandler,    
     BuildIt"/>
  </configSections>

  <appSettings>
    <add key="appendTraceOutput" value="off" />
    <add key="enableCustomMessageFilter" value="on"/>
    <add key="visualStudioProgID" value="VisualStudio.Solution.7"/>
  </appSettings>

  <buildIt>
    <sourceControl username="username" password="password" 
     iniFilePath="c:\Program Files\Microsoft Visual Studio\VSS\srcsafe.ini" 
     srcVSSRootFolder="$/System" srcFileRootFolder="c:\System"/>

    <solutions latestRootFolderFullName="c:\System" 
     buildNumberFilePath="c:\System\BuildNumber.xml">
      <solution path=" c:\System\Solution1\Solution1.sln"/>
      <solution path=" c:\System\Solution2\Solution2.sln"/>
    </solutions>

    <options>
      <sendBuildReport mode="on/off" smtpServer="255.255.255.255" 
       toAddress="you@yourcompany.com"/>
      <archiveBuild mode="on/off" 
        archiveRootFolderFullName="c:\System\Archive">
        <additionalFoldersToArchive>
          <folder fullName="c:\System\Solution1\Setup1\Debug" 
           destFolderName="Debug\Setup1" />
          <folder fullName=" c:\System\Solution1\Setup1\Release" 
           destFolderName="Release\Setup1" />
        </additionalFoldersToArchive>
      </archiveBuild>
      <updateAssemblyVersion mode="on/off"   
       vbAssemblyVersionVSSPath="$/System/AssemblyVersionInfo.vb"
       csAssemblyVersionVSSPath="$/System/AssemblyVersionInfo.cs"/>  
    </options>
  </buildIt>
</configuration>
  

ConfigSections Element

The configSections element is used to link a section in the configuration file with a particular configuration section handler class. The section element in the preceding code is used to link the BuildIt section with the BuildItSectionHandler class in the Sapient.Framework.Tools.BuildIt namespace.

AppSettings Element

The appSettings element contains application-specific settings that can be represented as key-value pairs. BuildIt currently defines three specific settings:

  • appendTraceOutput. When this key is set to on, BuildIt appends trace output to the trace file named BuiltIt.log.
    Note   If this key is omitted or if the value is not set to on, BuildIt overwrites the trace file.
  • enableCustomMessageFilter. When this key is set to on, BuildIt enables a custom message filter to handle outgoing COM messages while waiting for a response from synchronous calls. The implementation of this filter retries rejected calls to Visual Studio .NET automation in the event that the objects are busy. If the Visual Studio .NET automation objects are busy and this filter is not enabled, an exception occurs.
    Note   If this key is omitted or if the value is not set to on, BuildIt does not enable the message filter.
  • visualStudioProgID. When the value of this key is set to a progID, BuiltIt is forced to use a specific version of Visual Studio .NET when building solutions.
    Note   If this key is omitted, BuildIt uses the latest installed version of Visual Studio .NET.

SourceControl Element

The sourceControl element contains information about the VSS database used during the build process. This element has the following attributes:

  • username. The name of the VSS user used to log on to the database.
  • password. The password of the VSS user.
  • iniFilePath. The VSS .ini file path used to locate the database (for example, C:\Program Files\Microsoft Visual Studio\VSS\srcsafe.ini).
  • srcVSSRootFolder. The VSS root folder that contains the source code being built (for example, $/System). BuildIt does a recursive Get operation from this VSS project.
  • srcFileRootFolder. The file system root folder where the source code is built (for example, C:\System). BuildIt copies files from the recursive Get operation to this directory.

Solutions Element

The solutions element contains information about the solutions being built. This element has the following attributes:

  • latestRootFolderFullName. The name of the root folder that contains the latest generated assemblies after the build is complete (for example, C:\System). For more information, see the "Copying Output to the Latest Folder" section of the article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library.
    Note   The article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library states that "single solution or partitioned-single solution systems do not require a Latest folder because you use project references rather than file references to refer to assemblies." However, because a single solution system can become a multi-solution system, BuildIt always copies build output to a latest folder. This allows developers to use file references when referring to assemblies generated from another solution.
  • buildNumberFilePath. The XML file used to generate the next build number (for example, C:\System\BuildNumber.xml). For more information, see the "Generating Build Version Numbers section" of the article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library.
    Note   The article "Team Development with Visual Studio .NET and Visual SourceSafe" does not dictate the way in which build numbers should be generated. BuildIt does it by incrementing the build number stored in a specified XML file at the end of each successful build. A successful build is one that does not contain any build errors.

Solution Element

The solution element contains information about a specific solution. This element has one attribute:

  • path. The solution file being built (for example, C:\System\Solution1\Solution1.sln).

Options Element

The options element contains child elements that correspond to various build options. Each build option is represented by a different element.

SendBuildReport Element

The sendBuildReport element controls whether the build report is sent to a specified e-mail address when the build completes. For more information, see the "Email Build Results" section of the article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library.

This element contains the following attributes:

  • mode. If "on," BuildIt sends the build report to the specified e-mail address.
  • smtpServer. If IP address of the SMTP server used to forward the e-mail message.
  • toAddress. The e-mail address to receive the build report.

Archive Build Element

The archiveBuild element controls whether the generated assemblies are archived to a folder named after the build number. For more information, see the "Consider Maintaining Previous Builds" section of the article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library.

This element contains the following attributes:

  • mode. If "on," BuildIt copies generated assemblies to a folder named after the build number.
  • archiveRootFolderFullName. The name of the root folder containing previously archived builds (for example, C:\System\Archive).

Additional Folders to Archive Element

By default, BuildIt archives output from only Visual C# and Visual Basic .NET projects. To archive output from other projects such as Visual Studio .NET setup projects, add folder elements to the additionalFoldersToArchive element.

The folder element contains the following attributes:

  • fullName. The full name of the source folder being archived (for example, C:\System\Solution1\Setup1\Debug).
  • destFolderName. The name of the destination folder to archive to (for example, Debug\Setup1).
Note   If the archiveBuild option is enabled, BuildIt archives the files in each specified folder to the specified destination folder under the archive root folder.

UpdateAssemblyVersion Element

The updateAssemblyVersion element controls whether the generated assemblies are versioned using the build number. For more information, see the "Controlling Assembly Version" section of the article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library.

This element contains the following attributes:

  • mode. If "on," BuildIt versions the generated assemblies with the build number.
  • vbAssemblyVersionVSSPath. The VSS path containing the assembly version file shared across all of the Visual Basic .NET projects being built (for example, $/System/AssemblyVersionInfo.vb). Leave this attribute value blank if your solution does not contain any Visual Basic projects. For more information, see the "Consider Centralizing Assembly Version Numbers" section of the article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library.
  • csAssemblyVersionVSSPath. The VSS path containing the assembly version file shared across all of the Visual C# projects being built (for example, $/System/AssemblyVersionInfo.cs). Leave this attribute value blank if your solution does not contain any Visual C# projects. For more information, see the "Consider Centralizing Assembly Version Numbers" section of the article "Team Development with Visual Studio .NET and Visual SourceSafe" in the MSDN Library.

Enhancements

This section contains a list of enhancements that were considered but ultimately scoped out of the first release of BuildIt due to time constraints. These are shared to expose the underlying thinking involved with the development of BuildIt, to suggest areas where you could expand BuildIt, and to invite you as a member of the community to contribute ideas—and code—using the feedback section at the end of the document. Potential enhancements include:

  • Define an interface to allow BuildIt to work with source control providers other than Visual SourceSafe (for example, ISourceControlProvider). In doing so, developers could configure BuildIt to use another source control provider such as Rational ClearCase.
  • Simplify the configuration of BuildIt by implementing default behavior if a particular setting is missing. Currently, BuildIt throws an error if a particular build setting is missing from the application configuration file. A more forgiving version of BuildIt would simply implement some default behavior if a setting were omitted.
  • Further simplify the configuration of BuildIt by utilizing relative paths instead of using fully qualified ones. Currently, all file paths must be fully qualified. Fully qualified paths are more flexible than relative ones, but at the expense of being cumbersome. Instead, simply configure by making some paths relative to the source root folder (for example, solution files, build number XML file, and so on).
  • Allow developers to specify an indefinite number of assembly version files with the updateAssemblyVersion build option. Currently, BuildIt allows developers to specify one Visual C# and one Visual Basic .NET assembly version file. This limitation is based on the assumption that developers will share the Visual C# assembly version file with all Visual C# projects and the Visual Basic .NET assembly version file with all Visual Basic .NET projects in VSS. However, developers may prefer to update individual assembly version files rather than relying on VSS file sharing.
  • Define a "post-build" event that developers can use to extend the build process. Currently, the only way to extend the build process is to alter the BuildIt source code. A more flexible design would be to implement an event that is raised at the end of the build. Developers could then wire event-handlers to this event to execute custom logic. This strategy could also be used to allow developers to customize other parts of the build process (for example, pre-build, build, post-build).
  • Allow developers to specify the name of the BuildIt configuration file. Currently, BuildIt looks for configuration settings in the standard application configuration file called BuildIt.exe.config. Because of this, developers cannot use BuildIt to build two different solutions at the same time. Instead, developers have to copy the BuildIt assemblies to a different directory. A more friendly solution would be to allow developers to specify the name of the configuration file as a command-line argument, rather than using the standard application configuration file.
  • Have BuildIt automatically create a virtual directory for any Web project that is not already mapped to one. Currently, Visual Studio .NET prompts the user to set the location for the working copy of a Web project if one does not exist. Instead of prompting the user to accept the default, BuildIt could simply create the virtual directory automatically.

Class Reference

This section includes information about the following class references:

BuildInitializer

BuildItSectionHandler

BuildManager

SourceSafeHelper

BuildItResourceManager

BuildItCommandLineArgs

BuildInitializer

The BuildInitializer class validates command-line options, retrieves build tool settings by way of the BuildItSectionHandler and initiates the build process by way of the BuildManager.

Remarks

The BuildInitializer class implements a single public method named Start that is called from the console application's static/Shared Main method. The Start method first validates any command-line arguments by calling a private method named AreCommandLineArgsValid. If the arguments are valid, the BuildInitializer retrieves build tool settings using the BuildItSectionHandler class. The final step is to initiate the build process by calling Build on the BuildManager.

Constructors

BuildInitializerInitializes a new instance of the BuildInitializer class.

Public Methods

StartReads settings from the build tool configuration file using the BuildItSectionHandler class and then starts the build process by way of the BuildManager class.

Private Methods

AreCommandLineArgsValidDetermines whether the given command-line arguments are valid.
IsCommandLineArgValidDetermines whether the given command-line argument is valid.
UsageWrites usage information to the console. Called if any of the command-line arguments are invalid.

BuildItSectionHandler

The BuildItSectionHandler class populates and returns a BuildItSettings structure with settings read from the build tool configuration file.

Remarks

The BuildItSectionHandler class, which implements the IConfigurationSectionHandler interface, parses the configuration settings in the BuildIt element of the build tool configuration file. It loads the information in the BuildIt element into a structure named BuildItSettings.

The BuildItSettings structure defines several properties that provide type-safe access to the configuration settings defined in the configuration file. For example, the BuildItSettings structure defines three properties that return different build options: OptionSendBuildReport, OptionArchiveBuild, and OptionUpdateAssemblyVersion. The BuildItSettings structure also defines a property called Solutions and one called SourceControlInfo that correspond to specific elements in the configuration file.

Constructors

BuildItSectionHandlerInitializes a new instance of the BuildItSectionHandler class.

Public Methods

CreatePopulates and returns a BuildItSettings structure with settings read from the build tool configuration file.

Private Methods

CreateBuildOptionCreates and populates a BuildOption structure with settings read from the build tool configuration file.

BuildManager

The BuildManager class orchestrates the build process.

Remarks

The BuildManager class is used by the BuildInitializer to coordinate the build process. The BuildManager implements a constructor that takes two parameters: one of type BuildItSettings and one of type BuildItResourceManager. When an instance of the BuildManager class is created, it initializes private member variables with the parameters passed to its constructor. This makes settings and error messages available to the BuildManager during the build process.

The BuildManager also exposes a single public method named Build that takes a BuildType enum used to determine whether to initiate a Build or a Rebuild. The BuildType enum is defined as follows.

[C#]
public enum BuildType {Build, Rebuild};
  

A Rebuild is defined as a system build that takes place after a build break is resolved. The distinction is made because some steps are omitted when doing a Rebuild. For example, the BuildManager creates a new label in VSS when doing a Build, but not when doing a Rebuild.

After the BuildType is determined, the BuildManager calls several private methods that perform various parts of the build process.

Constructors

BuildManagerInitializes a new instance of the BuildManager class.

Public Methods

BuildOrchestrates the build process.

Private Methods

ArchiveAdditionalFoldersCopies the contents of folders specified in the additionalFoldersToArchive section of the build tool configuration file to the archive root folder.
BackupLatestFolderBacks up the latest folder that contains the latest generated assemblies. The location of the latest folder is specified in the build tool configuration file.
BuildAssemblyVersionRegExBuilds a regular expression that is used to replace the build number component of an AssemblyVersion attribute. The expression is dependent upon whether the AssemblyVersion attribute is a Visual Basic or Visual C# attribute.
BuildSolutionAndCopyOutputBuilds a solution and copies the generated output to the given destination directories.
BuildSolutionConfigBuilds the given solution using the specified build configuration (for example, Release, Debug, and so on).
BuildSolutionsBuilds the given solution(s).
CopyFiles(string, string)Copies all files from the given source folder to the given destination folder by calling the overloaded version of the method with excludeDebugFiles flag set to false.
CopyFiles(string, string, bool)Copies all files from the given source folder to the given destination folder. If the excludeDebugFiles flag is set to true, copies all files except debug files.
CopyVSProjectOutputCopies output (Release or Debug) for all Visual Basic and Visual C# projects to the given destination root folder.
CopySolutionOutputCopies solution output (Release or Debug) to the given destination root folders.
DeleteArchiveFolderDeletes the archive folder if it exists. The location of the archive folder is specified in the build tool configuration file.
DeleteLatestBackupFolderDeletes the latest backup folder if it exists. The latest backup folder is located in the same place as the latest folder.
DeleteLatestFolderDeletes the latest folder if it exists.
GenerateBuildReportGenerates a build report called BuildReport.log and saves the report to the working folder.
GenerateLabelGenerates a label based on the build number.
GetSourceFromLabelGets the source root project from VSS using the given label.
GetVSProjectLangTypeDetermines the language used to create the specified file (Visual Basic or Visual C#). Uses the file extension to make this determination.
IncrementBuildNumberIncrements the build number by one and then writes it to the build number XML file by calling WriteBuildNumber.
LabelSourceLabels the source root project in VSS with the given label.
ReadBuildNumberReads the build number from the build number XML file. The name and location of this file is specified in the build tool configuration file.
RestoreLatestFolderRestores the latest folder from the latest backup folder if it exists.
SendBuildReportSend the given build report to the appropriate email recipient if the option is enabled in the build tool configuration file.
UpdateAssemblyVersionInfoGets the VSS path of the Visual Basic and Visual C# AssemblyVersion files (specified in the build tool configuration file) and calls the overloaded version of the method once for each file if the option is enabled in the build tool configuration file.
UpdateAssemblyVersionInfo(string)Gets the specified AssemblyVersion file from VSS, updates the AssemblyVersion attribute with the build number using a regular expression, and then checks the file back into VSS.
WriteBuildNumberWrites the given build number to the build number XML file.

SourceSafeHelper

The SourceSafeHelper wraps VSS automation objects to make it easier to work with VSS.

Remarks

The SourceSafeHelper class is used by the BuildManager to interact with VSS during the build process. It exposes several public methods, such as Checkin and Checkout, that hide the implementation details of working with VSS automation objects.

Note   The SourceSafeHelper class does not expose methods for every VSS operation. It exposes only those operations needed by the build tool.

Constructors

SourceSafeHelperInitializes a new instance of the SourceSafeHelper class.

Public Methods

CheckinChecks the given item back into VSS.
CheckoutChecks the given item out from VSS.
GetFromLabelGets a specific version of a given item from VSS. If the item is a project, the get operation is recursive.
LabelLabels the given VSS item with the specified label.
UndoCheckoutRemoves checkout status on a given VSS item.

Private Methods

GetItemsRecursivelyRecursively gets items from a versioned VSSItem (a project or file). The versioned item can be a project or a file. If the VSSItem is a file, this method simply gets the file. Otherwise, it recursively gets all items in the project.
GetVSSItemGets a reference to a VSSItem (that is, a project or file).

BuildItResourceManager

The BuildItResourceManager class provides type-safe access to error messages stored in a resource file.

Remarks

The BuildItResourceManager class, derived from the ResourceManager class in the System.Resources namespace, is used to retrieve error messages from the resource file contained in the build tool assembly called BuildIt.exe. It exposes several public methods, such as GetBuildSolutionFailedString, that provide type-safe access to resource values. This helps eliminate errors that can occur when calling the ResourceManager.GetString(string name) method with an invalid resource name.

Constructors

BuildItResourceManagerInitializes a new instance of the BuildItResourceManager class.

Public Methods

GetBuildSolutionFailedStringGets the BuildSolutionFailed error message from the build tool resource file. The rest of the get methods perform a similar function; they provide type-safe access to error messages stored in the build tool resource file.

Private Methods

None 

BuildItCommandLineArgs

The BuildItCommandLineArgs class encapsulates a collection of command-line arguments supported by the build tool.

Remarks

The BuildItCommandLineArgs class, derived from the StringCollection class in the System.Collections.Specialized namespace, represents the set of command-line arguments supported by BuildIt. It is used by the BuildInitializer to determine whether or not a command-line argument is valid.

Constructors

BuildItCommandLineArgsInitializes a new instance of the BuildItCommandLineArgs class.

Public Methods

ToStringOverrides the System.Object::ToString() method by providing a string representation of the valid command-line arguments.

Private Methods

None 

Frequently Asked Questions

Can I modify the BuildIt source code?

Yes, you can modify and extend the BuildIt source code. For example, you could change the Visual Source Safe-specific calls and build a Helper class that works with your Source Code Control product. Please tell us what changes you made! See the Feedback section below to share your experience with us.

Do I need to have Visual Studio installed where BuildIt runs?

Yes, you need to have Visual Studio installed on the server or workstation where you do the builds with BuildIt—having just the .NET Framework redistributable installed is not enough.

Summary

This document has described how BuildIt is built with simplicity and extensibility in mind so that you can adapt it to your specific build-process needs. Please use the e-mail address provided under "Feedback" to tell us your thoughts about BuildIt.

About the Author

Michael Monteiro is a technology consultant for Sapient Corporation and .NET Microsoft Certified Professional with more than eight years of experience. He currently works on a team responsible for providing architectural guidance to the technical community within Sapient. He can be reached at mmonte@sapient.com.

About Sapient

Sapient, a leading business and technology consultancy, helps Global 2000 clients achieve measurable business results through the rapid application and support of advanced technology on a fixed-price basis. Founded in 1991, Sapient employs more than 1,500 people in offices in Atlanta, Cambridge (Mass.), Chicago, Dallas, Dusseldorf, London, Los Angeles, Milan, Munich, New Delhi, New York, San Francisco, Toronto and Washington, D.C. More information about Sapient can be found at www.sapient.com.

Collaborators

Many thanks to the following contributors and reviewers: Bernard Chen (Sapient Corporation), Brett Keown, Craig Skibo, David Lewis, Deyan Lazarov, Dimitris Georgakopoulos (Sapient Corporation), Edward Jezierski, Filiberto Selvas Patiûo, Jeff Pflum, Joe Hom (Avanade), Ken Hardy, Kenny Jones, Korby Parnell, Martin Born, Mick Das, Mike Pietraszak, Niel Sutton, Oded Ye Shekel, Rajiv Sodhi (Sapient Corporation), Ray Escamilla, Rich Knox, Russell Christopher, and Sumit Sharma (Sapient Corporation).

Feedback

Questions? Comments? Suggestions? To give feedback on BuildIt, please e-mail buildit@sapient.com.

If you want to contact Microsoft for feedback, please e-mail devfdbck@microsoft.com.

Show: