Client Auto-Update Mechanism

Relevant source files

The following files were used as context for generating this wiki page:

• PeP.ExamApp/Services/UpdateService.cs
• Controllers/ExamAppController.cs
• PeP.ExamApp/Installer/README.md
• PeP.ExamApp/App.xaml.cs
• PeP.ExamApp/Installer/build-installer.ps1

The Client Auto-Update Mechanism is a critical feature of the PeP project, designed to ensure that the PeP.ExamApp WPF client application is always up-to-date. On startup, the client communicates with the PeP web server to check for new versions. If an update is available, the system can prompt the user, download the new installer, and execute it silently to provide a seamless update experience.

This mechanism is essential for deploying bug fixes, security patches, and new features to the secure exam environment, ensuring all students are using a consistent and approved version of the application. The process involves both client-side logic within the WPF application and a dedicated server-side API endpoint for distributing update information.

Architecture Overview

The auto-update system follows a client-server model. The PeP.ExamApp client initiates the process by sending its current version to a specific API endpoint on the PeP web server. The server checks its configuration for a newer version and responds with the update details if one exists. The client then handles the download, verification, and installation of the new version.

The following diagram illustrates the high-level components and their interaction.

Server-Side Components

The server is responsible for providing information about the latest available update. This is managed through a configuration file and a dedicated API endpoint.

API Endpoint

The server exposes a single endpoint for the client to check for updates.

Property	Value
Method	GET
Route	/api/examapp/update
Authorization	Anonymous
Controller	ExamAppController

Query Parameters

Parameter	Type	Description
currentVersion	string	The current version of the client application making the request.

Sources: Controllers/ExamAppController.cs:27-29

Server Configuration

The update information is stored in the appsettings.json file on the web server within the ExamAppUpdate section. When a new version of the client is released, this section must be updated with the new version's details and the installer's checksum.

Sources: PeP.ExamApp/Installer/README.md:91-102, Controllers/ExamAppController.cs:32

An example configuration block is shown below:

{
  "ExamAppUpdate": {
    "Version": "1.1.0",
    "DownloadUrl": "https://yourserver.com/downloads/PeP.ExamApp_Setup_1.1.0.exe",
    "ReleaseNotes": "- Bug fixes\n- Performance improvements",
    "ReleaseDate": "2025-12-22",
    "IsMandatory": false,
    "MinimumVersion": "1.0.0",
    "Checksum": "sha256hashofinstallerfile"
  }
}

Sources: PeP.ExamApp/Installer/README.md:93-101

Update Response Payload

If a newer version is found, the API endpoint returns a JSON object with the update details. This data is mapped from the ExamAppUpdate configuration section. The structure is defined by the UpdateInfoResponse record in the controller and the UpdateInfo class on the client.

Field	Type	Description
version	string	The new version number (e.g., "1.1.0").
downloadUrl	string	The direct URL to the installer .exe file.
releaseNotes	string	A description of the changes in the new version.
releaseDate	DateTime	The release date of the new version.
isMandatory	boolean	If true, the user is forced to update.
minimumVersion	string	The minimum required version to run the app.
checksum	string	The SHA256 hash of the installer file for verification.

Sources: Controllers/ExamAppController.cs:48-56, PeP.ExamApp/Services/UpdateService.cs:8-16, PeP.ExamApp/Installer/README.md:80-88

Client-Side Implementation

The client-side logic is encapsulated within the PeP.ExamApp project, primarily in the UpdateService.

Update Trigger

The update check is initiated automatically when the application starts. The App.OnStartup method calls CheckForUpdatesAsync, which creates an instance of UpdateService and begins the process.

// File: PeP.ExamApp/App.xaml.cs

protected override async void OnStartup(StartupEventArgs e)
{
    // ...
    base.OnStartup(e);

    // Check for updates in the background
    await CheckForUpdatesAsync();
}

private async Task CheckForUpdatesAsync()
{
    try
    {
        // Initialize update service with your server URL
        _updateService = new UpdateService("https://localhost:7170");
        
        // Clean up old update files
        _updateService.CleanupOldUpdates();

        // Check for updates
        var updateInfo = await _updateService.CheckForUpdateAsync();
        
        if (updateInfo != null)
        {
            await _updateService.PromptAndInstallUpdateAsync(updateInfo);
        }
    }
    // ...
}

Sources: PeP.ExamApp/App.xaml.cs:24-44

UpdateService Class

This class is the core of the client-side update mechanism. It handles checking, downloading, verifying, and installing updates.

The diagram below shows the structure of the UpdateService and its related UpdateInfo data class.

Key Methods:

Method	Description
CheckForUpdateAsync()	Contacts the server's update endpoint and deserializes the response. It compares the server version with the current client version.
DownloadUpdateAsync()	Downloads the installer from the downloadUrl. It reports progress and verifies the file's SHA256 checksum against the one from the server.
InstallUpdate()	Launches the downloaded installer with silent arguments (/SILENT /RESTARTAPPLICATIONS) and shuts down the current application.
PromptAndInstallUpdateAsync()	Shows a dialog to the user with the update details. If the update is mandatory or the user accepts, it orchestrates the download and installation.
CleanupOldUpdates()	Deletes old installer files from the local application data folder to save space.
VerifyChecksumAsync()	Computes the SHA256 hash of a downloaded file and compares it to the expected checksum from the server to ensure integrity.

Sources: PeP.ExamApp/Services/UpdateService.cs

Update Process Flow

The following sequence diagram details the end-to-end update process, from application startup to the launch of the new version's installer.

Installer and Deployment

The update mechanism relies on a distributable installer created using Inno Setup.

Installer Build Process

The build-installer.ps1 PowerShell script automates the creation of the installer.

1. It updates the version number in the PeP.ExamApp.csproj file.
2. It publishes the WPF application using dotnet publish.
3. It updates the version in the Inno Setup script (PeP.ExamApp.iss).
4. It invokes the Inno Setup command-line compiler (ISCC.exe) to build the final PeP.ExamApp_Setup_X.X.X.exe.
5. It generates a .sha256 checksum file for the installer, which is used in the appsettings.json on the server.

Sources: PeP.ExamApp/Installer/build-installer.ps1, PeP.ExamApp/Installer/README.md:10-13

Silent Installation

To ensure a smooth user experience, the UpdateService launches the installer with specific command-line arguments.

// File: PeP.ExamApp/Services/UpdateService.cs:141-146
var startInfo = new ProcessStartInfo
{
    FileName = installerPath,
    Arguments = "/SILENT /RESTARTAPPLICATIONS",
    UseShellExecute = true
};

• /SILENT: Runs the installer with minimal UI.
• /RESTARTAPPLICATIONS: A feature of Inno Setup that allows the installer to automatically close and restart the application being updated.

Sources: PeP.ExamApp/Services/UpdateService.cs:143, PeP.ExamApp/Installer/README.md:41