[Breaking Change] MinimumOSPlatformAttribute and RemovedInOSPlatformAttribute renamed, ObsoletedInOSPlatformAttribute removed

[jeffhandley]

MinimumOSPlatformAttribute and RemovedInOSPlatformAttribute renamed, ObsoletedInOSPlatformAttribute removed

MinimumOSPlatformAttribute was renamed to SupportedOSPlatformAttribute; RemovedInOSPlatformAttribute was renamed to UnsupportedOSPlatformAttribute; and ObsoletedInOSPlatformAttribute was removed.

These changes can introduce build-time or runtime errors for projects when retargeting from .NET 5.0 Preview 8 to .NET 5.0 RC1. The rename of MinimumOSPlatformAttribute is most likely to produce build-time or runtime errors in projects because the attribute is applied to platform-specific assemblies at build-time and old build artifacts will still reference the old API name.

Example build-time errors:

error CS0246: The type or namespace name 'MinimumOSPlatformAttribute' could not be found (are you missing a using directive or an assembly reference?)
error CS0246: The type or namespace name 'RemovedInOSPlatformAttribute' could not be found (are you missing a using directive or an assembly reference?)
error CS0246: The type or namespace name 'ObsoletedInOSPlatformAttribute' could not be found (are you missing a using directive or an assembly reference?)

Example runtime error:

Unhandled exception. System.TypeLoadException: Could not load type 'System.Runtime.Versioning.MinimumOSPlatformAttribute' from assembly 'System.Runtime, Version=5.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.

These errors are likely to be introduced for projects targeting OS specific flavors of .NET 5 through target framework monikers such as net5.0-windows. To resolve either error, the project must be rebuilt (clean + build) after retargeting to .NET 5.0 RC1.

Version introduced

.NET 5.0 RC1

Old behavior

In .NET 5.0 Preview 8, the following attributes existed within System.Runtime.Versioning:

1. MinimumOSPlatformAttribute
2. RemovedInOSPlatformAttribute
3. ObsoletedInOSPlatformAttribute

In .NET 5.0 Preview 8, when a project was targeting an OS specific flavor of .NET 5 through a target framework moniker such as net5.0-windows, the build would produce an assembly-level attribute using System.Runtime.Versioning.MinimumOSPlatformAttribute.

New behavior

In .NET 5.0 RC1, the following changes were made to the attributes:

1. MinimumOSPlatformAttribute was renamed to SupportedOSPlatformAttribute
2. RemovedInOSPlatformAttribute was renamed to UnsupportedOSPlatformAttribute
3. ObsoletedInOSPlatformAttribute was removed

In .NET 5.0 RC1, when a project was targeting an OS specific flavor of .NET 5 through a target framework moniker such as net5.0-windows, the build will produce an assembly-level attribute using System.Runtime.Versioning.SupportedOSPlatformAttribute.

Reason for change

.NET 5.0 Preview 8 introduced attributes in System.Runtime.Versioning with the purpose of performing platform checks for APIs that only work on specified platforms. The attributes are consumed by the Platform Compatibility Analyzer to produce build warnings when consuming platform-specific APIs on platforms those APIs don't support.

During .NET 5.0 RC1, an additional feature was added to the Platform Compatibility Analyzer for platform exclusion, allowing APIs to be marked as entirely unsupported on OS platforms. That feature prompted changes to the attributes, using API names more suitable for scenarios.

The following API changes were made in System.Runtime.Versioning to support this new feature:

1. MinimumOSPlatformAttribute renamed to SupportedOSPlatformAttribute, to support platform-specific API annotations
2. RemovedInOSPlatformAttribute renamed to UnsupportedOSPlatformAttribute, to support platform exclusion annotations
3. ObsoletedInOSPlatformAttribute was removed, as this annotation is not needed at this time

Recommended action

1. After retargeting the project to .NET 5.0 RC1, rebuild the project (or perform clean + build)
2. Update any references of MinimumOSPlatformAttribute to SupportedOSPlatformAttribute
3. Update any references of RemovedInOSPlatformAttribute to UnsupportedOSPlatformAttribute
4. Remove any references to ObsoletedInOSPlatformAttribute

Category

• ASP.NET Core
• C#
• Code analysis
• Core .NET libraries
• Cryptography
• Data
• Debugger
• Deployment
• Globalization
• Interop
• JIT
• LINQ
• Managed Extensibility Framework (MEF)
• MSBuild
• Networking
• Printing
• Security
• Serialization
• Visual Basic
• Windows Forms
• Windows Presentation Foundation (WPF)
• XML, XSLT

Affected APIs

• MinimumOSPlatformAttribute
• RemovedInOSPlatformAttribute
• ObsoletedInOSPlatformAttribute

---

Issue metadata

• Issue type: breaking-change

[jeffhandley]

FYI @jiangzeng01 @PriyaPurkayastha

@jiangzeng01 please let me know if you recommend any changes.

[PriyaPurkayastha]

cc @gewarren