Preparing .NET Applications for Deployment

It is remarkable that .NET assemblies may be copied anywhere and run, which is referred to as XCopy deployment. Because they are self-describing, there is no need for registry entries. To demonstrate, compile the code in Listing 18.1 as an executable, copy it anywhere on the system, and run it.

Listing 18.1 A Sample for XCopy Deployment (SimpleApp.cs)

 using System; class SimpleApp {    static void Main(string[] args)    {       Console.WriteLine("I'm a simple application.");       Console.ReadLine();    } } 

Creating Precompiled Assemblies with NGen.exe

The normal execution behavior of an assembly is that the CLR will load and perform JIT compilation on its code before execution. This method is sufficient for most applications, but there may be times when a precompiled assembly would improve performance during application startup. There is a tool in the .NET Framework, named NGen.exe, which will precompile Intermediate Language (IL) files to native machine code.

LOCATING COMMAND-LINE UTILITIES

Many of the .NET utilities used in deployment are command-line-driven. When executing these utilities you will have to either use the fully qualified path or change directories to where the utility program is located. Another option is to change your system path.

If you already had Visual Studio .NET 2003 installed before installing C#Builder, the .NET Framework SDK is on your machine at %windir%\ Microsoft.NET\Framework\v1.1.4322, which is the location of executable files and utilities for the .NET Framework SDK v1.1. The location of the .NET Framework SDK installed with Visual Studio .NET 2002 doesn't apply because it is v1.0 and C#Builder uses v1.1.

If the .NET Framework SDK is not on your machine, C#Builder will install it at C:\Program Files\Microsoft.NET\SDK\v1.1\Bin, which is the same location for the .NET Framework SDK if you downloaded and installed it from Microsoft's Web site. These are simply default directories and if you customized the location of the .NET Framework SDK installation directory during setup, you should use that custom path.

Before getting into NGen.exe too far, it is important to note that although the IL is compiled to machine code, the generated assembly is still a managed assembly and still requires the CLR to execute. NGen.exe only allows an assembly to bypass the JIT compilation process, but the CLR still manages execution.

Another point to remember about code compiled with NGen.exe is that it is not guaranteed to outperform JIT compiled code. The JIT compiler has potential opportunities at runtime to examine the environment dynamically and make adjustments to improve optimization. Further, well-tuned code compiled in memory with local optimizations may run faster after JIT compilation has been completed, resulting in overall performance benefits for the life of the program. Therefore, it is better to analyze the requirements of the program and do benchmarking on points that count before making a final decision about whether to NGen the code.

NGen.exe will create an assembly that is specific to the platform it is run on. These factors include the .NET Framework version, OS version, CPU, assembly identity, referenced assembly identities, and security settings. If any of these factors change, the NGen'd assembly becomes invalid and the CLR reverts to JIT compilation. Therefore, it would be better to move an assembly to the target platform and run NGen.exe in its deployed setting.

As a simple example of how to use NGen.exe, the following command line compiles the executable assembly that was produced by the code from Listing 18.1:

 NGen.exe SimpleApp.exe 

This ran NGen.exe against the executable assembly and put the compiled code into the Native Image Cache, a special part of the Global Assembly Cache (GAC), which will be explained later. When SimpleApp.exe is executed, the CLR will find its image in the Native Image Cache and run the compiled code. For more options to NGen.exe, use the /help option on the command line and/or look in the .NET Framework documentation for additional information.

Securing Assemblies

Assemblies can be secured with strong names, ensuring their integrity and safety from tampering. A strong name uniquely identifies an assembly and consists of an assembly name, version number, culture, and signature. The assembly name is the filename that appears in a directory listing. The culture identifies an assembly as being uniquely localized. By default, assemblies have a neutral culture, which defaults to the culture of the machine where the assembly was compiled. The final part of strong-naming an assembly is to sign it.

To add a strong name to a file you must generate a strong name key file with a public/private key pair, reference the strong name key file in the program to receive the strong name, and then compile the program. .NET comes with a utility, sn, which is used to generate a strong name key. The following command line demonstrates its use:

 sn  k CSharpBuilderKickStart.snk 

This generates a public/private key pair that can be used to sign an assembly, giving it a strong name. You can use any name you like for the strong name key file. By convention, its extension is .snk. Listing 18.2 shows a program that uses the key just generated to strong-name the assembly when it is compiled. This is a modified version of the AssemblyInfo.cs file that is included with every wizard-generated project in C#Builder.

