list-of-diagnostics.md

List of Diagnostics Produced by .NET Libraries APIs

Obsoletions

Per https://github.com/dotnet/designs/blob/master/accepted/2020/better-obsoletion/better-obsoletion.md, we now have a strategy for marking existing APIs as [Obsolete]. This takes advantage of the new diagnostic id and URL template mechanisms introduced to ObsoleteAttribute in .NET 5.

The diagnostic id values reserved for obsoletions are SYSLIB0001 through SYSLIB0999. When obsoleting an API, claim the next three-digit identifier in the SYSLIB0### sequence and add it to the list below. The URL template for all obsoletions is https://aka.ms/dotnet-warnings/{0}. The {0} placeholder is replaced by the compiler with the SYSLIB0### identifier.

The acceptance criteria for adding an obsoletion includes:

• Add the obsoletion to the table below, claiming the next diagnostic id
  • Ensure the description is meaningful within the context of this table, and without requiring the context of the calling code
• Add new constants to src\libraries\Common\src\System\Obsoletions.cs, following the existing conventions
  • A ...Message const using the same description added to the table below
  • A ...DiagId const for the SYSLIB0### id
• Annotate src files by referring to the constants defined from Obsoletions.cs
  • Specify the UrlFormat = Obsoletions.SharedUrlFormat
  • Example: [Obsolete(Obsoletions.CodeAccessSecurityMessage, DiagnosticId = Obsoletions.CodeAccessSecurityDiagId, UrlFormat = Obsoletions.SharedUrlFormat)]
  • If the Obsoletions type is not available in the project, link it into the project
    • <Compile Include="$(CommonPath)System\Obsoletions.cs" Link="Common\System\Obsoletions.cs" />
• Annotate ref files using the hard-coded strings copied from Obsoletions.cs
  • This matches our general pattern of ref files using hard-coded attribute strings
  • Example: [System.ObsoleteAttribute("The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.", DiagnosticId = "SYSLIB0001", UrlFormat = "https://aka.ms/dotnet-warnings/{0}")]
• If the library builds against downlevel targets earlier than .NET 5.0, then add an internal copy of ObsoleteAttribute
  • The compiler recognizes internal implementations of ObsoleteAttribute to enable the DiagnosticId and UrlFormat properties to light up downlevel
  • An MSBuild property can be added to the project's first <PropertyGroup> to achieve this easily
  • Example: <IncludeInternalObsoleteAttribute>true</IncludeInternalObsoleteAttribute>
  • This will need to be specified in both the src and ref projects
• If the library contains types that are forwarded within a generated shim
  • Errors will be received when running build libs, with obsoletion errors in src/libraries/shims/generated files
  • This is resolved by adding the obsoletion's diagnostic id to the <NoWarn> property for partial facade assemblies
  • That property is found in src/libraries/Directory.Build.targets
  • Search for the "Ignore Obsolete errors within the generated shims that type-forward types" comment and add the appropriate diagnostic id to the comment and the <NoWarn> property (other SYSLIB diagnostics already exist there)
• Apply the breaking-change label to the PR that introduces the obsoletion
  • A bot will automatically apply the needs-breaking-change-doc-created label when the breaking-change label is detected
• Follow up with the breaking change process to communicate and document the breaking change
  • In the breaking-change issue filed in dotnet/docs, specifically mention that this breaking change is an obsoletion with a SYSLIB diagnostic id
  • The documentation team will produce a PR that adds the obsoletion to the SYSLIB warnings page
  • That PR will also add a new URL specific to this diagnostic ID; e.g. SYSLIB0001
  • Connect with @gewarren or @BillWagner with any questions
• Register the SYSLIB0### URL in aka.ms
  • The vanity name will be dotnet-warnings/syslib0###
  • Ensure the link's group owner matches the group owner of dotnet-warnings/syslib0001
  • Connect with @jeffhandley, @GrabYourPitchforks, or @gewarren with any questions

An example obsoletion PR that can be referenced where each of the above criteria was met is:

