Version tracking

Browse the sample

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IVersionTracking interface. This interface lets you check the applications version and build numbers along with seeing additional information such as if it's the first time the application launched.

The default implementation of the IVersionTracking interface is available through the VersionTracking.Default property. Both the IVersionTracking interface and VersionTracking class are contained in the Microsoft.Maui.ApplicationModel namespace.

Get started

To enable version tracking in your app, invoke the ConfigureEssentials method on the MauiAppBuilder object in the MauiProgram.cs file. Then, on the IEssentialsBuilder object, call the UseVersionTracking() method:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts =>
        {
            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
        })
        .ConfigureEssentials(essentials =>
        {
            essentials.UseVersionTracking();
        });

    return builder.Build();
}

Check the version

The IVersionTracking interface provides many properties that describe the current version of the app and how it relates to the previous version. The following example writes the tracking information to labels on the page:

private void ReadVersion_Clicked(object sender, EventArgs e)
{
    labelIsFirst.Text = VersionTracking.Default.IsFirstLaunchEver.ToString();
    labelCurrentVersionIsFirst.Text = VersionTracking.Default.IsFirstLaunchForCurrentVersion.ToString();
    labelCurrentBuildIsFirst.Text = VersionTracking.Default.IsFirstLaunchForCurrentBuild.ToString();
    labelCurrentVersion.Text = VersionTracking.Default.CurrentVersion.ToString();
    labelCurrentBuild.Text = VersionTracking.Default.CurrentBuild.ToString();
    labelFirstInstalledVer.Text = VersionTracking.Default.FirstInstalledVersion.ToString();
    labelFirstInstalledBuild.Text = VersionTracking.Default.FirstInstalledBuild.ToString();
    labelVersionHistory.Text = String.Join(',', VersionTracking.Default.VersionHistory);
    labelBuildHistory.Text = String.Join(',', VersionTracking.Default.BuildHistory);

    // These two properties may be null if this is the first version
    labelPreviousVersion.Text = VersionTracking.Default.PreviousVersion?.ToString() ?? "none";
    labelPreviousBuild.Text = VersionTracking.Default.PreviousBuild?.ToString() ?? "none";
}

The first time the app is run after version tracking is enabled, the IsFirstLaunchEver property will return true. If you add version tracking in a newer version of an already released app, IsFirstLaunchEver may incorrectly report true. This property always returns true the first time version tracking is enabled and the user runs the app. You can't fully rely on this property if users have upgraded from older versions that weren't tracking the version.

Platform differences

All version information is stored using the Preferences API, and is stored with a filename of [YOUR-APP-PACKAGE-ID].microsoft.maui.essentials.versiontracking and follows the same data persistence outlined in the Preferences documentation.