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.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

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.

    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
        WebBrowser1.Navigate(TextBox1.Text)
    End Sub
    

    private void button1_Click(object sender, EventArgs e)
    {
        webBrowser1.Navigate(textBox1.Text);
    }
    

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.

   Note

   Make sure that you add an Installer Class; otherwise, the code file will not have necessary using statements.

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.

   Imports System.IO
   Imports System.Diagnostics
   

   using System.IO;
   using System.Diagnostics;
   

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

   Inherits System.Configuration.Install.Installer
   

   : System.Configuration.Install.Installer
   

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

       <System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)> _
   Private Sub ngenCA(ByVal savedState As System.Collections.IDictionary, ByVal ngenCommand As String)
           Dim argsArray As [String]()
   
           If String.Compare(ngenCommand, "install", StringComparison.OrdinalIgnoreCase) = 0 Then
               Dim args As [String] = Context.Parameters("Args")
               If [String].IsNullOrEmpty(args) Then
                   Throw New InstallException("No arguments specified")
               End If
   
               Dim separators As Char() = {";"c}
               argsArray = args.Split(separators)
               'It is Ok to 'ngen uninstall' assemblies which were not installed
               savedState.Add("NgenCAArgs", argsArray)
           Else
               argsArray = DirectCast(savedState("NgenCAArgs"), [String]())
           End If
   
           ' Gets the path to the Framework directory.
           Dim fxPath As String = System.Runtime.InteropServices.RuntimeEnvironment.GetRuntimeDirectory()
   
           For i As Integer = 0 To argsArray.Length - 1
               Dim arg As String = argsArray(i)
               ' Quotes the argument, in case it has a space in it.
               arg = """" & arg & """"
   
               Dim command As String = (ngenCommand & " ") + arg
   
               Dim si As New ProcessStartInfo(Path.Combine(fxPath, "ngen.exe"), command)
               si.WindowStyle = ProcessWindowStyle.Hidden
   
               Dim p As Process
   
               Try
                   Context.LogMessage((">>>>" & Path.Combine(fxPath, "ngen.exe ")) + command)
                   p = Process.Start(si)
                   p.WaitForExit()
               Catch ex As Exception
                   Throw New InstallException("Failed to ngen " & arg, ex)
               End Try
           Next
       End Sub
   

           [System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)]
           private void ngenCA(System.Collections.IDictionary savedState, string ngenCommand)
           {
               String[] argsArray;
   
               if (string.Compare(ngenCommand, "install", StringComparison.OrdinalIgnoreCase) == 0)
               {
                   String args = Context.Parameters["Args"];
                   if (String.IsNullOrEmpty(args))
                   {
                       throw new InstallException("No arguments specified");
                   }
   
                   char[] separators = { ';' };
                   argsArray = args.Split(separators);
                   savedState.Add("NgenCAArgs", argsArray); //It is Ok to 'ngen uninstall' assemblies which were not installed
               }
               else
               {
                   argsArray = (String[])savedState["NgenCAArgs"];
               }
   
               // Gets the path to the Framework directory.
               string fxPath = System.Runtime.InteropServices.RuntimeEnvironment.GetRuntimeDirectory();
   
               for (int i = 0; i < argsArray.Length; ++i)
               {
                   string arg = argsArray[i];
                   // Quotes the argument, in case it has a space in it.
                   arg = "\"" + arg + "\"";
   
                   string command = ngenCommand + " " + arg;
   
                   ProcessStartInfo si = new ProcessStartInfo(Path.Combine(fxPath, "ngen.exe"), command);
                   si.WindowStyle = ProcessWindowStyle.Hidden;
   
                   Process p;
   
                   try
                   {
                       Context.LogMessage(">>>>" + Path.Combine(fxPath, "ngen.exe ") + command);
                       p = Process.Start(si);
                       p.WaitForExit();
                   }
                   catch (Exception ex)
                   {
                       throw new InstallException("Failed to ngen " + arg, ex);
                   }
               }
           }
   
   

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

   <System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)> _
   Public Overloads Overrides Sub Install(ByVal savedState As System.Collections.IDictionary)
       MyBase.Install(savedState)
       Context.LogMessage(">>>> ngenCA: install")
       ngenCA(savedState, "install")
   End Sub
   
   <System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)> _
   Public Overrides Sub Commit(ByVal savedState As System.Collections.IDictionary)
       MyBase.Commit(savedState)
       Context.LogMessage(">>>> ngenCA: commit")
   End Sub
   
   <System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)> _
   Public Overloads Overrides Sub Uninstall(ByVal savedState As System.Collections.IDictionary)
       MyBase.Uninstall(savedState)
       Context.LogMessage(">>>> ngenCA: uninstall")
       ngenCA(savedState, "uninstall")
   End Sub
   
   <System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)> _
   Public Overloads Overrides Sub Rollback(ByVal savedState As System.Collections.IDictionary)
       MyBase.Rollback(savedState)
       Context.LogMessage(">>>> ngenCA: rollback")
       ngenCA(savedState, "uninstall")
   End Sub
   

   [System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)]
   public override void Install(System.Collections.IDictionary savedState)
   {
       base.Install(savedState);
       Context.LogMessage(">>>> ngenCA: install");
       ngenCA(savedState, "install");
   }
   
   [System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)]
   public override void Commit(IDictionary savedState)
   {
       base.Commit(savedState);
       Context.LogMessage(">>>> ngenCA: commit");
   }
   
   [System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)]
   public override void Uninstall(System.Collections.IDictionary savedState)
   {
       base.Uninstall(savedState);
       Context.LogMessage(">>>> ngenCA: uninstall");
       ngenCA(savedState, "uninstall");
   }
   
   [System.Security.Permissions.SecurityPermission(System.Security.Permissions.SecurityAction.Demand)]
   public override void Rollback(System.Collections.IDictionary savedState)
   {
       base.Rollback(savedState);
       Context.LogMessage(">>>> ngenCA: rollback");
       ngenCA(savedState, "uninstall");
   }
   

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

Reference

CustomActionData Property

Ngen.exe (Native Image Generator)

Concepts

Managed Execution Process

Other Resources

Custom Actions Management in Deployment