car ReadAsync

Author: mikeebowen

Directory.Build.props

@@ -70,7 +70,7 @@
         <LatestTargetFramework>net8.0</LatestTargetFramework>
         <SamplesFrameworks>net8.0</SamplesFrameworks>
         <SamplesFrameworks Condition=" '$(OS)' == 'Windows_NT' ">$(SamplesFrameworks);net472</SamplesFrameworks>
-        <DefineConstants Condition=" '$(TargetFramework)' != 'net35' And '$(TargetFramework)' != 'net40' And '$(TargetFramework)' != 'net46' And '$(TargetFramework)' != 'net472' ">$(DefineConstants);FEATURE_ASYNC_SAX_XML</DefineConstants>
+        <DefineConstants Condition=" '$(TargetFramework)' != 'net35' And '$(TargetFramework)' != 'net40' And '$(TargetFramework)' != 'net46' And '$(TargetFramework)' != 'net472' ">$(DefineConstants);TASKS_SUPPORTED</DefineConstants>
       </PropertyGroup>
     </Otherwise>
   </Choose>

src/DocumentFormat.OpenXml.Framework/OpenXmlPartReader.cs

@@ -10,6 +10,9 @@
 using System.Diagnostics;
 using System.IO;
 using System.Linq;
+#if TASKS_SUPPORTED
+using System.Threading.Tasks;
+#endif
 using System.Xml;
 
 namespace DocumentFormat.OpenXml
@@ -100,7 +103,7 @@ public OpenXmlPartReader(Stream partStream, IFeatureCollection features, OpenXml
 
             _resolver = features.GetRequired<IOpenXmlNamespaceResolver>();
             _rootElements = features.GetRequired<IRootElementFeature>();
-            _xmlReader = CreateReader(partStream, options.CloseStream, options.MaxCharactersInPart, ignoreWhitespace: options.IgnoreWhitespace, out _standalone, out _encoding);
+            _xmlReader = CreateReader(partStream, options, out _standalone, out _encoding);
         }
 
         /// <summary>
@@ -394,6 +397,17 @@ public override void Skip()
         /// <inheritdoc/>
         public override IXmlLineInfo GetLineInfo() => XmlLineInfo.Get(_xmlReader);
 
+        #region Async methods
+#if TASKS_SUPPORTED
+        public override Task<bool> ReadAsync()
+        {
+            ThrowIfObjectDisposed();
+
+
+            return _xmlReader.ReadAsync();
+        }
+#endif
+        #endregion
         #region private methods
 
         /// <summary>
@@ -667,17 +681,20 @@ public override void Close()
             _xmlReader.Close();
         }
 
-        private XmlReader CreateReader(Stream partStream, bool closeInput, long maxCharactersInPart, bool ignoreWhitespace, out bool? standalone, out string? encoding)
+        private XmlReader CreateReader(Stream partStream, OpenXmlPartReaderOptions options, out bool? standalone, out string? encoding)
         {
             var settings = new XmlReaderSettings
             {
-                MaxCharactersInDocument = maxCharactersInPart,
-                CloseInput = closeInput,
-                IgnoreWhitespace = ignoreWhitespace,
+                MaxCharactersInDocument = options.MaxCharactersInPart,
+                CloseInput = options.CloseStream,
+                IgnoreWhitespace = options.IgnoreWhitespace,
 #if NET35
                 ProhibitDtd = true,
 #else
                 DtdProcessing = DtdProcessing.Prohibit,
+#endif
+#if TASKS_SUPPORTED
+                Async = options.Async,
 #endif
             };
 

src/DocumentFormat.OpenXml.Framework/OpenXmlPartReaderOptions.cs

@@ -31,11 +31,26 @@ public struct OpenXmlPartReaderOptions
     /// </summary>
     public bool CloseStream { get; set; }
 
+#if TASKS_SUPPORTED
+    /// <summary>
+    /// Gets or sets a value indicating whether the part reader should operate asynchronously.
+    /// </summary>
+    /// <remarks>
+    /// When set to <c>true</c>, the reader will use asynchronous methods for reading XML data,
+    /// allowing non-blocking operations. This property is only available when the build target
+    /// supports asynchronous SAX XML processing.
+    /// </remarks>
+    public bool Async { get; set; }
+#endif
+
     internal OpenXmlPartReaderOptions UpdateForPart(OpenXmlPart part) => new()
     {
         ReadMiscellaneousNodes = ReadMiscellaneousNodes,
         MaxCharactersInPart = MaxCharactersInPart != 0 ? MaxCharactersInPart : part.MaxCharactersInPart,
         IgnoreWhitespace = IgnoreWhitespace,
         CloseStream = true,
+#if TASKS_SUPPORTED
+        Async = Async,
+#endif
     };
 }

src/DocumentFormat.OpenXml.Framework/OpenXmlPartWriter.cs

@@ -6,7 +6,7 @@
 using System.Collections.Generic;
 using System.IO;
 using System.Text;
-#if FEATURE_ASYNC_SAX_XML
+#if TASKS_SUPPORTED
 using DocumentFormat.OpenXml.Framework;
 using System.Threading.Tasks;
 #endif
