Creating Installations For Microsoft.net Framework - Wise -

Creating Installations for Microsoft’s .NET Framework using Wise for Windows Installer

Abstract This paper provides an overview of creating an installation for an application created for Microsoft’s .NET Framework. By following the process, a software developer can install private and shared .NET assemblies using a Windows Installer (.MSI) package.

Introduction

The .NET Framework makes it much easier to deploy certain types of applications, while others become more complicated and increase the reliance upon Microsoft’s Windows Installer service. As Microsoft explains: “The .NET Framework simplifies deployment by making zero-impact install and XCOPY deployment of applications feasible. Because all requests are resolved first to the private application directory, simply copying an application's directory files to disk is all that is needed to run the application. No registration is required. This scenario is particularly compelling for Web applications, Web Services, and self-contained desktop applications. However, there are scenarios where XCOPY is not sufficient as a distribution mechanism. An example is when the application has little private code and relies on the availability of shared assemblies, or when the application is not locally installed (but rather downloaded on demand). For these cases, the .NET Framework provides extensive code download services and integration with the Windows Installer. The code download support provided by the .NET Framework offers several advantages over current platforms, including incremental download, code access security (no more Authenticode dialogs), and application isolation (code downloaded on behalf of one application doesn't affect other applications). The Windows Installer is another powerful deployment mechanism available to .NET applications. All of the features of Windows Installer, including publishing, advertisement, and application repair will be available to .NET applications in Windows Installer 2.0” Excerpt from Microsoft .NET Framework FAQ, July 2001 Installation Options for Simple Applications For a .NET application that only uses managed code and private assemblies, the installation process can be as simple as copying files to the destination PC. Even in this case, however, developers typically need to create an installation that provides a user-friendly interface to the end user, pre-installs the required runtime, and has a compressed, single-file installation that can be easily deployed. Installation Options for Complex Applications For .NET applications that use shared assemblies or have a mix of managed and unmanaged code, the Windows Installer service should be used to install the application. The Windows Installer service manages all installed components on a system and can even fix components if they become corrupted. Wise for Windows Installer makes this installation technology accessible to developers by providing a visual, step-by-step approach to creating installations for .NET applications. This white paper describes the

Creating Installations for .NET

-2-

Copyright 2001, 2002 by Wise Solutions, Inc.

process of creating a .NET installation, as well as discussing how Wise for Windows Installer simplifies this process.

Getting Started

Before you begin to create an installation for your .NET application, identify the following information about your application: 1. Gather all of your assemblies, Win32 and .NET, and their associated manifests into a common location. 2. Determine where the assemblies are to be installed (see the section titled Best Practices for more information). 3. Generate PrivateKeyTokens for the assemblies and digitally sign all the assemblies if they are to be installed to the Global Assembly Cache. Preparing Wise for Windows Installer Wise for Windows Installer 4.0 includes the necessary features for creating installations for .NET. To take advantage of these features, you need to have the Windows Installer 2.0 runtime and the Common Language Runtime installed on your system. You must install the .NET Framework installation to obtain the Common Language Runtime. The Windows Installer runtime is automatically installed along with all versions of Wise for Windows Installer, and the .NET Framework is optionally installed with Wise for Windows Installer 4.01 or later. If you have the .NET Framework installed, you are ready to work on your .NET installation. Either create a new installation or open an existing installation that you wish to convert to .NET. Go to the Product Details page in Installation Expert and change the Application Type drop-down list to ".NET Application." Now .NET features are enabled in the current installation. A standard Win32 installation does not have assemblies, a mixed installation has both Win32 and .NET components, and a .NET installation has only .NET components. You can customize how Wise for Windows Installer handles the assemblies added to your installation by changing the settings on the .NET Assemblies tab of the Preferences dialog.

Creating Installations for .NET

-3-

Copyright 2001, 2002 by Wise Solutions, Inc.

The Default Application Type field specifies the installation type of all future installations you create, but does not change the current installation. The Rescan COM interop registry keys on compile checkbox determines how Wise handles the scanning of COM interop registry entries. In addition, you can set Wise up to automatically add any dependency assemblies. When Scan Dependencies is set to “Always scan dependencies”, Wise scans the assembly manifest for any dependencies and automatically adds those assemblies to the installation, along with the required assembly entries in the Windows Installer tables. For full control, this can be turned off and you can be prompted to scan for dependencies or you can add all files manually. This enables you, as the installation package author, to have a full range of control throughout the creation of the installation. Once you have customized .NET preferences, each future project you create with Wise for Windows Installer inherits the settings from these global options. Now you are ready to start adding components to your installation.

Creating Installations for .NET

-4-

Copyright 2001, 2002 by Wise Solutions, Inc.

Common Language You should add the Common Language Runtime redistributable runtime to your installation to ensure that all the necessary runtimes are preRuntime

installed on the destination PC. To add the Common Language Runtime, go to the Releases page of Installation Expert, double-click the release you are currently working with, and in Release Details, choose to preinstall the .NET common language runtime from the Pre-install Options drop-down list.

It is generally a good idea to include any runtimes that are required by the application you're installing. This prevents runtime errors for end users and can significantly decrease help desk calls. The .NET Framework runtime includes BOTH the Common Language Runtime and the Windows Installer 2.0 runtimes. Therefore, when including the .NET Framework runtime the Windows Installer runtime does not need to be included.

Creating Installations for .NET

-5-

Copyright 2001, 2002 by Wise Solutions, Inc.

Within the Wise for Windows Installer 4.0 Professional Edition, you can use WebDeploy to deploy applications over the Web. WebDeploy contains a feature to optionally download the Windows Installer and .NET runtimes if the user requires them. This can significantly reduce download times and reduces the number of concurrent connections on your http or ftp servers.

Creating Installations for .NET

-6-

Copyright 2001, 2002 by Wise Solutions, Inc.

Adding Files

Navigate to the Files page in Installation Expert. From here, you can drag and drop your assemblies into the appropriate directory. As you add assemblies, Wise automatically adds the appropriate table entries to install and register your assemblies in their destination location. Global Assembly Cache, WinSxS, Private Assemblies For those assemblies that should be installed into the Global Assembly Cache, select the files and drag and drop them into the Global Assembly Cache folder. Note: To install .NET Assemblies into the Global Assembly Cache, they must be Strongly Named. You can find out more on this topic in the .NET Framework SDK.

To install your Win32 assemblies into the WinSxS (side-by-side) folder, simply navigate to the WinSxS folder under the Windows folder in the lower left, then add your assembly files. Wise automatically designates the .MANIFEST file as the file in your component that contains the manifest. To install your assemblies to a private location, you can add them as you would add any other file to your installation directory. To customize any of these automated entries, double-click the assembly file you’d like to edit and the File Details dialog appears.

Creating Installations for .NET

-7-

Copyright 2001, 2002 by Wise Solutions, Inc.

In the File Details dialog, there is an option to register each assembly for reference within Visual Studio .NET. When marked, this option creates a registry entry for this assembly. Then, the next time Visual Studio.NET is opened, the assembly is available for any future projects via the Project > References menu item. Note: You cannot drag and drop files directly from the Global Assembly Cache (C:\WINNT\Assembly folder) on your development machine. In addition, any of these entries can be edited from the Table editor. Wise gives full access to all tables via the Tables tab of Setup Editor to ensure that you have full control throughout the installation authoring process. (See the section titled Behind the Scenes... for specific examples of how to edit these entries.)

Behind the Scenes...

Creating Installations for .NET

When you are using Wise for Windows Installer to automate the table entries for your .NET application, there is a lot going on behind the scenes. A Windows Installer package includes a number of database tables that describe the application to Microsoft’s Windows Installer service. The tables involved in installing an assembly are MsiAssembly and MsiAssemblyName. These tables are automatically filled in when you set the installation to be a “.NET Application” on the Product Details page. The tables that are described below store the necessary data that Windows Installer needs to install and/or register your assembly in the destination location.

-8-

Copyright 2001, 2002 by Wise Solutions, Inc.

MsiAssembly Table The MsiAssembly table contains one record for each assembly to be installed. There are five fields in the MsiAssembly table. The example MsiAssembly table shown below is referenced in examples later in this section.

Component_. This is the foreign key to the Component record that contains the assembly. If your assembly is comprised of multiple files, they should be authored into the same component. Feature_. This field specifies the feature in the installation with which the assembly is associated. File_Manifest. This field is a foreign key to the File table for the file that contains the manifest for the assembly. If the assembly is comprised of many files, this entry will be the file in the assembly that contains the assembly manifest information. A Portable Executable is a self-contained .NET assembly. It contains the compiled assembly in addition to the assembly manifest and Strong Name information. When working with Portable Executables (PE), the File_Manifest field contains the Portable Executable file name. This is because the manifest is self-contained within the PE .dll or .exe. File_Application. This field should be blank if the assembly is to be installed into the Global Assembly Cache on the destination PC. For private assemblies, the File_Application field contains a foreign key to the File table for the main application file. Windows Installer installs the assembly into the directory where the component is installed, as determined in the Component table’s Directory field. If the component is installed into the INSTALLDIR directory, the assembly is then installed in that directory, along with the application files. The directory assigned to this component is resolved in the Directory table and can be set at runtime by the user on the “Single Feature Destination” dialog. Private Assembly (NOT available with Windows 95, 98, or NT) In the example MsiAssembly table shown above, Component2 will be installed into the application directory. This means it is a private assembly and only available for the application that's being installed. Component1 is a shared assembly and will be installed and registered into the Global Assembly Cache on the destination PC. WinSxS Assembly (only available with Windows XP) When Win32 assemblies are installed into the WinSxS directory, they are not registered globally on the system, as they are when installed into the Global Assembly Cache. However, they are available to any application that references them. To enable side-byside sharing, your component must be installed into the WinSxS folder. During installation of the application, Windows Installer

Creating Installations for .NET

-9-

Copyright 2001, 2002 by Wise Solutions, Inc.

resolves the Directory table to obtain the path to the WinSxS folder if the File_Application field is not null. For assemblies to be installed into the WinSxS directory, a .LOCAL file is not needed, because it not utilized in this scenario. Shared Assembly (Global Assembly Cache or GAC) When the File_Application table is set to a null value, Windows Installer ignores the component’s destination directory and installs the entire component into the Global Assembly Cache. The assembly is then available to all other applications that use this assembly version. In the example above, Component2 will be installed into the Global Assembly Cache, based on the null value in the File_Application field. Attributes. This field is used to determine if the assembly is a Win32 or a .NET Application. For .NET assemblies, the value authored into this field would be 0 (zero), and if the assembly is a Win32 application, the value would be 1. MsiAssemblyName Table For each assembly attribute (as authored in the manifest), a record initializing the attribute and its data value must be entered into the MsiAssemblyName table. Wise for Windows Installer has added the ability to “scan” the assembly manifest to automate this process. Windows Installer needs these attributes to appropriately register the assembly when it is installed. When you add an assembly, this table is automatically propagated with the necessary data. You can modify the entries that Wise creates in this table by going to the Tables tab of Setup Editor and scrolling to the MsiAssemblyName table. Examples of possible entries are as follows:

Component. This field contains one of the Component_ values authored into the MsiAssembly table that represents an assembly. Name. This field contains one of the assembly attributes (as defined in the manifest). Value. This field contains the string value of that attribute. The entries are variable, and this example shows only a few possible entries. For all possible attributes, see the .NET Framework SDK. In the Creating Installations for .NET

- 10 -

Copyright 2001, 2002 by Wise Solutions, Inc.

