docs: add a troubleshooting entry for MSBuild-created releases with the wrong version #5691

Resolving which version gets used for a release (SentryCreateRelease / SentrySetCommits) turns out to be surprisingly confusing (not really our fault - just years of Microsoft flip flopping and adding different ways to do things). On Windows it's not even possibly to reliably detect what the version should be in some edge cases.

We should add an entry to the .NET Troubleshooting page (docs/platforms/dotnet/common/troubleshooting.mdx in getsentry/sentry-docs) explaining the mechanics, the edge cases and recommending what people should do on Windows to avoid/resolve issues.

The full mechanics are explained in:

• fix: SentryCreateRelease uses the assembly's informational version and no longer requires UseSentryCLI #5679 (comment)

We definitely don't want to include that massive wall of text so need to gist that down to the bare essentials.

What to cover

The release created at build time doesn't match the release on events

The build names the release <assembly name>@<version>. The version is meant to match the one the SDK reports at runtime: the assembly's informational version, or its assembly version if there isn't one (see the order on the MSBuild page).

Known reasons it doesn't:

• SDK versions before the fix: SentryCreateRelease uses the assembly's informational version and no longer requires UseSentryCLI #5679 fix: if the project has an assembly-level attribute that MSBuild can't load, the build silently uses the assembly version, e.g. App@1.0.0.0. Examples are <UserSecretsId>, or packages such as Microsoft.Identity.Web that make the Web SDK generate an ApplicationPartAttribute. Workaround: set SENTRY_RELEASE for the build, and give the app the same value at runtime.
• Windows, after the fix: this only affects builds that run on Windows, for non-SDK projects or SDK-style projects that turn off attribute generation (GenerateAssemblyInfo or GenerateAssemblyInformationalVersionAttribute set to false). If the assembly has no informational version and its file version differs from its assembly version, the build can't always tell which version the app will report. It then logs a warning that names both versions and picks one. Any of these avoids it:
  • Give the assembly an informational version that differs from its file version, e.g. [assembly: AssemblyInformationalVersion("1.2.3")] in AssemblyInfo.cs. The build and the SDK then both use it.
  • To choose the release name yourself, put the full release in the informational version, e.g. [assembly: AssemblyInformationalVersion("myapp@1.2.3")]. The build and the SDK both use a version containing @ as-is.
  • In an SDK-style project, let the SDK generate the informational version (the default) instead of turning generation off.
  • Make the file version match the assembly version.
  • Set SENTRY_RELEASE for the build, and give the app the same value at runtime (SENTRY_RELEASE in its environment, or options.Release).

SentryCreateRelease or SentrySetCommits doesn't create a release

In SDK versions before the #5679 fix, neither property did anything unless UseSentryCLI was also set to true explicitly, or SENTRY_RELEASE was set. Upgrading fixes this; on older versions, setting either one works around it.