Azure SDK documentation updateで示された今回の変更は、通常のアプリ開発者がすぐにコードを書き換える更新ではなく、TypeSpecからAzure SDK for .NETの生成コードを作るチームが確認すべき、C#クライアント生成系の更新です。特に、@azure-typespec/http-client-csharpを使ってSDKを再生成している場合、If-MatchやIf-None-Matchなどの条件付きリクエストヘッダーとAzure.Core.eTagの扱いを確認する必要があります。
今回の要点は、@azure-typespec/http-client-csharpの参照が prerelease 1.0.0-alpha.20260504.2 に更新され、Azure.Core.eTagを使う生成済みRestClientで不正な.Value参照が出る問題に対応した点です。GitHub上では、関連するPR #58950は「Generated by branded – http-client-csharp build 20260504.2」とされ、PR #58935をトリガーとして生成された更新であることが確認できます。なお、PR #58950自体はClosedであり、実装上の修正はPR #58935側でマージされています。(GitHub)
Azure SDK documentation updateで何が変わったのか
今回のAzure SDK documentation updateで注目すべき変更は、azure-sdk-for-netリポジトリ内のC#向けTypeSpecエミッター構成です。ファイル差分では、eng/azure-typespec-http-client-csharp-emitter-package.jsonにおいて、@azure-typespec/http-client-csharpの参照が以前の1.0.0-alpha.20260428.2から、1.0.0-alpha.20260504.2のtarball参照へ変更されています。あわせて、@azure-tools/typespec-client-generator-coreも0.67.3から0.67.4へ更新されています。(GitHub)
この更新は、単なるドキュメント文言の修正ではありません。TypeSpecからC#のAzure SDKクライアントを生成する際の出力に影響する、コード生成基盤の更新です。
変更点の整理
| 項目 | 変更内容 | 確認すべき人 |
|---|---|---|
@azure-typespec/http-client-csharp | prerelease 1.0.0-alpha.20260504.2へ更新 | TypeSpecから.NET SDKを生成しているチーム |
@azure-tools/typespec-client-generator-core | 0.67.4へ更新 | 生成ツールの依存関係を管理する担当者 |
MatchConditionsHeadersVisitor | ETag条件付きヘッダーの生成処理を修正 | C#生成コードのレビュー担当者 |
| 生成済みSDKコード | 複数サービスのGenerated配下に差分 | Azure SDK for .NETのサービス別メンテナー |
| 回帰テスト | If-Match / If-None-MatchとAzure.Core.eTagのケースを追加 | CI・品質保証担当者 |
背景にある問題：Azure.Core.eTagで不正なC#コードが生成されるケース
今回の更新で重要なのは、Azure.Core.eTagスカラーを使う条件付きヘッダーの生成です。関連Issueでは、If-MatchやIf-None-MatchヘッダーにAzure.Core.eTagを使うと、生成されたRestClient内で次のような不正なコードが出る問題が報告されていました。(GitHub)
request.Headers.Add("If-Match", TypeFormatters.ConvertToString(ifMatch).Value);このコードは、TypeFormatters.ConvertToString(ifMatch)が文字列を返すにもかかわらず、その後ろに.Valueを付けているため、C#コンパイル時にCS1061が発生します。Issueでは、stringにはValueの定義がないというエラーが明記されています。(GitHub)
修正後の意図は、ラップされた文字列式ではなく、変換後のETag?パラメーター側から.Valueを参照することです。PR #58935の説明では、出力が次のように整理されるとされています。(GitHub)
request.Headers.Add("If-Match", ifMatch.Value);この差は小さく見えますが、SDK生成では大きな意味があります。生成コードがコンパイルできなければ、SDKのビルド、テスト、リリースパイプラインが止まるためです。
誰が対応すべきか
今回のAzure SDK documentation updateは、すべてのAzure利用者に影響する更新ではありません。対応優先度が高いのは、次のようなチームです。
対応が必要な可能性が高いケース
- TypeSpecからAzure SDK for .NETを生成している
@azure-typespec/http-client-csharpを使っているtsp-location.yamlやエミッター用package.jsonを管理しているIf-Match、If-None-Match、ETag、条件付き更新、楽観的同時実行制御を扱うAPIを持っている- 生成済みコードで
CS1061や.Value関連のコンパイルエラーに遭遇している sdk/**/src/Generated配下の差分レビューを担当している
すぐに対応しなくてもよいケース
| 利用状況 | 対応要否 |
|---|---|
| NuGetで公開済みのAzure SDKだけをアプリから利用している | 原則として直接対応は不要 |
| TypeSpecやSDK生成を使っていない | 対応不要 |
| C#ではなくJavaScript、Python、Javaなど別言語SDKのみを扱う | 今回のC#生成問題としては優先度低め |
| 既存コードでETag条件付きヘッダーを使っていない | 影響は限定的 |
ただし、公開済みAzure SDKの利用者でも、今後リリースされるSDKで生成コード由来の差分が入る可能性はあります。アプリ側で独自に生成コードを取り込んでいる場合は、ビルド結果を確認してください。
影響範囲：生成コードと条件付きヘッダーを中心に確認する
PR #58950のファイル一覧では、eng配下のエミッター構成に加えて、複数サービスのsrc/Generated配下に差分が出ています。例として、AI、Anomaly Detector、App Configuration、Batch、Cognitive Language、Communication、Content Safety、Document Intelligence、Event Grid、Key Vault、Monitor、Purview、Search、Translation、Visionなどの生成コードが一覧に含まれています。(GitHub)
ここで重要なのは、「一覧にあるサービスすべてで実害が出る」という意味ではないことです。多くはエミッター更新に伴う再生成差分です。実務では、次の観点で絞り込むと確認しやすくなります。
| 確認観点 | 見るべき場所 | 判断基準 |
|---|---|---|
| ETag条件付きヘッダー | src/Generated配下のRequest生成処理 | If-Match / If-None-Matchの出力が妥当か |
| コンパイルエラー | CI、ローカルビルドログ | CS1061や.Value関連エラーが消えているか |
| 差分の大きさ | Git diff | 意図しない公開API変更がないか |
| 生成ツールの参照 | eng/azure-typespec-http-client-csharp-emitter-package.json | 期待するエミッター版を参照しているか |
| テスト | 条件付きリクエストの単体・回帰テスト | ETagのnull時・指定時でヘッダー出力が正しいか |
移行・設定確認の手順
TypeSpecベースで.NET SDKを生成している場合は、いきなり本番ブランチへ反映するのではなく、生成環境、差分、ビルド、テストの順に確認するのが安全です。
手順表
| 手順 | 作業 | 目的 |
|---|---|---|
| 1 | eng/azure-typespec-http-client-csharp-emitter-package.jsonを確認 | @azure-typespec/http-client-csharpの参照先を把握する |
| 2 | package-lock.jsonの差分を確認 | 依存関係の更新範囲を確認する |
| 3 | tsp-location.yamlのemitterPackageJsonPathを確認 | 正しいエミッター構成を使っているか確認する |
| 4 | SDKを再生成 | 新しいエミッターで生成結果を作る |
| 5 | src/Generatedの差分をレビュー | 生成コードの変化を確認する |
| 6 | dotnet buildを実行 | コンパイルエラーがないか確認する |
| 7 | ETag関連テストを追加・実行 | 条件付きヘッダーの退行を防ぐ |
Azure SDK for .NETのData Plane Code Generation Quickstartでは、新しいデータプレーンサービスについて、tsp-location.yamlのemitterPackageJsonPathにeng/azure-typespec-http-client-csharp-emitter-package.jsonを設定する流れが説明されています。また、SDKプロジェクトのsrc配下でdotnet build /t:GenerateCodeを実行して生成する手順も示されています。(GitHub)
dotnet build /t:GenerateCode生成時の詳細を追いたい場合は、トレース付きで実行します。
dotnet build /t:GenerateCode /p:Trace=true -v dレビュー時に見るべき具体的なコードパターン
今回の更新では、MatchConditionsHeadersVisitorの処理が変更され、単一の条件付きヘッダーに対して、元のヘッダー値式ではなく、変換後のマッチ条件パラメーターから.Valueを参照する方向に修正されています。PR差分では、ExtractHeaderInfoがExtractHeaderNameへ整理され、不要になったヘッダー値の取り回しが削除されています。(GitHub)
レビューでは、次のような不正パターンが残っていないかを確認します。
TypeFormatters.ConvertToString(ifMatch).Value
TypeFormatters.ConvertToString(ifNoneMatch).Value期待される形は、次のようにETag?パラメーター側の値を使うコードです。
if ((ifMatch != null))
{
request.Headers.Add("If-Match", ifMatch.Value);
}PR #58950のテストデータにも、If-MatchとIf-None-MatchでETag?を受け取り、nullでない場合にrequest.Headers.Add(..., ifMatch.Value)またはifNoneMatch.Valueを追加する期待出力が含まれています。(GitHub)
実務で失敗しやすいポイント
prereleaseを安定版のように扱わない
1.0.0-alpha.20260504.2はalpha付きのprereleaseです。生成結果の差分が大きくなる可能性があるため、安定版SDKの利用者向けに「必ず更新すべき」と案内するのは避けるべきです。
特に、社内テンプレートやCIでエミッター版を固定している場合、prerelease更新を取り込む前に、生成コードの差分レビューとビルド確認を必ず行ってください。
生成コードを手で直して終わらせない
src/Generated配下のコードを直接修正しても、次回の生成で上書きされます。TypeFormatters.ConvertToString(...).Valueのような問題を見つけた場合は、生成結果だけでなく、エミッター版、TypeSpec定義、生成設定を確認する必要があります。
ETagのケースだけでテストを終えない
今回の主な修正点はETagですが、生成ツールの更新では周辺の生成結果も変わることがあります。最低限、次の観点を確認しましょう。
| 確認項目 | 理由 |
|---|---|
| 条件付きヘッダー | 今回の中心的な修正箇所 |
| public API差分 | 利用者に影響する変更を検出するため |
| serialization/deserialization | 生成コード更新で影響が出やすい |
| null処理 | ETagや任意ヘッダーで退行しやすい |
| CIの全体ビルド | 単体ファイルだけでは検出できない問題がある |
Azure SDK利用者が今すぐ確認すべきこと
通常のアプリ開発者は、まず自分が「SDKを使っているだけ」なのか「SDKを生成している」のかを切り分けてください。
SDKを使っているだけの場合
NuGetでAzure.*パッケージを参照しているだけなら、今回の更新を理由にすぐコードを変更する必要は基本的にありません。対応すべきことは、利用中パッケージのリリースノート確認と、通常のアップデート前検証です。
SDKを生成している場合
TypeSpecからAzure SDK for .NETを生成している場合は、次の順で確認してください。
@azure-typespec/http-client-csharpの参照バージョンを確認するIf-Match/If-None-Matchを使うAPIがあるか確認するdotnet build /t:GenerateCodeで再生成するTypeFormatters.ConvertToString(...).Valueが残っていないか検索する- 生成後の
src/Generated差分をレビューする - CIで全体ビルドと回帰テストを通す
検索コマンドの例です。
grep -R "TypeFormatters.ConvertToString(.*).Value" ./sdkWindows環境でPowerShellを使う場合は、次のように確認できます。
Select-String -Path .\sdk\**\*.cs -Pattern "TypeFormatters\.ConvertToString\(.*\)\.Value"ヒットしなければ必ず安全というわけではありませんが、今回の既知パターンを素早く確認するには有効です。
まとめ：今回の更新は「生成環境の健全性」を確認するサイン
Azure SDK documentation update: Update azure-typespec/http-client-csharp version to prerelease 1.0.0-alpha.20260504.2は、一般的なAzure SDK利用者向けの大規模な移行告知というより、TypeSpecからC# SDKを生成する環境で、ETag条件付きヘッダーの生成不具合を解消するための重要な更新です。
最初に確認すべきことは、自分のプロジェクトが@azure-typespec/http-client-csharpでSDKを生成しているかどうかです。該当する場合は、エミッター参照、tsp-location.yaml、生成コード差分、If-Match / If-None-Match周辺のビルド結果を確認してください。該当しない場合は、今後のAzure SDK for .NETリリースで関連差分が入る可能性を把握しつつ、通常のアップデート検証で十分です。
コメント