Assembly Version Resource Information

When AL.exe or CSC.exe produces a PE file assembly, it also embeds into the PE file a standard Win32 Version resource. Users can examine this resource by viewing the file's properties. Figure 2-4 shows the Version page of the JeffTypes.dll Properties dialog box.

Legaltrademarks

-igure 2-4 : Version tab of the JeffTypes.dll Properties dialog box

In addition, you can use the resource editor in Visual Studio .NET, shown in Figure 2-5, to view/modify the version resource fields.

Microsoft Development Environment [design] - JeffTypes.dll (...

-G*

Debug Tools Window

Help

\3

JeffTypes.dll JeffTypes.dll (1 - Version)

Jf Key lvalue

JeffTypes.dll JeffTypes.dll (1 - Version)

Jf Key lvalue

FILEVERSION

PRODUCTVERSION

FILEFLAGSMASK

FILEFLAGS

FILEOS

FILETYPE

FILESUBTYPE

0x3fL

OxOL

VOS_WINDOWS32 VFT_DLL

VFT2 UNKNOWN

Block Header

Assembly Version

Comments

CompanyName

FileDescription

FileVersion

InternalName

LegalCopyright

LegalTrademarks

OriginalFilename

PrivateBuild

ProductName

ProductVersion

SpecialBuild

Ready

Language Neutral (000004b0) 3.0.0.0

This assembly contains Jeffs types The Jeffrey Richter Company Jeff's type assembly 1.0.0.0 JeffTypes.dll

Copyright (c) 2002 Jeffrey Richter

JeffTypes is a registered trademark of the Richter Company JeffTypes.dll

Jeffrey Richter Type Library 2.0.0.0

Figure 2-5 : Resource editor in Visual Studio .NET

When building an assembly, you should set the version resource fields using custom attributes that you apply at the assembly level in your source code. Here's what the code that produced the version information in Figure 2-5 looks like:

using System.Reflection;

// Set the version CompanyName, LegalCopyright & LegalTrademarks fields [assembly:AssemblyCompany("The Jeffrey Richter Company")] [assembly:AssemblyCopyright("Copyright (c) 2002 Jeffrey Richter")] [assembly:AssemblyTrademark(

"JeffTypes is a registered trademark of the Richter Company")]

// Set the version ProductName & ProductVersion fields [assembly:AssemblyProduct("Jeffrey Richter Type Library")] [assembly:AssemblyInformationalVersion("2.0.0.0")]

// Set the version FileVersion, AssemblyVersion, // FileDescription, and Comments fields [assembly:AssemblyFileVersion("1.0.0.0")] [assembly:AssemblyVersion("3.0.0.0")] [assembly:AssemblyTitle("Jeff's type assembly")]

[assembly:AssemblyDescription("This assembly contains Jeff's types")]

// Set the culture (discussed later in the "Culture" section) [assembly:AssemblyCulture("")]

Table 2-4 shows the version resource fields and the custom attributes that correspond to them. If you're using AL.exe to build your assembly, you can use command-line switches to set this information instead of using the custom attributes. The second column in Table 2-4 shows the AL.exe command-line switch that corresponds to each version resource field. Note that the C# compiler doesn't offer these command-line switches and that, in general, using custom attributes is the preferred way to set this information.

Table 2-4: Version Resource Fields and Their Corresponding AL.exe Switches and Custom Attributes

FILEVERS

Table 2-4: Version Resource Fields and Their Corresponding AL.exe Switches and Custom Attributes

Version Resource

AL.exe Switch

Custom Attribute/Comment

ON /fileversioi

i System.Re

flection.AssemblyFileVersionAttribute-FileVersionAttribute

PRODUCTVERSION

/productversion

System.Reflection.AssemblylnformationalVersionAttribute

FILEFLAGSMASK

(none)

Always set to VS FFI FILEFLAGSMASK (defined in WinVer.h as 0x0000003F)

FILEFLAGS

(none)

Always 0

FILEOS

(none)

Currently always VOS_WINDOWS32

FILETYPE

/target

Set to VFT_APP if /target:exe or /target:winexe is specified; set to VFT_DLL if /target:library is specified

FILESUBTYPE

(none)

Always set to VFT2 UNKNOWN (This field has no meaning for VFT_APP and VFT_DLL.)

AssemblyVersion

/version

System.Reflection.Assembly-VersionAttribute

Comments

/description

System.Reflection.Assembly-DescriptionAttribute

