Walkthrough: Using a Custom Action to Compile a Binary to Native Code at Installation

You can define custom actions to specify commands that are run after an installation. For example, in this walkthrough, you define a custom action and pass the path name of an EXE to the CustomActionData property to compile the executable to native code after the application is installed.

To create a Web browser application to deploy

1. On the File menu, point to New, and then click Project.

2. Click Windows Forms Application.

3. For the Name, type BrowserSample, and then click OK.

4. On the View menu, click Toolbox.

5. Expand All Windows Forms, and drag a Panel control to the top left of the form.

6. In the Form Designer, drag a TextBox control and Button control to the Panel control.

7. In the Form Designer, drag a WebBrowser control below the Panel.

8. Expand the size of the form to fit all the controls.

9. In the Form Designer, click the Panel control.

10. In the Properties Window, change the Dock property under Layout to Top.

11. In the Form Designer, click the WebBrowser control.

12. In the Properties Window, change the Dock property under Layout to Fill.

13. In the Form Designer, click the Button control.

14. In the Properties Window, change the Text property under Appearance to Go.

15. Resize the Form, Panel, Textbox, Button, and WebBrowser to your preferences.

16. In the Form Designer, double-click the Go button.

    The code view for the Form1 code file appears.

17. Add the following code, which adds Web browsing functionality to your application. The text in the TextBox control is the address bar for the WebBrowser control, and the action takes place when you click the Go button.

18. To test the browser, press F5.

    The form opens.

19. In the text box, type https://www.microsoft.com, and then click Go.

    The Microsoft Web site appears.

To create the custom action class

1. On the File menu, point to Add, and then click New Project.

2. In the Add New Project dialog box, click Windows, and then click Class Library.

3. In the Name box, type NGenCustomAction, and then click OK.

4. On the Project menu, click Add New Item.

5. In the Add New Item dialog box, click General, and then click Installer Class. In the Name box, type NGenCustomAction, and then click Add.

6. In Solution Explorer, delete the Class1 code file in the NGenCustomAction project.

To add code to the custom action

1. Right-click the NGenCustomAction code file in Solution Explorer (or the design surface), and then click View Code to open the Code Editor. Add the following code to the top of the module.

2. Update the class declaration to inherit from the System.Configuration.Install.Installer class.

3. In the NGenCustomAction code file, add the following helper method to generate the native image code file for any assembly.

4. In the NGenCustomAction code file, add the following procedure to override the Install, Commit, Rollback, and Uninstall procedures of the base class.

To add a deployment project for the Browser Sample application

1. On the File menu, point to Add, and then click New Project.

2. In the Add New Project dialog box, expand Other Project Types, expand Setup and Deployment Projects, click Visual Studio Installer, and then click Setup Project.

3. In the Name box, type Browser Sample Installer, and then click OK.

4. In the File System Editor, select the Application Folder. On the Action menu, click Add.

   The Add Project Output Group dialog box appears.

5. In the Project drop-down combo box, select BrowserSample, click Project Output, and then click OK.

6. In the File System Editor, select the Application Folder. On the Action menu, click Add.

   The Add Project Output Group dialog box appears.

7. In the Project drop-down combo box, select NGenCustomAction, click Project Output, and then click OK.

To add the NGEN custom action to the Setup project

1. In Solution Explorer, click the Browser Sample Installer project.

2. On the View menu, point to Editor, and then click Custom Actions.

3. In the Custom Actions Editor, select the Custom Actions node.

4. On the Action menu, click Add Custom Action.

5. In the Select Item in Project dialog box, double-click the Application Folder, click Primary output from NGenCustomAction (Active), and then click OK

   The NGen Custom Action is added to all four custom action nodes.

6. In the Install node, click Primary output from NGenCustomAction (Active).

7. In the Properties window, change the CustomActionData property to /Args="[TARGETDIR]BrowserSample.exe". Include the quotation marks.

   Note

   The [TARGETDIR] property is the location of the installed executable. The custom action uses ngen.exe to convert the installed executable to a native image.

8. In Solution Explorer, click the Browser Sample Installer setup project.

9. On the Build menu, click Build Browser Sample Installer.

To verify the native code generation

1. Navigate to the installation folder and find the BrowserSample.exe file. For example %PROGRAMFILES%\CompanyName\Brower Sample Installer\BrowserSample.exe.

2. In a Visual Studio command prompt, verify that the executable was precompiled to native code by running the following code:

   ngen.exe display FullPathToExe
   

   For example, you may run the following command:

   ngen.exe display "C:\Program Files (x86)\Microsoft\Browser Sample Installer\BrowserSample.exe"
   

   The command output appears.

   Microsoft (R) CLR Native Image Generator - Version 4.0.21102.0
   Copyright (c) Microsoft Corporation.  All rights reserved.
   
   NGEN Roots:
   
   C:\Program Files (x86)\Microsoft\Browser Sample Installer\BrowserSample.exe
   
   NGEN Roots that depend on "c:\Program Files (x86)\Microsoft\Browser Sample Installer\BrowserSample.exe":
   
   C:\Program Files (x86)\Microsoft\Browser Sample Installer\BrowserSample.exe
   
   Native Images:
   
   BrowserSample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null <debug>
   

   Note

   If ngen.exe does not display a native image, you can find the ngen logs in one of the following directories:

   %SystemRoot%\Microsoft.NET\Framework\v<CLR version> %SystemRoot%\Microsoft.NET\Framework64\v<CLR version>

   The ngen.log file is the most recent troubleshooting log.

See Also

Concepts

Managed Execution Process

Reference

CustomActionData Property

Native Image Generator (Ngen.exe)

Other Resources

Custom Actions Management in Deployment