Skip to content

Latest commit

 

History

History
140 lines (90 loc) · 14.1 KB

versioning.md

File metadata and controls

140 lines (90 loc) · 14.1 KB
Raw

Assembly Versioning

This document lists the guidelines we will be following for incrementing the assembly versions of WinRT.Runtime.dll and Microsoft.Windows.SDK.NET.dll, which are the runtime and Windows SDK projection assemblies generated by C#/WinRT. If we increment AssemblyVersion for either of these assemblies, application developers may have to upgrade their .NET SDK to the newest version and re-compile their applications. This may become painful for developers as we make frequent updates to the .NET 5.0+ SDK through servicing and feature releases, so the recommendation from the .NET team is to avoid making changes to AssemblyVersion when possible aside from major releases.

Guidelines

CsWinRT releases Windows SDK projection packages (which include the runtime and projection assemblies) for insertion into the .NET SDK, as well as the CsWinRT NuGet package for custom projection and authoring support. The CsWinRT NuGet package only includes the runtime assembly. Because of this, CsWinRT official releases will coordinate with updates to the Windows SDK projection package based on the feature and servicing release cadence for .NET.

Between .NET servicing or feature releases, we may issue "preview" releases of the CsWinRT NuGet package and the Windows SDK projection packages for developers that are blocked on specific bugs or want to try new features. We do not provide support for developers to ship applications or components using any preview releases, and they should instead wait until the specific CsWinRT fix or feature being used ships with a .NET servicing or feature release.

Our rule going forwards is to only increment AssemblyVersion with .NET feature releases if we make additive API surface changes. AssemblyVersion will not increment with .NET servicing releases. The exception to this rule is the first .NET5 servicing release, which will have an AssemblyVersion increment to WinRT.Runtime.dll. The reason for this is so we can make changes earlier in hopes of minimizing the number of impacted developers in the future. We expect to have a few additive API surface changes following .NET5 RTM, but long-term AssemblyVersion should stabilize.

The following sections list our guidelines for incrementing AssemblyVersion and AssemblyFileVersion.

AssemblyVersion

AssemblyVersion is used by the runtime to locate the correct version of the assembly to load. AssemblyVersion has the following format for CsWinRT generated assemblies:

AssemblyVersion Format
WinRT.Runtime.dll <major>.<minor>.0.0 *
Microsoft.Windows.SDK.NET.dll 10.0.<windows_build>.<projection_update>

* Note: this format for the runtime assembly takes effect starting with AssemblyVersion 1.1.0.0, which aligns with the first .NET5 servicing release.

The <windows_build> refers to the Windows SDK build number. As of .NET5 RTM, the supported <windows_build> versions are 17763, 18362, and 19041.

The guidelines for incrementing AssemblyVersion are as follows. Note that AssemblyVersion increments to either assembly are independent of one another.

  1. For WinRT.Runtime.dll:
    • Do not increment: if we only have backwards compatible bug-fixes.
      • Note: this differs from Semantic Versioning rules
    • Increment <minor> or <major>: if there are any changes to the public API surface.
  2. For Microsoft.Windows.SDK.NET.dll:
    • Increment <projection_update>: if there are changes to the CsWinRT generated API surface for the Windows SDK projections, for example if we expose more functions or if we discover we are not projecting a function that we should be.
    • Update <windows_build>: if there is a new version of the Windows API surface, which would occur with a new Windows OS release and corresponding Windows SDK. This will involve listing a new Windows SDK projection package for the new Windows version.

AssemblyFileVersion

AssemblyFileVersion is used for deployment and can mark assemblies with the same AssemblyVersion. It can be viewed in Windows from File Properties -> File Version. AssemblyFileVersion has the following format for CsWinRT generated assemblies:

AssemblyFileVersion Format
WinRT.Runtime.dll <major>.<minor>.<patch>.<build>
Microsoft.Windows.SDK.NET.dll 10.0.<windows_build>.<package_update>

