Save()・SaveAsync() の使い分け

ライブラリ HtmlAgilityPack（HAP）における「ドキュメントの保存・出力」機能の中で、Save() メソッドと SaveAsync() メソッドの使い分けは、同期処理と非同期処理の違いに基づいています。以下にそれぞれの詳細と、使い分けの判断基準を説明します。

---

1. Save() メソッド：同期保存

概要

Save() メソッドは 同期的（blocking）にHTMLドキュメントを保存します。処理が完了するまで次のコードには進まず、UIスレッドやメインスレッドで使用する場合は一時的にアプリケーションが停止して見えることもあります。

使用例

csharp
HtmlDocument doc = new HtmlDocument();
doc.Load("input.html");
doc.Save("output.html");

特徴

• ファイル、Stream、TextWriter などに出力可能

• 小規模な処理やスクリプト的な用途に適している

• エラー処理は try-catch により実装可能

適した用途

• コンソールアプリケーションなどで、UIのレスポンス性を気にしない場合

• 保存処理が非常に軽い場合（ローカルファイルへ即時保存など）

---

2. SaveAsync() メソッド：非同期保存

概要

SaveAsync() メソッドは 非同期的にHTMLドキュメントを保存します。主に UIアプリケーションやWebアプリケーションにおいて、アプリケーションの応答性を維持するために使用されます。

使用例（async/await を利用）

csharp
HtmlDocument doc = new HtmlDocument();
doc.Load("input.html");

using (var stream = new FileStream("output.html", FileMode.Create))
{
    await doc.SaveAsync(stream);
}

特徴

• Task を返す非同期メソッドであり、await を用いて呼び出す

• UIフリーズを防止

• I/O待機中に他の処理が並行して動作可能

適した用途

• Windows Forms/WPF/UWP アプリケーション

• ASP.NET などのWebアプリケーション

• 大規模データの書き込み、またはネットワーク越しの保存処理など

---

3. 使い分けの指針

---

4. 注意点

• SaveAsync() を使うには .NET Standard 2.1 以上、または .NET Core / .NET 5+ が推奨されます。

• 非同期メソッドを呼び出すには、呼び出し元も async 修飾子を持つ必要があります。

• SaveAsync() では書き込み先が Stream または TextWriter である必要があります。ファイルパスの直接指定はできません（手動で FileStream を作成する必要があります）。

---

以上が、HtmlAgilityPack における Save() と SaveAsync() の使い分けに関する詳細な説明です。目的や処理の特性に応じて適切なメソッドを選択することが重要です。