@@ -82,7 +82,7 @@ public OpenXmlPartWriter(OpenXmlPart openXmlPart, OpenXmlPartWriterSettings sett
             {
                 CloseOutput = true,
                 Encoding = settings.Encoding,
-#if FEATURE_ASYNC_SAX_XML
+#if TASKS_SUPPORTED
                 Async = settings.Async,
 #endif
             };
@@ -146,7 +146,7 @@ public OpenXmlPartWriter(Stream partStream, OpenXmlPartWriterSettings settings)
             {
                 CloseOutput = settings.CloseOutput,
                 Encoding = settings.Encoding,
-#if FEATURE_ASYNC_SAX_XML
+#if TASKS_SUPPORTED
                 Async = settings.Async,
 #endif
             };
@@ -430,7 +430,7 @@ public override void Close()
         #endregion
 
         // Async Methods
-#if FEATURE_ASYNC_SAX_XML
+#if TASKS_SUPPORTED
         /// <summary>
         /// Asynchronously writes the XML declaration with the version "1.0".
         /// </summary>

src/DocumentFormat.OpenXml.Framework/OpenXmlPartWriterSettings.cs

@@ -10,7 +10,7 @@ namespace DocumentFormat.OpenXml;
 /// </summary>
 public class OpenXmlPartWriterSettings
 {
-#if FEATURE_ASYNC_SAX_XML
+#if TASKS_SUPPORTED
     /// <summary>
     /// Gets or sets a value indicating whether asynchronous <see cref="OpenXmlPartWriter" />  methods can be used.
     /// </summary>

src/DocumentFormat.OpenXml.Framework/OpenXmlReader.cs

@@ -6,6 +6,9 @@
 using System.Collections.Generic;
 using System.Collections.ObjectModel;
 using System.IO;
+#if TASKS_SUPPORTED
+using System.Threading.Tasks;
+#endif
 using System.Xml;
 
 namespace DocumentFormat.OpenXml
@@ -235,6 +238,27 @@ public virtual bool HasAttributes
         /// </summary>
         public abstract void Close();
 
+#if TASKS_SUPPORTED
+        #region Async methods
+
+        /// <summary>
+        /// Asynchronously reads the next element in the Open XML document.
+        /// </summary>
+        /// <returns>
+        /// A task that represents the asynchronous read operation. The task result is <c>true</c> if the next element
+        /// was read successfully; <c>false</c> if there are no more elements to read.
+        /// </returns>
+        /// <remarks>
+        /// This method is only available when the build target supports asynchronous SAX XML processing.
+        /// It allows non-blocking operations for reading large Open XML documents.
+        /// </remarks>
+        public virtual Task<bool> ReadAsync()
+        {
+            return Task.FromResult(Read());
+        }
+        #endregion
+#endif
+
         /// <summary>
         /// Thrown if the object is disposed.
         /// </summary>

src/DocumentFormat.OpenXml.Framework/OpenXmlWriter.cs

@@ -6,7 +6,7 @@
 using System.Collections.Generic;
 using System.IO;
 using System.Text;
-#if FEATURE_ASYNC_SAX_XML
+#if TASKS_SUPPORTED
 using System.Threading.Tasks;
 #endif
 
@@ -131,7 +131,7 @@ protected OpenXmlWriter()
         /// </summary>
         public abstract void Close();
 
-#if FEATURE_ASYNC_SAX_XML
+#if TASKS_SUPPORTED
         /// <summary>
         /// Asynchronously writes the XML declaration with the version "1.0".
         /// </summary>

src/DocumentFormat.OpenXml.Framework/PublicAPI/PublicAPI.Unshipped.txt

@@ -1 +1,5 @@
 #nullable enable
+DocumentFormat.OpenXml.OpenXmlPartReaderOptions.Async.get -> bool
+DocumentFormat.OpenXml.OpenXmlPartReaderOptions.Async.set -> void
+override DocumentFormat.OpenXml.OpenXmlPartReader.ReadAsync() -> System.Threading.Tasks.Task<bool>!
+virtual DocumentFormat.OpenXml.OpenXmlReader.ReadAsync() -> System.Threading.Tasks.Task<bool>!

src/DocumentFormat.OpenXml.Framework/XmlConvertingReader.cs

@@ -4,6 +4,9 @@
 using DocumentFormat.OpenXml.Features;
 using DocumentFormat.OpenXml.Framework;
 using System;
+#if TASKS_SUPPORTED
+using System.Threading.Tasks;
+#endif
 using System.Xml;
 
 namespace DocumentFormat.OpenXml
@@ -53,6 +56,10 @@ protected override void Dispose(bool disposing)
         /// <inheritdoc/>
         public override bool Read() => BaseReader.Read();
 
+#if TASKS_SUPPORTED
+        public override Task<bool> ReadAsync() => BaseReader.ReadAsync();
+#endif
+
         /// <inheritdoc/>
         public override string GetAttribute(int index) => BaseReader.GetAttribute(index);
 

test/DocumentFormat.OpenXml.Tests/ofapiTest/OpenXmlWriterTest.cs

@@ -239,7 +239,7 @@ public void WriteStringExceptionTest7()
             }
         }
 
-#if FEATURE_ASYNC_SAX_XML
+#if TASKS_SUPPORTED
         [Fact]
         public async Task WriteStartDocumentAsync_ShouldWriteStartDocument()
         {