Preparations for release of preview version 3

.github/workflows/benchmark.yml

@@ -120,4 +120,4 @@ jobs:
           git config user.email github-actions@github.com
           git add ./*.md
           git commit -am "Automated benchmark report - ${{ github.ref_name }}"
-          git push origin master --force-with-lease
+          git push origin HEAD:master --force-with-lease

MiniExcel.slnx

@@ -9,7 +9,6 @@
     <File Path="appveyor.yml" />
     <File Path=".github\workflows\dotnet.yml" />
     <File Path="LICENSE" />
-    <File Path="README-NuGet.md" />
     <File Path="README.md" />
     <File Path="README.zh-CN.md" />
     <File Path=".github\workflows\benchmark.yml" />

README-V2.md

@@ -107,12 +107,12 @@ You can download the full package from [NuGet](https://www.nuget.org/packages/Mi
 dotnet add package MiniExcel
 ```
 
-This package will contain the assemblies with both Excel and Csv functionalities, along with the original `v1.x` methods' signatures.
-~~If you don't care for those you can also install the Excel and Csv packages separately:~~
-We're still pondering whether this is the best way to move forward with the library, and if we do this is how you'll be able to add the separate packages:
+This package will contain the assemblies with both Excel and Csv functionalities,
+along with the `MiniExcelConverter` utility class and the original `v1.x` methods' signatures.
+If you don't care for those you can also install the OpenXml and Csv packages separately:
 
 ```bash
-dotnet add package MiniExcel.Core
+dotnet add package MiniExcel.OpenXml
 ```
 
 ```bash

V2-Upgrade-Notes.md

@@ -6,7 +6,7 @@
 `MiniExcel.Importers`, `MiniExcel.Exporters` and `MiniExcel.Templaters` will give you access to, respectively, the `MiniExcelImporterProvider`, `MiniExcelExporterProvider` and `MiniExcelTemplaterProvider`.
 - This way Excel and Csv query methods are split between the `OpenXmlImporter` and the `CsvImporter`, accessible from the `MiniExcelImporterProvider`.
 - The same structure was adopted for export methods through `OpenXmlExporter` and `CsvExporter`, while template methods are instead currently only found in `OpenXmlTemplater`.
-- Csv methods are only available if the MiniExcel.Csv package is installed, which is pulled down automatically when the full MiniExcel package is downloaded.
+- OpenXml and Csv methods are only available if the respective `MiniExcel.OpenXml` and `MiniExcel.Csv` packages are downloaded, or if the complete `MiniExcel` package is installed.
 - You can only access the conversion methods `ConvertCsvToXlsx` and `ConvertXlsxToCsv` from the `MiniExcelConverter` utility class, which is part of the full MiniExcel package.
 - If the full MiniExcel package is downloaded, the previous namespace will coexist along the new one, containing the original static methods' signatures, which have become a facade for the aferomentioned providers.
 - `IConfiguration` is now `IMiniExcelConfiguration`, but most methods now require the proper implementation (`OpenXmlConfiguration` or `CsvConfiguration`) to be provided rather than the interface

benchmarks/MiniExcel.Benchmarks/BenchmarkBase.cs

@@ -2,10 +2,10 @@
 
 public abstract class BenchmarkBase
 {
-    public const string FilePath = "Test1,000,000x10.xlsx";
-    public const int RowCount = 1_000_000;
+    protected const string FilePath = "Test100,000x10.xlsx";
+    protected const int RowCount = 100_000;
 
-    public IEnumerable<DemoDto> GetValue() => Enumerable.Range(1, RowCount).Select(s => new DemoDto());
+    protected IEnumerable<DemoDto> GetValue() => Enumerable.Range(1, RowCount).Select(_ => new DemoDto());
 
     public class DemoDto
     {

benchmarks/MiniExcel.Benchmarks/BenchmarkSections/QueryExcelBenchmark.cs

@@ -53,7 +53,10 @@ public void MiniExcel_QueryFirst_Test()
     [Benchmark(Description = "MiniExcel Query")]
     public void MiniExcel_Query()
     {
-        foreach (var _ in _importer.Query(FilePath)) { }
+        foreach (var row in _importer.Query(FilePath))
+        {
+            var value = row;
+        }
     }
 
     [Benchmark(Description = "MiniExcel QueryFirst with Mapping")]
@@ -65,7 +68,10 @@ public void MiniExcel_QueryFirst_Mapping_Test()
     [Benchmark(Description = "MiniExcel Query with Mapping")]
     public void MiniExcel_Query_Mapping()
     {
-        foreach (var _ in _mappingImporter.Query<DemoDto>(FilePath)) { }
+        foreach (var row in _mappingImporter.Query<DemoDto>(FilePath))
+        {
+            var value = row;
+        }
     }
 
     [Benchmark(Description = "ExcelDataReader QueryFirst")]
@@ -74,11 +80,11 @@ public void ExcelDataReader_QueryFirst_Test()
         using var stream = File.Open(FilePath, FileMode.Open, FileAccess.Read);
         using var reader = ExcelReaderFactory.CreateReader(stream);
 
-        List<object> d = [];
         reader.Read();
-
         for (var i = 0; i < reader.FieldCount; i++)
-            d.Add(reader.GetValue(i));
+        {
+            var value = reader.GetValue(i);
+        }
     }
 
     [Benchmark(Description = "ExcelDataReader Query")]
@@ -89,9 +95,10 @@ public void ExcelDataReader_Query_Test()
 
         while (reader.Read())
         {
-            List<object> d = [];
             for (var i = 0; i < reader.FieldCount; i++)
-                d.Add(reader.GetValue(i));
+            {
+                var value = reader.GetValue(i);
+            }
         }
     }
 
@@ -105,8 +112,6 @@ public void Epplus_QueryFirst_Test()
     [Benchmark(Description = "Epplus Query")]
     public void Epplus_Query_Test()
     {
-        // [How do I iterate through rows in an excel table using epplus? - Stack Overflow] (https://stackoverflow.com/questions/21742038/how-do-i-iterate-through-rows-in-an-excel-table-using-epplus)
-
         using var p = new ExcelPackage(new FileInfo(FilePath));
 
         var workSheet = p.Workbook.Worksheets[0];
@@ -135,12 +140,14 @@ public void ClosedXml_Query_Test()
         using var workbook = new XLWorkbook(FilePath);
         workbook.Worksheet(1).Rows();
     }
+
     [Benchmark(Description = "NPOI QueryFirst")]
     public void NPOI_QueryFirst_Test()
     {
         using var wb = new XSSFWorkbook(FilePath,true);
         wb.GetSheetAt(0).GetRow(1);
     }
+
     [Benchmark(Description = "NPOI Query")]
     public void NPOI_Query_Test()
     {
@@ -181,6 +188,9 @@ public void OpenXmlSDK_Query_Test()
         var worksheetPart = workbookPart!.WorksheetParts.First();
 
         var sheetData = worksheetPart.Worksheet.Elements<SheetData>().First();
-        var firstRow = sheetData.Elements<Row>().ToList();
+        foreach(var row in sheetData.Elements<Row>())
+        {
+            var cellValue = row;
+        }
     }
 }

benchmarks/MiniExcel.Benchmarks/BenchmarkSections/TemplateExcelBenchmark.cs

@@ -35,7 +35,7 @@ public void Setup()
         _mappingTemplater = MiniExcel.Templaters.GetMappingTemplater(registry);
     }
 
-    [Benchmark(Description = "MiniExcel Template Generate")]
+    [Benchmark(Description = "MiniExcel Fill Template")]
     public void MiniExcel_Template_Generate_Test()
     {
         const string templatePath = "TestTemplateBasicIEmumerableFill.xlsx";
@@ -54,7 +54,7 @@ public void MiniExcel_Template_Generate_Test()
         _templater.FillTemplate(path.FilePath, templatePath, value);
     }
 
-    [Benchmark(Description = "ClosedXml.Report Template Generate")]
+    [Benchmark(Description = "ClosedXml.Report Generate Template")]
     public void ClosedXml_Report_Template_Generate_Test()
     {
         const string templatePath = "TestTemplateBasicIEmumerableFill_ClosedXML_Report.xlsx";
@@ -77,7 +77,7 @@ public void ClosedXml_Report_Template_Generate_Test()
         template.SaveAs(path.FilePath);
     }
 
-    [Benchmark(Description = "MiniExcel Mapping Template Generate")]
+    [Benchmark(Description = "MiniExcel Mapping Fill Template")]
     public void MiniExcel_Mapping_Template_Generate_Test()
     {
         using var templatePath = AutoDeletingPath.Create();
@@ -96,6 +96,6 @@ public void MiniExcel_Mapping_Template_Generate_Test()
                 Department = "HR"
             });
 
-        _mappingTemplater.ApplyTemplate(outputPath.FilePath, templatePath.FilePath, employees);
+        _mappingTemplater.FillTemplate(outputPath.FilePath, templatePath.FilePath, employees);
     }
 }

benchmarks/MiniExcel.Benchmarks/MiniExcel.Benchmarks.csproj

@@ -11,12 +11,12 @@
 	</PropertyGroup>
 
 	<ItemGroup>
-		<PackageReference Include="BenchmarkDotNet" Version="0.15.6" />
+		<PackageReference Include="BenchmarkDotNet" Version="0.15.8" />
 		<PackageReference Include="ClosedXML" Version="0.105.0" />
 		<PackageReference Include="ClosedXML.Report" Version="0.2.12" />
-		<PackageReference Include="DocumentFormat.OpenXml" Version="3.3.0" />
-		<PackageReference Include="EPPlus" Version="7.7.2" />
-		<PackageReference Include="ExcelDataReader" Version="3.7.0" />
+		<PackageReference Include="DocumentFormat.OpenXml" Version="3.5.1" />
+		<PackageReference Include="EPPlus" Version="7.7.3" />
+		<PackageReference Include="ExcelDataReader" Version="3.8.0" />
 		<PackageReference Include="NPOI" Version="2.7.5" />
 	</ItemGroup>
 

src/Directory.Build.props

@@ -2,7 +2,7 @@
 
     <PropertyGroup>
         <TargetFrameworks>netstandard2.0;net8.0;net9.0;net10.0</TargetFrameworks>
-        <Version>2.0.0-preview.2</Version>
+        <Version>2.0.0-preview.3</Version>
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
         <LangVersion>14</LangVersion>
@@ -12,11 +12,7 @@
         <Product>MiniExcel</Product>
         <Company>Mini-Software</Company>
         <PackageTags>excel;xlsx;csv;micro-helper;mini;openxml;helper;</PackageTags>
-        <Description>Fast, Low-Memory, Easy Excel .NET processing tool for importing, exporting and templating spreadsheets
-            Github : https://github.com/mini-software/MiniExcel
-            Gitee : https://gitee.com/dotnetchina/MiniExcel
-            Issues : https://github.com/mini-software/MiniExcel/issues
-            Todo : https://github.com/mini-software/MiniExcel/projects/1?fullscreen=true</Description>
+        <Description>Lightweight, fast and simple .NET processing tool for importing, exporting and templating spreadsheets.</Description>
         <Authors>Wei Lin, Michele Bastione, PING-HSIU SHIH, Amos(izanhzh), eynarhaji, Mini-Software team</Authors>
         <Copyright>Mini-Software, 2021 onwards</Copyright>
         <NeutralLanguage>en</NeutralLanguage>
@@ -25,7 +21,7 @@
         <RepositoryUrl>https://github.com/mini-software/MiniExcel</RepositoryUrl>
         <RepositoryType>Github</RepositoryType>
         <PackageIcon>icon.png</PackageIcon>
-        <PackageReleaseNotes>Please Check [Release Notes](https://github.com/mini-software/MiniExcel/tree/master/docs)</PackageReleaseNotes>
+        <PackageReleaseNotes>https://github.com/mini-software/MiniExcel/tree/master/docs</PackageReleaseNotes>
         <PublishRepositoryUrl>true</PublishRepositoryUrl>
         <IncludeSymbols>true</IncludeSymbols>
         <SymbolPackageFormat>snupkg</SymbolPackageFormat>

src/Directory.Packages.props

@@ -2,10 +2,12 @@
   <ItemGroup>
     <PackageReference Include="Zomp.SyncMethodGenerator" Version="[1.6.13]" PrivateAssets="all" IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />
   </ItemGroup>
+
   <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'">
-    <PackageReference Include="Microsoft.Bcl.Memory" Version="10.0.5" />
-    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.0" />
+    <PackageReference Include="Microsoft.Bcl.Memory" Version="10.0.7" />
+    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.7" />
   </ItemGroup>
+
   <ItemGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
   </ItemGroup>

src/MiniExcel.OpenXml/Api/OpenXmlTemplater.cs

@@ -132,4 +132,49 @@ private static OpenXmlTemplate GetOpenXmlTemplate(Stream stream, OpenXmlConfigur
     }
 
     #endregion
+
+    #region Obsolete
+
+    [CreateSyncVersion, Obsolete("Please use FillTemplate or FillTemplateAsync instead")]
+    public Task ApplyTemplateAsync(string path, string templatePath, object value, bool overwriteFile = false,
+        OpenXmlConfiguration? configuration = null, CancellationToken cancellationToken = default)
+    {
+        return FillTemplateAsync(path, templatePath, value, overwriteFile, configuration, cancellationToken);
+    }
+
+    [CreateSyncVersion, Obsolete("Please use FillTemplate or FillTemplateAsync instead")]
+    public Task ApplyTemplateAsync(string path, Stream templateStream, object value, bool overwriteFile = false,
+        OpenXmlConfiguration? configuration = null, CancellationToken cancellationToken = default)
+    {
+        return FillTemplateAsync(path, templateStream, value, overwriteFile, configuration, cancellationToken);
+    }
+
+    [CreateSyncVersion, Obsolete("Please use FillTemplate or FillTemplateAsync instead")]
+    public Task ApplyTemplateAsync(Stream stream, string templatePath, object value,
+        OpenXmlConfiguration? configuration = null, CancellationToken cancellationToken = default)
+    {
+        return FillTemplateAsync(stream, templatePath, value, configuration, cancellationToken);
+    }
+
+    [CreateSyncVersion, Obsolete("Please use FillTemplate or FillTemplateAsync instead")]
+    public Task ApplyTemplateAsync(Stream stream, Stream templateStream, object value,
+        OpenXmlConfiguration? configuration = null, CancellationToken cancellationToken = default)
+    {
+        return FillTemplateAsync(stream, templateStream, value, configuration, cancellationToken);
+    }
+
+    [CreateSyncVersion, Obsolete("Please use FillTemplate or FillTemplateAsync instead")]
+    public Task ApplyTemplateAsync(string path, byte[] templateBytes, object value, bool overwriteFile = false,
+        OpenXmlConfiguration? configuration = null, CancellationToken cancellationToken = default)
+    {
+        return FillTemplateAsync(path, templateBytes, value, overwriteFile, configuration, cancellationToken);
+    }
+
+    [CreateSyncVersion, Obsolete("Please use FillTemplate or FillTemplateAsync instead")]
+    public Task ApplyTemplateAsync(Stream stream, byte[] templateBytes, object value,
+        OpenXmlConfiguration? configuration = null, CancellationToken cancellationToken = default)
+    {
+        return FillTemplateAsync(stream, templateBytes, value, configuration, cancellationToken);
+    }
+    #endregion
 }