Updates, Versioning & Telemetry

The SDK-style project file is the single place to set all of them. A Directory.Build.props file in the solution root lets every project in the Bookshelf Desktop solution (Bookshelf.Core, Bookshelf.Desktop, the test projects) share the same numbers.

Source: Assembly versioning; MSBuild properties for Microsoft.NET.Sdk

Two details are worth knowing. IncludeSourceRevisionInInformationalVersion defaults to true, and from .NET 8 the SDK fills SourceRevisionId with the commit hash when Source Link is present, so the informational version of a default build already ends in the commit hash. A bare $(BUILD_NUMBER) that is empty on a developer machine produces a malformed file version, so a real build gives it a default (for example 0) in the same file.

Users report problems using the version they see in the About box, so that is the number that matters most for support. Read it from the informational version, which carries the commit hash, behind a small service so the view model stays testable.

Source: Assembly versioning

A packaged app has a second source of truth, the package version. In a packaged WinUI 3 or WPF app with package identity, Windows.ApplicationModel.Package.Current.Id.Version returns it; an unpackaged app has no package, so the assembly attributes remain the portable choice. Log both when they exist, because a mismatch between the manifest and the assemblies is one of the commonest packaging mistakes.

For an MSIX submitted to the Store, the Store re-signs the package with a Microsoft certificate after certification and hosts it on its content network, and the operating system performs the update; you write no update code. Your tasks are to submit a package whose Version is higher than the live one and to wait for certification. The Store offers every customer the highest-versioned package that applies to their device. Store package flights let you send a build to a chosen group before everyone, which is how a pre-release channel is done there. EXE and MSI submissions are different: you host the installer, sign it yourself, and the installer is not allowed to change after submission, so updates are a new submission each time.

An .appinstaller file is an XML file that names the MSIX and says how to update it. Users install by opening the .appinstaller, which associates the app with it; later you update the file to point at the new package, and Windows picks the change up. The documented update settings are small:

Source: App Installer file update settings

The following file mirrors the documented structure: launch-time checks with a prompt, a background check and no forced downgrade.

Source: Current status of Windows app distribution features

A few cautions. The Version on the root element is the version of the .appinstaller file, and the MainPackage Name, Publisher and Version must match the package identity exactly. Updates can be served over https, http or smb. And the ms-appinstaller: URI protocol has been disabled by default since December 2023, so a "Install" button that uses it no longer works on most machines: link to the .appinstaller file itself, or publish to the Store. The file uses the 2021 schema namespace on purpose: Visual Studio still generates the 2017/2 schema, which does not support ShowPrompt, UpdateBlocksActivation or HoursBetweenUpdateChecks and silently ignores them, as Distribution Channels explains.

WinGet updates are pull-based: nothing happens until the user, a script or a management tool runs winget upgrade. Your part is to publish a new manifest version to the winget-pkgs repository, which the wingetcreate tool automates.

Source: upgrade command

The documentation notes that packages without a version are always "latest", so they are skipped unless --include-unknown is given, and that pinned packages are skipped by --all unless --include-pinned is given (and then only those with non-blocking pins). winget update is an alias of winget upgrade.

On the publisher side, wingetcreate update takes the id of an existing manifest and the URL of the new installer, generates the new manifest version and, with --submit, opens the pull request. The same flow is scripted in CI/CD with GitHub Actions.

Source: winget-create

The update command takes the package id followed by --urls (-u), --version (-v) and --submit (-s); wingetcreate update --help lists the rest. The pull request goes through automated validation and, for many packages, a moderator review, so a WinGet release can lag behind your own site by hours or days. The manifest must also list the correct installer hash, and the installer URL must never be rewritten afterwards: a changed file at an old URL fails the hash check.

ClickOnce applications are self-updating by design. The deployment manifest holds the version clients should run, and a client compares it with what is installed. For .NET (Core 3.1, 5 and later) the options are narrower than for .NET Framework:

Source: Choosing a ClickOnce update strategy; ClickOnce for .NET 5 and later on Windows

With the default before-start check, a client that finds a newer version either installs it (when it is required) or asks the user whether to upgrade or start the existing version. To make an update mandatory, set the minimum required version; the documentation says that only the before-start strategy guarantees an older version can no longer run.

