このプロジェクトは .NET Foundation の一部であり、行動規範の下で運営されています。

あなたのスターや寄付がMiniExcelをより良くします

はじめに

MiniExcelは、.NET向けに設計された、シンプルで効率的なExcel処理ツールです。メモリ使用量を最小限に抑えることを目的としています。

現在、ほとんどの人気フレームワークは、操作を容易にするためにExcelドキュメントの全データをメモリに読み込む必要がありますが、これによりメモリ消費の問題が発生する場合があります。MiniExcelのアプローチは異なり、データを1行ずつストリーミング処理することで、元々数百メガバイトにも及ぶ消費を数メガバイトまで削減し、メモリ不足（OOM）問題を効果的に防ぎます。

flowchart LR
    A1(["Excel analysis
process"]) --> A2{{"Unzipping
XLSX file"}} --> A3{{"Parsing
OpenXML"}} --> A4{{"Model
conversion"}} --> A5(["Output"])
    B1(["Other Excel
Frameworks"]) --> B2{{"Memory"}} --> B3{{"Memory"}} --> B4{{"Workbooks &
Worksheets"}} --> B5(["All rows at
the same time"])
    C1(["MiniExcel"]) --> C2{{"Stream"}} --> C3{{"Stream"}} --> C4{{"POCO or dynamic"}} --> C5(["Deferred execution
row by row"])
    classDef analysis fill:#D0E8FF,stroke:#1E88E5,color:#0D47A1,font-weight:bold;
    classDef others fill:#FCE4EC,stroke:#EC407A,color:#880E4F,font-weight:bold;
    classDef miniexcel fill:#E8F5E9,stroke:#388E3C,color:#1B5E20,font-weight:bold;    class A1,A2,A3,A4,A5 analysis;
    class B1,B2,B3,B4,B5 others;
    class C1,C2,C3,C4,C5 miniexcel;

特徴

メモリ消費を最小限に抑え、メモリ不足（OOM）エラーを防止し、完全なガベージコレクションを回避します
大規模データセットでのパフォーマンス向上のため、リアルタイムかつ行単位のデータ操作を可能にします
LINQによる遅延実行をサポートし、高速かつメモリ効率の良いページングや複雑なクエリを実現します
Microsoft OfficeやCOM+コンポーネント不要で軽量、DLLサイズは500KB未満です
シンプルで直感的なAPIスタイルにより、Excelの読み書きやフィル操作が簡単です

バージョン2.0プレビュー

今後のMiniExcelバージョンに向けて、新しいモジュラー型で焦点を絞ったAPI、 CoreおよびCsv機能のための個別のNugetパッケージ、IAsyncEnumerableによる非同期ストリームクエリの完全サポート、さらに多くの機能を開発中です！パッケージはプレリリースで提供予定なので、ぜひお試しのうえご意見をお聞かせください！

ご利用の際は、新しいドキュメントとアップグレードノートもぜひご確認ください。

はじめ方

Excelのインポート／クエリ

Excelのエクスポート／作成

Excelテンプレート

Excel列名／インデックス／Ignore属性

サンプル

インストール

NuGetからパッケージをインストールできます

リリースノート

リリースノートをご確認ください

TODO

TODO をご確認ください

パフォーマンス

ベンチマークのコードは MiniExcel.Benchmarks で確認できます。

パフォーマンステストに使用されたファイルは Test1,000,000x10.xlsx です。32MBのドキュメントで、1,000,000行 × 10列のセルに "HelloWorld" という文字列が入力されています。

すべてのベンチマークを実行するには、以下を使用してください:

dotnet run -project .\benchmarks\MiniExcel.Benchmarks -c Release -f net9.0 -filter * --join

最新リリースのベンチマーク結果はこちらでご覧いただけます。

Excel クエリ/インポート

#### 1. クエリを実行し、結果を強く型付けされた IEnumerable にマッピングする [[試してみる]](https://dotnetfiddle.net/w5WD1J)

より高効率のため、Stream.Query の使用を推奨します。

public class UserAccount
{
    public Guid ID { get; set; }
    public string Name { get; set; }
    public DateTime BoD { get; set; }
    public int Age { get; set; }
    public bool VIP { get; set; }
    public decimal Points { get; set; }
}
var rows = MiniExcel.Query(path);
// orusing (var stream = File.OpenRead(path))
    var rows = stream.Query();

#### 2. ヘッドを使用せずに、クエリを実行してリスト形式の動的オブジェクトにマッピングする [[試してみる]](https://dotnetfiddle.net/w5WD1J)

dynamicキーは A.B.C.D.. です

| MiniExcel | 1 | |-----------|---| | Github | 2 |


var rows = MiniExcel.Query(path).ToList();
// or
using (var stream = File.OpenRead(path))
{
    var rows = stream.Query().ToList();    Assert.Equal("MiniExcel", rows[0].A);
    Assert.Equal(1, rows[0].B);
    Assert.Equal("Github", rows[1].A);
    Assert.Equal(2, rows[1].B);
}

#### 3. 最初のヘッダー行でクエリを実行する [[試してみる]](https://dotnetfiddle.net/w5WD1J)

注意 : 同じカラム名の場合は一番右側が使用されます

入力Excel：

| Column1 | Column2 | |-----------|---------| | MiniExcel | 1 | | Github | 2 |


var rows = MiniExcel.Query(useHeaderRow:true).ToList();
// or
using (var stream = File.OpenRead(path))
{
    var rows = stream.Query(useHeaderRow:true).ToList();    Assert.Equal("MiniExcel", rows[0].Column1);
    Assert.Equal(1, rows[0].Column2);
    Assert.Equal("Github", rows[1].Column1);
    Assert.Equal(2, rows[1].Column2);
}

#### 4. クエリサポート LINQ 拡張 First/Take/Skip ...など

クエリ First

var row = MiniExcel.Query(path).First();
Assert.Equal("HelloWorld", row.A);
// orusing (var stream = File.OpenRead(path))
{
    var row = stream.Query().First();
    Assert.Equal("HelloWorld", row.A);
}

MiniExcel/ExcelDataReader/ClosedXML/EPPlusのパフォーマンス比較 queryfirst

#### 5. シート名によるクエリ

MiniExcel.Query(path, sheetName: "SheetName");
//or
stream.Query(sheetName: "SheetName");

#### 6. すべてのシート名と行をクエリする

var sheetNames = MiniExcel.GetSheetNames(path);
foreach (var sheetName in sheetNames)
{
    var rows = MiniExcel.Query(path, sheetName: sheetName);
}

#### 7. 列の取得

var columns = MiniExcel.GetColumns(path); // e.g result : ["A","B"...]var cnt = columns.Count;  // get column count

#### 8. 動的クエリで行を IDictionary にキャストする

foreach(IDictionary row in MiniExcel.Query(path))
{
    //..
}// or
var rows = MiniExcel.Query(path).Cast>();
// or Query specified ranges (capitalized)
// A2 represents the second row of column A, C3 represents the third row of column C
// If you don't want to restrict rows, just don't include numbers
var rows = MiniExcel.QueryRange(path, startCell: "A2", endCell: "C3").Cast>();

#### 9. ExcelをクエリしてDataTableを返す

推奨されません。なぜなら、DataTableはすべてのデータをメモリに読み込むため、MiniExcelの低メモリ消費という特長が失われてしまうからです。

``C# var table = MiniExcel.QueryAsDataTable(path, useHeaderRow: true);


#### 10. データの読み取りを開始するセルを指定する

csharp
MiniExcel.Query(path,useHeaderRow:true,startCell:"B3")
#### 11. 結合セルの塗りつぶし注意：結合塗りつぶしを使用しない場合 と比較して効率が遅くなります
理由：OpenXml標準ではmergeCellsがファイルの末尾に配置されるため、sheetxmlを2回foreachする必要があります
csharp
    var config = new OpenXmlConfiguration()
    {
        FillMergedCells = true
    };
    var rows = MiniExcel.Query(path, configuration: config);
可変長・可変幅の複数行・複数列の埋め込みに対応
#### 12. ディスクベースキャッシュによる大容量ファイルの読み込み（Disk-Base Cache - SharedString）
SharedStrings のサイズが 5 MB を超える場合、MiniExcel はデフォルトでローカルディスクキャッシュを使用します。例えば、10x100000.xlsx（100万行データ）の場合、ディスクキャッシュを無効にすると最大メモリ使用量は195MBですが、有効にすると65MBで済みます。ただし、この最適化には効率のコストがかかるため、このケースでは読み込み時間が7.4秒から27.2秒に増加します。必要がない場合は、次のコードでディスクキャッシュを無効にできます。csharp
var config = new OpenXmlConfiguration { EnableSharedStringCache = false };
MiniExcel.Query(path,configuration: config)
SharedStringCacheSize を使用して、ディスクキャッシュ用に指定されたサイズを超えて sharedString ファイルのサイズを変更できます。
csharp
var config = new OpenXmlConfiguration { SharedStringCacheSize=50010241024 };
MiniExcel.Query(path, configuration: config);
Excelの作成/エクスポート  
パブリックなパラメータなしコンストラクタを持つ非抽象型でなければなりません。
MiniExcelはIEnumerableの遅延実行パラメータをサポートしています。最小限のメモリを使用したい場合は、ToListなどのメソッドを呼び出さないでください。
例 : ToListを使う場合と使わない場合のメモリ使用量
#### 1. 匿名型または強い型 [[試してみる]](https://dotnetfiddle.net/w5WD1J)
csharp
var path = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid()}.xlsx");
MiniExcel.SaveAs(path, new[] {
    new { Column1 = "MiniExcel", Column2 = 1 },
    new { Column1 = "Github", Column2 = 2}
});
#### 2. IEnumerable>csharp
var values = new List>()
{
    new Dictionary{{ "Column1", "MiniExcel" }, { "Column2", 1 } },
    new Dictionary{{ "Column1", "Github" }, { "Column2", 2 } }
};
MiniExcel.SaveAs(path, values);
ファイル作成結果：
| カラム1      | カラム2 |
|-------------|---------|
| MiniExcel   | 1       |
| Github      | 2       |

#### 3.  IDataReader
推奨、すべてのデータをメモリに読み込むことを避けられます

csharp
MiniExcel.SaveAs(path, reader);
DataReaderで複数シートをエクスポート（Dapper ExecuteReader推奨）csharp
using (var cnn = Connection)
{
    cnn.Open();
    var sheets = new Dictionary();
    sheets.Add("sheet1", cnn.ExecuteReader("select 1 id"));
    sheets.Add("sheet2", cnn.ExecuteReader("select 2 id"));
    MiniExcel.SaveAs("Demo.xlsx", sheets);
}
#### 4. データテーブル非推奨、すべてのデータがメモリにロードされます
データテーブルは最初にキャプションを列名として使用し、次にカラム名を使用します
csharp
var path = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid()}.xlsx");
var table = new DataTable();
{
    table.Columns.Add("Column1", typeof(string));
    table.Columns.Add("Column2", typeof(decimal));
    table.Rows.Add("MiniExcel", 1);
    table.Rows.Add("Github", 2);
}
MiniExcel.SaveAs(path, table);
####  5. Dapper クエリ@shaofing #552 に感謝します。CommandDefinition + CommandFlags.NoCache を使用してください。
csharp
using (var connection = GetConnection(connectionString))
{
    var rows = connection.Query(
        new CommandDefinition(
            @"select 'MiniExcel' as Column1,1 as Column2 union all select 'Github',2"
            , flags: CommandFlags.NoCache)
        );
    // Note: QueryAsync will throw close connection exception
    MiniExcel.SaveAs(path, rows);
}
以下のコードはすべてのデータをメモリに読み込みますcsharp
using (var connection = GetConnection(connectionString))
{
    var rows = connection.Query(@"select 'MiniExcel' as Column1,1 as Column2 union all select 'Github',2");
    MiniExcel.SaveAs(path, rows);
}
#### 6. MemoryStreamへのSaveAs  [[試してみる]](https://dotnetfiddle.net/JOen0e)
csharp
using (var stream = new MemoryStream()) //support FileStream,MemoryStream ect.
{
    stream.SaveAs(values);
}
例：ExcelエクスポートのAPIcsharp
public IActionResult DownloadExcel()
{
    var values = new[] {
        new { Column1 = "MiniExcel", Column2 = 1 },
        new { Column1 = "Github", Column2 = 2}
    };
    var memoryStream = new MemoryStream();
    memoryStream.SaveAs(values);
    memoryStream.Seek(0, SeekOrigin.Begin);
    return new FileStreamResult(memoryStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
    {
        FileDownloadName = "demo.xlsx"
    };
}
#### 7. 複数のシートを作成する
csharp
// 1. Dictionary
var users = new[] { new { Name = "Jack", Age = 25 }, new { Name = "Mike", Age = 44 } };
var department = new[] { new { ID = "01", Name = "HR" }, new { ID = "02", Name = "IT" } };
var sheets = new Dictionary
{
    ["users"] = users,
    ["department"] = department
};
MiniExcel.SaveAs(path, sheets);
// 2. DataSet
var sheets = new DataSet();
sheets.Add(UsersDataTable);
sheets.Add(DepartmentDataTable);
//..
MiniExcel.SaveAs(path, sheets);

#### 8. TableStyles オプション
デフォルトスタイル
スタイル設定なしcsharp
var config = new OpenXmlConfiguration()
{
     TableStyles = TableStyles.None
};
MiniExcel.SaveAs(path, value,configuration:config);

#### 9. オートフィルターv0.19.0 以降、OpenXmlConfiguration.AutoFilter でオートフィルターを有効／無効にできます。デフォルト値は true であり、オートフィルターの設定方法は以下の通りです。
csharp
MiniExcel.SaveAs(path, value, configuration: new OpenXmlConfiguration() { AutoFilter = false });
#### 10. イメージの作成csharp
var value = new[] {
    new { Name="github",Image=File.ReadAllBytes(PathHelper.GetFile("images/github_logo.png"))},
    new { Name="google",Image=File.ReadAllBytes(PathHelper.GetFile("images/google_logo.png"))},
    new { Name="microsoft",Image=File.ReadAllBytes(PathHelper.GetFile("images/microsoft_logo.png"))},
    new { Name="reddit",Image=File.ReadAllBytes(PathHelper.GetFile("images/reddit_logo.png"))},
    new { Name="statck_overflow",Image=File.ReadAllBytes(PathHelper.GetFile("images/statck_overflow_logo.png"))},
};
MiniExcel.SaveAs(path, value);
#### 11. バイト配列ファイルのエクスポートバージョン1.22.0以降、値の型が byte[] の場合、システムはデフォルトでセルにファイルパスを保存し、インポート時に byte[] に変換できます。また、これを使用したくない場合は、OpenXmlConfiguration.EnableConvertByteArray を false に設定することで、システムの効率を向上させることができます。
バージョン1.22.0以降、値の型が byte[] の場合、システムはデフォルトでセルにファイルパスを保存し、インポート時に byte[] に変換できます。また、これを使用したくない場合は、OpenXmlConfiguration.EnableConvertByteArray を false に設定することで、システムの効率を向上させることができます。
#### 12. 同じセルを縦に結合する
この機能は xlsx 形式でのみサポートされており、@merge と @endmerge タグ間でセルを縦方向に結合します。
@mergelimit を使用して、セルの縦方向の結合範囲を制限できます。
csharp
var mergedFilePath = Path.Combine(Path.GetTempPath(), $"{Guid.NewGuid().ToString()}.xlsx");
var path = @"../../../../../samples/xlsx/TestMergeWithTag.xlsx";
MiniExcel.MergeSameCells(mergedFilePath, path);
csharp
var memoryStream = new MemoryStream();
var path = @"../../../../../samples/xlsx/TestMergeWithTag.xlsx";
memoryStream.MergeSameCells(path);
マージ前後のファイル内容:
マージ制限なし:
マージ制限あり:
#### 13. null値をスキップ
null値に対して空のセルを書き込むための新しい明示的オプション:csharp
DataTable dt = new DataTable();
/ ... /
DataRow dr = dt.NewRow();
dr["Name1"] = "Somebody once";
dr["Name2"] = null;
dr["Name3"] = "told me.";
dt.Rows.Add(dr);
OpenXmlConfiguration configuration = new OpenXmlConfiguration()
{
     EnableWriteNullValueCell = true // Default value.
};
MiniExcel.SaveAs(@"C:\temp\Book1.xlsx", dt, configuration: configuration);
xml

    
        Somebody once
    
    
    
        told me.
    

以前の動作:csharp
/ ... /
OpenXmlConfiguration configuration = new OpenXmlConfiguration()
{
     EnableWriteNullValueCell = false // Default value is true.
};
MiniExcel.SaveAs(@"C:\temp\Book1.xlsx", dt, configuration: configuration);
xml

    
        Somebody once
    
    
        
    
    
        told me.
    

null値およびDBNull値に対応しています。#### 14. ウィンドウ枠の固定
csharp
/ ... /
OpenXmlConfiguration configuration = new OpenXmlConfiguration()
{
    FreezeRowCount = 1,     // default is 1
    FreezeColumnCount = 2   // default is 0
};
MiniExcel.SaveAs(@"C:\temp\Book1.xlsx", dt, configuration: configuration);
Excel テンプレートへのデータ挿入 
宣言方法は Vue テンプレートの {{変数名}} や、コレクション描画の {{コレクション名.フィールド名}} と似ています

コレクション描画は IEnumerable/DataTable/DapperRow をサポートしています
#### 1. 基本的な挿入
テンプレート:
結果:
コード:csharp
// 1. By POCO
var value = new
{
    Name = "Jack",
    CreateDate = new DateTime(2021, 01, 01),
    VIP = true,
    Points = 123
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);

// 2. By Dictionary
var value = new Dictionary()
{
    ["Name"] = "Jack",
    ["CreateDate"] = new DateTime(2021, 01, 01),
    ["VIP"] = true,
    ["Points"] = 123
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);
#### 2. IEnumerable データの埋め込み
Note1: 同じ列の最初の IEnumerable をリスト埋め込みの基準として使用します
テンプレート:
結果:
コード:
csharp
//1. By POCO
var value = new
{
    employees = new[] {
        new {name="Jack",department="HR"},
        new {name="Lisa",department="HR"},
        new {name="John",department="HR"},
        new {name="Mike",department="IT"},
        new {name="Neo",department="IT"},
        new {name="Loan",department="IT"}
    }
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);
//2. By Dictionary
var value = new Dictionary()
{
    ["employees"] = new[] {
        new {name="Jack",department="HR"},
        new {name="Lisa",department="HR"},
        new {name="John",department="HR"},
        new {name="Mike",department="IT"},
        new {name="Neo",department="IT"},
        new {name="Loan",department="IT"}
    }
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);
#### 3. 複雑なデータの埋め込み
注意: 複数シートをサポートし、同じ変数を使用可能
テンプレート:
結果:
csharp
// 1. By POCO
var value = new
{
    title = "FooCompany",
    managers = new[] {
        new {name="Jack",department="HR"},
        new {name="Loan",department="IT"}
    },
    employees = new[] {
        new {name="Wade",department="HR"},
        new {name="Felix",department="HR"},
        new {name="Eric",department="IT"},
        new {name="Keaton",department="IT"}
    }
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);
// 2. By Dictionary
var value = new Dictionary()
{
    ["title"] = "FooCompany",
    ["managers"] = new[] {
        new {name="Jack",department="HR"},
        new {name="Loan",department="IT"}
    },
    ["employees"] = new[] {
        new {name="Wade",department="HR"},
        new {name="Felix",department="HR"},
        new {name="Eric",department="IT"},
        new {name="Keaton",department="IT"}
    }
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);
#### 4. ビッグデータ書き込みパフォーマンス
注: MiniExcelではIEnumerableの遅延実行（ToListを使わない）を利用することで最大メモリ使用量を節約できます
#### 5. セル値の自動型マッピング
テンプレート
結果
クラスcsharp
public class Poco
{
    public string @string { get; set; }
    public int? @int { get; set; }
    public decimal? @decimal { get; set; }
    public double? @double { get; set; }
    public DateTime? datetime { get; set; }
    public bool? @bool { get; set; }
    public Guid? Guid { get; set; }
}
コードcsharp
var poco = new TestIEnumerableTypePoco { @string = "string", @int = 123, @decimal = decimal.Parse("123.45"), @double = (double)123.33, @datetime = new DateTime(2021, 4, 1), @bool = true, @Guid = Guid.NewGuid() };
var value = new
{
    Ts = new[] {
        poco,
        new TestIEnumerableTypePoco{},
        null,
        poco
    }
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);
#### 6. 例 : Githubプロジェクトの一覧表示
テンプレート

結果
コードcsharp
var projects = new[]
{
    new {Name = "MiniExcel",Link="https://github.com/mini-software/MiniExcel",Star=146, CreateTime=new DateTime(2021,03,01)},
    new {Name = "HtmlTableHelper",Link="https://github.com/mini-software/HtmlTableHelper",Star=16, CreateTime=new DateTime(2020,02,01)},
    new {Name = "PocoClassGenerator",Link="https://github.com/mini-software/PocoClassGenerator",Star=16, CreateTime=new DateTime(2019,03,17)}
};
var value = new
{
    User = "ITWeiHan",
    Projects = projects,
    TotalStar = projects.Sum(s => s.Star)
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);
#### 7. グループ化されたデータの入力csharp
var value = new Dictionary()
{
    ["employees"] = new[] {
        new {name="Jack",department="HR"},
        new {name="Jack",department="HR"},
        new {name="John",department="HR"},
        new {name="John",department="IT"},
        new {name="Neo",department="IT"},
        new {name="Loan",department="IT"}
    }
};
await MiniExcel.SaveAsByTemplateAsync(path, templatePath, value);
##### 1. @group タグと @header タグがある場合
Before
After
##### 2. @group タグがあり、@header タグがない場合
Before
After
##### 3. @group タグがない場合
Before
After
#### 8. セル内の If/ElseIf/Else 文
ルール:
DateTime、Double、Int の型では ==、!=、>、>=、<、<= 演算子がサポートされています。
String 型では ==、!= 演算子がサポートされています。
各文は新しい行で記述してください。
演算子の前後には半角スペースを入れてください。
文の中に改行を入れないでください。
セルは以下の正確な形式で記述してください。
csharp
@if(name == Jack)
{{employees.name}}
@elseif(name == Neo)
Test {{employees.name}}
@else
{{employees.department}}
@endif
以前
以後
#### 9. DataTable をパラメータとして使用csharp
var managers = new DataTable();
{
    managers.Columns.Add("name");
    managers.Columns.Add("department");
    managers.Rows.Add("Jack", "HR");
    managers.Rows.Add("Loan", "IT");
}
var value = new Dictionary()
{
    ["title"] = "FooCompany",
    ["managers"] = managers,
};
MiniExcel.SaveAsByTemplate(path, templatePath, value);
#### 10. 数式##### 1. 例
数式の前に $ を付け、$enumrowstart と $enumrowend を使用して列挙の開始行と終了行を参照します：
テンプレートがレンダリングされると、$ プレフィックスは削除され、$enumrowstart および $enumrowend は列挙の開始行番号と終了行番号に置き換えられます：
##### 2. その他の数式例：
|              |                                                                                           |
|--------------|-------------------------------------------------------------------------------------------|
| 合計         | $=SUM(C{{$enumrowstart}}:C{{$enumrowend}})                                              |
| 平均（別例） | $=SUM(C{{$enumrowstart}}:C{{$enumrowend}}) / COUNT(C{{$enumrowstart}}:C{{$enumrowend}}) |
| 範囲         | $=MAX(C{{$enumrowstart}}:C{{$enumrowend}}) - MIN(C{{$enumrowstart}}:C{{$enumrowend}})   |

#### 11. その他
##### 1. テンプレートパラメータキーの確認
V1.24.0 以降、デフォルトではテンプレートの不足しているパラメータキーは無視され、空文字列で置き換えられます。IgnoreTemplateParameterMissing によって例外をスローするかどうか制御できます。
csharp
var config = new OpenXmlConfiguration()
{
    IgnoreTemplateParameterMissing = false,
};
MiniExcel.SaveAsByTemplate(path, templatePath, value, config)
Excel 列名／列インデックス／無視属性 
#### 1. 列名、列インデックス、列の無視を指定する
Excel例
コードcsharp
public class ExcelAttributeDemo
{
    [ExcelColumnName("Column1")]
    public string Test1 { get; set; }
    [ExcelColumnName("Column2")]
    public string Test2 { get; set; }
    [ExcelIgnore]
    public string Test3 { get; set; }
    [ExcelColumnIndex("I")] // system will convert "I" to 8 index
    public string Test4 { get; set; }
    public string Test5 { get; } //wihout set will ignore
    public string Test6 { get; private set; } //un-public set will ignore
    [ExcelColumnIndex(3)] // start with 0
    public string Test7 { get; set; }
}
var rows = MiniExcel.Query(path).ToList();
Assert.Equal("Column1", rows[0].Test1);
Assert.Equal("Column2", rows[0].Test2);
Assert.Null(rows[0].Test3);
Assert.Equal("Test7", rows[0].Test4);
Assert.Null(rows[0].Test5);
Assert.Null(rows[0].Test6);
Assert.Equal("Test4", rows[0].Test7);
#### 2. カスタムフォーマット（ExcelFormatAttribute）V0.21.0 以降は、ToString(string content) メソッドを含むクラスのフォーマットをサポート
クラス
csharp
public class Dto
{
    public string Name { get; set; }
    [ExcelFormat("MMMM dd, yyyy")]
    public DateTime InDate { get; set; }
}
コードcsharp
var value = new Dto[] {
    new Issue241Dto{ Name="Jack",InDate=new DateTime(2021,01,04)},
    new Issue241Dto{ Name="Henry",InDate=new DateTime(2020,04,05)},
};
MiniExcel.SaveAs(path, value);
結果
クエリはカスタムフォーマット変換をサポートします
#### 3. 列幅の設定（ExcelColumnWidthAttribute）csharp
public class Dto
{
    [ExcelColumnWidth(20)]
    public int ID { get; set; }
    [ExcelColumnWidth(15.50)]
    public string Name { get; set; }
}
#### 4. 複数のカラム名が同じプロパティにマッピングされる場合。csharp
public class Dto
{
    [ExcelColumnName(excelColumnName:"EmployeeNo",aliases:new[] { "EmpNo","No" })]
    public string Empno { get; set; }
    public string Name { get; set; }
}
#### 5. System.ComponentModel.DisplayNameAttribute = ExcelColumnName.excelColumnNameAttribute
バージョン1.24.0以降、システムはSystem.ComponentModel.DisplayNameAttribute = ExcelColumnName.excelColumnNameAttributeをサポートします。C#
public class TestIssueI4TXGTDto
{
    public int ID { get; set; }
    public string Name { get; set; }
    [DisplayName("Specification")]
    public string Spc { get; set; }
    [DisplayName("Unit Price")]
    public decimal Up { get; set; }
}
#### 6. ExcelColumnAttributeV1.26.0以降、複数の属性を以下のように簡略化できます：
csharp
        public class TestIssueI4ZYUUDto
        {
            [ExcelColumn(Name = "ID",Index =0)]
            public string MyProperty { get; set; }
            [ExcelColumn(Name = "CreateDate", Index = 1,Format ="yyyy-MM",Width =100)]
            public DateTime MyProperty2 { get; set; }
        }
#### 7. DynamicColumnAttribute
V1.26.0以降、Columnの属性を動的に設定できるようになりました
csharp
            var config = new OpenXmlConfiguration
            {
                DynamicColumns = new DynamicExcelColumn[] {
                    new DynamicExcelColumn("id"){Ignore=true},
                    new DynamicExcelColumn("name"){Index=1,Width=10},
                    new DynamicExcelColumn("createdate"){Index=0,Format="yyyy-MM-dd",Width=15},
                    new DynamicExcelColumn("point"){Index=2,Name="Account Point"},
                }
            };
            var path = PathHelper.GetTempPath();
            var value = new[] { new { id = 1, name = "Jack", createdate = new DateTime(2022, 04, 12) ,point = 123.456} };
            MiniExcel.SaveAs(path, value, configuration: config);
#### 8. DynamicSheetAttributeV1.31.4以降、シートの属性を動的に設定できるようになりました。シート名や状態（表示/非表示）を設定できます。csharp
            var configuration = new OpenXmlConfiguration
            {
                DynamicSheets = new DynamicExcelSheet[] {
                    new DynamicExcelSheet("usersSheet") { Name = "Users", State = SheetState.Visible },
                    new DynamicExcelSheet("departmentSheet") { Name = "Departments", State = SheetState.Hidden }
                }
            };
            var users = new[] { new { Name = "Jack", Age = 25 }, new { Name = "Mike", Age = 44 } };
            var department = new[] { new { ID = "01", Name = "HR" }, new { ID = "02", Name = "IT" } };
            var sheets = new Dictionary
            {
                ["usersSheet"] = users,
                ["departmentSheet"] = department
            };
            var path = PathHelper.GetTempPath();
            MiniExcel.SaveAs(path, sheets, configuration: configuration);
新しい属性ExcelSheetAttributeも使用できます：C#
   [ExcelSheet(Name = "Departments", State = SheetState.Hidden)]
   private class DepartmentDto
   {
      [ExcelColumn(Name = "ID",Index = 0)]
      public string ID { get; set; }
      [ExcelColumn(Name = "Name",Index = 1)]
      public string Name { get; set; }
   }
### 追加、削除、更新
#### 追加
v1.28.0 で、最後の行の後に N 行のデータを CSV に挿入することをサポートcsharp
// Origin
{
    var value = new[] {
          new { ID=1,Name ="Jack",InDate=new DateTime(2021,01,03)},
          new { ID=2,Name ="Henry",InDate=new DateTime(2020,05,03)},
    };
    MiniExcel.SaveAs(path, value);
}
// Insert 1 rows after last
{
    var value = new { ID=3,Name = "Mike", InDate = new DateTime(2021, 04, 23) };
    MiniExcel.Insert(path, value);
}
// Insert N rows after last
{
    var value = new[] {
          new { ID=4,Name ="Frank",InDate=new DateTime(2021,06,07)},
          new { ID=5,Name ="Gloria",InDate=new DateTime(2022,05,03)},
    };
    MiniExcel.Insert(path, value);
}
v1.37.0は、Excelで既存のワークブックに新しいシートを挿入することをサポートしますcsharp
// Origin excel
{
    var value = new[] {
          new { ID=1,Name ="Jack",InDate=new DateTime(2021,01,03)},
          new { ID=2,Name ="Henry",InDate=new DateTime(2020,05,03)},
    };
    MiniExcel.SaveAs(path, value, sheetName: "Sheet1");
}
// Insert a new sheet
{
    var value = new { ID=3,Name = "Mike", InDate = new DateTime(2021, 04, 23) };
    MiniExcel.Insert(path, table, sheetName: "Sheet2");
}
#### 削除（待機中）
#### 更新（待機中）
Excelタイプ自動判別 
MiniExcelはデフォルトで「ファイル拡張子」に基づいてxlsxまたはcsvかどうかを判別しますが、正確でない場合もあるため、手動で指定してください。
ストリームの場合、どのExcel形式か判別できないため、手動で指定してください。
csharp
stream.SaveAs(excelType:ExcelType.CSV);
//or
stream.SaveAs(excelType:ExcelType.XLSX);
//or
stream.Query(excelType:ExcelType.CSV);
//or
stream.Query(excelType:ExcelType.XLSX);
CSV
#### 注記デフォルトでは string 型が返され、値は数値や日付型には変換されません。強い型指定のジェネリックで型が定義されている場合を除きます。
#### カスタムセパレーターデフォルトのセパレーターは , です。カスタマイズするには Seperator プロパティを変更できます。
csharp
var config = new MiniExcelLibs.Csv.CsvConfiguration()
{
    Seperator=';'
};
MiniExcel.SaveAs(path, values,configuration: config);
V1.30.1以降、カスタムセパレーターを設定する機能が追加されました（@hyzx86に感謝）csharp
var config = new CsvConfiguration()
{
    SplitFn = (row) => Regex.Split(row, $"\"" target="_blank" rel="noopener noreferrer">\t,$)")
        .Select(s => Regex.Replace(s.Replace("\"\"", "\""), "^\"|\"$", "")).ToArray()
};
var rows = MiniExcel.Query(path, configuration: config).ToList();
#### カスタム改行デフォルトでは改行文字として \r\n が使用されますが、カスタマイズのために NewLine プロパティを変更できます
csharp
var config = new MiniExcelLibs.Csv.CsvConfiguration()
{
    NewLine='\n'
};
MiniExcel.SaveAs(path, values,configuration: config);
#### カスタムコーディング
デフォルトのエンコーディングは「バイトオーダーマークからエンコーディングを検出する」（detectEncodingFromByteOrderMarks: true）です
カスタムのエンコーディング要件がある場合は、StreamReaderFunc / StreamWriterFunc プロパティを修正してください
csharp
// Read
var config = new MiniExcelLibs.Csv.CsvConfiguration()
{
    StreamReaderFunc = (stream) => new StreamReader(stream,Encoding.GetEncoding("gb2312"))
};
var rows = MiniExcel.Query(path, true,excelType:ExcelType.CSV,configuration: config);
// Write
var config = new MiniExcelLibs.Csv.CsvConfiguration()
{
    StreamWriterFunc = (stream) => new StreamWriter(stream, Encoding.GetEncoding("gb2312"))
};
MiniExcel.SaveAs(path, value,excelType:ExcelType.CSV, configuration: config);
#### 空文字列をnullとして読み込む
デフォルトでは、空の値はstring.Emptyにマッピングされます。この動作を変更することができますcsharp
var config = new MiniExcelLibs.Csv.CsvConfiguration()
{
   ReadEmptyStringAsNull = true
};
### DataReader
#### 1. GetReader
1.23.0以降、GetDataReaderを使用できます
csharp
    using (var reader = MiniExcel.GetReader(path,true))
    {
        while (reader.Read())
        {
            for (int i = 0; i < reader.FieldCount; i++)
            {
                var value = reader.GetValue(i);
            }
        }
    }
 非同期
v0.17.0 で非同期をサポート（isdaniel ( SHIH,BING-SIOU)](https://github.com/isdaniel) に感謝）
csharp
public static Task SaveAsAsync(string path, object value, bool printHeader = true, string sheetName = "Sheet1", ExcelType excelType = ExcelType.UNKNOWN, IConfiguration configuration = null)
public static Task SaveAsAsync(this Stream stream, object value, bool printHeader = true, string sheetName = "Sheet1", ExcelType excelType = ExcelType.XLSX, IConfiguration configuration = null)
public static Task> QueryAsync(string path, bool useHeaderRow = false, string sheetName = null, ExcelType excelType = ExcelType.UNKNOWN, string startCell = "A1", IConfiguration configuration = null)
public static Task> QueryAsync(this Stream stream, string sheetName = null, ExcelType excelType = ExcelType.UNKNOWN, string startCell = "A1", IConfiguration configuration = null) where T : class, new()
public static Task> QueryAsync(string path, string sheetName = null, ExcelType excelType = ExcelType.UNKNOWN, string startCell = "A1", IConfiguration configuration = null) where T : class, new()
public static Task>> QueryAsync(this Stream stream, bool useHeaderRow = false, string sheetName = null, ExcelType excelType = ExcelType.UNKNOWN, string startCell = "A1", IConfiguration configuration = null)
public static Task SaveAsByTemplateAsync(this Stream stream, string templatePath, object value)
public static Task SaveAsByTemplateAsync(this Stream stream, byte[] templateBytes, object value)
public static Task SaveAsByTemplateAsync(string path, string templatePath, object value)
public static Task SaveAsByTemplateAsync(string path, byte[] templateBytes, object value)
public static Task QueryAsDataTableAsync(string path, bool useHeaderRow = true, string sheetName = null, ExcelType excelType = ExcelType.UNKNOWN, string startCell = "A1", IConfiguration configuration = null)
-  v1.25.0 は cancellationToken をサポートします。
その他
#### 1. 列挙型
必ず Excel とプロパティ名を同じにしてください。システムが自動的にマッピングします（大文字小文字は区別しません）
V0.18.0 以降、Enum の説明をサポートしていますcsharp
public class Dto
{
    public string Name { get; set; }
    public I49RYZUserType UserType { get; set; }
}
public enum Type
{
    [Description("General User")]
    V1,
    [Description("General Administrator")]
    V2,
    [Description("Super Administrator")]
    V3
}
バージョン1.30.0以降、ExcelのDescriptionからEnumへの対応が追加されました。@KaneLeungに感謝します。
#### 2. CSVをXLSXに変換、またはXLSXをCSVに変換csharp
MiniExcel.ConvertXlsxToCsv(xlsxPath, csvPath);
MiniExcel.ConvertXlsxToCsv(xlsxStream, csvStream);
MiniExcel.ConvertCsvToXlsx(csvPath, xlsxPath);
MiniExcel.ConvertCsvToXlsx(csvStream, xlsxStream);
`csharp
using (var excelStream = new FileStream(path: filePath, FileMode.Open, FileAccess.Read))
using (var csvStream = new MemoryStream())
{
   MiniExcel.ConvertXlsxToCsv(excelStream, csvStream);
}
#### 3. カスタム CultureInfo

1.22.0 以降、以下のようにカスタム CultureInfo を設定できます。システムのデフォルトは CultureInfo.InvariantCulture です。

var config = new CsvConfiguration()
{
    Culture = new CultureInfo("fr-FR"),
};
MiniExcel.SaveAs(path, value, configuration: config);// or
MiniExcel.Query(path, configuration: config);


#### 4. カスタムバッファサイズ
    public abstract class Configuration : IConfiguration
    {
        public int BufferSize { get; set; } = 1024 * 512;
    }
#### 5. FastMode
システムはメモリを制御しませんが、より高速な保存速度を得ることができます。
var config = new OpenXmlConfiguration() { FastMode = true };
MiniExcel.SaveAs(path, reader,configuration:config);
#### 6. 画像の一括追加（MiniExcel.AddPicture）
行データを一括生成する前に画像を追加してください。そうしないと、AddPictureを呼び出す際に大量のメモリを消費します。
var images = new[]
{
    new MiniExcelPicture
    {
        ImageBytes = File.ReadAllBytes(PathHelper.GetFile("images/github_logo.png")),
        SheetName = null, // default null is first sheet
        CellAddress = "C3", // required
    },
    new MiniExcelPicture
    {
        ImageBytes = File.ReadAllBytes(PathHelper.GetFile("images/google_logo.png")),
        PictureType = "image/png", // default PictureType = image/png
        SheetName = "Demo",
        CellAddress = "C9", // required
        WidthPx = 100,
        HeightPx = 100,
    },
};
MiniExcel.AddPicture(path, images);
#### 7. シートのサイズを取得
var dim = MiniExcel.GetSheetDimensions(path);
例：
#### 1. SQLite & Dapper 「大容量ファイル」SQL挿入でOOMを回避
注意：Queryの後にToListやToArrayメソッドを呼び出さないでください。すべてのデータがメモリに読み込まれます。
using (var connection = new SQLiteConnection(connectionString))
{
    connection.Open();
    using (var transaction = connection.BeginTransaction())
    using (var stream = File.OpenRead(path))
    {
       var rows = stream.Query();
       foreach (var row in rows)
             connection.Execute("insert into T (A,B) values (@A,@B)", new { row.A, row.B }, transaction: transaction);
       transaction.Commit();
    }
}
パフォーマンス：
#### 2. ASP.NET Core 3.1 または MVC 5 の Excel Xlsx ダウンロード/アップロード API デモ お試しはこちら
public class ApiController : Controller
{
    public IActionResult Index()
    {
        return new ContentResult
        {
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
            Content = @"
DownloadExcel

DownloadExcelFromTemplatePath

DownloadExcelFromTemplateBytes

Upload Excel

     

    

    public IActionResult DownloadExcel()
    {
        var values = new[] {
            new { Column1 = "MiniExcel", Column2 = 1 },
            new { Column1 = "Github", Column2 = 2}
        };
        var memoryStream = new MemoryStream();
        memoryStream.SaveAs(values);
        memoryStream.Seek(0, SeekOrigin.Begin);
        return new FileStreamResult(memoryStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
        {
            FileDownloadName = "demo.xlsx"
        };
    }
    public IActionResult DownloadExcelFromTemplatePath()
    {
        string templatePath = "TestTemplateComplex.xlsx";
        Dictionary value = new Dictionary()
        {
            ["title"] = "FooCompany",
            ["managers"] = new[] {
                new {name="Jack",department="HR"},
                new {name="Loan",department="IT"}
            },
            ["employees"] = new[] {
                new {name="Wade",department="HR"},
                new {name="Felix",department="HR"},
                new {name="Eric",department="IT"},
                new {name="Keaton",department="IT"}
            }
        };
        MemoryStream memoryStream = new MemoryStream();
        memoryStream.SaveAsByTemplate(templatePath, value);
        memoryStream.Seek(0, SeekOrigin.Begin);
        return new FileStreamResult(memoryStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
        {
            FileDownloadName = "demo.xlsx"
        };
    }
    private static Dictionary TemplateBytesCache = new Dictionary();
    static ApiController()
    {
        string templatePath = "TestTemplateComplex.xlsx";
        byte[] bytes = System.IO.File.ReadAllBytes(templatePath);
        TemplateBytesCache.Add(templatePath, bytes);
    }
    public IActionResult DownloadExcelFromTemplateBytes()
    {
        byte[] bytes = TemplateBytesCache["TestTemplateComplex.xlsx"];
        Dictionary value = new Dictionary()
        {
            ["title"] = "FooCompany",
            ["managers"] = new[] {
                new {name="Jack",department="HR"},
                new {name="Loan",department="IT"}
            },
            ["employees"] = new[] {
                new {name="Wade",department="HR"},
                new {name="Felix",department="HR"},
                new {name="Eric",department="IT"},
                new {name="Keaton",department="IT"}
            }
        };
        MemoryStream memoryStream = new MemoryStream();
        memoryStream.SaveAsByTemplate(bytes, value);
        memoryStream.Seek(0, SeekOrigin.Begin);
        return new FileStreamResult(memoryStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
        {
            FileDownloadName = "demo.xlsx"
        };
    }
    public IActionResult UploadExcel(IFormFile excel)
    {
        var stream = new MemoryStream();
        excel.CopyTo(stream);
        foreach (var item in stream.Query(true))
        {
            // do your logic etc.
        }        return Ok("File uploaded successfully");
    }
}
####  3. ページングクエリ
void Main()
{
    var rows = MiniExcel.Query(path);
    Console.WriteLine("==== No.1 Page ====");
    Console.WriteLine(Page(rows,pageSize:3,page:1));
    Console.WriteLine("==== No.50 Page ====");
    Console.WriteLine(Page(rows,pageSize:3,page:50));
    Console.WriteLine("==== No.5000 Page ====");
    Console.WriteLine(Page(rows,pageSize:3,page:5000));
}public static IEnumerable Page(IEnumerable en, int pageSize, int page)
{
    return en.Skip(page * pageSize).Take(pageSize);
}
#### 4. WebFormでメモリストリームを使ったExcelエクスポート
var fileName = "Demo.xlsx";
var sheetName = "Sheet1";
HttpResponse response = HttpContext.Current.Response;
response.Clear();
response.ContentType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
response.AddHeader("Content-Disposition", $"attachment;filename=\"{fileName}\"");
var values = new[] {
    new { Column1 = "MiniExcel", Column2 = 1 },
    new { Column1 = "Github", Column2 = 2}
};
var memoryStream = new MemoryStream();
memoryStream.SaveAs(values, sheetName: sheetName);
memoryStream.Seek(0, SeekOrigin.Begin);
memoryStream.CopyTo(Response.OutputStream);
response.End();

#### 5. 動的i18n多言語およびロール権限管理

例のように、i18nと権限管理を処理するメソッドを作成し、yield return を使用して IEnumerable> を返すことで、動的かつ低メモリ処理を実現します

void Main()
{
    var value = new Order[] {
        new Order(){OrderNo = "SO01",CustomerID="C001",ProductID="P001",Qty=100,Amt=500},
        new Order(){OrderNo = "SO02",CustomerID="C002",ProductID="P002",Qty=300,Amt=400},
    };
    Console.WriteLine("en-Us and Sales role");
    {
        var path = Path.GetTempPath() + Guid.NewGuid() + ".xlsx";
        var lang = "en-US";
        var role = "Sales";
        MiniExcel.SaveAs(path, GetOrders(lang, role, value));
        MiniExcel.Query(path, true).Dump();
    }
    Console.WriteLine("zh-CN and PMC role");
    {
        var path = Path.GetTempPath() + Guid.NewGuid() + ".xlsx";
        var lang = "zh-CN";
        var role = "PMC";
        MiniExcel.SaveAs(path, GetOrders(lang, role, value));
        MiniExcel.Query(path, true).Dump();
    }
}
private IEnumerable> GetOrders(string lang, string role, Order[] orders)
{
    foreach (var order in orders)
    {
        var newOrder = new Dictionary();
        if (lang == "zh-CN")
        {
            newOrder.Add("客户编号", order.CustomerID);
            newOrder.Add("订单编号", order.OrderNo);
            newOrder.Add("产品编号", order.ProductID);
            newOrder.Add("数量", order.Qty);
            if (role == "Sales")
                newOrder.Add("价格", order.Amt);
            yield return newOrder;
        }
        else if (lang == "en-US")
        {
            newOrder.Add("Customer ID", order.CustomerID);
            newOrder.Add("Order No", order.OrderNo);
            newOrder.Add("Product ID", order.ProductID);
            newOrder.Add("Quantity", order.Qty);
            if (role == "Sales")
                newOrder.Add("Amount", order.Amt);
            yield return newOrder;
        }
        else
        {
            throw new InvalidDataException($"lang {lang} wrong");
        }
    }
}public class Order
{
    public string OrderNo { get; set; }
    public string CustomerID { get; set; }
    public decimal Qty { get; set; }
    public string ProductID { get; set; }
    public decimal Amt { get; set; }
}


よくある質問
#### Q: Excelのヘッダータイトルがクラスのプロパティ名と一致しない場合、どのようにマッピングしますか？
A. ExcelColumnName属性をご利用ください
#### Q. 複数のシートをクエリまたはエクスポートする方法は？

A. GetSheetNames メソッドと Query の sheetName パラメータをご利用ください。

var sheets = MiniExcel.GetSheetNames(path);
foreach (var sheet in sheets)
{
    Console.WriteLine($"sheet name : {sheet} ");
    var rows = MiniExcel.Query(path,useHeaderRow:true,sheetName:sheet);
    Console.WriteLine(rows);
}


#### Q. シートの表示状態に関する情報を照会またはエクスポートする方法は？

A. GetSheetInformations メソッドを使用します。

var sheets = MiniExcel.GetSheetInformations(path);
foreach (var sheetInfo in sheets)
{
    Console.WriteLine($"sheet index : {sheetInfo.Index} "); // next sheet index - numbered from 0
    Console.WriteLine($"sheet name : {sheetInfo.Name} ");   // sheet name
    Console.WriteLine($"sheet state : {sheetInfo.State} "); // sheet visibility state - visible / hidden
}


#### Q. Countを使用するとすべてのデータがメモリにロードされますか？
いいえ、イメージテストは100万行×10列のデータで、最大メモリ使用量は60MB未満、所要時間は13.65秒です
#### Q. Queryはどのように整数インデックスを使用しますか？
Queryのデフォルトインデックスは文字列キー：A,B,C...です。数値インデックスに変更したい場合は、以下のメソッドを作成して変換してください
void Main()
{
    var path = @"D:\git\MiniExcel\samples\xlsx\TestTypeMapping.xlsx";
    var rows = MiniExcel.Query(path,true);
    foreach (var r in ConvertToIntIndexRows(rows))
    {
        Console.Write($"column 0 : {r[0]} ,column 1 : {r[1]}");
        Console.WriteLine();
    }
}
private IEnumerable> ConvertToIntIndexRows(IEnumerable

MiniExcel

はじめに

特徴

バージョン2.0プレビュー

はじめ方

インストール

リリースノート

TODO

パフォーマンス

Excel クエリ/インポート

Excelの作成/エクスポート

Excel テンプレートへのデータ挿入

Excel 列名／列インデックス／無視属性

Excelタイプ自動判別

CSV

非同期

その他

例：

よくある質問

制限事項および注意点

参考

謝辞

貢献共有・寄付

コントリビューター