Document the IStartupValidator obsoletion in .NET 11

docs/core/compatibility/core-libraries/11/obsolete-apis.md

@@ -2,7 +2,7 @@
 title: "Breaking change: .NET 11 obsoletions with custom IDs"
 titleSuffix: ""
 description: Learn about the APIs that have been marked as obsolete in .NET 11 with a custom diagnostic ID.
-ms.date: 07/06/2026
+ms.date: 10/14/2026
 ai-usage: ai-assisted
 ---
 # API obsoletions with non-default diagnostic IDs (.NET 11)
@@ -20,6 +20,7 @@ The following table lists the custom diagnostic IDs and their corresponding warn
 | Diagnostic ID                                                           | Description | Severity |
 |-------------------------------------------------------------------------|-------------|----------|
 | [SYSLIB0064](../../../../fundamentals/syslib-diagnostics/syslib0064.md) | <xref:System.Security.Cryptography.RSACryptoServiceProvider.Encrypt(System.Byte[],System.Boolean)?displayProperty=nameWithType> and <xref:System.Security.Cryptography.RSACryptoServiceProvider.Decrypt(System.Byte[],System.Boolean)?displayProperty=nameWithType> are obsolete. Use the overloads that accept an <xref:System.Security.Cryptography.RSAEncryptionPadding> instead. | Warning |
+| [SYSLIB0066](../../../../fundamentals/syslib-diagnostics/syslib0066.md) | <xref:Microsoft.Extensions.Options.IStartupValidator> is obsolete. Implement and register a custom <xref:Microsoft.Extensions.Options.IAsyncStartupValidator> instead; don't register the same implementation under both startup-validator interfaces. | Warning |
 
 ## Version introduced
 
@@ -42,6 +43,10 @@ These obsoletions can affect [source compatibility](../../categories.md#source-c
 - <xref:System.Security.Cryptography.RSACryptoServiceProvider.Encrypt(System.Byte[],System.Boolean)?displayProperty=fullName>
 - <xref:System.Security.Cryptography.RSACryptoServiceProvider.Decrypt(System.Byte[],System.Boolean)?displayProperty=fullName>
 
+### SYSLIB0066
+
+- <xref:Microsoft.Extensions.Options.IStartupValidator>
+
 ## See also
 
 - [Cryptography obsoletions (.NET 11)](../../cryptography/11/obsolete-apis.md)

docs/fundamentals/syslib-diagnostics/obsoletions-overview.md

@@ -90,6 +90,7 @@ The following table lists the `SYSLIB0XXX` obsoletions in .NET 5+.
 | [SYSLIB0063](syslib0063.md) | Warning | The <xref:System.IO.Pipes.NamedPipeClientStream> constructor that has an `isConnected` parameter is obsolete because the argument has no effect. Use the constructor that accepts `direction`, `isAsync`, and `safePipeHandle`. |
 | [SYSLIB0064](syslib0064.md) | Warning | <xref:System.Security.Cryptography.RSACryptoServiceProvider.Encrypt(System.Byte[],System.Boolean)?displayProperty=nameWithType> and <xref:System.Security.Cryptography.RSACryptoServiceProvider.Decrypt(System.Byte[],System.Boolean)?displayProperty=nameWithType> are obsolete. Use the overloads that accept an <xref:System.Security.Cryptography.RSAEncryptionPadding> instead. |
 | [SYSLIB0065](syslib0065.md) | Warning | The `set` accessor of <xref:System.Security.Cryptography.AsnEncodedData.RawData?displayProperty=nameWithType> is obsolete. Use the constructor of the appropriate type to decode data, or use <xref:System.Security.Cryptography.AsnEncodedData.CopyFrom(System.Security.Cryptography.AsnEncodedData)?displayProperty=nameWithType> for mutable scenarios. |
+| [SYSLIB0066](syslib0066.md) | Warning | <xref:Microsoft.Extensions.Options.IStartupValidator> is obsolete. Implement <xref:Microsoft.Extensions.Options.IAsyncStartupValidator> for new custom startup validators. |
 
 ## EXTOBS obsoletions
 

docs/fundamentals/syslib-diagnostics/syslib0066.md

@@ -0,0 +1,48 @@
+---
+title: SYSLIB0066 warning - IStartupValidator is obsolete
+description: Learn about the obsoletion of IStartupValidator. Use of this interface generates compile-time warning SYSLIB0066.
+ms.date: 10/13/2026
+ai-usage: ai-generated
+f1_keywords:
+  - SYSLIB0066
+---
+
+# SYSLIB0066: IStartupValidator is obsolete
+
+Starting in .NET 11, <xref:Microsoft.Extensions.Options.IStartupValidator> is obsolete. When you reference or implement this interface, the compiler generates warning `SYSLIB0066` with the message `Implement IAsyncStartupValidator instead.` The interface remains available and functional for compatibility.
+
+## Reason for obsoletion
+
+Host startup has an asynchronous entry point through <xref:Microsoft.Extensions.Hosting.IHost.StartAsync*>. New custom startup validators should use <xref:Microsoft.Extensions.Options.IAsyncStartupValidator>. Its asynchronous `ValidateAsync` contract means asynchronous implementations don't need to provide an unused synchronous `Validate` method. The two interfaces are independent.
+
+## Workaround
+
+To migrate a custom startup validator, implement and register <xref:Microsoft.Extensions.Options.IAsyncStartupValidator> instead. Use asynchronous operations in `ValidateAsync` when validation requires them, and forward the cancellation token. Register the implementation only under the startup-validation contract it provides; don't register it under both `IStartupValidator` and `IAsyncStartupValidator`.
+
+Applications that only call `OptionsBuilder<TOptions>.ValidateOnStart()` and don't directly implement a startup-validator interface normally don't need to change their code.
+
+## Suppress a warning
+
+If you must use the obsolete interface, you can suppress the warning in code or in your project file.
+
+To suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the warning.
+
+```csharp
+#pragma warning disable SYSLIB0066
+
+// Code that uses the obsolete interface.
+
+#pragma warning restore SYSLIB0066
+```
+
+To suppress all `SYSLIB0066` warnings in your project, add a `<NoWarn>` property to your project file.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <NoWarn>$(NoWarn);SYSLIB0066</NoWarn>
+  </PropertyGroup>
+</Project>
+```
+
+For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings).

docs/navigate/tools-diagnostics/toc.yml

@@ -4232,6 +4232,8 @@ items:
             href: ../../fundamentals/syslib-diagnostics/syslib0064.md
           - name: SYSLIB0065
             href: ../../fundamentals/syslib-diagnostics/syslib0065.md
+          - name: SYSLIB0066
+            href: ../../fundamentals/syslib-diagnostics/syslib0066.md
       - name: Experimental features
         items:
           - name: Overview