Use a dedicated attribute to mark implementation-only members

.github/copilot-instructions.md

@@ -555,7 +555,7 @@ The MSBuild integration is orchestrated through several `.props` and `.targets`
 - **Compiler strict mode**: `<Features>strict</Features>` in all projects
 - **XML documentation**: generated for all projects
 - **`SkipLocalsInit`**: enabled in runtime and build tools for performance
-- **Suppressed warnings**: `CS8500` (ref safety in unsafe contexts), `AD0001` (analyzer crashes), `CSWINRT3001` (obsolete internal members)
+- **Suppressed warnings**: `CS8500` (ref safety in unsafe contexts), `AD0001` (analyzer crashes)
 - **Strong-name signing**: all assemblies signed with `src/WinRT.Runtime2/key.snk`
 
 ### C++ project (cswinrt)
@@ -598,7 +598,6 @@ All four .NET build tools (`cswinrtimplgen`, `cswinrtprojectiongen`, `cswinrtint
 | Projection Generator | `CSWINRTPROJECTIONGENxxxx` | `0001`–`0008`, `9999` |
 | Interop Generator | `CSWINRTINTEROPGENxxxx` | Various, `9999` |
 | WinMD Generator | `CSWINRTWINMDGENxxxx` | `0001`–`0007` |
-| Runtime (obsolete markers) | `CSWINRT3xxx` | `CSWINRT3001` |
 
 ---
 

docs/interop.md

@@ -4,8 +4,6 @@
 
 CsWinRT 3.0 provides a complete COM interop layer for Windows Runtime types on .NET 10+. All interop types are in the `WindowsRuntime.InteropServices` namespace (assembly: `WinRT.Runtime.dll`). Most marshalling is handled automatically by the generated projection and interop assemblies, but advanced scenarios may require direct use of the APIs below.
 
-> **Note:** CsWinRT exposes many types and methods marked `[Obsolete]` with diagnostic `CSWINRT3001`. These are **private implementation details** consumed only by generated code (`cswinrt.exe` and `cswinrtinteropgen.exe`). They are not part of the versioned API surface, may change without notice, and should not be used in application code. This guide covers only the supported public APIs.
-
 ## Summary
 
 | Scenario | CsWinRT 3.0 API |

src/Authoring/WinRT.Host.Shim/Module.cs

@@ -11,8 +11,6 @@
 
 [assembly: global::System.Runtime.Versioning.SupportedOSPlatform("Windows")]
 
-#pragma warning disable CSWINRT3001 // Type or member is obsolete
-
 namespace WinRT.Host;
 
 public static class Shim

src/Tests/FunctionalTests/CCW/Program.cs

@@ -10,8 +10,6 @@
 using WindowsRuntime.InteropServices;
 using WindowsRuntime.InteropServices.Marshalling;
 
-#pragma warning disable CSWINRT3001 // Type or member is obsolete
-
 var managedProperties = new ManagedProperties(42);
 var instance = new Class();
 

src/Tests/FunctionalTests/Collections/Program.cs

@@ -80,7 +80,6 @@
     return 101;
 }
 
-#pragma warning disable CSWINRT3001 // Type or member is obsolete
 TestComponent.Nested[] nestedArr = new TestComponent.Nested[]{
                 new TestComponent.Nested(
                     new TestComponent.Blittable(1, 2, 3, 4, -5, -6, -7, 8.0f, 9.0, typeof(TestComponent.ITests).GUID),
@@ -92,7 +91,6 @@
                     new TestComponent.Blittable(1, 2, 3, 4, -5, -6, -7, 8.0f, 9.0, WellKnownInterfaceIIDs.IID_IInspectable),
                     new TestComponent.NonBlittable(false, 'Z', "Third", (long?)PropertyValue.CreateInt64(789)))
             };
-#pragma warning restore CSWINRT3001 // Type or member is obsolete
 TestComponent.Nested[] nestedArr2 = new TestComponent.Nested[nestedArr.Length];
 TestComponent.Nested[] outNestedArr;
 TestComponent.Nested[] retNestedArr = instance2.Array15(nestedArr, nestedArr2, out outNestedArr);

src/Tests/UnitTest/TestComponent_Tests.cs

@@ -599,10 +599,8 @@ public void Collections_Dictionary()
 
         class TestIDICInspectable : WindowsRuntimeObject
         {
-#pragma warning disable CSWINRT3001 // Type or member is obsolete
             public unsafe TestIDICInspectable(void* ptr)
                 : base(WindowsRuntimeComWrappersMarshal.CreateObjectReferenceUnsafe(ptr, WellKnownInterfaceIIDs.IID_IInspectable, out _))
-#pragma warning restore CSWINRT3001 // Type or member is obsolete
             {
             }
 

src/WinRT.Runtime2/ABI/System/Boolean.cs

@@ -2,7 +2,6 @@
 // Licensed under the MIT License.
 
 using System;
-using System.ComponentModel;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using Windows.Foundation;
@@ -43,10 +42,7 @@ namespace ABI.System;
 /// <summary>
 /// Marshaller for <see cref="bool"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class BooleanMarshaller
 {
     /// <inheritdoc cref="WindowsRuntimeValueTypeMarshaller.BoxToUnmanaged{T}(T?, CreateComInterfaceFlags, in Guid)"/>
@@ -288,4 +284,4 @@ private static HRESULT get_Type(void* thisPtr, PropertyType* value)
 
         return WellKnownErrorCodes.S_OK;
     }
-}
+}

src/WinRT.Runtime2/ABI/System/Byte.cs

@@ -2,7 +2,6 @@
 // Licensed under the MIT License.
 
 using System;
-using System.ComponentModel;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using Windows.Foundation;
@@ -43,10 +42,7 @@ namespace ABI.System;
 /// <summary>
 /// Marshaller for <see cref="byte"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class ByteMarshaller
 {
     /// <inheritdoc cref="WindowsRuntimeValueTypeMarshaller.BoxToUnmanaged{T}(T?, CreateComInterfaceFlags, in Guid)"/>
@@ -456,4 +452,4 @@ private static HRESULT GetDouble(void* thisPtr, double* value)
             return RestrictedErrorInfoExceptionMarshaller.ConvertToUnmanaged(e);
         }
     }
-}
+}

src/WinRT.Runtime2/ABI/System/Char.cs

@@ -2,7 +2,6 @@
 // Licensed under the MIT License.
 
 using System;
-using System.ComponentModel;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using Windows.Foundation;
@@ -43,10 +42,7 @@ namespace ABI.System;
 /// <summary>
 /// Marshaller for <see cref="char"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class CharMarshaller
 {
     /// <inheritdoc cref="WindowsRuntimeValueTypeMarshaller.BoxToUnmanaged{T}(T?, CreateComInterfaceFlags, in Guid)"/>
@@ -288,4 +284,4 @@ private static HRESULT get_Type(void* thisPtr, PropertyType* value)
 
         return WellKnownErrorCodes.S_OK;
     }
-}
+}

src/WinRT.Runtime2/ABI/System/Collections/IEnumerable.cs

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections;
-using System.ComponentModel;
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
@@ -23,10 +22,7 @@ namespace ABI.System.Collections;
 /// <summary>
 /// Marshaller for <see cref="IEnumerable"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class IEnumerableMarshaller
 {
     /// <inheritdoc cref="WindowsRuntimeObjectMarshaller.ConvertToUnmanaged"/>
@@ -87,10 +83,7 @@ public static unsafe object CreateObject(void* value, out CreatedWrapperFlags wr
 /// <summary>
 /// A custom <see cref="WindowsRuntimeComWrappersMarshallerAttribute"/> implementation for <see cref="IEnumerable"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public sealed unsafe class IEnumerableComWrappersMarshallerAttribute : WindowsRuntimeComWrappersMarshallerAttribute
 {
     /// <inheritdoc/>
@@ -108,10 +101,7 @@ public override object CreateObject(void* value, out CreatedWrapperFlags wrapper
 /// <summary>
 /// Interop methods for <see cref="IEnumerable"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static class IEnumerableMethods
 {
     /// <inheritdoc cref="IEnumerable.GetEnumerator"/>
@@ -124,10 +114,7 @@ public static IEnumerator GetEnumerator(WindowsRuntimeObjectReference thisRefere
 /// <summary>
 /// The <see cref="IEnumerable"/> implementation.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class IEnumerableImpl
 {
     /// <summary>

src/WinRT.Runtime2/ABI/System/Collections/IEnumerator.cs

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections;
-using System.ComponentModel;
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
@@ -23,10 +22,7 @@ namespace ABI.System.Collections;
 /// <summary>
 /// Marshaller for <see cref="IEnumerator"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class IEnumeratorMarshaller
 {
     /// <inheritdoc cref="WindowsRuntimeObjectMarshaller.ConvertToUnmanaged"/>
@@ -87,10 +83,7 @@ public static unsafe object CreateObject(void* value, out CreatedWrapperFlags wr
 /// <summary>
 /// A custom <see cref="WindowsRuntimeComWrappersMarshallerAttribute"/> implementation for <see cref="IEnumerator"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public sealed unsafe class IEnumeratorComWrappersMarshallerAttribute : WindowsRuntimeComWrappersMarshallerAttribute
 {
     /// <inheritdoc/>
@@ -108,10 +101,7 @@ public override object CreateObject(void* value, out CreatedWrapperFlags wrapper
 /// <summary>
 /// Interop methods for <see cref="IEnumerator"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static class IEnumeratorMethods
 {
     /// <inheritdoc cref="IEnumerator.Current"/>
@@ -131,10 +121,7 @@ public static bool MoveNext(WindowsRuntimeObjectReference thisReference)
 /// <summary>
 /// The <see cref="IEnumerator"/> implementation.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class IEnumeratorImpl
 {
     /// <summary>
@@ -275,4 +262,4 @@ void IEnumerator.Reset()
     {
         throw new NotSupportedException();
     }
-}
+}

src/WinRT.Runtime2/ABI/System/Collections/IList.cs

@@ -3,7 +3,6 @@
 
 using System;
 using System.Collections;
-using System.ComponentModel;
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
@@ -27,10 +26,7 @@ namespace ABI.System.Collections;
 /// <summary>
 /// Marshaller for <see cref="IList"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class IListMarshaller
 {
     /// <inheritdoc cref="WindowsRuntimeObjectMarshaller.ConvertToUnmanaged"/>
@@ -91,10 +87,7 @@ public static unsafe object CreateObject(void* value, out CreatedWrapperFlags wr
 /// <summary>
 /// A custom <see cref="WindowsRuntimeComWrappersMarshallerAttribute"/> implementation for <see cref="IList"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public sealed unsafe class IListComWrappersMarshallerAttribute : WindowsRuntimeComWrappersMarshallerAttribute
 {
     /// <inheritdoc/>
@@ -112,10 +105,7 @@ public override object CreateObject(void* value, out CreatedWrapperFlags wrapper
 /// <summary>
 /// Interop methods for <see cref="IList"/>.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static class IListMethods
 {
     /// <inheritdoc cref="ICollection.Count"/>
@@ -188,10 +178,7 @@ public static void Clear(WindowsRuntimeObjectReference thisReference)
 /// <summary>
 /// The <see cref="IList"/> implementation.
 /// </summary>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public static unsafe class IListImpl
 {
     /// <summary>
@@ -551,4 +538,4 @@ void ICollection.CopyTo(Array array, int index)
 
         BindableIListMethods.CopyTo(thisReference, array, index);
     }
-}
+}

src/WinRT.Runtime2/ABI/System/Collections/IReadOnlyList.cs

@@ -1,8 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using System;
-using System.ComponentModel;
 using System.Runtime.InteropServices;
 using WindowsRuntime;
 using WindowsRuntime.InteropServices;
@@ -22,10 +20,7 @@ namespace ABI.System.Collections;
 /// type will be generated at compile time, as its runtime class name will depend on the XAML configuration being used.
 /// </para>
 /// </remarks>
-[Obsolete(WindowsRuntimeConstants.PrivateImplementationDetailObsoleteMessage,
-    DiagnosticId = WindowsRuntimeConstants.PrivateImplementationDetailObsoleteDiagnosticId,
-    UrlFormat = WindowsRuntimeConstants.CsWinRTDiagnosticsUrlFormat)]
-[EditorBrowsable(EditorBrowsableState.Never)]
+[WindowsRuntimeImplementationOnlyMember]
 public sealed unsafe class IReadOnlyListComWrappersMarshallerAttribute : WindowsRuntimeComWrappersMarshallerAttribute
 {
     /// <inheritdoc/>
@@ -38,4 +33,4 @@ public override object CreateObject(void* value, out CreatedWrapperFlags wrapper
 
         return new WindowsRuntimeReadOnlyList(valueReference);
     }
-}
+}