AssemblyFileVersion will be incremented with each release, regardless of whether there are API changes. This means if AssemblyVersion does not increment, we will still increment AssemblyFileVersion. The guidelines for incrementing AssemblyFileVersion are as follows.

  1. For WinRT.Runtime.dll:
    • Increment <minor> or <major>: if there is an API change these will be updated as needed, which will also cause an increment to AssemblyVersion.
    • Increment <patch> and/or <build>: if there are no API changes and therefore no increment to AssemblyVersion. We can manually increment <patch> to be non-zero, and <build> is always automatically incremented.
  2. For Microsoft.Windows.SDK.NET.dll:
    • Increment <package_update> automatically for each build.

Future Version Numbers

As of .NET5 RTM (5.0.100), AssemblyVersion and AssemblyFileVersion for the runtime and Windows SDK assemblies are identical. Going forwards, AssemblyVersion and AssemblyFileVersion will be decoupled.

The CsWinRT NuGet version and Windows SDK projection package version will correspond with the AssemblyFileVersion of WinRT.Runtime.dll and Microsoft.Windows.SDK.NET.dll, respectively.

The table below is an example of how we will increment future version numbers.

  • The AssemblyVersion and AssemblyFileVersion column cells list the WinRT.Runtime.dll version followed by the Microsoft.Windows.SDK.NET.dll version.
  • The NuGet package version column cells list the CsWinRT NuGet package version followed by the Windows SDK projection package version.
Release AssemblyVersion AssemblyFileVersion NuGet package version
.NET5 RTM (5.0.100) 1.0.1.33301
10.0.xxxxx.10		 1.0.1.33301
10.0.xxxxx.10		 1.0.1
10.0.xxxxx.10
.NET Servicing Release (5.0.101) * 1.1.0.0
10.0.xxxxx.10		 1.1.0.<build>
10.0.xxxxx.11		 1.1.0
10.0.xxxxx.11
.NET Servicing Release (5.0.102) 1.1.0.0
10.0.xxxxx.10		 1.1.1.<build>
10.0.xxxxx.12		 1.1.1
10.0.xxxxx..12
.NET Feature Release (5.0.200)
Scenario 1: WinRT.Runtime API surface changes only 1.2.0.0
10.0.xxxxx.10		 1.2.0.<build>
10.0.xxxxx.13		 1.2.0
10.0.xxxxx.13
Scenario 2: Windows SDK projection changes only 1.1.0.0
10.0.xxxxx.11		 1.1.2.<build>
10.0.xxxxx.13		 1.1.2
10.0.xxxxx.13
Scenario 3: Only bug-fixes 1.1.0.0
10.0.xxxxx.10		 1.1.2.<build>
10.0.xxxxx.13		 1.1.2
10.0.xxxxx.13

* The .NET 5.0.101 servicing release is an exception to any other future servicing releases, as it will include API surface changes and an increment to AssemblyVersion for WinRT.Runtime.dll. The .NET Servicing Release (5.0.102) row reflects the assembly versioning rules for servicing releases going forwards, as it will only include bug-fixes and no AssemblyVersion increments.

Note: AssemblyVersion for WinRT.Runtime.dll will never have a non-zero <patch> or <build>, with the exception of .NET5 RTM.

CsWinRT NuGet Prereleases

For CsWinRT NuGet prereleases between any .NET servicing or feature releases, <patch> will be incremented for the WinRT.Runtime.dll AssemblyFileVersion (e.g., 1.1.0 -> 1.1.1). In general, AssemblyVersion will not be incremented for prereleases until just prior to a feature release. The NuGet version will have the -prerelease suffix, for example between the 5.0.101 and 5.0.102 servicing releases, a CsWinRT prerelease NuGet version would have the format 1.1.1-prerelease.<build>.

