Add async xmlwriter methods

Directory.Build.props

@@ -70,6 +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>
       </PropertyGroup>
     </Otherwise>
   </Choose>

src/DocumentFormat.OpenXml.Framework/OpenXmlPartWriter.cs

@@ -6,6 +6,10 @@
 using System.Collections.Generic;
 using System.IO;
 using System.Text;
+#if FEATURE_ASYNC_SAX_XML
+using DocumentFormat.OpenXml.Framework;
+using System.Threading.Tasks;
+#endif
 using System.Xml;
 
 namespace DocumentFormat.OpenXml
@@ -56,6 +60,36 @@ public OpenXmlPartWriter(OpenXmlPart openXmlPart, Encoding encoding)
             _xmlWriter = XmlWriter.Create(partStream, settings);
         }
 
+#if FEATURE_ASYNC_SAX_XML
+        /// <summary>
+        /// Initializes a new instance of the OpenXmlPartWriter.
+        /// </summary>
+        /// <param name="openXmlPart">The OpenXmlPart to be written to.</param>
+        /// <param name="settings">The settings for the OpenXmlPartWriter.</param>
+        public OpenXmlPartWriter(OpenXmlPart openXmlPart, OpenXmlPartWriterSettings settings)
+        {
+            if (openXmlPart is null)
+            {
+                throw new ArgumentNullException(nameof(openXmlPart));
+            }
+
+            if (settings is null)
+            {
+                throw new ArgumentNullException(nameof(settings));
+            }
+
+            var partStream = openXmlPart.GetStream(FileMode.Create);
+            XmlWriterSettings xmlWriterSettings = new()
+            {
+                CloseOutput = true,
+                Encoding = settings.Encoding,
+                Async = settings.Async,
+            };
+
+            _xmlWriter = XmlWriter.Create(partStream, xmlWriterSettings);
+        }
+#endif
+
         /// <summary>
         /// Initializes a new instance of the OpenXmlPartWriter.
         /// </summary>
@@ -91,6 +125,35 @@ public OpenXmlPartWriter(Stream partStream, Encoding encoding)
             _xmlWriter = XmlWriter.Create(partStream, settings);
         }
 
+#if FEATURE_ASYNC_SAX_XML
+        /// <summary>
+        /// Initializes a new instance of the OpenXmlPartWriter.
+        /// </summary>
+        /// <param name="partStream">The given part stream.</param>
+        /// <param name="settings">The settings for the OpenXmlPartWriter.</param>
+        public OpenXmlPartWriter(Stream partStream, OpenXmlPartWriterSettings settings)
+        {
+            if (partStream is null)
+            {
+                throw new ArgumentNullException(nameof(partStream));
+            }
+
+            if (settings is null)
+            {
+                throw new ArgumentNullException(nameof(settings));
+            }
+
+            XmlWriterSettings xmlWriterSettings = new()
+            {
+                CloseOutput = settings.CloseOutput,
+                Encoding = settings.Encoding,
+                Async = settings.Async,
+            };
+
+            _xmlWriter = XmlWriter.Create(partStream, xmlWriterSettings);
+        }
+#endif
+
         #region public OpenXmlWriter methods
 
         /// <summary>
@@ -365,5 +428,184 @@ public override void Close()
         }
 
         #endregion