Source: Choosing a ClickOnce update strategy

ClickOnce is not available for WinUI 3 applications, and updates need network connectivity: with no connection the app runs without checking, whatever strategy you chose.

MSI and EXE installers (built with tools such as WiX, Inno Setup or NSIS) carry no update mechanism of their own that Windows drives for you. Options are a manual download, a managed deployment, WinGet, or an updater inside the application. Velopack is a third-party installer and update framework for .NET desktop apps; it is not a Microsoft product and is only named here so you can evaluate it at https://velopack.io/. Whatever you choose, an in-app updater must follow the rules in the security page: fetch over https, verify a signature on what you download, and never run unsigned code. See Security & App Isolation, which discusses update-channel security.

WER lets users send Microsoft information about application faults and unresponsive applications; users choose whether to report, and administrators can override with Group Policy. Developers can register with the Windows Desktop Application Program to receive information about problems customers hit. For apps in the Store, the same data reaches you through the Health report in Partner Center, which shows crash counts and unresponsiveness rates, stack traces, affected OS and device combinations, and trends, and lets you compare app versions. The crash rate is calculated from devices that opted in to share optional diagnostic data, so it is a sample, not a count of every user. To get symbolicated stacks, submit the .msixupload file that Visual Studio creates: it includes an .appxsym file (a compressed PDB of public symbols), and if you omit it no crash analytics are available for the app.

Source: Windows Error Reporting; Health report

The Windows App SDK 2.5.1 release notes list "Windows Error Reporting support": the windows.diagnosticServiceModule package-manifest extension, which a self-contained .NET MSIX app can use to declare diagnostic modules so that WER can load them and collect actionable crash dumps. The release notes do not show the manifest XML, so this page does not either; read the current release notes before relying on it.

Source: Windows App SDK 2.x release notes

For machines you control (a pilot group, a test lab) WER can write dumps locally after a crash. The feature is not enabled by default and needs administrator rights. The settings live under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps: DumpFolder (default %LOCALAPPDATA%\CrashDumps), DumpCount (default 10) and DumpType (0 custom, 1 mini, 2 full; default 1). A subkey named after the executable, for example Bookshelf.Desktop.exe, overrides the global settings for that program only. Full dumps contain process memory, which can include book data, file paths and tokens, so keep them in a folder with a restricted ACL and delete them when the case closes. See Collecting user-mode dumps.

Inside the app, a WPF application has three places where an exception can surface after every try block has failed: Application.DispatcherUnhandledException for the UI thread, AppDomain.CurrentDomain.UnhandledException for any thread when the process is about to end, and TaskScheduler.UnobservedTaskException for tasks nobody awaited. Hook all three in App.xaml.cs, route them to one ILogger (see Dependency Injection & the Generic Host) together with the version from IAppInfo, and decide deliberately whether to continue. Setting Handled to true swallows an exception and leaves the application in an unknown state; for most exceptions it is safer to log, offer to restart and let the process end so that WER and the Health report record the crash. A WinUI 3 app uses Application.UnhandledException and WinForms uses Application.ThreadException.

OpenTelemetry is a cross-platform, open standard for emitting logs, metrics and traces. In .NET it builds on the platform APIs you already have — ILogger<T> for logs, System.Diagnostics.Metrics.Meter for metrics and System.Diagnostics.ActivitySource for traces — and exports to a backend over the vendor-neutral OTLP protocol or a specific exporter. The backend is your choice: Azure Monitor and Application Insights, Prometheus and Grafana, or a commercial vendor. For a desktop app the model differs from a server in two ways: the telemetry leaves a machine you do not own, so it must be opt-in, and the network is unreliable, so exporters must buffer and drop rather than block the UI thread.

Source: .NET observability with OpenTelemetry

The packages involved are OpenTelemetry, OpenTelemetry.Exporter.OpenTelemetryProtocol and, for the hosting extension method used above, OpenTelemetry.Extensions.Hosting. The first two are listed on the Microsoft page; the hosting package and its fluent configuration API are documented by the OpenTelemetry .NET project, and the API can change between package versions.

Choose the metrics before the tool. A short list of counts answers most product questions: sessions started, features used, import failures by category, startup time, and the runtime and OS version (to know when you can drop .NET 8 or Windows 10). None of them needs a book title or a path.