Changes to nullable reference type annotations

In .NET 6, some nullability annotations in the .NET libraries have changed.

Change description

In previous .NET versions, some nullable reference type annotations are incorrect, and build warnings are either absent or incorrect. Starting in .NET 6, some annotations that were previously applied have been updated. New build warnings will be produced and incorrect build warnings will no longer be produced for the affected APIs.

Some of these changes are considered to be breaking because they can lead to new build-time warnings. When you migrate to .NET 6, code that references these APIs will need to be updated.

Other changes that aren't considered to be breaking are also documented on this page. Any code that references the updated APIs may benefit from removing operators or pragmas that are no longer necessary.

Version introduced

6.0

Type of breaking change

This change can affect source compatibility.

Reason for change

Starting in .NET Core 3.0, nullability annotations were applied to the .NET libraries. From the outset of the effort, mistakes in these annotations were anticipated. Through feedback and further testing, the nullable annotations for the affected APIs were determined to be inaccurate. The updated annotations correctly represent the nullability contracts for the APIs.

Update code that calls these APIs to reflect the revised nullability contracts.

Affected APIs

The following table lists the affected APIs:

API What changed Breaking or nonbreaking
System.ComponentModel.DataAnnotations.AssociatedMetadataTypeTypeDescriptionProvider.GetTypeDescriptor(Type, Object) instance parameter type is nullable Nonbreaking
System.ComponentModel.ISite.Container Property type is nullable Breaking
System.Xml.Linq.XContainer.Add(Object[]) Parameter type is nullable Nonbreaking
System.Xml.Linq.XContainer.AddFirst(Object[]) Parameter type is nullable Nonbreaking
System.Xml.Linq.XContainer.ReplaceNodes(Object[]) Parameter type is nullable Nonbreaking
XDocument(Object[]) Parameter type is nullable Nonbreaking
XDocument(XDeclaration, Object[]) Parameter type is nullable Nonbreaking
XElement(XName, Object[]) Second parameter type is nullable Nonbreaking
System.Xml.Linq.XElement.ReplaceAll(Object[]) Parameter type is nullable Nonbreaking
System.Xml.Linq.XElement.ReplaceAttributes(Object[]) Parameter type is nullable Nonbreaking
System.Xml.Linq.XNode.AddAfterSelf(Object[]) Parameter type is nullable Nonbreaking
System.Xml.Linq.XNode.AddBeforeSelf(Object[]) Parameter type is nullable Nonbreaking
System.Xml.Linq.XNode.ReplaceWith(Object[]) Parameter type is nullable Nonbreaking
XStreamingElement(XName, Object) Second parameter type is nullable Nonbreaking
XStreamingElement(XName, Object[]) Second parameter type is nullable Nonbreaking
System.Xml.Linq.XStreamingElement.Add(Object[]) Parameter type is nullable Nonbreaking
System.Xml.XmlDocument.XmlResolver The setter accepts a nullable reference Breaking
System.Net.Http.HttpClient.PatchAsync content parameter type is nullable Nonbreaking
System.Net.Http.HttpClient.PostAsync content parameter type is nullable Nonbreaking
System.Net.Http.HttpClient.PutAsync content parameter type is nullable Nonbreaking
System.Linq.Expressions.MethodCallExpression.Update(Expression, IEnumerable<Expression>) First parameter type is nullable Nonbreaking
System.Linq.Expressions.Expression<TDelegate>.Update(Expression, IEnumerable<ParameterExpression>) Return type is not nullable Nonbreaking
System.Data.IDataRecord.GetBytes(Int32, Int64, Byte[], Int32, Int32) buffer parameter type is nullable Breaking
System.Data.IDataRecord.GetChars(Int32, Int64, Char[], Int32, Int32) buffer parameter type is nullable Breaking
System.Data.Common.DbDataRecord.GetBytes(Int32, Int64, Byte[], Int32, Int32) buffer parameter type is nullable Breaking
System.Data.Common.DbDataRecord.GetChars(Int32, Int64, Char[], Int32, Int32) buffer parameter type is nullable Breaking
System.Net.HttpListenerContext.AcceptWebSocketAsync subProtocol parameter type is nullable Nonbreaking
Methods that override System.Object.Equals(Object) and many others that return bool [NotNullWhen(true)] added to first nullable parameter Breaking
System.Collections.Immutable.ImmutableArray<T>.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Collections.Specialized.BitVector32.Equals(Object) NotNullWhen(true) was added to the o parameter Breaking
System.Collections.Specialized.BitVector32.Section.Equals(Object) NotNullWhen(true) was added to the o parameter Breaking
System.Reflection.Metadata.BlobContentId.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.BlobHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.CustomDebugInformationHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.DocumentNameBlobHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.EntityHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.GuidHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.Handle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.ImportScopeHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.LocalConstantHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.NamespaceDefinitionHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.SequencePoint.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.SignatureHeader.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.Ecma335.EditAndContinueLogEntry.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Metadata.Ecma335.LabelHandle.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Emit.Label.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.Reflection.Emit.OpCode.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking
System.DateOnly.Equals(Object) NotNullWhen(true) was added to the value parameter Breaking
System.TimeOnly.Equals(Object) NotNullWhen(true) was added to the value parameter Breaking
System.Reflection.Pointer.Equals(Object) NotNullWhen(true) was added to the obj parameter Breaking

See also