Listing 18.2 Strong-Naming an Assembly (AssemblyInfo.cs)

 using System.Reflection; using System.Runtime.CompilerServices; // // General Information about an assembly //  is controlled through the following // set of attributes. Change these attribute // values to modify the information // associated with an assembly. // [assembly: AssemblyTitle("Simple Application")] [assembly: AssemblyDescription( "Designed to demonstrate .NET deployment.")] [assembly: AssemblyConfiguration("Release")] [assembly: AssemblyCompany("Sams Publishing")] [assembly: AssemblyProduct("C#Builder Kick Start")] [assembly: AssemblyCopyright( "(C) 2003, All Rights Reserved.")] [assembly: AssemblyTrademark("C#Builder Kick Start")] [assembly: AssemblyCulture("")] // // Version information for an assembly // consists of the following four values: // //      Major Version //      Minor Version //      Build Number //      Revision // // You can specify all the values or you // can default the Revision and Build Numbers // by using the '*' as shown below: [assembly: AssemblyVersion("1.0.*")] // // In order to sign your assembly you must // specify a key to use. Refer to the // Microsoft .NET Framework documentation for // more information on assembly signing. // // Use the attributes below to control which // key is used for signing. // // Notes: //   (*) If no key is specified, the assembly //       is not signed. //   (*) KeyName refers to a key that has been //       installed in the Crypto Service //       Provider (CSP) on your machine. KeyFile //       refers to a file which contains //       a key. //   (*) If the KeyFile and the KeyName values //       are both specified, the //       following processing occurs: //       (1) If the KeyName can be found in the //           CSP, that key is used. //       (2) If the KeyName does not exist and the //           KeyFile does exist, the key //           in the KeyFile is installed into //           the CSP and used. //   (*) In order to create a KeyFile, you can use //       the sn.exe (Strong Name) utility. //       When specifying the KeyFile, the location //       of the KeyFile should be //       relative to the project output directory which is //       %Project Directory%\bin\<configuration>. //       For example, if your KeyFile is //       located in the project directory, you //       would specify the AssemblyKeyFile //       attribute as [assembly: AssemblyKeyFile( //                        "..\\..\\mykey.snk")] //   (*) Delay Signing is an advanced option  //       see the Microsoft .NET Framework //       documentation for more information on this. // [assembly: AssemblyDelaySign(false)] [assembly: AssemblyKeyFile(     "..\\..\\CSharpBuilderKickStart.snk")] [assembly: AssemblyKeyName("")] 

The important part of Listing 18.2 to notice is the [assembly: AssemblyKeyFile("..\\..\\ CSharpBuilderKickStart.snk")] attribute. The C# compiler recognizes this attribute and signs the assembly with the strong name key. The single parameter "..\\..\\CSharpBuilder KickStart.snk" assumes that the key is located in the base directory along with other source files. If the key is located elsewhere, this parameter may specify either a full or relative path.

All the other attributes in Listing 18.2 help identify and document this program. For example, the AssemblyVersion attribute contributes to the identity of the assembly. Because of the asterisk, the assembly number will be updated every time the program is compiled. The asterisk may be replaced with a specified version number to explicitly control versions. The next section discusses version numbers in greater detail.

The other assembly attributes, such as AssemblyTitle, AssemblyDescription, and so on help document the assembly. After the SimpleApp program is compiled, find the executable in the Windows Explorer, which would be located at the relative directory bin\Release for a deployment build and bin\Debug for a development build (or an explicitly specified location for a custom build configuration as explained earlier in this chapter). Right-click on SimpleApp.exe, select Properties from the context menu, and select the Version tab (see Figure 18.2). The information on the Version tab is what was entered into the documentation attributes in AssemblyInfo.cs.

Figure 18.2. The File Properties dialog showing assembly version documentation.

Managing Assembly Versioning

An assembly version consists of a four-part number, separated by periods. Version numbers take the form of <major>.<minor>.<build>.<revision>. Table 18.1 describes each part of an assembly version number. It is best to think of the description as simply a suggestion because there is nothing limiting custom interpretation of these numbers for local version management.

Table 18.1. Assembly Version Numbers

VERSION PART	DESCRIPTION
<major>	Changes version number to a program that significantly modify its features
<minor>	Upgrades version number to an existing version that enhance features and/or fix bugs
<build>	Incremented version number for each application build
<revision>	Incremented version number for a small change to the program