Azure REST API documentation update: Remove @azure-tools/typespec-csharp from all tspconfig.yaml files は、Azure REST API仕様をTypeSpecで管理しているチーム向けの設定整理です。結論から言うと、Azure REST APIを呼び出している一般のアプリ開発者が、すぐにREST APIのエンドポイントや認証方式を変更する必要はありません。対応が必要なのは、Azure REST API仕様リポジトリ、TypeSpec、C# SDK生成、CI検証に関わる担当者です。
今回のポイントは、非推奨になったC# emitterである @azure-tools/typespec-csharp を tspconfig.yaml から取り除き、C#生成が必要な仕様では @azure-typespec/http-client-csharp または @azure-typespec/http-client-csharp-mgmt にそろえることです。Azure REST API仕様リポジトリは、Microsoft AzureのREST API仕様の正本として位置付けられているため、ここでの設定変更はSDK生成やAPI仕様レビューの流れに影響します。(GitHub)
Azure REST API documentation updateで何が変わったか
今回の更新は、REST APIそのものの仕様変更というより、Azure REST API仕様を生成・検証するためのTypeSpec設定ファイルの整理です。
対象になるのは主に tspconfig.yaml です。TypeSpecでは、このファイルにコンパイラ設定やemitterの出力先、生成オプションなどを記述します。TypeSpecの公式ドキュメントでも、tspconfig.yaml はTypeSpecコンパイラの設定ファイルとして説明されており、client emitterの設定もこのファイルに置かれます。(Typespec)
GitHubのPRでは、非推奨の @azure-tools/typespec-csharp に関する有効な設定ブロック、コメントアウトされた設定、emit: リスト内の記述、コメントだけの案内文まで削除対象として説明されています。初期説明では70ファイル、428行の削除が示されていました。(GitHub)
ただし、実務上は「古いemitter名を新しいemitter名へ機械的に置換すれば終わり」ではありません。PRの後続更新では、C#生成が必要な仕様には新しいemitter設定を追加し、resource-manager系では管理プレーン向けの @azure-typespec/http-client-csharp-mgmt を使う調整も行われています。(GitHub)
変更前後の違い
今回のAzure REST API documentation updateを理解するうえで、まずは旧設定と新設定の対応関係を押さえておきましょう。
| 観点 | 変更前 | 変更後 | 確認ポイント |
|---|---|---|---|
| C#生成用emitter | @azure-tools/typespec-csharp | 原則として @azure-typespec/http-client-csharp | data-planeのC#クライアント生成が必要な場合に使用 |
| 管理プレーン向けC#生成 | 旧emitterまたは不適切な新emitter設定 | @azure-typespec/http-client-csharp-mgmt | resource-manager / ARM系の仕様ではこちらを確認 |
emit: リスト | 古いemitter名が残っている可能性 | 古いemitter名を削除 | コメントアウトされた行も検索対象にする |
options: ブロック | 古いemitter名の配下に出力先やnamespaceを記述 | 新しいemitter名の配下に必要な設定を記述 | namespace と emitter-output-dir の引き継ぎミスに注意 |
| コメント・案内文 | 「この行をコメント解除して…」のような古い案内が残る可能性 | 古いemitterへの言及を削除 | 将来の誤設定を防ぐためコメントも更新する |
PRの概要でも、非推奨の @azure-tools/typespec-csharp 設定を削除し、必要な箇所では @azure-typespec/http-client-csharp と @azure-typespec/http-client-csharp-mgmt に標準化する方針が説明されています。(GitHub)
対応が必要な人、不要な人
この更新は、Azure REST APIを使うすべての開発者に同じ影響があるわけではありません。影響範囲を切り分けると、対応の優先度が分かります。
| 立場 | 対応要否 | やるべきこと |
|---|---|---|
| Azure REST API仕様のメンテナー | 必要 | 自分のサービス配下の tspconfig.yaml に古いemitter参照が残っていないか確認する |
| TypeSpecでAzure API仕様を管理している開発者 | 必要 | C#生成が必要かを判断し、必要なら新emitter設定へ移行する |
| Azure SDK生成パイプラインの担当者 | 必要 | CI、検証ツール、スクリプトが旧emitter名に依存していないか確認する |
| C# SDKの生成結果をレビューする担当者 | 必要 | namespace、出力先、生成差分を確認する |
| Azure REST APIを呼び出すだけのアプリ開発者 | 多くの場合不要 | REST APIのURL、HTTPメソッド、認証、リクエスト形式に直接影響がないかだけ確認する |
| Swagger / OpenAPI中心で、TypeSpec C#生成を使っていないチーム | 多くの場合影響小 | CI上はno-opになり得るが、設定ファイルに古いコメントが残っていないかは確認する |
PR内のレビューコメントでは、まだSwaggerベースのライブラリについてはCIチェック上はno-opかという確認に対し、PR作成者が「Correct」と回答しています。つまり、TypeSpec C# emitterを実際に使っていない領域では、実害よりも設定の整合性確認が中心になります。(GitHub)
まず確認すべきファイルと検索コマンド
自分のリポジトリやforkで対応する場合は、最初に「古いemitter名がどこに残っているか」を洗い出します。ポイントは、有効な設定だけでなく、コメントアウトや説明文も検索することです。
git grep -n "@azure-tools/typespec-csharp"@azure-tools/typespec-csharp が見つかったら、次の観点で分類します。
| 見つかった場所 | 判断 |
|---|---|
emit: リスト内 | C#生成を実行する設定の可能性が高い。新emitterへ移行するか、生成不要なら削除する |
options: 配下 | 出力先やnamespaceなどの設定。新emitterへ引き継ぐ前に、本当にC#生成が必要か確認する |
| コメントアウトされた設定 | 将来の誤使用を防ぐため削除または新emitter名へ更新する |
| READMEや手順書 | 開発者が古い手順を使わないよう修正する |
| CIスクリプトやテストfixture | 検証ロジックがemitter名に依存していないか確認する |
新emitter側の設定が存在するかも確認します。
git grep -n "@azure-typespec/http-client-csharp"
git grep -n "@azure-typespec/http-client-csharp-mgmt"検索結果を見るときは、「古いemitterを削除した結果、C# SDK生成そのものが消えていないか」を確認してください。PRでも、古い設定を削除したが新しい @azure-typespec/http-client-csharp または @azure-typespec/http-client-csharp-mgmt がなかったファイルに対して、旧設定から namespace と emitter-output-dir を引き継ぐ追加対応が行われています。(GitHub)
移行の基本手順
C#生成が必要かを先に判断する
最初に決めるべきことは、「そのTypeSpec仕様から標準のAzure C# SDKを生成する必要があるか」です。
古い @azure-tools/typespec-csharp が書かれているからといって、必ず新emitterを追加するとは限りません。PRの後続修正では、もともと旧emitterが emit: リストに入っておらず、標準Azure C# SDKの生成対象ではないと判断されたファイルについて、新しく追加した @azure-typespec/http-client-csharp ブロックを削除しています。(GitHub)
判断基準は次の通りです。
| 判断項目 | 新emitterを残すべきケース | 削除でよいケース |
|---|---|---|
| C# SDKを生成しているか | CIやSDK生成手順でC#出力が使われている | C# SDK生成を行っていない |
emit: にC# emitterがあるか | 新emitterを emit: に含める必要がある | コメントや古い残骸だけなら削除でよい |
| namespaceがAzure SDK規約に合うか | Azure. で始まるC#向けnamespaceとして妥当 | lowercaseや別体系のnamespaceで、標準SDK生成対象ではない |
| 管理プレーンか | ARM / resource-manager向けなら http-client-csharp-mgmt を検討 | data-planeなら通常の http-client-csharp を検討 |
data-planeの例
data-planeのC#クライアント生成が必要な場合は、概念的には次のように変更します。
変更前の例です。
emit:
- "@azure-tools/typespec-autorest"
- "@azure-tools/typespec-csharp"
options:
"@azure-tools/typespec-csharp":
emitter-output-dir: "{output-dir}/{service-dir}/{namespace}"
namespace: "Azure.Example.Service"
model-namespace: false変更後の例です。
emit:
- "@azure-tools/typespec-autorest"
- "@azure-typespec/http-client-csharp"
options:
"@azure-typespec/http-client-csharp":
emitter-output-dir: "{output-dir}/{service-dir}/{namespace}"
namespace: Azure.Example.Service
model-namespace: falseここで重要なのは、namespace と emitter-output-dir を単純にコピーするだけでなく、現在のC# SDK生成ルールに合っているかを確認することです。PRでは、namespace が Azure. 形式に合わないため、新しく追加したC# emitterブロックを削除した例もあります。(GitHub)
resource-manager / ARM系の例
管理プレーン、つまりAzure Resource Manager向けの仕様では、@azure-typespec/http-client-csharp-mgmt を使うべきケースがあります。PRでも、resource-manager / Management系の26ファイルについて、@azure-typespec/http-client-csharp から @azure-typespec/http-client-csharp-mgmt へ切り替えるコミットが追加されています。(GitHub)
例は次の通りです。
emit:
- "@azure-tools/typespec-autorest"
- "@azure-typespec/http-client-csharp-mgmt"
options:
"@azure-typespec/http-client-csharp-mgmt":
emitter-output-dir: "{output-dir}/{service-dir}/{namespace}"
namespace: Azure.ResourceManager.Exampledata-planeとresource-managerを取り違えると、生成されるSDKの形や検証結果に影響する可能性があります。specification/<service>/resource-manager/ 配下か、data-plane/ 配下かを必ず確認しましょう。
CIで確認すべきポイント
この更新で失敗しやすいのは、TypeSpecのコンパイルそのものよりも、CIや検証ルールに関係する部分です。PRでも、TypeSpec Validation、Protected Files、Swagger Avocado、Automated merging requirements met など複数のチェックに関する調査と修正が行われています。最終的に、Foundry関連の変更を戻した後、13個の必須技術チェックは通過したと説明されています。(GitHub)
確認すべきポイントは次の通りです。
| 確認項目 | 具体的に見る場所 | 失敗しやすい理由 |
|---|---|---|
| TypeSpec Validation | tspconfig.yaml、suppressions.yaml | 古い問題が、今回ファイルを触ったことで初めて検出される |
| namespace検証 | C# emitterの namespace | Azure. 形式に合わないnamespaceで失敗する可能性がある |
| YAMLのインデント | options: 配下 | 新emitterブロックが別emitterの子要素になってしまう |
| Protected Files | eng/* 配下 | テストfixtureを変更すると保護対象に引っかかる場合がある |
| Swagger Avocado | READMEの配置や大文字小文字 | Linux runnerではファイル名の大文字小文字が区別される |
| 生成差分 | SDK出力、APIView | 設定変更だけのつもりでも、生成コード差分が出る可能性がある |
特にYAMLのインデントミスは見落とされやすいです。PR内のコメントでも、@azure-typespec/http-client-csharp または @azure-typespec/http-client-csharp-mgmt が別emitterのオプション配下にネストされてしまう例が指摘されています。(GitHub)
「全ファイルから削除」と読んでよいのか
PRタイトルだけを見ると、すべての tspconfig.yaml から @azure-tools/typespec-csharp が完全に消えるように見えます。しかし、実務では最新差分を必ず確認する必要があります。
PRの後続コメントでは、specification/ai-foundry/data-plane/Foundry/tspconfig.yaml を main に戻したため、このファイルでは @azure-tools/typespec-csharp ブロックが残り、移行は別PRで行うべきだと説明されています。理由は、Foundry配下に既存のTypeSpec Validation失敗があり、今回の変更でその領域が「影響あり」と判定されてCIを壊すためです。(GitHub)
つまり、この記事で扱う更新の本質は「古いC# emitterを使わない方向へ移行すること」ですが、個別サービスによっては例外や段階的対応が残る可能性があります。自分のサービスで対応するときは、PRタイトルではなく、実際の最新差分、CI結果、対象サービスの生成要件を確認してください。
よくある失敗と回避策
古いemitterを削除しただけでC#生成が消える
@azure-tools/typespec-csharp を削除するだけで、代替の @azure-typespec/http-client-csharp を追加しないと、C#生成が不要になったのか、設定漏れなのか分からなくなります。
回避策は、削除前に次を確認することです。
git grep -n "@azure-tools/typespec-csharp" -- "**/tspconfig.yaml"
git grep -n "emit:" -- "**/tspconfig.yaml"C# SDK生成が必要な仕様なら、新emitterを emit: と options: の両方で整合させます。C#生成が不要なら、削除理由をPR説明に明記しておくとレビューが通りやすくなります。
data-planeとmanagement-planeを混同する
Azure REST API仕様では、data-planeとmanagement-planeでSDK生成の期待値が異なります。resource-manager配下の仕様にdata-plane向けのC# emitterを入れると、後で生成差分やレビュー指摘につながりやすくなります。
回避策は、パスとnamespaceをセットで確認することです。
| パスの例 | 推奨される確認 |
|---|---|
specification/<service>/data-plane/... | @azure-typespec/http-client-csharp が適切か確認 |
specification/<service>/resource-manager/... | @azure-typespec/http-client-csharp-mgmt が適切か確認 |
*.Management を含むTypeSpecプロジェクト | 管理プレーン向けnamespaceになっているか確認 |
namespaceをそのまま移して検証に落ちる
旧emitterでは見逃されていたnamespaceが、新emitterやTypeSpec Validationでは問題になることがあります。PRでは、azure.ApiCenter や azure.ai.resources.autogen のようにlowercaseで始まるnamespace、または Microsoft.VoiceServices.Provisioning のようなnamespaceが、C# data-plane namespaceの検証に合わない例として扱われています。(GitHub)
回避策は、旧設定をそのまま移す前に「この仕様は標準Azure C# SDKを生成する対象なのか」を確認することです。対象でないなら、新emitterを無理に追加せず、古い参照だけを削除する判断もあります。
コメントだけの古い案内を残す
有効な設定だけを消しても、コメントに @azure-tools/typespec-csharp が残っていると、後から別の開発者が古い手順を再利用してしまいます。
回避策は、コメントも含めて検索することです。
git grep -n "typespec-csharp"コメントの修正は小さな作業ですが、将来の設定ミスを防ぐ効果があります。今回のPRでも、コメントアウトされた設定やコメントだけの参照が削除対象に含まれています。(GitHub)
レビュー時のチェックリスト
PRを出す前、またはレビューするときは、次の順番で確認すると効率的です。
| 順番 | チェック項目 | 確認方法 |
| -: | ————————————— | ——————————————– |
| 1 | 古いemitter名が残っていないか | git grep -n "@azure-tools/typespec-csharp" |
| 2 | C#生成が必要な仕様か | SDK生成手順、既存の emit:、サービスのSDK方針を見る |
| 3 | data-plane / resource-managerの区分が正しいか | ディレクトリパスとnamespaceを見る |
| 4 | 新emitterのoptionsが正しい階層にあるか | YAMLインデントを確認する |
| 5 | namespace が妥当か | C# SDKの命名方針とTypeSpec Validation結果を見る |
| 6 | emitter-output-dir が旧設定から正しく引き継がれているか | 生成先の差分を確認する |
| 7 | CIが既存の潜在問題を拾っていないか | TypeSpec ValidationやAvocadoのログを見る |
| 8 | 生成コード差分が意図通りか | APIViewやSDK差分を確認する |
この更新は設定ファイルの整理に見えますが、生成パイプラインに関わるため、最後は必ず生成結果まで見るべきです。tspconfig.yaml の差分が小さくても、SDK生成に使われるemitter、出力ディレクトリ、namespaceが変われば、レビュー対象の差分は広がる可能性があります。
この記事の結論
今回のAzure REST API documentation updateは、REST APIの利用方法を変える更新ではなく、Azure REST API仕様リポジトリ内のTypeSpec C#生成設定を新しいemitterへ整理する変更です。対応の中心は、tspconfig.yaml に残る @azure-tools/typespec-csharp を確認し、C#生成が必要な場合は @azure-typespec/http-client-csharp または @azure-typespec/http-client-csharp-mgmt へ適切に移行することです。
次に取るべき行動は明確です。自分が担当するサービス仕様で git grep -n "@azure-tools/typespec-csharp" を実行し、見つかった箇所を「削除だけでよいのか」「新emitterへ移行すべきか」に分けてください。そのうえで、TypeSpec Validation、生成コード差分、CI結果を確認します。PRタイトルの「all files」をそのまま受け取らず、最新差分とサービスごとの例外を確認することが、今回の変更で最も重要な実務ポイントです。
コメント