Walkthrough: Creating a Custom Bootstrapper to Show a Privacy Prompt

Article
08/29/2011

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 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.

Prerequisites

You need the following components to complete this walkthrough:

Visual Studio 2010.

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

On the File menu, point to New, and then click Project.
In the New Project dialog box, click Windows, and then click Windows Forms Application.
For the Name, type ConsentDialog, and then click OK.
In the designer, click the form.
In the Properties window, change the Text property to Update Consent Dialog.
In the Toolbox, expand All Windows Forms, and drag a Label control to the form.
In the designer, click the label control.
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.
In the Toolbox, drag a Checkbox control to the middle of the form.
In the Properties window, change the Text property under Layout to I Agree.
In the Toolbox, drag a Button control to the lower left of the form.
In the Properties window, change the Text property under Layout to Proceed.
In the Properties window, change the (Name) property under Design to ProceedButton.
In the Toolbox, drag a Button control to the bottom right of the form.
In the Properties window, change the Text property under Layout to Cancel.
In the Properties window, change the (Name) property under Design to CancelButton.
In the designer, double-click the I Agree checkbox to generate the CheckedChanged event handler.

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

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

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

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

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

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

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 accepted As Boolean = False
```
```
public bool accepted = false;
```
In the designer, double-click the Proceed button to generate the Click event handler.

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

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

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

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

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

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

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

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;
}
```
On the Build menu, click Build Solution.

Creating 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

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.
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

Create a text file called product.xml.

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

<Product
  xmlns="https://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>

Save the file to the UpdateConsentDialog bootstrapper directory.

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

Create a text file called package.xml.

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="https://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>

Save the file to the en subdirectory in the UpdateConsentDialog bootstrapper directory.
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.
Save the document to the en subdirectory in the UpdateConsentDialog bootstrapper directory.
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.

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

In Solution Explorer, click the name of your application that you want to deploy.
On the Project menu, click ProjectName Properties.
Click the Publish page, and then click Prerequisites.
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.
Click OK.

Creating and Testing 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

In Solution Explorer, click the name of your application that you want to deploy.
On the Project menu, click ProjectName Properties.
Click the Publish page, and then click Publish Now.
If the publish output does not open automatically, navigate to the publish output.
Run the Setup.exe program.

The Setup program shows the Update Consent Dialog software license agreement.
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.
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.
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
Click Close.

To create and test the Setup program by clicking I agree

In Solution Explorer, click the name of your application that you want to deploy.
On the Project menu, click ProjectName Properties.
Click the Publish page, and then click Publish Now.
If the publish output does not open automatically, navigate to the publish output.
Run the Setup.exe program.

The Setup program shows the Update Consent Dialog software license agreement.
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.
Click I Agree, and then click Proceed.

The application starts to install.
If the Application Install dialog box appears, click Install.

Walkthrough: Creating a Custom Bootstrapper to Show a Privacy Prompt

Prerequisites

Creating the Custom Bootstrapper Package

Step 1: To create the bootstrapper directory

Step 2: To create the product.xml manifest file

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

Creating and Testing the Setup Program

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

To create and test the Setup program by clicking I agree

See Also

Tasks

Reference

Concepts

Additional resources

Walkthrough: Creating a Custom Bootstrapper to Show a Privacy Prompt

Prerequisites

Creating an Update Consent Dialog Box

To create a consent dialog box

Creating the Custom Bootstrapper Package

Step 1: To create the bootstrapper directory

Step 2: To create the product.xml manifest file

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

Setting the Update Consent Application as a Prerequisite

To set the Update Consent Application as a prerequisite

Creating and Testing the Setup Program

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

To create and test the Setup program by clicking I agree

See Also

Tasks

Reference

Concepts

Additional resources