Walkthrough: Create a custom bootstrapper with a privacy prompt

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

You can configure ClickOnce applications to automatically update when assemblies with newer file versions and assembly versions become available. To make sure that your customers consent to this behavior, you can display a privacy prompt to them. Then, they can choose whether to grant permission to the application to update automatically. If the application is not allowed to update automatically, it does not install.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in this article. You may be using a different edition of Visual Studio or different environment settings. For more information, see Personalize the IDE.

Prerequisites

You need the following components to complete this walkthrough:

• Visual Studio 2010.

Create an Update Consent dialog box

To display a privacy prompt, create an application that asks the reader to consent to automatic updates for the application.

To create a consent dialog box

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

2. In the New Project dialog box, click Windows, and then click WindowsFormsApplication.

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

4. In the designer, click the form.

5. In the Properties window, change the Text property to Update Consent Dialog.

6. In the Toolbox, expand All Windows Forms, and drag a Label control to the form.

7. In the designer, click the label control.

8. In the Properties window, change the Text property under Appearance to the following:

   The application that you are about to install checks for the latest updates on the Web. By clicking on "I Agree", you authorize the application to check for and install updates automatically from the Internet.

9. In the Toolbox, drag a Checkbox control to the middle of the form.

10. In the Properties window, change the Text property under Layout to I Agree.

11. In the Toolbox, drag a Button control to the lower left of the form.

12. In the Properties window, change the Text property under Layout to Proceed.

13. In the Properties window, change the (Name) property under Design to ProceedButton.

14. In the Toolbox, drag a Button control to the bottom right of the form.

15. In the Properties window, change the Text property under Layout to Cancel.

16. In the Properties window, change the (Name) property under Design to CancelButton.

17. In the designer, double-click the I Agree checkbox to generate the CheckedChanged event handler.

18. In the Form1 code file, add the following code for the CheckedChanged event handler.

    private void checkBox1_CheckedChanged(object sender, EventArgs e)
    {
        ProceedButton.Enabled = !ProceedButton.Enabled;
    }
    

    Private Sub CheckBox1_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles CheckBox1.CheckedChanged
        ProceedButton.Enabled = Not ProceedButton.Enabled
    End Sub
    

19. Update the class constructor to disable the Proceed button by default.

    public Form1()
    {
        InitializeComponent();
        ProceedButton.Enabled = false;
    }
    

    Public Sub New()
        InitializeComponent()
        ProceedButton.Enabled = False
    End Sub
    

20. In the Form1 code file, add the following code for a Boolean variable to track if the end user has consented to online updates.

    public bool accepted = false;
    

    Public accepted As Boolean = False
    

21. In the designer, double-click the Proceed button to generate the Click event handler.

22. In the Form1 code file, add the following code to the Click event handler for the Proceed button.

    private void ProceedButton_Click(object sender, EventArgs e)
    {
        if (ProceedButton.Enabled)
        {
            accepted = true;
            this.Close();
        }
    }
    

    Private Sub ProceedButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles ProceedButton.Click
        If ProceedButton.Enabled Then
            accepted = True
            Me.Close()
        End If
    End Sub
    

23. In the designer, double-click the Cancel button to generate the Click event handler.

24. In the Form1 code file, add the following code for the Click event handler for the Cancel button.

    private void CancelButton_Click(object sender, EventArgs e)
    {
        this.Close();
    }
    

    Private Sub CancelButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles CancelButton.Click
        Me.Close()
    End Sub
    

25. Update the application to return an error if the end user does not consent to online updates.

    For Visual Basic developers only:

    1. In Solution Explorer, click ConsentDialog.

    2. On the Project menu, click Add Module, and then click Add.

    3. In the Module1.vb code file, add the following code.

       Module Module1
       
           Function Main() As Integer
               Application.EnableVisualStyles()
               Application.SetCompatibleTextRenderingDefault(False)
               Dim f As New Form1()
               Application.Run(f)
               If (Not f.accepted) Then
                   Return -1
               Else
                   Return 0
               End If
           End Function
       
       End Module
       

    4. On the Project menu, click ConsentDialog Properties, and then click the Application tab.

    5. Uncheck Enable application framework.

    6. In the Startup object drop-down menu, select Module1.

       Note

       Disabling the application framework disables features such as Windows XP visual styles, application events, splash screen, single instance application, and more. For more information, see Application Page, Project Designer (Visual Basic).

       For Visual C# developers only:

       Open the Program.cs code file, and add the following code.

       static int Main()
       {
           Application.EnableVisualStyles();
           Application.SetCompatibleTextRenderingDefault(false);
           Form1 f = new Form1();
           Application.Run(f);
           if (!f.accepted)
               return -1;
           else
               return 0;
       }
       

26. On the Build menu, click BuildSolution.

Create the custom bootstrapper package

To show the privacy prompt to end users, you can create a custom bootstrapper package for the Update Consent Dialog application and include it as a prerequisite in all of your ClickOnce applications.

This procedure demonstrates how to create a custom bootstrapper package by creating the following documents:

• A product.xml manifest file to describe the contents of the bootstrapper.

• A package.xml manifest file to list the localization-specific aspects of your package, such as strings and the software license terms.

• A document for the software license terms.

Step 1: To create the bootstrapper directory

1. Create a directory named UpdateConsentDialog in the %PROGRAMFILES%\Microsoft SDKs\Windows\v7.0A\Bootstrapper\Packages.

   Note

   You may need administrative privileges to create this folder.

2. In the UpdateConsentDialog directory, create a subdirectory named en.

   Note

   Create a new directory for each locale. For example, you can add subdirectories for the fr and de locales. These directories would contain the French and German strings and language packs, if necessary.

Step 2: To create the product.xml manifest file

1. Create a text file called product.xml.

2. In the product.xml file, add the following XML code. Make sure that you do not overwrite the existing XML code.

   <Product
     xmlns="http://schemas.microsoft.com/developer/2004/01/bootstrapper"
     ProductCode="Microsoft.Sample.EULA">
     <!-- Defines the list of files to be copied on build. -->
     <PackageFiles CopyAllPackageFiles="false">
       <PackageFile Name="ConsentDialog.exe"/>
     </PackageFiles>
   
     <!-- Defines how to run the Setup package.-->
     <Commands >
       <Command PackageFile = "ConsentDialog.exe" Arguments=''>
         <ExitCodes>
           <ExitCode Value="0" Result="Success" />
           <ExitCode Value="-1" Result="Fail" String="AU_Unaccepted" />
           <DefaultExitCode Result="Fail"
             FormatMessageFromSystem="true" String="GeneralFailure" />
         </ExitCodes>
       </Command>
     </Commands>
   
   </Product>
   

3. Save the file to the UpdateConsentDialog bootstrapper directory.

Step 3: To create the package.xml manifest file and the software license terms

1. Create a text file called package.xml.

2. In the package.xml file, add the following XML code to define the locale and include the software license terms. Make sure that you do not overwrite the existing XML code.

   <Package
     xmlns="http://schemas.microsoft.com/developer/2004/01/bootstrapper"
     Name="DisplayName"
     Culture="Culture"
     LicenseAgreement="eula.rtf">
     <PackageFiles>
       <PackageFile Name="eula.rtf"/>
     </PackageFiles>
   
     <!-- Defines a localizable string table for error messages. -->
     <Strings>
       <String Name="DisplayName">Update Consent Dialog</String>
       <String Name="Culture">en</String>
       <String Name="AU_Unaccepted">The automatic update agreement is not accepted.</String>
       <String Name="GeneralFailure">A failure occurred attempting to launch the setup.</String>
     </Strings>
   </Package>
   

3. Save the file to the en subdirectory in the UpdateConsentDialog bootstrapper directory.

4. Create a document called eula.rtf for the software license terms.

   Note

   The software license terms should include information about licensing, warranties, liabilities, and local laws. These files should be locale-specific, so make sure that the file is saved in a format that supports MBCS or UNICODE characters. Consult your legal department about the content of the software license terms.

5. Save the document to the en subdirectory in the UpdateConsentDialog bootstrapper directory.

6. If necessary, create a new package.xml manifest file and a new eula.rtf document for the software license terms for each locale. For example, if you created subdirectories for the fr and de locales, create separate package.xml manifest files and software license terms and save them to the fr and de subdirectories.

Set the Update Consent Application as a prerequisite

In Visual Studio, you can set the Update Consent application as a prerequisite.

To set the Update Consent Application as a prerequisite

1. In Solution Explorer, click the name of your application that you want to deploy.

2. On the Project menu, click ProjectName Properties.

3. Click the Publish page, and then click Prerequisites.

4. Select Update Consent Dialog.

   Note

   You may have to close and reopen Visual Studio to see the Update Consent Dialog in the Prerequisites Dialog Box.

5. Click OK.

Create and test the Setup program

After you set the Update Consent application as a prerequisite, you can generate the installer and bootstrapper for your application.

To create and test the Setup program by not clicking I agree

1. In Solution Explorer, click the name of your application that you want to deploy.

2. On the Project menu, click ProjectName Properties.

3. Click the Publish page, and then click Publish Now.

4. If the publish output does not open automatically, navigate to the publish output.

5. Run the Setup.exe program.

   The Setup program shows the Update Consent Dialog software license agreement.

6. Read the software license agreement, and then click Accept.

   The Update Consent Dialog application appears and shows the following text: The application that you are about to install checks for the latest updates on the Web. By clicking on I Agree, you authorize the application to check for updates automatically on the Internet.

7. Close the application or click Cancel.

   The application shows an error: An error occurred while installing system components for ApplicationName. Setup cannot continue until all system components have been successfully installed.

8. Click Details to show the following error message: Component Update Consent Dialog has failed to install with the following error message: "The automatic update agreement is not accepted." The following components failed to install: - Update Consent Dialog

9. Click Close.

To create and test the Setup program by clicking I agree

1. In Solution Explorer, click the name of your application that you want to deploy.

2. On the Project menu, click ProjectName Properties.

3. Click the Publish page, and then click Publish Now.

4. If the publish output does not open automatically, navigate to the publish output.

5. Run the Setup.exe program.

   The Setup program shows the Update Consent Dialog software license agreement.

6. Read the software license agreement, and then click Accept.

   The Update Consent Dialog application appears and shows the following text: The application that you are about to install checks for the latest updates on the Web. By clicking on I Agree, you authorize the application to check for updates automatically on the Internet.

7. Click I Agree, and then click Proceed.

   The application starts to install.

8. If the Application Install dialog box appears, click Install.

See also

• Application deployment prerequisites
• Create bootstrapper packages
• How to: Create a product manifest
• How to: Create a package manifest
• Product and package schema reference