Team Development with Visual Studio.NET and Visual SourceSafe
| Retired Content |
|---|
| This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
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
- In Visual SourceSafe® (VSS) version control system, create a new project named BuildItTest.
- Set the working folder on $/BuildItTest to Program Files\BuildIt\Code\BuildItTest.
- Add assembly version files to VSS:
- Add Program Files\BuildIt\Code\BuildItTest\AssemblyVersionInfo.cs to $/BuildItTest.
- Repeat for AssemblyVersionInfo.vb.
- Create a virtual directory for the Web project (Project2):
- Browse to Program Files\BuildIt\Code\BuildItTest\Solution2\Project2.
- Right-click Project2, and then click Properties.
- Click the Web Sharing tab, and then click Share this folder.
- Accept the default alias, and then click OK to close the Edit Alias dialog box.
- Click OK to close the Properties dialog box.
- Add solutions to VSS:
- Open Program Files\BuildIt\Code\BuildItTest\Solution1\Solution1.sln.
- In Solution Explorer, right-click Solution1, and then click Add Solution to Source Control.
- Browse to $/BuildItTest, and then click OK (click Yes to create the VSS project).
- If prompted to specify the location for Project1, browse to $/BuildItTest/Solution1, and then click OK.
- Repeat Steps a–d for Solution2.
- Share assembly version files in VSS:
- Share****$/BuildItTest/AssemblyVersionInfo.cs to $/BuildItTest/Solution1/Project1.
- Share****$/BuildItTest/AssemblyVersionInfo.vb to $/BuildItTest/Solution2/Project2.
To add assembly version files to projects
- Add AssemblyVersionInfo.cs to Project1 found in Solution1:
- Open Program Files\BuildIt\Code\BuildItTest\Solution1\Solution1.sln.
- In Solution Explorer, right-click Project1, point to Add, and then click Add Existing Item.
- Browse to Program Files\BuildIt\Code\BuildItTest\Solution1\Project1\AssemblyVersionInfo.cs, and then click Open.
- In the Check Out for Edit dialog box, click Check Out to check out Project1.csproj.
- Open AssemblyVersionInfo.cs and note the version number (1.0.0.*).
- Press CTRL+SHIFT+B to build the solution.
- In Solution Explorer, right-click Project1, and then click Check In Now (Recursive).
- Repeat Steps a–g to add AssemblyVersionInfo.vb to Project2 found in Solution2.
- Update configuration settings:
- Open Program Files\BuildIt\Code\BuildItTest\BuildIt.exe.config.
- Update the sourceControl settings.
- Deploy BuildIt:
- Open Program Files\BuildIt\Code\BuildIt.sln.
- Press CTRL+SHIFT+B to build the solution (make sure you build a Release version).
- Copy the .exe file and all .dll files from Program Files\BuildIt\Code\BuildIt\bin\Release to Program Files\BuildIt\Code\BuildItTest.
- Execute BuildIt and verify:
- Open Program Files\BuildIt\Code\BuildItTest\BuildNumber.xml and note that the next build number is 1.
- Open Program Files\BuildIt\Code\BuildItTest\BuildIt.bat to review the BuildIt command line.
- Run BuildIt.bat to build the solutions.
- Open Program Files\BuildIt\Code\BuildItTest\BuildIt.log to check for errors.
- Open Program Files\BuildIt\Code\BuildItTest\BuildReport.log to review results of the build.
- Open BuildNumber.xml and note that the next build number was incremented to 2.
- Open AssemblyVersionInfo.cs and AssemblyVersionInfo.vb and note that the version numbers were updated from 1.0.0.* to 1.0.1.*.
- 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.
- Browse to Program Files\BuildIt\Code\BuildItTest\Latest to see that the generated assemblies were copied to the latest folder.
- 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
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.
Make the code change, recompile using Visual Studio .NET, and then test the recompiled files.
After the problem is resolved, check in the modified files.
Manually update the label on each checked-in file with the label that was generated by the previous build, as follows:
- Right-click the file name, and then click Show History.
- In the History Options dialog box, click OK.
- Click the version of the file whose label you want to update, and then click Details.
- Update the Label field with the label used during the build (for example, "Build 100").
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
| Issue | Description | Resolution |
|---|---|---|
| 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:
- BuildIt is launched with the appropriate command-line arguments.
- The Main1 class calls the Start method of the BuildInitializer class.
- 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.
- The BuildInitializer creates an instance of the BuildManager, passing the BuildItSettings structure to the Constructor.
- 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/SharedMain 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
| BuildInitializer | Initializes a new instance of the BuildInitializer class. |
|---|
Public Methods
| Start | Reads 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
| AreCommandLineArgsValid | Determines whether the given command-line arguments are valid. |
|---|---|
| IsCommandLineArgValid | Determines whether the given command-line argument is valid. |
| Usage | Writes 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
| BuildItSectionHandler | Initializes a new instance of the BuildItSectionHandler class. |
|---|
Public Methods
| Create | Populates and returns a BuildItSettings structure with settings read from the build tool configuration file. |
|---|
Private Methods
| CreateBuildOption | Creates 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
| BuildManager | Initializes a new instance of the BuildManager class. |
|---|
Public Methods
| Build | Orchestrates the build process. |
|---|
Private Methods
| ArchiveAdditionalFolders | Copies the contents of folders specified in the additionalFoldersToArchive section of the build tool configuration file to the archive root folder. |
|---|---|
| BackupLatestFolder | Backs up the latest folder that contains the latest generated assemblies. The location of the latest folder is specified in the build tool configuration file. |
| BuildAssemblyVersionRegEx | Builds 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. |
| BuildSolutionAndCopyOutput | Builds a solution and copies the generated output to the given destination directories. |
| BuildSolutionConfig | Builds the given solution using the specified build configuration (for example, Release, Debug, and so on). |
| BuildSolutions | Builds 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. |
| CopyVSProjectOutput | Copies output (Release or Debug) for all Visual Basic and Visual C# projects to the given destination root folder. |
| CopySolutionOutput | Copies solution output (Release or Debug) to the given destination root folders. |
| DeleteArchiveFolder | Deletes the archive folder if it exists. The location of the archive folder is specified in the build tool configuration file. |
| DeleteLatestBackupFolder | Deletes the latest backup folder if it exists. The latest backup folder is located in the same place as the latest folder. |
| DeleteLatestFolder | Deletes the latest folder if it exists. |
| GenerateBuildReport | Generates a build report called BuildReport.log and saves the report to the working folder. |
| GenerateLabel | Generates a label based on the build number. |
| GetSourceFromLabel | Gets the source root project from VSS using the given label. |
| GetVSProjectLangType | Determines the language used to create the specified file (Visual Basic or Visual C#). Uses the file extension to make this determination. |
| IncrementBuildNumber | Increments the build number by one and then writes it to the build number XML file by calling WriteBuildNumber. |
| LabelSource | Labels the source root project in VSS with the given label. |
| ReadBuildNumber | Reads the build number from the build number XML file. The name and location of this file is specified in the build tool configuration file. |
| RestoreLatestFolder | Restores the latest folder from the latest backup folder if it exists. |
| SendBuildReport | Send the given build report to the appropriate email recipient if the option is enabled in the build tool configuration file. |
| UpdateAssemblyVersionInfo | Gets 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. |
| WriteBuildNumber | Writes 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
| SourceSafeHelper | Initializes a new instance of the SourceSafeHelper class. |
|---|
Public Methods
| Checkin | Checks the given item back into VSS. |
|---|---|
| Checkout | Checks the given item out from VSS. |
| GetFromLabel | Gets a specific version of a given item from VSS. If the item is a project, the get operation is recursive. |
| Label | Labels the given VSS item with the specified label. |
| UndoCheckout | Removes checkout status on a given VSS item. |
Private Methods
| GetItemsRecursively | Recursively 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. |
|---|---|
| GetVSSItem | Gets 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
| BuildItResourceManager | Initializes a new instance of the BuildItResourceManager class. |
|---|
Public Methods
| GetBuildSolutionFailedString | Gets 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
| BuildItCommandLineArgs | Initializes a new instance of the BuildItCommandLineArgs class. |
|---|
Public Methods
| ToString | Overrides 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.
| Retired Content |
|---|
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |