Skip to content

Latest commit

 

History

History
252 lines (240 loc) · 14 KB

obsoletions-in-net5.md

File metadata and controls

252 lines (240 loc) · 14 KB
Raw

Obsoletions in .NET 5

Owner Immo Landwerth

For .NET 5, we're making it more viable to obsolete APIs. In this document, we're describing which APIs we intend to obsolete in .NET 5 and which diagnostic IDs we will use for those.

With dotnet/runtime PR #33248, the ObsoleteAttribute gained new DiagnosticId and UrlFormat properties. With these properties, obsoletions can be grouped together when multiple APIs are marked as obsolete for the same reason. This capability is reflected in the list of obsoletions below. All of these obsoletions will use the UrlFormat of https://aka.ms/dotnet-warnings/{0}.

  1. The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.
    • DiagnosticId: SYSLIB0001
    • APIs:
      • System.Text.UTF7Encoding (constructors)
      • System.Text.Encoding.UTF7
  2. PrincipalPermissionAttribute is not honored by the runtime and must not be used.
    • DiagnosticId: SYSLIB0002
    • APIs:
      • System.Security.Permissions.PrincipalPermissionAttribute (constructor)
      • Level: Error
  3. Code Access Security is not supported or honored by the runtime.
    • DiagnosticId: SYSLIB0003
    • APIs:
      • Classes: (everything public from the System.Security.Permissions namespace)
        • CodeAccessSecurityAttribute
        • DataProtectionPermission
        • DataProtectionPermissionAttribute
        • EnvironmentPermission
        • EnvironmentPermissionAttribute
        • FileDialogPermission
        • FileDialogPermissionAttribute
        • FileIOPermission
        • FileIOPermissionAttribute
        • GacIdentityPermission
        • GacIdentityPermissionAttribute
        • HostProtectionAttribute
        • IsolatedStorageFilePermission
        • IsolatedStorageFilePermissionAttribute
        • IsolatedStoragePermission
        • IsolatedStoragePermissionAttribute
        • KeyContainerPermission
        • KeyContainerPermissionAttribute
        • KeyContainerPermissionAccessEntry
        • KeyContainerPermissionAccessEntryCollection
        • KeyContainerPermissionAccessEntryEnumerator
        • MediaPermission
        • MediaPermissionAttribute
        • PermissionSetAttribute
        • PrincipalPermission
        • PrincipalPermissionAttribute (the type itself will become obsolete as a warning while the constructor will be obsolete as an error)
        • PublisherIdentityPermission
        • PublisherIdentityPermissionAttribute
        • ReflectionPermission
        • ReflectionPermissionAttribute
        • RegistryPermission
        • RegistryPermissionAttribute
        • ResourcePermissionBase
        • ResourcePermissionBaseEntry
        • SecurityAttribute
        • SecurityPermission
        • SecurityPermissionAttribute
        • SiteIdentityPermission
        • SiteIdentityPermissionAttribute
        • StorePermission
        • StorePermissionAttribute
        • StrongNameIdentityPermission
        • StrongNameIdentityPermissionAttribute
        • StrongNamePublicKeyBlob
        • TypeDescriptorPermission
        • TypeDescriptorPermissionAttribute
        • UIPermission
        • UIPermissionAttribute
        • UrlIdentityPermission
        • UrlIdentityPermissionAttribute
        • WebBrowserPermission
        • WebBrowserPermissionAttribute
        • ZoneIdentityPermission
        • ZoneIdentityPermissionAttribute
      • Classes that derive from CodeAccessSecurityAttribute
        • System.Configuration.ConfigurationPermissionAttribute
        • System.Data.Common.DBDataPermissionAttribute
        • System.Data.OracleClient.OraclePermissionAttribute
        • System.Diagnostics.EventLogPermissionAttribute
        • System.Diagnostics.PerformanceCounterPermissionAttribute
        • System.DirectoryServices.DirectoryServicesPermissionAttribute
        • System.Drawing.Printing.PrintingPermissionAttribute
        • System.Net.DnsPermissionAttribute
        • System.Net.SocketPermissionAttribute
        • System.Net.WebPermissionAttribute
        • System.Net.Mail.SmtpPermissionAttribute
        • System.Net.NetworkInformation.NetworkInformationPermissionAttribute
        • System.Net.PeerToPeer.PnrpPermissionAttribute
        • System.Net.PeerToPeer.Collaboration.PeerCollaborationPermissionAttribute
        • System.ServiceProcess.ServiceControllerPermissionAttribute
        • System.Transactions.DistributedTransactionPermissionAttribute
        • System.Web.AspNetHostingPermissionAttribute
      • Interfaces:
        • System.Security.Permissions.IUnrestrictedPermission
        • System.Security.IPermission
        • System.Security.IStackWalk
        • System.Security.Policy.IIdentityPermissionFactory (has a single member that returns IPermission)
      • Classes that implement IStackWalk
        • System.Security.PermissionSet
          • System.Security.NamedPermissionSet
      • Classes that implement IPermission
        • System.Security.CodeAccessPermission
      • Classes that derive from CodeAccessPermission (also includes implementations of PermissionsIUnrestrictedPermission)
        • System.Configuration.ConfigurationPermission
        • System.Data.Common.DBDataPermission
          • System.Data.Odbc.OdbcPermission
          • System.Data.OleDb.OleDbPermission
          • System.Data.SqlClient.SqlClientPermission
        • System.Data.OracleClient.OraclePermission
        • System.Drawing.Printing.PrintingPermission
        • System.Net.DnsPermission
        • System.Net.SocketPermission
        • System.Net.WebPermission
        • System.Net.Mail.SmtpPermission
        • System.Net.NetworkInformation.NetworkInformationPermission
        • System.Net.PeerToPeer.PnrpPermission
        • System.Net.PeerToPeer.Collaboration.PeerCollaborationPermission
        • System.Transactions.DistributedTransactionPermission
        • System.Web.AspNetHostingPermission
        • System.Xaml.Permissions.XamlLoadPermission
      • Classes that derive from ResourcePermissionBase
        • System.Diagnostics.EventLogPermission
        • System.Diagnostics.PerformanceCounterPermission
        • System.DirectoryServices.DirectoryServicesPermission
        • System.ServiceProcess.ServiceControllerPermission
      • Enums: (everything from the System.Security.Permissions namespace)
        • DataProtectionPermissionFlags
        • EnvironmentPermissionAccess
        • FileDialogPermissionAccess
        • FileIOPermissionAccess
        • HostProtectionResource
        • IsolatedStorageContainment
        • KeyContainerPermissionFlags
        • MediaPermissionAudio
        • MediaPermissionImage
        • MediaPermissionVideo
        • PermissionState
        • ReflectionPermissionFlag
        • RegistryPermissionAccess
        • SecurityAction (with removal of the existing attributes on members)
        • SecurityPermissionFlag
        • StorePermissionFlags
        • TypeDescriptorPermissionFlags
        • UIPermissionClipboard
        • UIPermissionWindow
        • WebBrowserPermissionLevel
      • Classes/Members that depend on CAS types:
        • System.AppDomain.PermissionSet (property of type PermissionSet)
        • System.Security.HostProtectionException (heavily uses HostProtectionResource)
        • System.Security.Policy.FileCodeGroup (constructor requires FileIOPermissionAccess)
        • System.Security.Policy.StrongName (constructor requires StrongNamePublicKeyBlob and implements IIdentityPermissionFactory)
        • System.Security.Policy.StrongNameMembershipCondition (constructor requires StrongNamePublicKeyBlob)
        • System.Security.Policy.ApplicationTrust(PermissionSet, IEnumerable<StrongName>)
        • System.Security.Policy.ApplicationTrust.FullTrustAssemblies (property of type IList<StrongName>)
        • System.Security.Policy.GacInstalled (implements IIdentityPermissionFactory)
        • System.Security.SecurityManager (GetStandardSandbox(Evidence) returns type PermissionSet; all other members were obsolete or return default(T))
        • System.Security.Policy.PolicyStatement (obsoleting the constructors -- they both require PermissionSet)
        • System.Security.Policy.PolicyLevel.AddNamedPermissionSet(NamedPermissionSet)
        • System.Security.Policy.PolicyLevel.ChangeNamedPermissionSet(string, PermissionSet)
        • System.Security.Policy.PolicyLevel.GetNamedPermissionSet(string) (returns type NamedPermissionSet)
        • System.Security.Policy.PolicyLevel.RemoveNamedPermissionSet(NamedPermissionSet) (returns type NamedPermissionSet)
        • System.Security.Policy.PolicyLevel.RemoveNamedPermissionSet(string) (returns type NamedPermissionSet)
        • System.Security.Policy.Publisher (implements IIdentityPermissionFactory)
        • System.Security.Policy.Site (implements IIdentityPermissionFactory)
        • System.Security.Policy.Url (implements IIdentityPermissionFactory)
        • System.Security.Policy.Zone (implements IIdentityPermissionFactory)
  4. The Constrained Execution Region (CER) feature is not supported.
    • DiagnosticId: SYSLIB0004
    • APIs:
      • System.Runtime.ConstrainedExecution.PrePrepareMethodAttribute
      • System.Runtime.ConstrainedExecution.ReliabilityContractAttribute
      • System.Runtime.ConstrainedExecution.Cer
      • System.Runtime.ConstrainedExecution.Consistency
      • System.Runtime.CompilerServices.RuntimeHelpers.ExecuteCodeWithGuaranteedCleanup
      • System.Runtime.CompilerServices.RuntimeHelpers.PrepareConstrainedRegions
      • System.Runtime.CompilerServices.RuntimeHelpers.PrepareConstrainedRegionsNoOP
      • System.Runtime.CompilerServices.RuntimeHelpers.PrepareContractedDelegate
      • System.Runtime.CompilerServices.RuntimeHelpers.ProbeForSufficientStack
  5. The Global Assembly Cache is not supported.
    • DiagnosticId: SYSLIB0005
    • APIs:
      • System.Reflection.Assembly.GlobalAssemblyCache
  6. Thread.Abort is not supported and throws PlatformNotSupportedException.
    • DiagnosticId: SYSLIB0006
    • APIs:
      • System.Threading.Thread.Abort()
      • System.Threading.Thread.Abort(Object)
  7. The default implementation of this cryptography algorithm is not supported.
    • DiagnosticId: SYSLIB0007
    • APIs:
      • System.Security.Cryptography.SymmetricAlgorithm.Create()
      • System.Security.Cryptography.AssymetricAlgorithm.Create()
      • System.Security.Cryptography.HMAC.Create()
      • System.Security.Cryptography.KeyedHashAlgorithm.Create()
  8. The CreatePdbGenerator API is not supported and throws PlatformNotSupportedException.
    • DiagnosticId: SYSLIB0008
    • APIs:
      • System.Runtime.CompilerServices.DebugInfoGenerator.CreatePdbGenerator
  9. The AuthenticationManager Authenticate and PreAuthenticate methods are not supported and throw PlatformNotSupportedException.
    • DiagnosticId: SYSLIB0009
    • APIs:
      • System.Net.AuthenticationManager.Authenticate
      • System.Net.AuthenticationManager.PreAuthenticate
  10. This Remoting API is not supported and throws PlatformNotSupportedException.
    • DiagnosticId: SYSLIB0010
    • APIs:
      • System.MarshalByRefObject.GetLifetimeService
      • System.MarshalByRefObject.InitializeLifetimeService

Other Considerations

Several other APIs were considered for obsoletion in .NET 5, but we chose to focus on groupings of APIs that categorically do not work in .NET 5. This strategy optimizes for projects migrating from .NET Framework while keeping the risk of negative disruption relatively low.

Some specific APIs had already been suggested for obsoletion. We reviewed those suggestions during this consideration as well. For example, SecureString was considered but we chose to omit it for now. We are aware of some notable usage of SecureString where marking it as obsolete would cause disruption, and we do not yet have a clear alternative approach to recommend.

Obsoleting the set of APIs above will still provide enough usage of the new obsoletion behavior that we can collect feedback from users and determine how aggressively we can obsolete more APIs in .NET 6.

We would also like to thank @Joe4evr for helping kickstart the conversation with #33360. That issue will remain open and we will continue consider the APIs noted there in future releases.

Warnings vs. Errors

The Obsolete attributes will be applied to classes, interfaces, and enums, in addition to being applied to specific members where appropriate. When applying Obsolete attributes to types, we do not support using the error level. This is due to how type forwarding is set up for our downlevel .NET Framework and .NET Standard compatibility, where type forwarding files would be referencing those types and build errors would be unavoidable.

When an error level is needed, a separate diagnostic ID must be used, and the attribute must be applied to type members. The PrincipalPermissionAttribute constructor is obsoleted as an error using SYSLIB0002, while the class itself is obsoleted as a warning using SYSLIB0003. This combination allows the interfaces the class implements to also be marked as Obsolete while also avoiding the type forwarding build errors.