CompanyName

/company

System.Reflection.AssemblyCompanyAttribute

FileDescription

/title

System.Reflection.AssemblyTitleAttribute

FileVersion

/version

System.Reflection.AssemblyVersionAttribute

InternalName

/out

Set to the name of the output file specified (without the extension)

LegalCopyright

/copyright

System.Reflection.AssemblyCopyrightAttribute

LegalTrademarks

/trademark

System.Reflection.AssemblyTrademarkAttribute

OriginalFilename

/out

Set to the name of the output file (without a path)

PrivateBuild

(none)

Always blank

ProductName

/product

System.Reflection.AssemblyProductAttribute

ProductVersion

/productversion

System.Reflection.AssemblyInformationalVersionAttribute

SpecialBuild

(none)

Always blank

Important When you create a new C# project in Visual Studio .NET, an AssemblyInfo.cs file is automatically created for you. This file contains all the assembly attributes described in this section plus a few additional attributes that I'll cover in Chapter 3. You can simply open the AssemblyInfo.cs file and modify your assembly-specific information. The file that Visual Studio .NET creates for you has some problems that I'll go over later in this chapter. In a real production project, you must modify the contents of this file.

Version Numbers

In the previous section, you saw that several version numbers can be applied to an assembly. All these version numbers have the same format: each consists of four period-separated parts, as shown in Table 2-5.

Table 2-5: Format of Version Numbers

Part

Major Number

Minor Number

Build Number

Revision Number

Example:

2

5

719

2

Table 2-5 shows an example of a version number: 2.5.719.2. The first two numbers make up the "public perception" of the version. The public will think of this example as version 2.5 of the assembly. The third number, 719, indicates the build of the assembly. If your company builds its assembly every day, you should increment the build number each day as well. The last number, 2, indicates the revision of the build. If for some reason your company has to build an assembly twice in one day, maybe to resolve a hot bug that is halting other work, then the revision number should be incremented.

Microsoft uses this version-numbering scheme, and it's simply a recommendation; you're welcome to devise your own number-versioning scheme if you prefer. The only assumption the CLR makes is that bigger numbers indicate later versions.

You'll notice that an assembly has three version numbers associated with it. This is very unfortunate and leads to a lot of confusion. Let me explain each version number's purpose and how it is expected to be used:

• AssemblyFileVersion This version number is stored in the Win32 version resource. This number is informational only; the CLR doesn't examine or care about this version number in any way. Typically, you set the major and minor parts to represent the version you want the public to see. Then you increment the build and revision parts each time a build is performed. Ideally, Microsoft's tool (such as CSC.exe or AL.exe) would automatically update the build and revision numbers for you (based on the data/time when the build was performed), but unfortunately they don't. This version number can be seen when using Windows Explorer and is used to determine exactly when an assembly file was built.

• AssemblylnformationalVersionAttribute This version number is also stored in the Win32 version resource, and again, this number is informational only; the CLR doesn't examine or care about it in any way. This version number exists to indicate the version of the product that includes this assembly. For example, Version 2.0 of MyProduct might contain several assemblies; one of these assemblies is marked as Version 1.0 since it's a new assembly that didn't ship in Version 1.0 of MyProduct. Typically, you set the major and minor parts of this version number to represent the public version of your product. Then you increment the build and revision parts each time you package a complete product with all its assemblies.

• AssemblyVersion This version number is stored in the AssemblyDef manifest metadata table. The CLR uses this version number when binding to strongly named assemblies (discussed in Chapter 3). This number is extremely important and is used to uniquely identify an assembly. When starting to develop an assembly, you should set the major, minor, build, and revision numbers and shouldn't change them until you're ready to begin work on the next deployable version of your assembly. When you build an assembly, this version number in the referenced assembly is embedded in the AssemblyRef table's entry. This means that an assembly is tightly bound to a specific version of a reference assembly.

Important The CSC.exe and AL.exe tools support the ability to automatically increment the assembly version number with each build. This feature is a bug and shouldn't be used because changing the assembly version number will break any assemblies that reference this assembly. The AssemblyInfo.cs file that Visual Studio .NET automatically creates for you when you create a new project is in error: it sets the AssemblyVersion attribute so that its major and minor parts are 1.0 and that the build and revision parts are automatically updated by the compiler. You should definitely modify this file and hard-code all four parts of the assembly version number.

Was this article helpful?

+1 0

Post a comment