example above, Name, Version and Culture are pulled directly from the string that is entered into the manifest.

Compilation and Distribution

At this point, you have enough information to distribute .NET and Win32 assemblies. After you add all of the assemblies needed for your application, the installation package is ready to be compiled and distributed. Compilation of your Wise project produces an .MSI or .EXE, depending on the settings you have set on the Releases Page of Installation Expert. After you create the .MSI or .EXE, your project can be distributed.

Best Practices

Managed Assemblies that are shared with many other applications authored by different vendors should be installed into the Global Assembly Cache. This is a central repository of all shared assemblies. The installation of assemblies into the Global Assembly Cache should be well planned. Assemblies should not arbitrarily placed in the Global Assembly Cache without justification. The WinSxS folder is a subdirectory located off the Windows directory on Windows XP. Both managed and unmanaged assemblies can be installed into the WinSxS directory. It is good common practice to install assemblies that are shared with applications created by the same vendor into the WinSxS directory. In addition, assemblies can be stored in the application directory if they are to be private, or if they are only used by the application being installed. In this case, it makes most sense not to share them, since no other application will be calling them.

Conclusion

Wise Solutions, Inc. is committed to providing the most current and thorough support for Microsoft’s .NET Framework. This is exemplified by the timely .NET updates to our Wise for Windows Installer product line, the frequent updates to white papers and resource materials, as well as our close relationship with several key Microsoft teams. Please keep checking our Web site for product updates and support documentation to aid you in your transition to the .NET Framework.

Creating Installations for .NET

- 11 -

Copyright 2001, 2002 by Wise Solutions, Inc.

For More Information

The following pages of the .NET Framework Developer’s Guide provide an excellent background for the information in this white paper. Shared and Private Assemblies Described http://msdn.microsoft.com/library/default.asp?url=/library/enus/msi/assm_5i5v.asp

Global Assembly Cache http://msdn.microsoft.com/library/default.asp?url=/library/enus/cpguide/html/cpconglobalassemblycache.asp

Redirecting Assembly Versions http://msdn.microsoft.com/library/default.asp?url=/library/enus/cpguide/html/cpconassemblyversionredirection.asp

Best Practices: When to provide a shared component as a side-byside assembly http://msdn.microsoft.com/library/default.asp?url=/library/enus/sbscs/sidebyside_3bp5.asp

Here are some additional links that provide a better understanding of the underlying concepts of Microsoft’s .NET Framework. Microsoft .NET Framework FAQ http://msdn.microsoft.com/library/techart/faq111700.htm

Simplifying Deployment and Solving DLL Hell with the .NET Framework http://msdn.microsoft.com/library/techart/dplywithnet.htm

Download Page for .NET Framework SDK http://msdn.microsoft.com/downloads/default.asp?URL=/downloads/sample.asp? url=/MSDN-FILES/027/000/976/msdncompositedoc.xml

Download for Windows Installer 2.0 Runtime For Windows 9x: http://www.microsoft.com/downloads/release.asp?ReleaseID=32831

For Windows NT 4.0 \ Windows 2000: http://www.microsoft.com/downloads/release.asp?ReleaseID=32832

Wise for Windows Installer Resource Kit http://www.wisesolutions.com/wikitform.asp

Support for Shared and Private Assemblies http://msdn.microsoft.com/library/default.asp?url=/library/enus/sbscs/sidebysideref_2gc3.asp

Definitions of common .NET terminology http://msdn.microsoft.com/library/enus/cpguide/html/cpconinsidenetframework.asp?frame=true

 2001, 2002 Wise Solutions, Inc. All rights reserved. Wise Solutions and Wise for Windows Installer are registered trademarks of Wise Solutions, Inc. Other companies and products mentioned herein may be the trademarks of their respective owners. Wise Solutions, Inc. • 47911 Halyard • Plymouth, MI 48170 • USA 01/2002

Creating Installations for .NET

- 12 -

Copyright 2001, 2002 by Wise Solutions, Inc.