MrHihi.HiUtility 2.0.0

HiUtility

HiUtility 是一個適用於 C# 專案的實用工具函式庫，提供文字處理、加密、Excel 匯出與網路通訊等常用功能。

安裝

從 NuGet 安裝 MrHihi.HiUtility：

dotnet add package MrHihi.HiUtility

目前套件以 net10.0 為目標框架。各功能位於以下 namespace：

using MrHihi.HiUtility.Cryptography;
using MrHihi.HiUtility.Excel;
using MrHihi.HiUtility.Net;
using MrHihi.HiUtility.Text;

Text 文字工具

TextExtensions 提供 Base64、字串重複及逐行文字差異比對；預設使用 UTF-8，也可以指定其他編碼。

var encoded = "Hello HiUtility".ToBase64();
var text = encoded.GetStrFromBase64();
var stream = encoded.Base64ToStream();
var repeated = "Hi".Repeat(3); // HiHiHi

var differences = "A\nB".CompareTextLine("A\nC");

DynamicJsonConverter.Options 可搭配 System.Text.Json，將 JSON 物件讀取為 dynamic/ExpandoObject 結構：

using System.Text.Json;

var value = JsonSerializer.Deserialize<dynamic>(
    "{\"name\":\"HiUtility\"}",
    DynamicJsonConverter.Options);

Cryptography 加密工具

BCrypt

Bcrypt 提供密碼雜湊與驗證：

IHash bcrypt = new Bcrypt();
var hash = bcrypt.Hash("secret");
var valid = bcrypt.Verify("secret", hash);

AES-256

Aes256crypt 提供字串 AES-256 加解密。加密結果為 Base64 字串，解密時必須使用相同 key。

ISymmetric aes = new Aes256crypt();
var encrypted = aes.Encrypt("Hello", "12345678901234567890123456789012");
var plainText = aes.Decrypt(encrypted, "12345678901234567890123456789012");

RSA

RSAcrypt 支援產生 key pair、RSA SHA-256/PKCS#1 簽章與驗章：

IAsymmetric rsa = new RSAcrypt();
var keys = rsa.GenerateKeyPair();
var signature = rsa.Sign("Hello", keys.privateKey);
var valid = rsa.Verify("Hello", signature, keys.publicKey);

RSAcrypt.ConvertToBase64String 與 ConvertFromBase64String 可在 RSAParameters 和函式庫使用的 Base64 key 格式間轉換。私鑰應妥善保存，不要提交至版本控制。

Excel 匯出

ExcelTool 使用 ClosedXML 建立一個或多個 worksheet，支援 strong type 物件集合與 IDictionary<string, object> dynamic 資料，並可輸出至 Stream 或檔案。

var data = new Dictionary<string, IEnumerable<object>>
{
    ["Users"] = new[]
    {
        new { Name = "SuperUser", Age = 18 },
        new { Name = "Admin", Age = 20 }
    }
};

using var excel = new ExcelTool(data, (workbook, worksheet, columns) =>
{
    worksheet.RangeUsed()?.SetAutoFilter();
});

await using var stream = await excel.Export();

Strong type 的 property 可以使用 ExcelColumnAttribute 控制欄位：

public class User
{
    [ExcelColumn(width: 24)]
    public string Name { get; set; } = "";

    [ExcelColumn(ignored: true)]
    public string InternalId { get; set; } = "";

    [ExcelColumn(zeroToEmpty: true)]
    public int Age { get; set; }
}

ExcelColumnAttribute 支援 Width、Ignored 與 ZeroToEmpty；post-processing callback 可在資料填入後調整 worksheet 格式。

Net 網路工具

HTTP

HttpUtil 提供共用 HttpClient、GET、POST、query string、JSON content、JSON 反序列化、Basic Authentication 與 headers 管理。

var http = HttpUtil.Http(new Uri("https://example.com"))
    .SetBasicAuth("user", "password");

var response = http.Get("/api/items", new Dictionary<string, string>
{
    ["page"] = "1"
});
var rawJson = http.GetRaw("/api/items", null);

AjaxUtil 繼承 HttpUtil，針對 JSON API 提供泛型 GET/POST：

var ajax = AjaxUtil.Ajax(new Uri("https://example.com"));
var result = ajax.Get<MyResponse>("/api/items");

SMTP 郵件

MailUtil 支援 SMTP 認證、SSL、收件者、Cc、純文字內容與 Stream/檔案附件。

var smtp = new MailUtil.SmtpInfo
{
    SmtpServer = "smtp.example.com",
    SmtpPort = 587,
    UserName = "sender@example.com",
    Password = "password",
    UseSSL = true
};

var message = new MailUtil.MessageInfo
{
    Sender = "sender@example.com",
    Reciver = new List<string> { "receiver@example.com" },
    Subject = "Hello",
    Content = "Hello from HiUtility"
};

MailUtil.SendMail(smtp, message);

Ping

NetUtil.Ping 可對指定主機執行 ping，並回傳 PingReply：

var reply = NetUtil.Ping("example.com");

開發指令

專案根目錄提供 Makefile，預設指令是 help：

make
make help
make build
make test

發佈至 NuGet

先複製 .env.example 為 .env，再填入 NuGet API key：

cp .env.example .env
# 編輯 .env：NUGET_API_KEY=your-nuget-api-key
make publish

make publish 會依序執行 Release build、test、pack，最後推送至 NuGet.org。.env 只供本機使用，請勿提交或分享。

License

本專案採用 MIT License。