Professional Visual Studio 2005 (2006) [eng]

Chapter 46

Compilation Constants

Compilation constants can be used to control what information is included in the build output and even what code is compiled. The Compilation Constants options control the following:

Define DEBUG constant and Define TRACE constant: Enable debug and trace information to be included in the compiled application based on the DEBUG and TRACE flags, respectively.

Custom constants: If your application build process requires custom constants you can specify them here in the form ConstantName=”Value”. If you have multiple constants, they should be delimited by commas.

Generate serialization assemblies: By default this option is set to Auto, which enables the build process to determine whether serialization assemblies are needed or not, but you can change it to On or Off if you want to hard-code the behavior.

Target CPU: Depending on what CPU types are known to your system, this option enables you to optimize the build output to a specific platform. The default option of AnyCPU provides output that can be run on any CPU capable of running .NET 2.0 software.

Build Events

You can perform additional actions before or after the build process by adding them to an events list. Click the Build Events button on the My Project Compile page to display the Build Events dialog (shown in Figure 46-7).

Figure 46-7

656

Build Customization

Each action you want to perform should be on a separate line, and can be added directly into either the “Pre-build event command line” text area or the “Post-build event command line” text area, or you can use the Edit Pre-build and Edit Post-build buttons to access the known predefined aliases that you can use in the actions.

Shown in Figure 46-8, the Event Command Line dialog includes a list of macros you can use in the creation of your actions. A value is displayed for each macro so you know exactly what text will be included if you use it.

In this sample, the developer has created a command line of $(TargetDir)$(TargetFileName)$ (TargetExt), assuming that it would execute the built application when finished. However, analyzing the values of each of the macros, it’s easy to see that the extension will be included twice, which can be amended quickly by either simply removing the $(TargetExt) macro or replacing the $(TargetFileName) macro with $(TargetFile).

Figure 46-8

C# Build Pages

C# provides its own set of build options. In general, the options are the same as those available to a Visual Basic project, but in a different location because it’s more likely that C# programmers will want to tweak the output than Visual Basic developers, who are typically more interested in rapid development than fine-tuning performance.

Instead of a single Compile page in the project property pages, C# has a Build page and a Build Events page. The Build Events page acts in exactly the same way as the Build Events dialog in Visual Basic, so refer to the previous discussion for information on that page.

657

Chapter 46

As you can see in Figure 46-9, many of the options on the Build page have direct correlations to settings found in the Compile page or in the Advanced Compiler Settings area of Visual Basic. Some settings, such as the Define DEBUG constant and the Define TRACE constant, are identical to their Visual Basic counterparts.

Figure 46-9

However, some are renamed to fit in with a C-based vocabulary, so Allow Unsafe Code is effectively the same as the Visual Basic “Remove integer overflow checks,” “Optimize code is equivalent to Enable optimizations,” and so on.

The Errors and Warnings section of the C# Build page, covered in Chapter 29, is the same as the Visual Basic Conditions and Warnings settings, as they deal with conditional and pre-emptive messages warning you of potential errors in your code.

Advanced

Clicking the Advanced button on the Build page invokes the Advanced Build Settings dialog, shown in Figure 46-10, which includes settings that are not accessible to Visual Basic developers. These settings give you tight control over how the build will be performed, including information on the internal errors that occur during the compilation process and what debug information is to be generated.

658

Build Customization

Figure 46-10

These settings are mostly self-explanatory, so the following list is a quick summary of what effect each one has on the build:

Language Version: Specifies which version of the C# language to use. The default is to use the current version. In Visual Studio 2005, the only other option is ISO-1, which restricts the available language features to the ISO standard.

Internal Compiler Error Reporting: If errors occur during the compilation (not compilation errors, but errors with the compilation process itself), you can have information sent to Microsoft so they can add it to their revision of the compiler code. The default setting is prompt, which asks you whether you want to send the information to Microsoft.

Other values include none, which won’t send the information; send, to automatically send the error information; and queue, which adds the details to a queue to be sent later.

Check for arithmetic overflow/underflow: Checks for overflow errors that can cause unsafe execution. Underflow errors occur when the precision of the number is too fine for the system.

Do not reference mscorlib.dll: By default, the mscorlib.dll, which defines the System namespace, is automatically referenced in your project, but you can check this option to build your own System namespace and associated objects.

Debug Info: Identical to the Visual Basic Generate debug info setting

File Alignment: Used to set the section boundaries in the output file, and enables you to control the internal layout of the compiled output. The values are measured in bytes.

