Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open Beginner friendly
  • Is something wrong?
#5,691 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
csharp
Domain
documentation

Research direction

Edit docs/platforms/dotnet/common/troubleshooting.mdx, the .NET Troubleshooting page. Read the linked explanation in PR #5679 and the MSBuild documentation to verify the release-version behavior, then condense the listed edge cases and workarounds into a troubleshooting entry. Done when the page covers both mismatched release versions and cases where SentryCreateRelease or SentrySetCommits does not create a release.

Written by the indexing model from the issue text.

Description

Docs MSBuild

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:

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 #5679 fix: if the project has an assembly-level attribute that MSBuild can't load, the build silently uses the assembly version, e.g. [email protected]. 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("[email protected]")]. 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.

Dominant language
C#
Stars
768
Forks
250
Avg merge
3d 1h
Merged PRs (30d)
79

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from getsentry/sentry-dotnet

All issues in getsentry/sentry-dotnet

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.