Azure Files 新 SDK（Azure.Storage.Files.Shares）移行時にハマったポイントまとめ
はじめに
Azure Files を .NET アプリケーションから操作する場合、
従来は Microsoft.WindowsAzure.Storage（旧 SDK）を利用しているケースが多くありました。
しかし現在は、
Azure.Storage.Files.Shares（いわゆる v12 系の新 SDK） への移行が推奨されています。
本記事では、
実際に 旧 SDK → 新 SDK へ移行した際に発生した事象 と、
調査・整理したポイントを備忘録としてまとめます。
前提環境
- アプリケーション種別
- Console Application
- .NET バージョン
- 旧 SDK：.NET Framework 4.7.2
- 新 SDK：.NET 6 / 7 / 8
- 利用サービス
- Azure Files（SMB）
- SDK
- 旧：Microsoft.WindowsAzure.Storage
- 新：Azure.Storage.Files.Shares
旧 SDK と新 SDK の大きな違い
API 設計の違い
| 観点 | 旧 SDK | 新 SDK |
|---|---|---|
| 名前空間 | Microsoft.WindowsAzure.Storage | Azure.Storage.Files.Shares |
| API | 同期 API が中心 | 非同期 API が前提 |
| 例外設計 | 比較的寛容 | REST API の結果を厳密に反映 |
新 SDK は Azure Storage REST API の挙動をより正確に反映 する設計になっており、
「今まで通っていた処理が例外になる」ケースが発生し得ます。
新 SDK の最小構成サンプル（Console App）
using Azure.Storage.Files.Shares;
string connectionString =
"DefaultEndpointsProtocol=https;" +
"AccountName=<account>;" +
"AccountKey=<key>;" +
"EndpointSuffix=core.windows.net;";
var serviceClient = new ShareServiceClient(connectionString);
var shareClient = serviceClient.GetShareClient("share-name");
if (!shareClient.Exists())
{
Console.WriteLine("Share does not exist");
return;
}
var rootDir = shareClient.GetRootDirectoryClient();
var subDir = rootDir.GetSubdirectoryClient("input");
ポイント
-
Azure.Storage.Files.Shares（新 SDK）は仕様準拠で挙動が厳密
- Azure Storage REST API の結果をそのまま反映する設計
- 旧 SDK より例外が発生しやすい
-
GetSubdirectoryClient()は存在確認を行わない- クライアント生成のみ
- 実在チェックが必要な場合は
Exists()を明示的に呼ぶ必要あり
-
旧 SDK の「動いていた」は仕様保証ではない
- 0 バイトファイルなどの境界値は特に注意
- 実装上たまたま通っていただけの可能性がある
移行時の注意点
1. 旧 SDK で問題なかった処理を前提にしない
- 新 SDK では以下のケースで例外が発生しやすい
- 0 バイトファイルの作成・アップロード
- 存在しないディレクトリへの操作
- 権限不足・アクセス拒否時の処理
2. 事前チェックを必ず実装する
0 バイトファイルのチェック
if (fileSize == 0)
{
// スキップ、ログ出力、またはエラー扱いなど
}
調査・説明時の整理ポイント
調査や説明を行う際は、以下を分けて整理するとよいです。
公式にサポートされている仕様
- Microsoft Learn や公式ドキュメントに明記されている挙動
- サポート可否を明確に判断できる内容
- 将来的な SDK 更新でも前提として扱えるもの
実装上の挙動（ドキュメントに根拠がないもの）
- 公式ドキュメントに明記されていないが、実際には動作している挙動
- 旧 SDK の実装に依存して「たまたま動いていた」可能性があるもの
- 新 SDK では例外やエラーとして扱われる可能性があるもの
まとめ
-
Azure Files の新 SDK（Azure.Storage.Files.Shares）は
より厳密で仕様に忠実な挙動を採用している -
旧 SDK から移行する際は、次の点を重点的に確認することが重要
- 暗黙に通っていた処理
- 境界値（特に 0 バイトファイル）
-
「旧 SDK で問題なかった」という事実は、
新 SDK でも同様に動作することを保証するものではないということで、新SDKに行こうする際は、想定された動作をするのかを確認し、
新SDKの挙動にあった処理を実装するようにしましょう。