feat(io): expose leaveOpen on Read/ReadAsync and WriteAsync(path) overload; fail fast on ZIP32 4GB limit

- Xlsx.Read/ReadAsync 增加 leaveOpen 参数，默认释放流，可选保留\n- 新增 Xlsx.WriteAsync(path) 便利重载\n- ForwardOnlyZipWriter 在超过 ZIP32(4GB)上限时提前抛出清晰异常\n- Directory.Build.props NoWarn 加入 NU5119，使 TreatWarningsAsErrors 下打包成功\n- 补充 WriteAsync(path)/leaveOpen 保留与默认释放的单元测试

Author: hueifeng

Directory.Build.props

@@ -33,7 +33,7 @@
     <Version>2.9.0</Version>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
-    <NoWarn>1701;1702;CS1591;CS1573;1591;NU1507</NoWarn>
+    <NoWarn>1701;1702;CS1591;CS1573;1591;NU1507;NU5119</NoWarn>
     <CheckEolTargetFramework>false</CheckEolTargetFramework>
     <NuGetAuditMode>direct</NuGetAuditMode>
   </PropertyGroup>

src/Magicodes.IE.IO/Engine/XlsxReader.cs

@@ -20,7 +20,7 @@ namespace Magicodes.IE.IO
 
     /// <summary>
     /// Advanced streaming reader for xlsx workbooks.
-    /// For ordinary reads, use <see cref="Xlsx.Read{T}(Stream, XlsxReadOptions{T}?, Action{XlsxReadErrorInfo}?)"/>.
+    /// For ordinary reads, use <see cref="Xlsx.Read{T}(Stream, XlsxReadOptions{T}?, Action{XlsxReadErrorInfo}?, bool)"/>.
     /// </summary>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public sealed class XlsxReader : IDisposable

src/Magicodes.IE.IO/Internal/ForwardOnlyZipWriter.cs

