Renaming the "new" MiniExcel class to MiniExcelV2 (#1010)

* Renamed MiniExcelLib.MiniExcel class to MiniExcelV2

This change was adopted to avoid confusion with the `MiniExcelLibs.MiniExcel` facade class containing the V1 methods' signatures. Users will be able to unambiguosly distinguish between the legacy facade methods and the new idiomatic ones.

* Added summary to the MiniExcel facade class

The remarks explain the purpose of the class and advise the consumers of the library to favor the usage of the new `MiniExcelV2` class instead for a better user experience.

* Updated docs to reflect last changes and fixed a few minor mistakes

* Clarified the difference between the `MiniExcel` and `MiniExcelV2` classes in the upgrade notes

Author: michelebastione

README_V2.md

@@ -1,19 +1,18 @@
 ## MiniExcel 2.0 Upgrade Notes
 
 - Support for .NET Framework 4.5 was dropped, the minimum supported Framework version is now 4.6.2. 
-- The root namespace was changed from `MiniExcelLibs` to `MiniExcelLib`.  
-- Instead of having all methods being part of the `MiniExcel` static class, the functionalities are now split into 3 providers:
-`MiniExcel.Importers`, `MiniExcel.Exporters` and `MiniExcel.Templaters` will give you access to, respectively, the `MiniExcelImporterProvider`, `MiniExcelExporterProvider` and `MiniExcelTemplaterProvider`.
+- The root namespace was changed from `MiniExcelLibs` to `MiniExcelLib`; there is also a new entry point to the library, the static class `MiniExcelV2`. The original class has been turned into a facade for backwards compatibility reasons (more on that later).   
+- Instead of having all methods being part of a single static class, the functionalities are now split into 3 providers:
+`MiniExcelV2.Importers`, `MiniExcelV2.Exporters` and `MiniExcelV2.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`.
 - 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.
+- If the full MiniExcel package is downloaded, the previous namespace will coexist along the new one, containing a facade `MiniExcel` static class with all the original methods' signatures for backwards compatibility.
 - `IConfiguration` is now `IMiniExcelConfiguration`, but most methods now require the proper implementation (`OpenXmlConfiguration` or `CsvConfiguration`) to be provided rather than the interface
-- MiniExcel now fully supports asynchronous streaming the queries, 
+- MiniExcel now fully supports asynchronously streaming the queries, 
 so the return type for `OpenXmlImporter.QueryAsync` is `IAsyncEnumerable<T>` instead of `Task<IEnumerable<T>>`
 - When applying a template, unlike version 1.x, the flag for overwriting an already existing file must be provided explicitly.
-- `leaveOpen` parameter has been added to most methods that take a stream as input in both `OpenXmlImporter` and `CsvImporter` to configure whether the stream must be disposed after the operation performed is completed.   
-- `useHeaderRow` parameter in multiple `OpenXmlImporter` methods has been renamed to `hasHeaderRow` for making its usage clearer.
+- A `leaveOpen` parameter has been added to most methods that take a stream as input in both `OpenXmlImporter` and `CsvImporter` to configure whether the stream must be disposed after the operation performed is completed.   
+- The `useHeaderRow` parameter in multiple `OpenXmlImporter` and `CsvImporter` methods has been renamed to `hasHeaderRow` for making its usage clearer.
 - `CsvExporter.Export` API methods, not being required to return the same type of `OpenXmlExporter.Export`, now return `int` instead of `int[]`.
-- Most `OpenXmlImporter` and `CsvImporter` methods that take a stream as input now take an additional `leaveOpen` boolean parameter, to set to `true` explicitly if you want the stream to be left open at the of the operation.

V2-Upgrade-Notes.md

@@ -24,7 +24,7 @@ public void SetUp()
         ExcelPackage.LicenseContext = LicenseContext.NonCommercial;
         Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
 
-        _exporter = MiniExcel.Exporters.GetOpenXmlExporter();
+        _exporter = MiniExcelV2.Exporters.GetOpenXmlExporter();
 
         var simpleRegistry = new MappingRegistry();
         simpleRegistry.Configure<DemoDto>(config =>
@@ -40,7 +40,7 @@ public void SetUp()
             config.Property(x => x.Column9).ToCell("I1");
             config.Property(x => x.Column10).ToCell("J1");
         });
