Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document issues with using * in AssemblyVersion #9892

Merged
merged 4 commits into from
May 24, 2024
Merged

Document issues with using * in AssemblyVersion #9892

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4fd26fc
Document issues with using * in AssemblyVersion
tmat May 9, 2024
e6f794f
Apply suggestions from code review
tmat May 16, 2024
694eb8a
Update AssemblyVersionAttribute.xml
tmat May 16, 2024
770a3e1
Update xml/System.Reflection/AssemblyVersionAttribute.xml
tmat May 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 24 additions & 6 deletions xml/System.Reflection/AssemblyVersionAttribute.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,12 +86,30 @@

> [!IMPORTANT]
> All components of the version must be integers greater than or equal to 0. Metadata restricts the major, minor, build, and revision components for an assembly to a maximum value of <xref:System.UInt16.MaxValue?displayProperty=nameWithType> - 1. If a component exceeds this value, a compilation error occurs.

You can specify all the values or you can accept the default build number, revision number, or both by using an asterisk (\*). For example, `[assembly:AssemblyVersion("2.3.25.1")]` indicates 2 as the major version, 3 as the minor version, 25 as the build number, and 1 as the revision number. A version number such as `[assembly:AssemblyVersion("1.2.*")]` specifies 1 as the major version, 2 as the minor version, and accepts the default build and revision numbers. A version number such as `[assembly:AssemblyVersion("1.2.15.*")]` specifies 1 as the major version, 2 as the minor version, 15 as the build number, and accepts the default revision number. The default build number increments daily. The default revision number is the number of seconds since midnight local time (without taking into account time zone adjustments for daylight saving time), divided by 2.

> [!NOTE]
> If you specify an asterisk for the build number, you cannot specify a revision number.


For example, `[assembly:AssemblyVersion("2.3.25.1")]` indicates 2 as the major version, 3 as the minor version, 25 as the build number, and 1 as the revision number.

The <xref:System.Reflection.AssemblyVersionAttribute> attribute allows you to specify an asterisk (\*) in place of the build or revision number. A version number such as `[assembly:AssemblyVersion("1.2.*")]` specifies 1 as the major version and 2 as the minor version, and accepts the default build and revision numbers. A version number such as `[assembly:AssemblyVersion("1.2.15.*")]` specifies 1 as the major version, 2 as the minor version, and 15 as the build number, and accepts the default revision number. The default build number increments daily. The default revision number is the number of seconds since midnight local time (without taking into account time zone adjustments for daylight saving time), divided by 2. If you specify an asterisk for the build number, you can't specify a revision number.

> [!IMPORTANT]
> Use of the <xref:System.Reflection.AssemblyVersionAttribute> attribute that specifies an asterisk:
>
> - Makes the build outputs non-reproducible (see [Reproducible builds](https://reproducible-builds.org/)). If the project sets `Deterministic` build property to `true` an error `CS8357` is reported by the compiler.
> - Might degrade build performance, as it prevents build from caching compiler outputs.
> - Is incompatible with the [Edit & Continue](/visualstudio/debugger/edit-and-continue-visual-csharp) and [Hot Reload](/visualstudio/debugger/hot-reload) features.

You can mitigate some of these issues by limiting the use of time-based versions to release builds using conditional compilation, like so:

```
#if DEBUG
[assembly: AssemblyVersion("1.0.0.0")]
#else
[assembly: AssemblyVersion("1.0.*")]
#endif
```

A better approach to versioning is to derive the assembly or file version from the `HEAD` commit SHA (for git repositories). See, for example, [Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning).

The assembly major and minor versions are used as the type library version number when the assembly is exported. Some COM hosts do not accept type libraries with the version number 0.0. Therefore, if you want to expose an assembly to COM clients, set the assembly version explicitly to 1.0 in the `AssemblyVersionAttribute` page for projects created outside Visual Studio 2005 and with no `AssemblyVersionAttribute` specified. Do this even when the assembly version is 0.0. All projects created in Visual Studio 2005 have a default assembly version of 1.0.*.

To get the name of an assembly you have loaded, call <xref:System.Reflection.Assembly.GetName%2A> on the assembly to get an <xref:System.Reflection.AssemblyName>, and then get the <xref:System.Reflection.AssemblyName.Version%2A> property. To get the name of an assembly you have not loaded, call <xref:System.Reflection.AssemblyName.GetAssemblyName%2A> from your client application to check the assembly version that your application uses.
Expand Down
Loading