@@ -119,6 +119,7 @@ internal static ValueTask DisposeEntryStreamAsync(Stream entryStream)
         internal void WriteRaw(byte[] buffer, int offset, int count)
         {
             if (count == 0) return;
+            if (_position + count > uint.MaxValue) ThrowZip32LimitExceeded();
 #if NETSTANDARD2_0
             _output.Write(buffer, offset, count);
 #else
@@ -130,6 +131,7 @@ internal void WriteRaw(byte[] buffer, int offset, int count)
         internal async Task WriteRawAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
         {
             if (count == 0) return;
+            if (_position + count > uint.MaxValue) ThrowZip32LimitExceeded();
 #if NETSTANDARD2_0
             await _output.WriteAsync(buffer, offset, count, cancellationToken).ConfigureAwait(false);
             _position += count;
@@ -143,6 +145,7 @@ internal async Task WriteRawAsync(byte[] buffer, int offset, int count, Cancella
         internal ValueTask WriteRawAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken)
         {
             if (buffer.Length == 0) return default;
+            if (_position + buffer.Length > uint.MaxValue) ThrowZip32LimitExceeded();
             var vt = _output.WriteAsync(buffer, cancellationToken);
             if (vt.IsCompletedSuccessfully)
             {
@@ -461,10 +464,18 @@ private static Utf8NameBuffer RentUtf8Name(string name)
 
         internal static uint CheckedToUInt32(long value)
         {
-            if ((ulong)value > uint.MaxValue) throw new NotSupportedException("ZIP64 is not supported by this forward-only zip writer.");
+            if ((ulong)value > uint.MaxValue) ThrowZip32LimitExceeded();
             return (uint)value;
         }
 
+        private static void ThrowZip32LimitExceeded()
+        {
+            throw new NotSupportedException(
+                "The output exceeds the 4 GB (ZIP32) size limit supported by this forward-only zip writer. " +
+                "Magicodes.IE.IO does not emit ZIP64 archives. To write workbooks larger than 4 GB, " +
+                "split the data across multiple files or sheets, or write to a consumer that supports ZIP64.");
+        }
+
         private void EnsureNotDisposed()
         {
             if (_disposed) throw new ObjectDisposedException(nameof(ForwardOnlyZipWriter));
@@ -1004,7 +1015,8 @@ public static DosDateTime From(DateTime value)
 
         private static readonly uint[] Crc32Table = BuildCrc32Table();
 
-#if DEBUG
+        // Self-check the CRC-32 implementation at type load. This guards the SIMD/intrinsic path
+        // (active on ARM64 in Release builds) so a wrong CRC never silently corrupts every xlsx.
         static ForwardOnlyZipWriter()
         {
             var data = System.Text.Encoding.ASCII.GetBytes("123456789");
@@ -1020,7 +1032,6 @@ static ForwardOnlyZipWriter()
             if (sliced.Result != expected)
                 throw new InvalidOperationException($"SlicingBy8Crc32 self-test failed: {sliced.Result:X8}");
         }
-#endif
 
         internal interface ICrc32
         {

src/Magicodes.IE.IO/Magicodes.IE.IO.csproj

@@ -4,7 +4,7 @@
     <TargetFrameworks>netstandard2.0;net6.0;net8.0;net10.0</TargetFrameworks>
     <LangVersion>latest</LangVersion>
     <Nullable>enable</Nullable>
-    <TreatWarningsAsErrors>false</TreatWarningsAsErrors>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <PackageId>Magicodes.IE.IO</PackageId>
     <Description>
       High-performance, low-allocation Excel (.xlsx) I/O library for .NET, with streaming write APIs and a simple high-level API for import and export.

src/Magicodes.IE.IO/Xlsx.cs

@@ -13,7 +13,7 @@ namespace Magicodes.IE.IO
     /// </summary>
     /// <remarks>
     /// <para><b>Export:</b> use the <see cref="Write{T}(System.String, IEnumerable{T}, System.Action{ExportProfile{T}}, XlsxWriteOptions)"/> overloads to write rows to a file, stream, <see cref="IBufferWriter{T}"/>, or <see cref="byte"/> array.</para>
-    /// <para><b>Import:</b> use the <see cref="Read{T}(Stream, XlsxReadOptions{T}, Action{XlsxReadErrorInfo})"/> overloads to stream deserialized rows from a workbook.</para>
+    /// <para><b>Import:</b> use the <see cref="Read{T}(Stream, XlsxReadOptions{T}?, Action{XlsxReadErrorInfo}?, bool)"/> overloads to stream deserialized rows from a workbook.</para>
     /// <para><b>Multi-sheet:</b> <see cref="WriteWorkbook(Stream, IReadOnlyList{SheetBase})"/>. <b>Template export:</b> <see cref="ExportByTemplateAsync{T}(System.String, System.String, T, CancellationToken)"/>.</para>
     /// <para>When no <see cref="ExportProfile{T}"/> is supplied, headers and formats are inferred from property names and from <c>[Display]</c>, <c>[Description]</c>, and <c>[DisplayFormat]</c> attributes. The underlying writer/reader is a dependency-free, streaming, low-allocation OOXML implementation and does not depend on EPPlus.</para>
     /// <para><b>Lifetime:</b> overloads that take a <c>path</c> own and dispose the underlying <see cref="FileStream"/>; overloads that take a <see cref="Stream"/> or <see cref="IBufferWriter{T}"/> do not, and the caller is responsible for disposal. Note: the Read/ReadAsync stream overloads DO own and dispose the supplied stream when enumeration completes.</para>
@@ -161,6 +161,65 @@ public static async Task WriteAsync<T>(Stream output, IEnumerable<T> data, Expor
             await XlsxWritePipeline.RunAsync(writer, data, profile, cancellationToken).ConfigureAwait(false);
         }
 
+        /// <summary>
+        /// Asynchronously writes the specified rows to the .xlsx file at <paramref name="path"/>.
+        /// </summary>
+        /// <remarks>Equivalent to opening a <see cref="FileStream"/> and calling the stream overload; the file stream is owned and disposed by this method.</remarks>
+        public static async Task WriteAsync<T>(string path, IEnumerable<T> data, Action<ExportProfile<T>>? configure = null, XlsxWriteOptions? options = null, CancellationToken cancellationToken = default)
+        {
+            ValidatePath(path);
+            if (data is null) throw new ArgumentNullException(nameof(data));
+            var compression = options?.Compression ?? System.IO.Compression.CompressionLevel.Fastest;
+            var strictCellReferences = options?.StrictCellReferences ?? true;
+            using var fs = File.Create(path);
+            await using var writer = new XlsxWriter(fs, sheetName: null, compression, defaultRowHeight: 0, strictCellReferences);
+            await XlsxWritePipeline.RunAsync(writer, data, configure, cancellationToken).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Asynchronously writes the specified rows to the .xlsx file at <paramref name="path"/> using a pre-built profile.
+        /// </summary>
+        public static async Task WriteAsync<T>(string path, IEnumerable<T> data, ExportProfile<T> profile, XlsxWriteOptions? options = null, CancellationToken cancellationToken = default)
+        {
+            ValidatePath(path);
+            if (data is null) throw new ArgumentNullException(nameof(data));
+            if (profile is null) throw new ArgumentNullException(nameof(profile));
+            var compression = options?.Compression ?? System.IO.Compression.CompressionLevel.Fastest;
+            var strictCellReferences = options?.StrictCellReferences ?? true;
+            using var fs = File.Create(path);
+            await using var writer = new XlsxWriter(fs, sheetName: null, compression, defaultRowHeight: 0, strictCellReferences);
+            await XlsxWritePipeline.RunAsync(writer, data, profile, cancellationToken).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Asynchronously streams rows from an <see cref="IAsyncEnumerable{T}"/> to the .xlsx file at <paramref name="path"/>.
+        /// </summary>
+        public static async Task WriteAsync<T>(string path, IAsyncEnumerable<T> data, Action<ExportProfile<T>>? configure = null, XlsxWriteOptions? options = null, CancellationToken cancellationToken = default)
+        {
+            ValidatePath(path);
+            if (data is null) throw new ArgumentNullException(nameof(data));
+            var compression = options?.Compression ?? System.IO.Compression.CompressionLevel.Fastest;
+            var strictCellReferences = options?.StrictCellReferences ?? true;
+            using var fs = File.Create(path);
+            await using var writer = new XlsxWriter(fs, sheetName: null, compression, defaultRowHeight: 0, strictCellReferences);
+            await XlsxWritePipeline.RunAsync(writer, data, configure, cancellationToken).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Asynchronously streams rows from an <see cref="IAsyncEnumerable{T}"/> to the .xlsx file at <paramref name="path"/> using a pre-built profile.
+        /// </summary>
+        public static async Task WriteAsync<T>(string path, IAsyncEnumerable<T> data, ExportProfile<T> profile, XlsxWriteOptions? options = null, CancellationToken cancellationToken = default)
+        {
+            ValidatePath(path);
+            if (data is null) throw new ArgumentNullException(nameof(data));
+            if (profile is null) throw new ArgumentNullException(nameof(profile));
+            var compression = options?.Compression ?? System.IO.Compression.CompressionLevel.Fastest;
+            var strictCellReferences = options?.StrictCellReferences ?? true;
+            using var fs = File.Create(path);
+            await using var writer = new XlsxWriter(fs, sheetName: null, compression, defaultRowHeight: 0, strictCellReferences);
+            await XlsxWritePipeline.RunAsync(writer, data, profile, cancellationToken).ConfigureAwait(false);
+        }
+
         /// <summary>
         /// Exports the specified rows to a <see cref="byte"/> array.
         /// </summary>
@@ -205,9 +264,9 @@ private static int EstimateToBytesCapacity<T>(IEnumerable<T> data)
         /// <param name="onParseError">Optional callback invoked when a cell cannot be parsed. When omitted, a <see cref="XlsxException"/> is thrown on the first parse error.</param>
         /// <returns>A lazy <see cref="IEnumerable{T}"/>. Each row is parsed on demand as you iterate; do not enumerate the result more than once.</returns>
         /// <remarks>When a source-generated reader is available for <typeparamref name="T"/>, it is used for reflection-free reading; otherwise reflection is used.</remarks>
-        public static IEnumerable<T> Read<T>(Stream stream, XlsxReadOptions<T>? profile = null, Action<XlsxReadErrorInfo>? onParseError = null) where T : new()
+        public static IEnumerable<T> Read<T>(Stream stream, XlsxReadOptions<T>? profile = null, Action<XlsxReadErrorInfo>? onParseError = null, bool leaveOpen = false) where T : new()
         {
-            using var reader = new XlsxReader(stream, leaveOpen: false);
+            using var reader = new XlsxReader(stream, leaveOpen);
             var headers = reader.ReadHeader();
             var converters = profile?.GetConverters();
             int rowIndex = 0;
@@ -268,12 +327,12 @@ private static int EstimateToBytesCapacity<T>(IEnumerable<T> data)
         /// <summary>
         /// Reads the first worksheet of a .xlsx workbook asynchronously and returns the deserialized rows as <typeparamref name="T"/>.
         /// </summary>
-        /// <remarks>Supports cancellation via <paramref name="cancellationToken"/>. Otherwise the behavior matches <see cref="Read{T}(Stream, XlsxReadOptions{T}, Action{XlsxReadErrorInfo})"/>.</remarks>
+        /// <remarks>Supports cancellation via <paramref name="cancellationToken"/>. Otherwise the behavior matches <see cref="Read{T}(Stream, XlsxReadOptions{T}?, Action{XlsxReadErrorInfo}?, bool)"/>.</remarks>
         /// <returns>A lazy <see cref="IAsyncEnumerable{T}"/>. Do not enumerate the result more than once.</returns>
-        public static async IAsyncEnumerable<T> ReadAsync<T>(Stream stream, XlsxReadOptions<T>? profile = null, Action<XlsxReadErrorInfo>? onParseError = null, [EnumeratorCancellation] CancellationToken cancellationToken = default) where T : new()
+        public static async IAsyncEnumerable<T> ReadAsync<T>(Stream stream, XlsxReadOptions<T>? profile = null, Action<XlsxReadErrorInfo>? onParseError = null, [EnumeratorCancellation] CancellationToken cancellationToken = default, bool leaveOpen = false) where T : new()
         {
             cancellationToken.ThrowIfCancellationRequested();
-            using var reader = new XlsxReader(stream, leaveOpen: false);
+            using var reader = new XlsxReader(stream, leaveOpen);
             var headers = await reader.ReadHeaderAsync(cancellationToken).ConfigureAwait(false);
             var converters = profile?.GetConverters();
             int rowIndex = 0;
@@ -330,7 +389,7 @@ private static int EstimateToBytesCapacity<T>(IEnumerable<T> data)
         {
             ValidatePath(path);
             using var fs = File.OpenRead(path);
-            await foreach (var item in ReadAsync<T>(fs, profile, onParseError, cancellationToken).ConfigureAwait(false))
+            await foreach (var item in ReadAsync<T>(fs, profile, onParseError, cancellationToken: cancellationToken).ConfigureAwait(false))
                 yield return item;
         }
 

tests/Magicodes.IE.IO.Tests/XlsxIO_Reader_Tests.cs

@@ -792,5 +792,62 @@ private static async IAsyncEnumerable<T> DataToAsync<T>(IEnumerable<T> data, [Sy
                 await Task.Yield();
             }
         }
+
+        [Fact]
+        public async Task WriteAsync_PathOverload_WritesReadableFile()
+        {
+            var path = Path.Combine(Path.GetTempPath(), $"io_writeasync_{Guid.NewGuid():N}.xlsx");
+            try
+            {
+                var data = new[]
+                {
+                    new OrderDto { OrderNo = "WA1", Amount = 7m, CreatedAt = new DateTime(2024, 7, 7) },
+                    new OrderDto { OrderNo = "WA2", Amount = 8m, CreatedAt = new DateTime(2024, 7, 8) },
+                };
+                await Xlsx.WriteAsync(path, data);
+
+                var list = Xlsx.Read<OrderDto>(path).ToList();
+                list.Count.ShouldBe(2);
+                list[0].OrderNo.ShouldBe("WA1");
+                list[0].Amount.ShouldBe(7m);
+                list[1].OrderNo.ShouldBe("WA2");
+            }
+            finally
+            {
+                if (File.Exists(path)) File.Delete(path);
+            }
+        }
+
+        [Fact]
+        public void Read_Stream_LeaveOpen_KeepsStreamUsable()
+        {
+            var bytes = Xlsx.ToBytes(new[] { new OrderDto { OrderNo = "LO", Amount = 1m } });
+            using var ms = new MemoryStream(bytes);
+            var list = Xlsx.Read<OrderDto>(ms, leaveOpen: true).ToList();
+            list.Count.ShouldBe(1);
+            // Stream must still be readable because we asked the reader to leave it open.
+            ms.Position = 0;
+            ms.Length.ShouldBe(bytes.Length);
+            ms.Dispose();
+        }
+
+        [Fact]
+        public void Read_Stream_DefaultDisposesStream()
+        {
+            var path = Path.Combine(Path.GetTempPath(), $"io_read_dispose_{Guid.NewGuid():N}.xlsx");
+            try
+            {
+                Xlsx.Write(path, new[] { new OrderDto { OrderNo = "DX" } });
+                var fs = File.OpenRead(path);
+                var list = Xlsx.Read<OrderDto>(fs).ToList();
+                list.Count.ShouldBe(1);
+                // Default behavior disposes the stream; touching it afterwards must fail.
+                Should.Throw<ObjectDisposedException>(() => fs.ReadByte());
+            }
+            finally
+            {
+                if (File.Exists(path)) File.Delete(path);
+            }
+        }
     }
 }