• Implement new GetContextAPI overloads (#49186)

The PR that reveals the implementation of the <IncludeInternalObsoleteAttribute> property was:

• Mark DirectoryServices CAS APIs as Obsolete (#40756)

Obsoletion Diagnostics (SYSLIB0001 - SYSLIB0999)

Diagnostic ID	Description
SYSLIB0001	The UTF-7 encoding is insecure and should not be used. Consider using UTF-8 instead.
SYSLIB0002	PrincipalPermissionAttribute is not honored by the runtime and must not be used.
SYSLIB0003	Code Access Security is not supported or honored by the runtime.
SYSLIB0004	The Constrained Execution Region (CER) feature is not supported.
SYSLIB0005	The Global Assembly Cache is not supported.
SYSLIB0006	Thread.Abort is not supported and throws PlatformNotSupportedException.
SYSLIB0007	The default implementation of this cryptography algorithm is not supported.
SYSLIB0008	The CreatePdbGenerator API is not supported and throws PlatformNotSupportedException.
SYSLIB0009	The AuthenticationManager Authenticate and PreAuthenticate methods are not supported and throw PlatformNotSupportedException.
SYSLIB0010	This Remoting API is not supported and throws PlatformNotSupportedException.
SYSLIB0011	BinaryFormatter serialization is obsolete and should not be used. See https://aka.ms/binaryformatter for recommended alternatives.
SYSLIB0012	Assembly.CodeBase and Assembly.EscapedCodeBase are only included for .NET Framework compatibility. Use Assembly.Location instead.
SYSLIB0013	Uri.EscapeUriString can corrupt the Uri string in some cases. Consider using Uri.EscapeDataString for query string components instead.
SYSLIB0014	WebRequest, HttpWebRequest, ServicePoint, and WebClient are obsolete. Use HttpClient instead.
SYSLIB0015	DisablePrivateReflectionAttribute has no effect in .NET 6.0+.
SYSLIB0016	Use the Graphics.GetContextInfo overloads that accept arguments for better performance and fewer allocations.
SYSLIB0017	Strong name signing is not supported and throws PlatformNotSupportedException.
SYSLIB0018	ReflectionOnly loading is not supported and throws PlatformNotSupportedException.
SYSLIB0019	RuntimeEnvironment members SystemConfigurationFile, GetRuntimeInterfaceAsIntPtr, and GetRuntimeInterfaceAsObject are not supported and throw PlatformNotSupportedException.
SYSLIB0020	JsonSerializerOptions.IgnoreNullValues is obsolete. To ignore null values when serializing, set DefaultIgnoreCondition to JsonIgnoreCondition.WhenWritingNull.
SYSLIB0021	Derived cryptographic types are obsolete. Use the Create method on the base type instead.
SYSLIB0022	The Rijndael and RijndaelManaged types are obsolete. Use Aes instead.
SYSLIB0023	RNGCryptoServiceProvider is obsolete. To generate a random number, use one of the RandomNumberGenerator static methods instead.
SYSLIB0024	Creating and unloading AppDomains is not supported and throws an exception.
SYSLIB0025	SuppressIldasmAttribute has no effect in .NET 6.0+.
SYSLIB0026	X509Certificate and X509Certificate2 are immutable. Use the appropriate constructor to create a new certificate.
SYSLIB0027	PublicKey.Key is obsolete. Use the appropriate method to get the public key, such as GetRSAPublicKey.
SYSLIB0028	X509Certificate2.PrivateKey is obsolete. Use the appropriate method to get the private key, such as GetRSAPrivateKey, or use the CopyWithPrivateKey method to create a new instance with a private key.
SYSLIB0029	ProduceLegacyHmacValues is obsolete. Producing legacy HMAC values is not supported.
SYSLIB0030	HMACSHA1 always uses the algorithm implementation provided by the platform. Use a constructor without the useManagedSha1 parameter.
SYSLIB0031	EncodeOID is obsolete. Use the ASN.1 functionality provided in System.Formats.Asn1.
SYSLIB0032	Recovery from corrupted process state exceptions is not supported; HandleProcessCorruptedStateExceptionsAttribute is ignored.
SYSLIB0033	Rfc2898DeriveBytes.CryptDeriveKey is obsolete and is not supported. Use PasswordDeriveBytes.CryptDeriveKey instead.
SYSLIB0034	CmsSigner(CspParameters) is obsolete and is not supported. Use an alternative constructor instead.
SYSLIB0035	ComputeCounterSignature without specifying a CmsSigner is obsolete and is not supported. Use the overload that accepts a CmsSigner.

Analyzer Warnings

The diagnostic id values reserved for .NET Libraries analyzer warnings are SYSLIB1001 through SYSLIB1999. When creating a new analyzer that ships as part of the Libraries (and not part of the SDK), claim the next three-digit identifier in the SYSLIB1### sequence and add it to the list below.

Analyzer Diagnostics (SYSLIB1001 - SYSLIB1999)

Diagnostic ID	Description
SYSLIB1001	Logging method names cannot start with _
SYSLIB1002	Don't include log level parameters as templates in the logging message
SYSLIB1003	InvalidLoggingMethodParameterNameTitle
SYSLIB1004	Logging class cannot be in nested types
SYSLIB1005	Could not find a required type definition
SYSLIB1006	Multiple logging methods cannot use the same event id within a class
SYSLIB1007	Logging methods must return void
SYSLIB1008	One of the arguments to a logging method must implement the Microsoft.Extensions.Logging.ILogger interface
SYSLIB1009	Logging methods must be static
SYSLIB1010	Logging methods must be partial
SYSLIB1011	Logging methods cannot be generic
SYSLIB1012	Redundant qualifier in logging message
SYSLIB1013	Don't include exception parameters as templates in the logging message
SYSLIB1014	Logging template has no corresponding method argument
SYSLIB1015	Argument is not referenced from the logging message
SYSLIB1016	Logging methods cannot have a body
SYSLIB1017	A LogLevel value must be supplied in the LoggerMessage attribute or as a parameter to the logging method
SYSLIB1018	Don't include logger parameters as templates in the logging message
SYSLIB1019	Couldn't find a field of type Microsoft.Extensions.Logging.ILogger
SYSLIB1020	Found multiple fields of type Microsoft.Extensions.Logging.ILogger
SYSLIB1021	Can't have the same template with different casing
SYSLIB1022	Can't have malformed format strings (like dangling {, etc)
SYSLIB1023	Generating more than 6 arguments is not supported
SYSLIB1024	SYSLIB1024-SYSLIB1029 reserved for logging.
SYSLIB1025	SYSLIB1024-SYSLIB1029 reserved for logging.
SYSLIB1026	SYSLIB1024-SYSLIB1029 reserved for logging.
SYSLIB1027	SYSLIB1024-SYSLIB1029 reserved for logging.
SYSLIB1028	SYSLIB1024-SYSLIB1029 reserved for logging.
SYSLIB1029	SYSLIB1024-SYSLIB1029 reserved for logging.
SYSLIB1030	[System.Text.Json.SourceGeneration] Did not generate serialization metadata for type.
SYSLIB1031	[System.Text.Json.SourceGeneration] Duplicate type name.
SYSLIB1032	SYSLIB1032-SYSLIB1039 reserved for System.Text.Json.SourceGeneration.
SYSLIB1033	SYSLIB1032-SYSLIB1039 reserved for System.Text.Json.SourceGeneration.
SYSLIB1034	SYSLIB1032-SYSLIB1039 reserved for System.Text.Json.SourceGeneration.
SYSLIB1035	SYSLIB1032-SYSLIB1039 reserved for System.Text.Json.SourceGeneration.
SYSLIB1036	SYSLIB1032-SYSLIB1039 reserved for System.Text.Json.SourceGeneration.
SYSLIB1037	SYSLIB1032-SYSLIB1039 reserved for System.Text.Json.SourceGeneration.
SYSLIB1038	SYSLIB1032-SYSLIB1039 reserved for System.Text.Json.SourceGeneration.
SYSLIB1039	SYSLIB1032-SYSLIB1039 reserved for System.Text.Json.SourceGeneration.