Nbsp;   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. Application code can also acquire and examine this information at run time by calling System.Diagnostics.File­ VersionInfo’s static GetVersionInfo method with the assembly path as parameter. Figure 2-4 shows the Details tab of the Ch02-3-MultiFileLibrary.dll Properties dialog box.

FIGURE 2-4The Details tab of the Ch02-3-MultiFileLibrary.dll Properties dialog box.

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

using System.Reflection;

// FileDescription version information: [assembly: AssemblyTitle("MultiFileLibrary.dll")]

// Comments version information:

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

// CompanyName version information: [assembly: AssemblyCompany("Wintellect")]

// ProductName version information:

[assembly: AssemblyProduct("Wintellect (R) MultiFileLibrary's Type Library")]

// LegalCopyright version information:

[assembly: AssemblyCopyright("Copyright (c) Wintellect 2013")]

// LegalTrademarks version information:

[assembly:AssemblyTrademark("MultiFileLibrary is a registered trademark of Wintellect")]

// AssemblyVersion version information: [assembly: AssemblyVersion("3.0.0.0")]

// FILEVERSION/FileVersion version information: [assembly: AssemblyFileVersion("1.0.0.0")]

// PRODUCTVERSION/ProductVersion version information: [assembly: AssemblyInformationalVersion("2.0.0.0")]

// Set the Language field (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 informa- tion instead of using the custom attributes. The second column in Table 2-4 shows the AL.exe com- mand-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-4Version Resource Fields and Their Corresponding AL.exe Switches and Custom Attributes

Version Numbers

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

TABLE 2-5Format of Version Numbers

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 revi- sion 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, the revision number should be incremented. Microsoft uses this version-numbering scheme, and it’s highly recommended that you use this scheme as well.

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

■ AssemblyFileVersionThis version number is stored in the Win32 version resource. This number is for information purposes only; the CLR doesn’t examine 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 date and time when the build was performed), but unfor- tunately, they don’t. This version number can be seen when using Windows Explorer and is typically used to identify a specific version of an assembly when troubleshooting a customer’s system.

■ AssemblyInformationalVersionThis version number is also stored in the Win32 version resource, and again, this number is for information purposes 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 a product might contain several assemblies; one of these assemblies is marked as version 1.0 because it’s a new assembly that didn’t ship in version 1.0 of the same product. 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.

■ AssemblyVersionThis version number is stored in the AssemblyDef manifest metadata table. The CLR uses this version number when binding to strongly named assemblies (dis- cussed 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 Assembly-A references a strongly named Assem- bly-B, Assembly-B’s version is embedded inside Assembly-A’s AssemblyRef table’s entry. This way, when the CLR needs to load Assembly-B, it knows exactly which version Assembly-A was built and tested with. It is possible to have the CLR load a different version by using a binding redirect, which is discussed in Chapter 3.

Date: 2016-03-03; view: 853