Azure REST API documentation update: Add C# client customizations for Compute TypeSpec migration は、Azure Compute の REST API仕様そのものを大きく使い替える話ではなく、Azure.ResourceManager.Compute の C#/.NET SDKを TypeSpec ベース生成へ移行する際に、既存SDKとの互換性を保つための仕様側カスタマイズです。結論から言うと、すぐにRESTエンドポイントの呼び出しを変更する必要がある利用者は多くありません。一方で、C#で Azure.ResourceManager.Compute を使っている開発者、SDK生成・API仕様管理を担当するチームは、名前変更、型の差し替え、ページング、コンストラクタやsetterの有無を確認しておくべき更新です。対象PRはAzure REST API仕様リポジトリのDraft PRで、ComputeのTypeSpec移行に向けたC#向けカスタマイズを追加する内容として整理されています。(GitHub)
今回のAzure REST API documentation updateで確認すべき結論
今回の更新で最も重要なのは、「REST APIの通信仕様」ではなく「C# SDKとして生成される公開APIの形」を整える変更だという点です。Azure REST APIの仕様はTypeSpecへ移行されつつあり、TypeSpecはAPI定義からOpenAPI仕様やクライアントコードなどを生成する仕組みです。Microsoft Learnでも、TypeSpecはAPIを定義し、emittersによってAPI仕様、クライアントコード、サーバー側コードを生成する言語として説明されています。(Microsoft Learn)
今回のPRでは、Compute管理SDKを従来のAutoRest/Swaggerベース生成からTypeSpecベース生成へ移すため、C#向けに @@clientName、@@alternateType、@@usage、名前空間設定などを追加・調整しています。関連する.NET SDK側PRでも、Azure.ResourceManager.Compute をAutoRest/SwaggerからTypeSpecベース生成へ移行する作業として位置づけられています。(GitHub)
| 確認ポイント | 何が変わるか | 実務上の見方 |
|---|---|---|
| C# SDKの名前 | 型名、プロパティ名、メソッド名、enumメンバー名を既存SDKに近づける | コンパイルエラーや補完候補の変化を確認する |
| 型の扱い | string ではなく AzureLocation、ResourceIdentifier、独自enum相当へ寄せる箇所がある | 型変換、比較、テストコードの期待値を見直す |
| ページング | 一部のlist操作をC# SDKでページング扱いにする | IEnumerable / IAsyncEnumerable の利用箇所を確認する |
| Gallery系リソース | SharedGallery / CommunityGallery系の扱いを調整 | 既存の拡張メソッドや取得メソッド名との衝突を避ける |
| TypeSpec設定 | C#管理SDK向けemitter設定やroot client.tsp への集約 | API仕様管理者・SDK生成担当者は設定差分を確認する |
影響を受ける人、受けにくい人
今回のAzure REST API documentation updateは、すべてのAzure利用者に同じ影響がある更新ではありません。PRの説明では、カスタマイズはC#管理SDKのTypeSpec移行に必要なもので、デコレーターは csharp スコープに限定され、他言語には影響しないと説明されています。(GitHub)
| 対象者 | 影響度 | 確認すべきこと |
|---|---|---|
C#で Azure.ResourceManager.Compute を使う開発者 | 高 | SDK更新時のコンパイル、型名・プロパティ名・enum名・名前付き引数 |
| Azure SDK生成やTypeSpec仕様を扱う担当者 | 高 | client.tsp、tspconfig.yaml、C#スコープ、ApiCompat結果 |
| REST APIをHTTPで直接呼び出している開発者 | 低〜中 | HTTPパスやリクエスト/レスポンスschemaの変更有無を個別に確認 |
| Java、Python、Go、JavaScript SDK利用者 | 低 | C#限定カスタマイズであることを前提に、別PRや別SDK生成結果を確認 |
| Azure CLIやPowerShell中心の利用者 | 低 | 通常は直接対応不要。ただしCompute関連のSDK更新を内包するツールではリリースノート確認が必要 |
特に注意したいのは、「C#だけの互換性調整」でも、C#アプリケーション側ではソース互換性・バイナリ互換性・テスト結果に影響し得ることです。関連する.NET SDK側PRでは、TypeSpecベース生成に伴う多数の互換性調整が行われ、ApiCompatの残課題も追跡されています。(GitHub)
2026年5月5日前後の主な変更点
2026年5月5日のコミット群では、C# SDKの既存公開APIに近づけるための細かい名前・型・利用方法の調整が追加されています。たとえば、source を gallerySource にする変更、v1.14.0のベースラインに合わせたプロパティ名の調整、diskControllerType を DiskControllerKind に寄せる変更、GallerySoftDeletedResourceProperties.softDeletedTime を SoftDeletedOn として扱う変更、10個のoutput-onlyモデルへ @@usage(Usage.input, csharp) を付ける変更などが含まれます。(GitHub)
C# SDKの名前を既存の公開APIに近づける
TypeSpec移行で生成器が変わると、同じREST APIでもSDK上の名前が変わることがあります。今回のPRでは、その差分を抑えるために @@clientName が多数使われています。
具体例として、過去のコミットでは Disk を ManagedDisk、Image を DiskImage、RestorePointCollection を RestorePointGroup、PrivateEndpointConnection を ComputePrivateEndpointConnection に寄せる変更が追加されています。また、VirtualMachineScaleSetVMRunCommands のような VM 表記をC#の既存命名に合わせて Vm へ調整する変更もあります。(GitHub)
実務では、次のようなコードが影響を受けやすくなります。
// 型名やプロパティ名を直接参照しているコード
ManagedDiskResource disk = ...;
// enumメンバー名を比較しているコード
if (endpointType == ComputeGalleryEndpointType.Imds)
{
// 処理
}
// 名前付き引数を使っているコード
SomeMethod(vmInstanceIds: ids);C#では型名・プロパティ名・メソッド名が変わると、コンパイル時に検出しやすい一方、リフレクション、JSON変換、テストの文字列比較では見落としやすくなります。SDKを更新する前に、単にビルドするだけでなく、Computeリソース作成、VM拡張、Gallery取得、Disk操作など、実際に使っている処理単位でテストすることが重要です。
enumや型の差分を @@alternateType で吸収する
今回のPRでは、C# SDKで従来使われていた型に合わせるため、@@alternateType による型の差し替えも行われています。たとえば、Usage.unit は仕様上の文字列リテラルとして扱われるとC#では単なる string になり得ますが、既存SDKでは ComputeUsageUnit として公開されていたため、C#向けに型を戻す変更が追加されています。(GitHub)
また、LocationParameter から LocationResourceParameter へ切り替える変更もあります。これは、C# SDKでAzureリージョンを単なる文字列ではなく AzureLocation 型として扱う流れに関係します。PRの説明では、subscription-scoped action operationsや VirtualMachineExtensionImages のルートで LocationResourceParameter に切り替え、C# SDKで従来AutoRestが出していた AzureLocation パラメータ型を復元すると説明されています。(GitHub)
確認すべきコードの例は次のとおりです。
// 文字列としてlocationを渡していた箇所
// SDK更新後に AzureLocation 型が求められる場合がある
var location = AzureLocation.JapanEast;すべての利用箇所で変更が必要とは限りません。ただし、SDK更新後に「文字列で渡していたlocationが型不一致になる」「テストで型名を検証している」といった問題が出た場合は、今回のTypeSpec移行に伴う型調整が原因候補になります。
ページング、flatten、コンストラクタの扱いも確認が必要
C# SDKの使い勝手に影響するのは名前だけではありません。今回のPRでは、一部のlist操作をC# SDKでページングとして扱うための markAsPageable も追加されています。具体的には、VirtualMachineExtensions.list と VirtualMachineScaleSetVMExtensions.list が単一ページのlist結果を返すものの、C# SDKで IEnumerable / IAsyncEnumerable を適切に生成するためページング扱いが必要だと説明されています。(GitHub)
また、@@usage(Usage.input, csharp) をoutput-onlyモデルへ付ける変更も重要です。PRでは、TypeSpecの既定ではoutput usageとなることでpublicな引数なしコンストラクタとプロパティsetterが生成されなくなるため、AutoRest時代に公開されていたコンストラクタとsetterを復元する目的だと説明されています。対象には DiskRestorePoint、VirtualMachineImage、VirtualMachineExtensionImage、PurchasePlan、GallerySoftDeletedResource などが含まれます。(GitHub)
テストデータ作成で次のようなコードを書いている場合は、特に注意してください。
var image = new VirtualMachineImage
{
// テスト用にプロパティをセット
};このようなコードは、コンストラクタやsetterがなくなるとすぐ壊れます。今回のカスタマイズはそれを避ける方向の変更ですが、SDK更新時には「本当に従来どおりインスタンス生成できるか」をテストで確認するのが安全です。
Gallery系の扱いは「リソース」か「操作」かを意識する
Shared GalleryやCommunity Gallery周辺は、今回の変更で特に読み間違えやすい箇所です。PRでは、SharedGallery、SharedGalleryImage、SharedGalleryImageVersion、CommunityGallery、CommunityGalleryImage、CommunityGalleryImageVersionの6種類について、.NET SDKではARMリソースとしては非推奨で、手書きカスタムコードに置き換えられていたため、TypeSpec定義をARM resource patternからraw operationsへ変換し、C# generatorがこれらをARMリソースとして扱わないようにしたと説明されています。(GitHub)
これは、単に「Gallery APIが消える」という意味ではありません。むしろ、既存の.NET SDKで公開されていた取得メソッドや拡張メソッドとの衝突を避けるため、生成されるSDKの形を調整していると見るべきです。5月3日の変更では、既存の GetSharedGallery / GetCommunityGallery との共存のため、自動生成されるgetter名を *GalleryData 側へ寄せる説明もあります。(GitHub)
REST API利用者が過度に心配しなくてよい理由
今回の更新はAzure REST API仕様リポジトリのPRですが、主眼はC# SDK生成の互換性です。PRの説明では、デコレーターはC#スコープであり他言語に影響しないとされています。さらに、たとえば ComputeGalleryEndpointType.IMDS をC#向けに Imds として復元する変更では、wire valueである IMDS は変更しないと説明されています。(GitHub)
つまり、HTTPリクエストで送るJSONの値やREST APIのパスが直ちに変わる、という読み方は避けるべきです。もちろん、仕様ファイルに変更が入る以上、利用しているAPIバージョンや生成クライアントによって影響が出る可能性はあります。ただし、今回の中心は「C# SDKとして見える名前・型・生成結果の互換性維持」です。
C#開発者向けの確認手順
Azure.ResourceManager.Computeを使っている場合は、SDK更新前に次の順で確認すると、移行時のトラブルを減らせます。
| 手順 | やること | 目的 |
|---|---|---|
| 現在の依存関係を確認 | Azure.ResourceManager.Compute の利用バージョンを確認 | どのSDK世代から更新するかを把握する |
| Compute関連コードを洗い出す | VM、Disk、VMSS、Gallery、RunCommand、Extension周辺を検索 | 影響箇所を限定する |
| 名前付き引数を確認 | vmInstanceIDs、inVM... など大文字小文字に依存する箇所を確認 | C#の名前変更によるコンパイル差分を見つける |
| ビルドとテストを実行 | 単体テストだけでなく実APIに近い統合テストも実行 | 型・ページング・setter有無の差分を検出する |
| 生成SDKの公開APIを比較 | ApiCompatやpublic API差分を確認 | バイナリ互換性・公開面の変化を確認する |
ローカルでまず実行したいコマンド例は次のとおりです。
dotnet list package | grep Azure.ResourceManager.ComputeWindowsのコマンドプロンプトで確認するなら、次のように実行できます。
dotnet list package | findstr Azure.ResourceManager.Compute影響を受けやすい名前を検索する場合は、リポジトリ内で次のように確認します。
git grep -n "GetSharedGallery\|GetCommunityGallery\|RollingUpgradeStatusInfo\|DiskControllerType\|StorageAccountType"
git grep -n "vmInstanceIDs\|vmInstanceIds\|inVMAccessControlProfile\|inVmAccessControlProfile"関連する.NET SDK側PRでは、CreateResourceIdentifier の一部パラメータで inVM... と inVm... の大文字小文字が既知の論点として挙げられており、名前付き引数の利用者だけが影響し、位置引数の利用者は影響を受けないと説明されています。(GitHub)
API仕様・SDK生成担当者が見るべき設定
SDK生成やAzure REST API仕様の管理に関わる場合は、アプリ利用者よりも細かい確認が必要です。今回のPRでは、変更対象ファイルとして tspconfig.yaml、rootの client.tsp、csharp-alternate-type-stubs.tsp、Compute / ComputeGallery配下のTypeSpecファイル、stable配下の GalleryRP.json などが並んでいます。(GitHub)
特に見るべき観点は次の4つです。
tspconfig.yaml のC#管理SDK向け設定
PR説明では、tspconfig.yaml に @azure-typespec/http-client-csharp-mgmt emitter configを追加し、namespaceを Azure.ResourceManager.Compute とする変更が挙げられています。これは生成されるC# SDKの名前空間に直結するため、SDK生成担当者は最初に確認すべき設定です。(GitHub)
C#限定のスコープ指定
Azure REST API仕様リポジトリのカスタマイズガイドでは、Azure.ClientGenerator.Coreのデコレーターが最後の引数としてscopeを持ち、"csharp"、"python"、"java"、"javascript"、"go" などの言語識別子を指定できると説明されています。C#だけに必要な互換性調整を全言語へ広げてしまうと、他言語SDKで不要な差分を生む可能性があります。(GitHub)
client.tsp への集約
5月6日のコミットでは、各サービス配下の client.tsp に散らばっていたC# client customization decoratorsをrootの client.tsp に移し、セクションコメントで整理したうえで、per-service client.tsp をmainに戻す変更が入っています。続くコミットでは、TypeSpecのnamespaceルールによりalternate type stubsを専用ファイルに戻し、さらに csharp-alternate-type-stubs.tsp へリネームしています。(GitHub)
TypeSpecで表現できない場合のSDK側カスタマイズ
カスタマイズガイドでは、SDKカスタマイズはまず client.tsp のデコレーターを使うべきで、TypeSpecで表現できない場合は各言語のpost-generation customizationを使う流れが示されています。C#ではpartial classやCodeGen系属性を使うパターンが案内されています。(GitHub)
今回の.NET SDK側PRでも、仕様側カスタマイズだけでなく、src/Customize/ 配下のpartial-class customizationsでバイナリ互換性を保つ作業が説明されています。仕様側だけで解決できる問題と、SDK側の手書き・partial対応が必要な問題を分けて見ることが重要です。(GitHub)
移行時に起こりやすい失敗と対策
| 失敗しやすいポイント | 起こる問題 | 対策 |
|---|---|---|
| REST API変更だと誤解する | HTTP呼び出し側まで不要に修正してしまう | まずwire value、path、schema変更か、SDK生成名の変更かを切り分ける |
| C#スコープを見落とす | 他言語SDKにも影響すると誤認する | @@clientName(..., "csharp") のようなscopeを確認する |
| 名前付き引数を軽視する | 大文字小文字の差分でビルドが落ちる | Compute関連メソッド呼び出しを検索し、名前付き引数を重点確認する |
| テスト用モデル生成を見落とす | public constructorやsetterの有無でテストが壊れる | output-onlyモデルの生成コードとテストデータ作成箇所を確認する |
| generator-level課題を仕様側だけで直そうとする | 無理な @@clientName や @@alternateType が増える | SDK PR側の既知課題・残ApiCompat差分を確認する |
| Draft PRを確定情報として扱う | 後続コミットで整理方針が変わる | mainへのmerge状況、SDKリリースノート、最終diffを確認してから本番反映する |
関連SDK PRでは、ApiCompatの残課題としてbase typeや Id プロパティ、virtualityに関するgenerator-levelの差分が残っていると説明されています。こうした差分は、アプリ側の単純な置換や仕様側の名前変更だけでは解決できない場合があります。(GitHub)
今回の更新をどう判断すべきか
今回のAzure REST API documentation updateは、Azure ComputeをC# SDKで扱うチームにとっては「将来のSDK更新で壊れないか」を確認するための重要なシグナルです。一方、REST APIを直接呼び出しているだけの利用者にとっては、慌てて実装を変更する類の情報ではありません。
実務での判断基準はシンプルです。
Azure.ResourceManager.Computeを使っているなら、SDK更新前にビルド・統合テスト・名前付き引数の確認を行う- ComputeのTypeSpec仕様やSDK生成を担当しているなら、root
client.tsp、C# scope、@@clientName、@@alternateType、@@usage、ApiCompat結果を確認する - REST APIを直接使っているなら、HTTPパス・schema・wire valueが変わっているかを個別に確認し、SDK向け命名変更と混同しない
- Draftや未mergeの状態では、最終リリース前提で本番コードを変更しすぎない
次に取るべき行動は、自分の立場で分かれます。C#アプリ開発者は、Compute関連の利用箇所を検索し、SDK更新時のコンパイルと統合テストを先に実行してください。API仕様・SDK生成担当者は、PRの最終diff、関連.NET SDK PR、ApiCompat結果を追い、C#互換性のためのカスタマイズが他言語やREST wire contractへ不要に波及していないかを確認するのが安全です。
コメント