-        _simpleMappingExporter = MiniExcel.Exporters.GetMappingExporter(simpleRegistry);
+        _simpleMappingExporter = MiniExcelV2.Exporters.GetMappingExporter(simpleRegistry);
     }
 
     [Benchmark(Description = "MiniExcel Create Xlsx")]

benchmarks/MiniExcel.Benchmarks/BenchmarkSections/CreateExcelBenchmark.cs

@@ -23,7 +23,7 @@ public void SetUp()
         ExcelPackage.LicenseContext = LicenseContext.NonCommercial;
         Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
 
-        _importer = MiniExcel.Importers.GetOpenXmlImporter();
+        _importer = MiniExcelV2.Importers.GetOpenXmlImporter();
 
         // Setup mapping for query (matches CreateExcelBenchmark mapping)
         var registry = new MappingRegistry();
@@ -40,7 +40,7 @@ public void SetUp()
             config.Property(x => x.Column9).ToCell("I1");
             config.Property(x => x.Column10).ToCell("J1");
         });
-        _mappingImporter = MiniExcel.Importers.GetMappingImporter(registry);
+        _mappingImporter = MiniExcelV2.Importers.GetMappingImporter(registry);
     }
 
     [Benchmark(Description = "MiniExcel QueryFirst")]

benchmarks/MiniExcel.Benchmarks/BenchmarkSections/QueryExcelBenchmark.cs

@@ -22,16 +22,16 @@ public class Employee
     [GlobalSetup]
     public void Setup()
     {
-        _templater = MiniExcel.Templaters.GetOpenXmlTemplater();
-        _exporter = MiniExcel.Exporters.GetOpenXmlExporter();
+        _templater = MiniExcelV2.Templaters.GetOpenXmlTemplater();
+        _exporter = MiniExcelV2.Exporters.GetOpenXmlExporter();
 
         var registry = new MappingRegistry();
         registry.Configure<Employee>(config =>
         {
             config.Property(x => x.Name).ToCell("A2");
             config.Property(x => x.Department).ToCell("B2");
         });
-        _mappingTemplater = MiniExcel.Templaters.GetMappingTemplater(registry);
+        _mappingTemplater = MiniExcelV2.Templaters.GetMappingTemplater(registry);
     }
 
     [Benchmark(Description = "MiniExcel Fill Template")]

benchmarks/MiniExcel.Benchmarks/BenchmarkSections/TemplateExcelBenchmark.cs

@@ -12,8 +12,8 @@ public class XlsxAsyncBenchmark : BenchmarkBase
     [GlobalSetup]
     public void Setup()
     {
-        _exporter = MiniExcel.Exporters.GetOpenXmlExporter();
-        _templater = MiniExcel.Templaters.GetOpenXmlTemplater();
+        _exporter = MiniExcelV2.Exporters.GetOpenXmlExporter();
+        _templater = MiniExcelV2.Templaters.GetOpenXmlTemplater();
     }
 
     [Benchmark(Description = "MiniExcel Create Xlsx Async")]

benchmarks/MiniExcel.Benchmarks/BenchmarkSections/XlsxAsyncBenchmark.cs

@@ -0,0 +1,19 @@
+using MiniExcelLib.Core;
+
+// ReSharper disable once CheckNamespace
+namespace MiniExcelLib;
+
+public static class MiniExcelV2
+{
+    public static readonly MiniExcelExporterProvider Exporters = new();
+    public static readonly MiniExcelImporterProvider Importers = new();
+    public static readonly MiniExcelTemplaterProvider Templaters = new();
+}
+
+[Obsolete("This class will be removed in the full release, use MiniExcelV2 instead.", true)]
+public static class MiniExcel
+{
+    public static readonly MiniExcelExporterProvider Exporters = new();
+    public static readonly MiniExcelImporterProvider Importers = new();
+    public static readonly MiniExcelTemplaterProvider Templaters = new();
+}