DLL Base Address: Identical to the Visual Basic setting of the same name

Using these settings for your projects enables you to closely control how the build process will perform. However, you have another option with Visual Studio 2005, which is to edit the build scripts directly. This is made possible because Visual Studio 2005 uses MSBuild for its compilations.

659

Chapter 46

MSBuild

MSBuild is the new compilation engine Microsoft has released simultaneously with Visual Studio 2005. It uses XML-based configuration files to identify the layout of a build project, including all of the settings discussed earlier in this chapter, as well as what files should be included in the actual compilation.

In fact, Visual Studio 2005 uses MSBuild configuration files as its project definition files, in place of the old project file formats used by previous versions of Visual Studio. This enables the MSBuild engine to be used automatically when compiling your applications within the IDE because the same settings file is used for both your project definition in the IDE and the build process.

How Visual Studio Uses MSBuild

As already mentioned, the contents of Visual Studio 2005 project files are based on the MSBuild XML Schema and can be edited directly in Visual Studio so you can customize how the project is loaded and compiled.

However, to edit the project file you need to effectively remove the project’s active status from the Solution Explorer. Right-click the project you want to edit in the Solution Explorer and choose the Unload Project command from the bottom of the context menu that is displayed.

The project will be collapsed in the Solution Explorer and marked as unavailable. In addition, any open files that belong to the project will be closed while it is unloaded from the solution. Right-click the project entry again and an additional menu command will be available to edit the project file (see Figure 46-11).

Figure 46-11

660

Build Customization

The XML-based project file will be correspondingly opened in the XML editor of Visual Studio 2005, enabling you to collapse and expand nodes. The following listing is a sample MSBuild project file for an empty Visual Basic project:

<?xml version=”1.0” encoding=”utf-8”?> <Project DefaultTargets=”Build”

xmlns=”http://schemas.microsoft.com/developer/msbuild/2003”>

<PropertyGroup>

<Configuration Condition=” ‘$(Configuration)’ == ‘’ “>Debug</Configuration> <Platform Condition=” ‘$(Platform)’ == ‘’ “>AnyCPU</Platform> <ProductVersion>8.0.50727</ProductVersion> <SchemaVersion>2.0</SchemaVersion> <ProjectGuid>{7ED1BE7E-502C-4AF2-83FD-F441848A567B}</ProjectGuid> <OutputType>WinExe</OutputType>

<RootNamespace>Project1</RootNamespace>

<AssemblyName>Project1</AssemblyName>

<MyType>Empty</MyType>

</PropertyGroup>

<PropertyGroup Condition=” ‘$(Configuration)|$(Platform)’ == ‘Debug|AnyCPU’ “> <DebugSymbols>true</DebugSymbols>

<DebugType>full</DebugType>

<DefineDebug>true</DefineDebug>

<DefineTrace>true</DefineTrace>

<OutputPath>bin\Debug\</OutputPath>

<DocumentationFile>

</DocumentationFile>

</PropertyGroup>

<PropertyGroup Condition=” ‘$(Configuration)|$(Platform)’ == ‘Release|AnyCPU’ “> <DebugType>pdbonly</DebugType>

<DefineDebug>false</DefineDebug>

<DefineTrace>true</DefineTrace>

<Optimize>true</Optimize>

<OutputPath>bin\Release\</OutputPath>

<DocumentationFile>

</DocumentationFile>

</PropertyGroup>

<ItemGroup>

<Import Include=”Microsoft.VisualBasic” /> <Import Include=”System” />

</ItemGroup>

<ItemGroup>

<Folder Include=”My Project\” /> </ItemGroup>

<Import Project=”$(MSBuildBinPath)\Microsoft.VisualBasic.targets” />

<!-- To modify your build process, add your task inside one of the targets below and uncomment it.

Other similar extension points exist, see Microsoft.Common.targets. <Target Name=”BeforeBuild”>

</Target>

<Target Name=”AfterBuild”> </Target>

--> </Project>

661

Chapter 46

The XML contains the information about the build. In fact, most of these nodes directly relate to settings you saw earlier in the Compile and Build pages, but also include any Framework namespaces that are required.

When the project includes additional files, such as forms and user controls, each one is defined in the project file with its own set of nodes. For example, the following listing shows the additional XML that is included in a standard WindowsApplication project, identifying the Form, its designer code file, and the additional system files required for a Windows-based application:

<ItemGroup>

<Compile Include=”Form1.vb”> <SubType>Form</SubType>

