Use ExperimentalAttribute instead of Obsolete (#1573)

Directory.Build.props

@@ -20,7 +20,7 @@
   </PropertyGroup>
 
   <PropertyGroup>
-    <!-- Experimental APIs currently use obsolete messages -->
+    <!-- We want to use experimental APIs internally -->
     <NoWarn>$(NoWarn);CS0436;OOXML0001</NoWarn>
   </PropertyGroup>
 

src/DocumentFormat.OpenXml.Framework/Packaging/IPackage.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.IO.Packaging;
 
@@ -11,7 +12,7 @@ namespace DocumentFormat.OpenXml.Packaging;
 /// <summary>
 /// An abstraction similar to <see cref="System.IO.Packaging.Package"/> that allows for pass through implementations
 /// </summary>
-[Obsolete(ExperimentalApis.PackageApis.Message, DiagnosticId = ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
+[Experimental(ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
 public interface IPackage
 {
     /// <summary>

src/DocumentFormat.OpenXml.Framework/Packaging/IPackagePart.cs

@@ -2,14 +2,15 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 
 namespace DocumentFormat.OpenXml.Packaging;
 
 /// <summary>
 /// An abstraction for <see cref="System.IO.Packaging.PackagePart"/> that is easier to override.
 /// </summary>
-[Obsolete(ExperimentalApis.PackageApis.Message, DiagnosticId = ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
+[Experimental(ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
 public interface IPackagePart
 {
     /// <summary>

src/DocumentFormat.OpenXml.Framework/Packaging/IPackageProperties.cs

@@ -2,13 +2,14 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System;
+using System.Diagnostics.CodeAnalysis;
 
 namespace DocumentFormat.OpenXml.Packaging;
 
 /// <summary>
 /// An abstraction of package properties, similar to <see cref="System.IO.Packaging.PackageProperties"/>.
 /// </summary>
-[Obsolete(ExperimentalApis.PackageApis.Message, DiagnosticId = ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
+[Experimental(ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
 public interface IPackageProperties
 {
     /// <summary>

src/DocumentFormat.OpenXml.Framework/Packaging/IPackageRelationship.cs

@@ -2,14 +2,15 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System;
+using System.Diagnostics.CodeAnalysis;
 using System.IO.Packaging;
 
 namespace DocumentFormat.OpenXml.Packaging;
 
 /// <summary>
 /// An interface that defines the relationship between a source and a target part. Similar to <see cref="PackageRelationship"/> but allows full overriding.
 /// </summary>
-[Obsolete(ExperimentalApis.PackageApis.Message, DiagnosticId = ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
+[Experimental(ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
 public interface IPackageRelationship
 {
     /// <summary>

src/DocumentFormat.OpenXml.Framework/Packaging/IRelationshipCollection.cs

@@ -3,14 +3,15 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.IO.Packaging;
 
 namespace DocumentFormat.OpenXml.Packaging;
 
 /// <summary>
 /// A collection of relationships for a <see cref="IPackage"/> of <see cref="IPackagePart"/>.
 /// </summary>
-[Obsolete(ExperimentalApis.PackageApis.Message, DiagnosticId = ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
+[Experimental(ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
 public interface IRelationshipCollection : IEnumerable<IPackageRelationship>
 {
     /// <summary>

src/DocumentFormat.OpenXml.Framework/Packaging/PackageExtensions.cs

@@ -4,13 +4,14 @@
 using DocumentFormat.OpenXml.Features;
 using DocumentFormat.OpenXml.Packaging;
 using System;
+using System.Diagnostics.CodeAnalysis;
 
 namespace DocumentFormat.OpenXml.Experimental;
 
 /// <summary>
 /// Extensions to retrieve package details.
 /// </summary>
-[Obsolete(ExperimentalApis.PackageApis.Message, DiagnosticId = ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
+[Experimental(ExperimentalApis.PackageApis.DiagnosticId, UrlFormat = ExperimentalApis.UrlFormat)]
 public static class PackageExtensions
 {
     /// <summary>

src/common/FrameworkShims.targets

@@ -8,6 +8,7 @@
     <ShimFile Include="$(MSBuildThisFileDirectory)System\IO\StreamReadExtensions.cs" />
     <ShimFile Include="$(MSBuildThisFileDirectory)System\EnumExtensions.cs" />
     <ShimFile Include="$(MSBuildThisFileDirectory)System\ObsoleteAttribute.cs" />
+    <ShimFile Include="$(MSBuildThisFileDirectory)System\Diagnostics\CodeAnalysis\ExperimentalAttribute.cs" />
   </ItemGroup>
 
   <ItemGroup Condition=" '$(TargetFramework)' == 'net35' ">

src/common/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs

@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// Copied from https://github.com/dotnet/runtime/blob/4001e074ee648506d64277729a7cce089a4996e2/src/libraries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/ExperimentalAttribute.cs
+// to enable downlevel usage.
+#if !NET8_0_OR_GREATER
+namespace System.Diagnostics.CodeAnalysis;
+
+/// <summary>
+///  Indicates that an API is experimental and it may change in the future.
+/// </summary>
+/// <remarks>
+///   This attribute allows call sites to be flagged with a diagnostic that indicates that an experimental
+///   feature is used. Authors can use this attribute to ship preview features in their assemblies.
+/// </remarks>
+[AttributeUsage(
+    AttributeTargets.Assembly |
+    AttributeTargets.Module |
+    AttributeTargets.Class |
+    AttributeTargets.Struct |
+    AttributeTargets.Enum |
+    AttributeTargets.Constructor |
+    AttributeTargets.Method |
+    AttributeTargets.Property |
+    AttributeTargets.Field |
+    AttributeTargets.Event |
+    AttributeTargets.Interface |
+    AttributeTargets.Delegate, Inherited = false)]
+internal sealed class ExperimentalAttribute : Attribute
+{
+    /// <summary>
+    ///  Initializes a new instance of the <see cref="ExperimentalAttribute"/> class, specifying the ID that the compiler will use
+    ///  when reporting a use of the API the attribute applies to.
+    /// </summary>
+    /// <param name="diagnosticId">The ID that the compiler will use when reporting a use of the API the attribute applies to.</param>
+    public ExperimentalAttribute(string diagnosticId)
+    {
+        DiagnosticId = diagnosticId;
+    }
+
+    /// <summary>
+    ///  Gets the ID that the compiler will use when reporting a use of the API the attribute applies to.
+    /// </summary>
+    /// <value>The unique diagnostic ID.</value>
+    /// <remarks>
+    ///  The diagnostic ID is shown in build output for warnings and errors.
+    ///  <para>This property represents the unique ID that can be used to suppress the warnings or errors, if needed.</para>
+    /// </remarks>
+    public string DiagnosticId { get; }
+
+    /// <summary>
+    ///  Gets or sets the URL for corresponding documentation.
+    ///  The API accepts a format string instead of an actual URL, creating a generic URL that includes the diagnostic ID.
+    /// </summary>
+    /// <value>The format string that represents a URL to corresponding documentation.</value>
+    /// <remarks>An example format string is <c>https://contoso.com/obsoletion-warnings/{0}</c>.</remarks>
+    public string? UrlFormat { get; set; }
+}
+#endif