src/MiniExcel.Core/MiniExcel.cs

@@ -6,21 +6,26 @@
 using MiniExcelLib.OpenXml.Picture;
 using Zomp.SyncMethodGenerator;
 
-using NewMiniExcel = MiniExcelLib.MiniExcel;
 using NewOpenXmlConfiguration = MiniExcelLib.OpenXml.OpenXmlConfiguration;
+using NewCsvConfiguration = MiniExcelLib.Csv.CsvConfiguration;
 using MiniExcelDataReader = MiniExcelLib.Core.MiniExcelDataReaderBase;
 
 // ReSharper disable once CheckNamespace
 namespace MiniExcelLibs;
 
+/// <summary>
+/// This class is a facade containing the methods' signatures from the V1 API, preserved for backwards compatibility.
+/// We encourage the users to take advantage of the idiomatic <see cref="MiniExcelV2"/> class instead
+/// for a compartmentalized, richer and more flexible API.
+/// </summary>
 public static partial class MiniExcel
 {
-    private static readonly OpenXmlExporter ExcelExporter = NewMiniExcel.Exporters.GetOpenXmlExporter();
-    private static readonly OpenXmlImporter ExcelImporter = NewMiniExcel.Importers.GetOpenXmlImporter();
-    private static readonly OpenXmlTemplater ExcelTemplater = NewMiniExcel.Templaters.GetOpenXmlTemplater();
+    private static readonly OpenXmlExporter ExcelExporter = MiniExcelV2.Exporters.GetOpenXmlExporter();
+    private static readonly OpenXmlImporter ExcelImporter = MiniExcelV2.Importers.GetOpenXmlImporter();
+    private static readonly OpenXmlTemplater ExcelTemplater = MiniExcelV2.Templaters.GetOpenXmlTemplater();
 
-    private static readonly CsvExporter CsvExporter = NewMiniExcel.Exporters.GetCsvExporter();
-    private static readonly CsvImporter CsvImporter = NewMiniExcel.Importers.GetCsvImporter();
+    private static readonly CsvExporter CsvExporter = MiniExcelV2.Exporters.GetCsvExporter();
+    private static readonly CsvImporter CsvImporter = MiniExcelV2.Importers.GetCsvImporter();
 
 
     [CreateSyncVersion]
@@ -62,7 +67,7 @@ public static async Task<int> InsertAsync(string path, object value, string shee
         return type switch
         {
             ExcelType.XLSX => await ExcelExporter.InsertSheetAsync(path, value, sheetName, printHeader, overwriteSheet, configuration as NewOpenXmlConfiguration, progress, cancellationToken).ConfigureAwait(false),
-            ExcelType.CSV => await CsvExporter.AppendAsync(path, value, printHeader, configuration as Csv.CsvConfiguration, progress, cancellationToken).ConfigureAwait(false),
+            ExcelType.CSV => await CsvExporter.AppendAsync(path, value, printHeader, configuration as NewCsvConfiguration, progress, cancellationToken).ConfigureAwait(false),
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -76,7 +81,7 @@ public static async Task<int> InsertAsync(this Stream stream, object value, stri
         return type switch
         {
             ExcelType.XLSX => await ExcelExporter.InsertSheetAsync(stream, value, sheetName, printHeader, overwriteSheet, configuration as NewOpenXmlConfiguration, progress, cancellationToken).ConfigureAwait(false),
-            ExcelType.CSV => await CsvExporter.AppendAsync(stream, value, configuration as Csv.CsvConfiguration, progress, cancellationToken).ConfigureAwait(false),
+            ExcelType.CSV => await CsvExporter.AppendAsync(stream, value, configuration as NewCsvConfiguration, progress, cancellationToken).ConfigureAwait(false),
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -90,7 +95,7 @@ public static async Task<int[]> SaveAsAsync(string path, object value, bool prin
         return type switch
         {
             ExcelType.XLSX => await ExcelExporter.ExportAsync(path, value, printHeader, sheetName, overwriteFile, configuration as NewOpenXmlConfiguration, progress, cancellationToken).ConfigureAwait(false),
-            ExcelType.CSV => [await CsvExporter.ExportAsync(path, value, printHeader, overwriteFile, configuration as Csv.CsvConfiguration, progress, cancellationToken).ConfigureAwait(false)],
+            ExcelType.CSV => [await CsvExporter.ExportAsync(path, value, printHeader, overwriteFile, configuration as NewCsvConfiguration, progress, cancellationToken).ConfigureAwait(false)],
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -104,7 +109,7 @@ public static async Task<int[]> SaveAsAsync(this Stream stream, object value, bo
         return type switch
         {
             ExcelType.XLSX => await ExcelExporter.ExportAsync(stream, value, printHeader, sheetName, configuration as NewOpenXmlConfiguration, progress, cancellationToken).ConfigureAwait(false),
-            ExcelType.CSV => [await CsvExporter.ExportAsync(stream, value, printHeader, configuration as Csv.CsvConfiguration, progress, cancellationToken).ConfigureAwait(false)],
+            ExcelType.CSV => [await CsvExporter.ExportAsync(stream, value, printHeader, configuration as NewCsvConfiguration, progress, cancellationToken).ConfigureAwait(false)],
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -119,7 +124,7 @@ public static async Task<int[]> SaveAsAsync(this Stream stream, object value, bo
         return type switch
         {
             ExcelType.XLSX => ExcelImporter.QueryAsync<T>(path, sheetName, startCell, !hasHeader, configuration as NewOpenXmlConfiguration, cancellationToken),
-            ExcelType.CSV => CsvImporter.QueryAsync<T>(path, !hasHeader, configuration as Csv.CsvConfiguration, cancellationToken),
+            ExcelType.CSV => CsvImporter.QueryAsync<T>(path, !hasHeader, configuration as NewCsvConfiguration, cancellationToken),
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -134,7 +139,7 @@ public static async Task<int[]> SaveAsAsync(this Stream stream, object value, bo
         return type switch
         {
             ExcelType.XLSX => ExcelImporter.QueryAsync<T>(stream, sheetName, startCell, !hasHeader, configuration as NewOpenXmlConfiguration, leaveOpen: true, cancellationToken),
-            ExcelType.CSV => CsvImporter.QueryAsync<T>(stream, !hasHeader, configuration as Csv.CsvConfiguration, leaveOpen: true, cancellationToken),
+            ExcelType.CSV => CsvImporter.QueryAsync<T>(stream, !hasHeader, configuration as NewCsvConfiguration, leaveOpen: true, cancellationToken),
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -146,7 +151,7 @@ public static IAsyncEnumerable<dynamic> QueryAsync(string path, bool useHeaderRo
         return type switch
         {
             ExcelType.XLSX => ExcelImporter.QueryAsync(path, useHeaderRow, sheetName, startCell, configuration as NewOpenXmlConfiguration, cancellationToken),
-            ExcelType.CSV => CsvImporter.QueryAsync(path, useHeaderRow, configuration as Csv.CsvConfiguration, cancellationToken),
+            ExcelType.CSV => CsvImporter.QueryAsync(path, useHeaderRow, configuration as NewCsvConfiguration, cancellationToken),
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -158,7 +163,7 @@ public static IAsyncEnumerable<dynamic> QueryAsync(this Stream stream, bool useH
         return type switch
         {
             ExcelType.XLSX => ExcelImporter.QueryAsync(stream, useHeaderRow, sheetName, startCell, configuration as NewOpenXmlConfiguration, leaveOpen: true, cancellationToken),
-            ExcelType.CSV => CsvImporter.QueryAsync(stream, useHeaderRow, configuration as Csv.CsvConfiguration,leaveOpen: true, cancellationToken),
+            ExcelType.CSV => CsvImporter.QueryAsync(stream, useHeaderRow, configuration as NewCsvConfiguration,leaveOpen: true, cancellationToken),
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -191,7 +196,7 @@ public static IAsyncEnumerable<dynamic> QueryRangeAsync(this Stream stream, bool
         return type switch
         {
             ExcelType.XLSX => ExcelImporter.QueryRangeAsync(stream, useHeaderRow, sheetName, startCell, endCell, configuration as NewOpenXmlConfiguration, leaveOpen: true, cancellationToken),
-            ExcelType.CSV => CsvImporter.QueryAsync(stream, useHeaderRow, configuration as Csv.CsvConfiguration, leaveOpen: true, cancellationToken),
+            ExcelType.CSV => CsvImporter.QueryAsync(stream, useHeaderRow, configuration as NewCsvConfiguration, leaveOpen: true, cancellationToken),
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -285,7 +290,7 @@ public static async Task<DataTable> QueryAsDataTableAsync(string path, bool useH
         return type switch
         {
             ExcelType.XLSX => await ExcelImporter.QueryAsDataTableAsync(path, useHeaderRow, sheetName, startCell, configuration as NewOpenXmlConfiguration, cancellationToken).ConfigureAwait(false),
-            ExcelType.CSV => await CsvImporter.QueryAsDataTableAsync(path, useHeaderRow, configuration as Csv.CsvConfiguration, cancellationToken).ConfigureAwait(false),
+            ExcelType.CSV => await CsvImporter.QueryAsDataTableAsync(path, useHeaderRow, configuration as NewCsvConfiguration, cancellationToken).ConfigureAwait(false),
             _ => throw new InvalidDataException($"Type {type} is not a valid Excel type")
         };
     }
@@ -298,7 +303,7 @@ public static async Task<DataTable> QueryAsDataTableAsync(this Stream stream, bo
         return type switch
         {
             ExcelType.XLSX => await ExcelImporter.QueryAsDataTableAsync(stream, useHeaderRow, sheetName, startCell, configuration as NewOpenXmlConfiguration, leaveOpen: true, cancellationToken).ConfigureAwait(false),
-            ExcelType.CSV => await CsvImporter.QueryAsDataTableAsync(stream, useHeaderRow, configuration as Csv.CsvConfiguration, leaveOpen: true, cancellationToken).ConfigureAwait(false),
+            ExcelType.CSV => await CsvImporter.QueryAsDataTableAsync(stream, useHeaderRow, configuration as NewCsvConfiguration, leaveOpen: true, cancellationToken).ConfigureAwait(false),
             _ => throw new InvalidDataException($"Excel type {type} is not a valid Excel type")
         };
     }
@@ -326,7 +331,7 @@ public static async Task<ICollection<string>> GetColumnsAsync(string path, bool
         return type switch
         {
             ExcelType.XLSX => await ExcelImporter.GetColumnNamesAsync(path, useHeaderRow, sheetName, startCell, cancellationToken).ConfigureAwait(false),
-            ExcelType.CSV => await CsvImporter.GetColumnNamesAsync(path, useHeaderRow, configuration as Csv.CsvConfiguration, cancellationToken).ConfigureAwait(false),
+            ExcelType.CSV => await CsvImporter.GetColumnNamesAsync(path, useHeaderRow, configuration as NewCsvConfiguration, cancellationToken).ConfigureAwait(false),
             _ => throw new InvalidDataException($"Excel type {type} is not a valid Excel type")
         };
     }
@@ -338,7 +343,7 @@ public static async Task<ICollection<string>> GetColumnsAsync(this Stream stream
         return type switch
         {
             ExcelType.XLSX => await ExcelImporter.GetColumnNamesAsync(stream, useHeaderRow, sheetName, startCell, leaveOpen: true, cancellationToken).ConfigureAwait(false),
-            ExcelType.CSV => await CsvImporter.GetColumnNamesAsync(stream, useHeaderRow, configuration as Csv.CsvConfiguration, leaveOpen: true, cancellationToken).ConfigureAwait(false),
+            ExcelType.CSV => await CsvImporter.GetColumnNamesAsync(stream, useHeaderRow, configuration as NewCsvConfiguration, leaveOpen: true, cancellationToken).ConfigureAwait(false),
             _ => throw new InvalidDataException($"Excel type {type} is not a valid Excel type")
         };
     }