Scenarios

  1. [Direct Reference]: An app developer builds on a lower .NET SDK version than its dependency. For example, an app developer builds with the .NET 5.0.100 SDK and references a library built with the .NET 5.0.200 SDK. In this scenario, the .NET 5.0.200 SDK included an AssemblyVersion update to either WinRT.Runtime.dll or Microsoft.Windows.SDK.NET.dll. The following sub-scenarios apply:

    a. The library does not expose Windows SDK types.

    • If there is an AssemblyVersion update to Microsoft.Windows.SDK.NET.dll, the app developer will get the following warning/errors:

      • Build warning upon referencing the library - Warning MSB3277: Found conflicts between different versions of "Microsoft.Windows.SDK.NET" that could not be resolved.

      • Runtime error upon calling any of the library APIs that use Windows SDK types - System.IO.FileLoadException: Could not load file or assembly Microsoft.Windows.SDK.NET

    • If only WinRT.Runtime.dll has an AssemblyVersion update, the app developer is unaffected.

      An exception is if the library uses any new APIs (for example, VectorExtensions methods were added in the .NET 5.0.101 SDK). In the case where any new APIs are used in the library, we would have the following

      • Build warning upon referencing the library - Warning MSB3277: Found conflicts between different versions of "WinRT.Runtime" that could not be resolved.

      • Runtime error when the application uses any of the new APIs - System.IO.FileLoadException: Could not load file or assembly WinRT.Runtime.

    b. The library exposes Windows SDK types.

    For example, the WinUI library decides to upgrade and build with .NET 5.0.200, as this .NET SDK version contains a fix for one of their scenarios. Before this, WinUI was building their library with an earlier .NET SDK version (e.g., 5.0.100). An app developer using WinUI notices the update and updates their WinUI package version. Since WinUI moved to building against .NET 5.0.200, the app developer needs to update their .NET SDK version even if they were not using any of those scenarios that required the Windows SDK projection fixes. The app developer will either get a warning or build error, specified below.

    • If the application does not consume the exposed Windows SDK types, this results in one of the following build warnings depending on which AssemblyVersion is incremented:

      • Warning MSB3277: Found conflicts between different versions of "Microsoft.Windows.SDK.NET" that could not be resolved.

      • Warning MSB3277 Found conflicts between different versions of "WinRT.Runtime" that could not be resolved.

    • If the application does consume the exposed Windows SDK types, this results in a CS1705 compiler build error: Assembly 'AssemblyName1' uses 'TypeName' which has a higher version than referenced assembly 'AssemblyName2'.

  2. [Diamond Dependency]: An application is built using multiple components, for example WinUI and a library named SimpleMath. The WinUI library is built with .NET 5.0.100 while the SimpleMath library is built with .NET 5.0.200. In this scenario, there is an AssemblyVersion update in .NET 5.0.200. The application developer must upgrade to the latest version of the .NET SDK for any of its dependencies, in this case .NET 5.0.200. The warnings and errors encountered are manifested in the same manner as in Scenario #1.

  3. [Windows SDK package override]: An application developer runs into a blocking bug with the Windows SDK projections in the latest CsWinRT release. To address this issue, Microsoft releases a preview Windows SDK projection package that the developer can use by adding an override in their project file. This would be a temporary workaround for the developer that should be removed when there is a .NET SDK update.

    Starting in .NET SDK 5.0.302 and .NET SDK 5.0.205 or later, developers can use WindowsSdkPackageVersion to override their Windows SDK package version, as shown below. FrameworkReference is no longer supported in these versions of the .NET SDK.

    <PropertyGroup>
   <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

    For earlier versions of the .NET SDK, developers can override the Windows SDK package with a FrameworkReference override:

    <ItemGroup>
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.18362.11-preview" />
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.18362.11-preview" />
</ItemGroup>

  4. [Long-term Servicing Release]: An application developer builds with .NET 5.0.102 and references a component built with .NET 5.0.103, which is a typical servicing update. Since AssemblyVersion is unchanged for servicing releases and only AssemblyFileVersion has been updated, the developer does not have to update anything and is unaffected.

  5. [Long-term Feature Release]: An application developer builds with .NET 5.0.200 and references a component built with .NET 5.0.300, which is a feature release. For a feature release there are two possibilities:

    • AssemblyVersion was incremented in either the runtime or projection assembly with .NET 5.0.300. The application developer faces the same build warnings or errors in Scenario #1.
    • AssemblyVersion is not incremented in either assembly. The application developer is unaffected as in Scenario #4.

  6. [New Windows OS Version + Windows SDK Version]: A new Windows OS release and corresponding Windows SDK comes out, such as the Windows Iron (Fe) update. We will provide new Windows SDK projection packages with an updated <windows_build>, and the <projection_update> would continue from the most recent verison for consistency. Support would be added for a new TFM, such as net5.0-windows10.0.2xxxx.0.