</Compile>

<Compile Include=”Form1.Designer.vb”> <DependentUpon>Form1.vb</DependentUpon> <SubType>Form</SubType>

</Compile>

<Compile Include=”My Project\AssemblyInfo.vb” /> <Compile Include=”My Project\Application.Designer.vb”>

<AutoGen>True</AutoGen>

<DependentUpon>Application.myapp</DependentUpon>

</Compile>

<Compile Include=”My Project\Resources.Designer.vb”> <AutoGen>True</AutoGen> <DesignTime>True</DesignTime> <DependentUpon>Resources.resx</DependentUpon>

</Compile>

<Compile Include=”My Project\Settings.Designer.vb”> <AutoGen>True</AutoGen> <DependentUpon>Settings.settings</DependentUpon> <DesignTimeSharedInput>True</DesignTimeSharedInput>

</Compile>

</ItemGroup>

You can also include additional tasks in the build process in the included Target nodes for BeforeBuild and AfterBuild, but if you use a new PropertyGroup node that includes PreBuildEvent and PostBuildEvent entries, you can then view the included actions in the Build Events window discussed earlier in this chapter.

For instance, if you wanted to execute the application after it was successfully built, you could include the following XML block immediately before the closing </Project> tag:

<PropertyGroup> <PostBuildEvent>$(TargetDir)$(TargetFileName)</PostBuildEvent>

</PropertyGroup>

Once you’ve finished editing the project file’s XML, you need to re-enable it in the solution by rightclicking the project’s entry in the Solution Explorer and selecting the Reload Project command. If you still have the project file open, Visual Studio will close it automatically.

662

Build Customization

MSBuild Schema

An extended discussion on the MSBuild engine is beyond the scope of this book. However, it’s useful to understand the different components that make up the MSBuild project file so you can look at and update your own projects.

Four major elements form the basis of the project file: items, properties, targets, and tasks. Brought together, you can use these four node types to create a configuration file that describes a project in full, as shown in the previous sample Visual Basic project file.

Items

Items are those elements that define inputs to the build system and project. They are defined as children of an ItemGroup node, and the most common item is the Compile node used to identify to MSBuild that the specified file is to be included in the compilation. The following snippet from a project file shows an Item element defined for the Form1.Designer.vb file of a WindowsApplication project:

<ItemGroup>

<Compile Include=”Form1.Designer.vb”> <DependentUpon>Form1.vb</DependentUpon>

<SubType>Form</SubType>

</Compile>

</ItemGroup>

Properties

PropertyGroup nodes are used to contain any properties defined to the project. Properties are typically key/value pairings. They can only contain a single value and are used to store the project settings you can access in the Build and Compile pages in the IDE.

PropertyGroup nodes can be optionally included by specifying a Condition attribute, as shown in the following sample listing:

<PropertyGroup Condition=” ‘$(Configuration)|$(Platform)’ == ‘Release|AnyCPU’ “> <DebugType>pdbonly</DebugType>

<DefineDebug>false</DefineDebug>

<DefineTrace>true</DefineTrace>

<Optimize>true</Optimize>

<OutputPath>bin\Release\</OutputPath>

</PropertyGroup>

This XML defines a PropertyGroup that will only be included in the build if the project is being built as a Release for the AnyCPU platform. Each of the five property nodes within the PropertyGroup uses the name of the property as the name of the node.

Targets

Target elements enable you to arrange tasks (discussed in the next section) into a sequence. Each Target element should have a Name attribute to identify it, and it can be called directly, thus enabling you to provide multiple entry points into the build process. The following snippet defines a Target with a name of BeforeBuild:

663

Chapter 46

<Target Name=”BeforeBuild”>

</Target>

Tasks

Tasks define actions that MSBuild will execute under certain conditions. You can define your own tasks or take advantage of the many built-in tasks such as Copy. Shown in the following snippet, Copy can copy one or more files from one location to another:

<Target Name=”CopyFiles”>

<Copy

SourceFiles=”@(MySourceFiles)”

DestinationFolder=”\\PDSERVER01\SourceBackup\”

/>

</Target>

Summar y

The default build behavior can be customized with an enormous range of options in Visual Studio 2005, particularly for Visual Basic and C# projects because they’re based on the MSBuild engine. Within the project file you can include additional actions to perform both before and after the build has taken place, as well as include additional files in the compilation.

With the information in this chapter, you can now set up your projects to build in a way that makes sense for your own requirements.

664