+
+        // Async Methods
+#if FEATURE_ASYNC_SAX_XML
+        /// <summary>
+        /// Asynchronously writes the XML declaration with the version "1.0".
+        /// </summary>
+        public override Task WriteStartDocumentAsync()
+        {
+            ThrowIfObjectDisposed();
+
+            return _xmlWriter.WriteStartDocumentAsync();
+        }
+
+        /// <summary>
+        /// Asynchronously writes the XML declaration with the version "1.0" and the standalone attribute.
+        /// </summary>
+        /// <param name="standalone">If true, it writes "standalone=yes"; if false, it writes "standalone=no". </param>
+        public override Task WriteStartDocumentAsync(bool standalone)
+        {
+            ThrowIfObjectDisposed();
+
+            return _xmlWriter.WriteStartDocumentAsync(standalone);
+        }
+
+        /// <summary>
+        /// Asynchronously writes out a start tag of the element and all the attributes of the element.
+        /// </summary>
+        /// <param name="elementObject">The OpenXmlElement object to be written.</param>
+        public async override Task WriteStartElementAsync(OpenXmlElement elementObject)
+        {
+            if (elementObject is null)
+            {
+                throw new ArgumentNullException(nameof(elementObject));
+            }
+
+            if (elementObject is OpenXmlMiscNode)
+            {
+                throw new ArgumentOutOfRangeException(nameof(elementObject));
+            }
+
+            ThrowIfObjectDisposed();
+
+            await _xmlWriter.WriteStartElementAsync(elementObject.Prefix, elementObject.LocalName, elementObject.NamespaceUri).ConfigureAwait(true);
+
+            if (elementObject.HasAttributes)
+            {
+                // write attributes
+                foreach (var attribute in elementObject.GetAttributes())
+                {
+                    await _xmlWriter.WriteAttributeStringAsync(attribute.Prefix, attribute.LocalName, attribute.NamespaceUri, attribute.Value).ConfigureAwait(true);
+                }
+            }
+
+            if (elementObject is OpenXmlLeafTextElement)
+            {
+                _isLeafTextElementStart = true;
+            }
+            else
+            {
+                _isLeafTextElementStart = false;
+            }
+        }
+
+        /// <summary>
+        /// Asynchronously writes out a start tag of the element. And write the attributes in attributes. The attributes of the element will be omitted.
+        /// </summary>
+        /// <param name="elementObject">The OpenXmlElement object to be written.</param>
+        /// <param name="attributes">The attributes to be written.</param>
+        public override Task WriteStartElementAsync(OpenXmlElement elementObject, IEnumerable<OpenXmlAttribute> attributes)
+        {
+            if (elementObject is null)
+            {
+                throw new ArgumentNullException(nameof(elementObject));
+            }
+
+            return WriteStartElementAsync(elementObject, attributes, elementObject.NamespaceDeclarations);
+        }
+
+        /// <summary>
+        /// Asynchronously writes out a start tag of the element. And write the attributes in attributes. The attributes of the element will be omitted.
+        /// </summary>
+        /// <param name="elementObject">The OpenXmlElement object to be written.</param>
+        /// <param name="attributes">The attributes to be written.</param>
+        /// <param name="namespaceDeclarations">The namespace declarations to be written, can be null if no namespace declarations.</param>
+        public async override Task WriteStartElementAsync(OpenXmlElement elementObject, IEnumerable<OpenXmlAttribute> attributes, IEnumerable<KeyValuePair<string, string>> namespaceDeclarations)
+        {
+            if (elementObject is null)
+            {
+                throw new ArgumentNullException(nameof(elementObject));
+            }
+
+            if (elementObject is OpenXmlMiscNode)
+            {
+                throw new ArgumentOutOfRangeException(nameof(elementObject));
+            }
+
+            ThrowIfObjectDisposed();
+
+            await _xmlWriter.WriteStartElementAsync(elementObject.Prefix, elementObject.LocalName, elementObject.NamespaceUri).ConfigureAwait(true);
+
+            if (namespaceDeclarations is not null)
+            {
+                foreach (var item in namespaceDeclarations)
+                {
+                    await _xmlWriter.WriteAttributeStringAsync(OpenXmlElementContext.XmlnsPrefix, item.Key, OpenXmlElementContext.XmlnsUri, item.Value).ConfigureAwait(true);
+                }
+            }
+
+            if (attributes is not null)
+            {
+                // write attributes
+                foreach (var attribute in attributes)
+                {
+                    await _xmlWriter.WriteAttributeStringAsync(attribute.Prefix, attribute.LocalName, attribute.NamespaceUri, attribute.Value).ConfigureAwait(true);
+                }
+            }
+
+            if (elementObject is OpenXmlLeafTextElement)
+            {
+                _isLeafTextElementStart = true;
+            }
+            else
+            {
+                _isLeafTextElementStart = false;
+            }
+        }
+
+        /// <summary>
+        /// Asynchronously closes one element.
+        /// </summary>
+        public override Task WriteEndElementAsync()
+        {
+            ThrowIfObjectDisposed();
+
+            _isLeafTextElementStart = false;
+
+            return _xmlWriter.WriteEndElementAsync();
+        }
+
+        /// <summary>
+        /// Asynchronously writes the OpenXmlElement to the writer.
+        /// </summary>
+        /// <param name="elementObject">The OpenXmlElement object to be written.</param>
+        public async override Task WriteElementAsync(OpenXmlElement elementObject)
+        {
+            if (elementObject is null)
+            {
+                throw new ArgumentNullException(nameof(elementObject));
+            }
+
+            ThrowIfObjectDisposed();
+
+            await WriteStartElementAsync(elementObject).ConfigureAwait(true);
+
+            await WriteEndElementAsync().ConfigureAwait(true);
+
+            _isLeafTextElementStart = false;
+        }
+
+        /// <summary>
+        /// Asynchronously writes the given text content.
+        /// </summary>
+        /// <param name="text">The text to be written. </param>
+        public override Task WriteStringAsync(string text)
+        {
+            ThrowIfObjectDisposed();
+
+            if (_isLeafTextElementStart)
+            {
+                return _xmlWriter.WriteStringAsync(text);
+            }
+            else
+            {
+                throw new InvalidOperationException(ExceptionMessages.InvalidWriteStringCall);
+            }
+
+            // can continue WriteStringAsync(), so don't set _isLeafTextElementStart to false.
+        }
+#endif
     }
 }

src/DocumentFormat.OpenXml.Framework/OpenXmlPartWriterSettings.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+#if FEATURE_ASYNC_SAX_XML
+using System.Text;
+
+namespace DocumentFormat.OpenXml;
+
+/// <summary>
+/// Settings for the OpenXmlPartWriter.
+/// </summary>
+public class OpenXmlPartWriterSettings
+{
+    /// <summary>
+    /// Gets or sets a value indicating whether asynchronous OpenXmlPartWriter methods can be used.
+    /// </summary>
+    public bool Async { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the OpenXmlPartWriter should check to ensure that all characters in the document conform to the "2.2 Characters" section of the W3C XML 1.0 Recommendation.
+    /// </summary>
+    public bool CloseOutput { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the OpenXmlPartWriter should also close the underlying stream or TextWriter when the Close() method is called.
+    /// </summary>
+    public Encoding Encoding { get; set; } = Encoding.UTF8;
+}
+#endif