NeoFileMagic

提供「安全、輕量、可控資源上限」的多種檔案格式讀取器， 以支援後續應用快速擷取結構化資料（目前先提供 ODS，後續會陸續擴充其他格式）。

專案一覽（3 個專案）

• NeoFileMagic（類別庫）: 核心檔案讀取框架與公開 API（目前含 ODS 模組）。
• NeoFileMagic.Tests（測試）: xUnit 測試，驗證解析正確性與安全/上限行為。
  • 內含最小 ODS 測試檔與外部資料集連結（下載測試預設略過）。
• Sample（範例）: 範例程式，展示如何載入 ODS 與讀取儲存格。

安裝

• NuGet：dotnet add package NeoFileMagic

基本使用（C#）

using NeoFileMagic.FileReader.Ods;

// 從檔案載入 ODS
var doc = NeoOds.Load("sample.ods");

// 讀取第一個工作表的 (0,0) 儲存格
var cell = doc.Sheets[0].GetCell(0, 0);
Console.WriteLine(NeoOds.OneLine(cell));

使用範例

1) 遍歷列與欄

using NeoFileMagic.FileReader.Ods;

var doc = NeoOds.Load("sample.ods");
var sheet = doc.Sheets[0];

for (int r = 0; r < sheet.RowCount; r++)
{
    var row = sheet.Rows[r];
    for (int c = 0; c < row.ColumnCount; c++)
    {
        var cell = row.Cells[c];
        // 以單行輸出：換行/Tab 摺疊為空白
        Console.Write(NeoOds.OneLine(cell));
        Console.Write('\t');
    }
    Console.WriteLine();
}

2) 安全與資源上限設定

using NeoFileMagic.FileReader.Ods;

var options = new OdsReaderOptions
{
    // 預設 true：若檔案加密則丟出 NotSupportedException
    ThrowOnEncrypted = true,

    // 控制上限，避免惡意/異常檔案造成記憶體壓力
    MaxSheets = 64,
    MaxRowsPerSheet = 100_000,
    MaxColumnsPerRow = 256,
    MaxRepeatedRows = 100_000,
    MaxRepeatedColumns = 256,
};

var doc = NeoOds.Load("sample.ods", options);

3) 以強型別模型反序列化工作表

嚴格依表頭（或 [JsonPropertyName]）對應欄位，欄位順序/缺漏或格式錯誤會拋出具體例外。 反序列化內部使用 Newtonsoft.Json 進行型別轉換。

using Newtonsoft.Json;
using NeoFileMagic.FileReader.Ods;

public sealed class Person
{
    [JsonProperty(PropertyName = "Name")] public string Name { get; set; } = string.Empty;
    [JsonProperty(PropertyName = "Age")]  public int Age  { get; set; }
}

var doc = NeoOds.Load("people.ods");
var sheet = doc.Sheets[0];
var list = NeoOds.DeserializeSheetOrThrow<Person>(sheet);
// list 為強型別結果，若欄位/資料不符會拋出 Ods* 相關例外

4) 從 URL 讀取（非同步）

using NeoFileMagic.FileReader.Ods;

var doc = await NeoOds.LoadFromUrlAsync("https://example.com/data.ods");

建置/測試：

• 還原/建置：dotnet restore、dotnet build NeoFileMagic -c Debug
• 測試：dotnet test