MENU

Azure SDKのTypeSpec移行とは？Azure.ResourceManager.Compute更新の影響と確認ポイント

Azure

Azure SDKのAzure.ResourceManager.Computeで「Begin TypeSpec migration」という更新を見て、いますぐコードを直す必要があるのか不安に感じた方も多いはずです。結論から言うと、これはAzure VMやディスクなどのクラウド側の動作変更というより、.NET向け管理SDKのコード生成方式をAutoRest/SwaggerからTypeSpecベースへ移行する作業です。2026年5月5日時点では、利用者が最初にやるべきことは「急いで本番更新すること」ではなく、Azure.ResourceManager.Computeを使っている箇所を洗い出し、将来のSDK更新に備えてビルド・API差分・実運用シナリオのテスト範囲を決めることです。対象PRでは、Azure.ResourceManager.ComputeをAutoRest/Swagger生成からTypeSpecベース生成へ移行することが明記されています。(GitHub)

この更新は、特にAzure SDK for .NETで仮想マシン、ディスク、スナップショット、Compute Gallery、VM Scale Sets、SKU一覧などを操作している開発者に関係します。TypeSpecはAPIを定義し、エミッターを通じてAPI仕様やクライアントコードなどを生成するためのMicrosoft発のオープンソース言語です。つまり今回のポイントは「Compute管理SDKの作り方が変わることで、公開APIの名前・型・オーバーロード・互換性にどの程度影響が出るか」を確認することにあります。(Microsoft Learn)

目次

この更新で何が変わるのか

今回の[Mgmt] Azure.ResourceManager.Compute: Begin TypeSpec migrationは、Azure SDK for .NETリポジトリ上の管理パッケージ向けPRです。PRはDraftとして扱われており、Azure.ResourceManager.ComputeをTypeSpecベース生成へ移行するための変更、依存する仕様PR、ジェネレーター修正、互換性維持のためのカスタマイズが整理されています。(GitHub)

変更点内容利用者が見るべきポイント
生成方式の変更AutoRest/SwaggerベースからTypeSpecベースへ移行SDKの公開API名、型、オーバーロードに差分が出る可能性がある
tsp-location.yamlの追加TypeSpec仕様の場所を指す構成に変更SDK生成・検証に関わる開発者は生成元を確認する
IncludeAutorestDependencyの削除AutoRest依存を外す方向の変更通常のアプリ利用者より、SDK生成や内部ビルドを行う人に影響しやすい
autorest.mdの削除旧AutoRest向け設定を削除旧設定に依存した名前変更や生成ルールがTypeSpec側へ移る
互換性用カスタマイズsrc/Customize/配下のpartial classやModelFactory shimを追加既存コードの互換性維持が目的だが、差分テストは必要
残課題ApiCompatで29件のユニークなbreakが残る状態と記載リリース前の作業であり、最終仕様として断定しない

PRでは、tsp-location.yamlがComputeのTypeSpec仕様を指すこと、.csprojからIncludeAutorestDependencyを削除すること、autorest.mdを削除すること、@@clientNameや@@alternateTypeなどのTypeSpec側カスタマイズを使うことが示されています。あわせて、SDK側では互換性維持のためにpartial classやArmComputeModelFactoryのshimが追加されています。(GitHub)

いますぐ本番コードを変更すべきか

多くのアプリ開発者は、現時点で本番コードを急いで書き換える必要はありません。理由は、今回の情報がSDKリポジトリ上の移行PRであり、安定版パッケージの更新そのものとは別だからです。

Azure SDK Releasesの最新ページでは、.NETのAzure.ResourceManager.Computeは安定版1.14.0、ベータ版1.15.0-beta.1が掲載されています。(Azure) NuGetのAzure.ResourceManager.Computeページでも、このライブラリはMicrosoft Azure Computeリソースを管理するための.NET向け管理クライアントライブラリとして説明されています。([NuGet][4])

判断基準は次のように考えると安全です。

状況対応
本番でAzure.ResourceManager.Computeを使っている現行バージョンを固定し、将来の更新に備えてテスト項目を作る
ベータ版やプレビューSDKを検証しているTypeSpec移行後の差分を優先的に確認する
SDK生成、Azure SDKコントリビューション、社内ラッパー開発をしているPRと仕様PRを追い、生成設定・互換性shim・ApiCompat結果を確認する
Bicep、ARMテンプレート、Terraform、Azure Portalだけを使っている直接影響は小さい。SDK利用があるかだけ確認する
JavaScript、Go、Pythonなど別言語SDKを使っている今回の主対象はC#管理SDK。ただしAzure REST API仕様側のTypeSpec移行は別途確認する価値がある

TypeSpec移行がAzure SDK利用者に影響する理由

TypeSpec移行は、単なる内部実装変更に見えます。しかしAzure SDKでは、生成方式の違いが公開APIの形に出ることがあります。

たとえば、次のような差分が起きる可能性があります。

影響しやすい箇所起きうる変化確認方法
モデルクラスプロパティ名、型、nullable、setterの有無が変わるコンパイルエラーとシリアライズ結果を確認
enum / extensible enum大文字小文字や名前が変わる既存コードの参照名、JSON変換、比較処理を確認
GetAll / List系メソッドオーバーロードや戻り値の形が変わる一覧取得処理、ページング処理を実行
ArmComputeModelFactoryテスト用モデル生成やモックで差分が出る単体テスト、Mockable系コードを確認
CloudService関連非推奨・未サポート扱いがより明確になる参照している場合は置き換え方針を決める
リフレクション利用文字列ベースの型名・プロパティ名参照が壊れるnameof化、型安全な参照への変更を検討

PRの履歴では、TypeSpec生成後にModelFactoryの互換性用オーバーロード、CloudService関連のshim、プロパティ名・型・flatten処理の調整が多く行われています。これは「移行によって既存APIとの差分が出やすい領域」を示す重要な手がかりです。(GitHub)

特に確認すべき変更点

生成元がAutoRest/SwaggerからTypeSpecへ移る

これまでAutoRest/Swaggerを前提にしていた生成設定は、TypeSpec側のclient.tspやtspconfig.yaml、tsp-location.yamlを中心に整理されます。通常のアプリ開発者がこれらのファイルを直接編集することは少ないものの、Azure SDKを社内でフォークしている場合や、生成コードをもとに独自ラッパーを作っている場合は影響します。

見るべきポイントは次の3つです。

  • autorest.mdに依存した命名や型変換がTypeSpec側で再現されているか
  • 生成されたGenerated配下の型名・メソッド名が既存コードと一致するか
  • src/Customize/配下のpartial classで互換性が維持されているか

C#向けカスタマイズが仕様PR側に集約される

依存関係として示されている仕様PRでは、C#クライアント向けに@@clientName、@@alternateType、@@usageなどのカスタマイズが追加されています。PR説明では、これらのカスタマイズはC#にスコープされ、他言語には影響しないとされています。(GitHub)

実務上は、次のように理解すると分かりやすいです。

TypeSpec側の調整目的
@@clientName生成されるC#のクラス名、プロパティ名、メソッド名を既存SDKに近づける
@@alternateType文字列やIDなどをResourceIdentifier、AzureLocation、既存enum相当の型に合わせる
@@usage入力モデル・出力モデルの扱いを調整し、コンストラクターやsetterの互換性を保つ
@@clientLocation操作がどのクライアント・拡張メソッドに生成されるかを調整する

つまり、TypeSpec移行は「新しい名前に全部変える」作業ではなく、既存のAzure.ResourceManager.Compute利用者ができるだけ壊れないように生成結果を寄せる作業でもあります。

複数サービスを含むCompute SDKのAPIバージョン処理が見直される

Compute管理SDKは単一の小さなAPIではありません。Compute、Disk、Gallery、SKUなど複数の領域を含みます。PRの途中経過では、Compute、ComputeDisk、ComputeGallery、ComputeSkuの4サービスに対して複数のAPIバージョンが関係し、トップレベルのApiVersionsが空になることがジェネレーター不具合の原因として説明されています。(GitHub)

アプリ利用者が直接APIバージョンを指定していない場合でも、SDK内部でどのAPIバージョンが使われるかは重要です。特に、次のようなコードは回帰テストに含めてください。

  • VM、VMSS、ディスク、スナップショットを作成・更新する処理
  • Gallery ImageやShared Galleryを一覧・取得する処理
  • SKUやUsageの一覧取得
  • リージョン指定、Edge Zone、Location関連の処理
  • REST APIレスポンスをモデルにデシリアライズして独自処理する箇所

CloudService classic関連は注意して扱う

PRの履歴では、CloudService classicがTypeSpec仕様から削除され、互換性維持のためにArmComputeModelFactory側へ手書きのshimを追加し、NotSupportedExceptionを投げる形のスタブにしていることが説明されています。(GitHub)

古いCloudService関連コードをまだ保持している場合、「コンパイルできるか」だけでは不十分です。実際に呼び出したときに例外になる可能性があるため、次のように対応を分けてください。

利用状況対応
参照だけ残っている不要なら削除。必要なら非推奨扱いとして隔離
単体テストでModelFactoryを使っている例外発生の有無を確認
本番処理でCloudService関連操作を呼ぶ代替サービスや削除計画を検討
互換性維持のためだけにラッパーがある呼び出しパスが存在しないことをテストで確認

自分のプロジェクトで影響を確認する手順

利用中のパッケージを洗い出す

まず、Azure.ResourceManager.Computeを直接または間接的に使っているか確認します。

.NETプロジェクトでは、次のコマンドで参照状況を確認できます。

dotnet list package --include-transitive

Windows環境でプロジェクトファイルを横断検索する場合は、PowerShellで次のように確認できます。

Get-ChildItem -Recurse -Filter *.csproj | Select-String "Azure.ResourceManager.Compute"

LinuxやmacOSでは、次のように検索できます。

grep -R "Azure.ResourceManager.Compute" -n .

見つかったら、次の情報をメモしておきます。

確認項目見る場所
利用バージョン.csproj、Directory.Packages.props、packages.lock.json
直接参照か推移的参照かdotnet list package --include-transitive
利用している機能VM、Disk、Gallery、SKU、Availability Set、VMSSなど
モック・テスト利用ArmComputeModelFactory、Mockable系、独自ラッパー
依存固定の有無lock file、Central Package Management、CIのrestore設定

パッケージバージョンを固定する

TypeSpec移行のような大きな生成方式変更が近い場合、Version="*"や範囲指定で自動更新される構成は避けた方が安全です。Central Package Managementを使っている場合は、Directory.Packages.propsで明示的に固定します。

<ItemGroup>
  <PackageVersion Include="Azure.ResourceManager.Compute" Version="1.14.0" />
</ItemGroup>

プレビュー版を検証する場合も、本番ブランチではなく検証ブランチで行ってください。

git checkout -b verify-azure-compute-sdk-update
dotnet restore --locked-mode
dotnet build
dotnet test

packages.lock.jsonを使っている場合は、意図しない更新が混ざらないように--locked-modeで復元するのが有効です。

コンパイルだけでなく実行テストを行う

SDKの生成方式変更では、コンパイルが通っても実行時に差分が出ることがあります。特に、モデルのシリアライズ、nullable、enum名、ページング、LROの完了待ちを確認してください。

テスト対象具体的に確認すること
VM作成・更新CreateOrUpdateAsync、UpdateAsync、タグ更新、WaitUntil.Completed
VMSSインスタンス一覧、拡張機能、スケール操作、モデルのnested property
Disk / Snapshot作成、取得、一覧、ResourceIdentifier型の扱い
Compute GalleryGallery、Image、Image Versionの取得と一覧
SKU / UsageGetAll系メソッド、ページング、フィルター、戻り値の型
ModelFactory既存テストのモデル生成コード、オーバーロード解決
Mockable系モック生成、継承、virtualメンバー、Idプロパティ
例外処理RequestFailedExceptionのStatus、ErrorCode、ログ出力

とくにModelFactoryを多用しているテストコードは、SDK更新時に壊れやすい領域です。PRでもModelFactory互換性のための手書きshimが追加されており、生成された互換オーバーロードだけでは対応しきれないケースが示されています。(GitHub)

移行時に確認したいコード例

たとえば、Availability Setの作成や一覧取得のような基本操作は、更新後も必ず検証しておきたい処理です。NuGetのREADMEでも、ArmClientをDefaultAzureCredentialで作成し、サブスクリプション、リソースグループ、Availability Set collectionを取得して操作する流れが紹介されています。([NuGet][4])

確認対象のイメージは次のようになります。

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.Compute;

ArmClient armClient = new ArmClient(new DefaultAzureCredential());

SubscriptionResource subscription = await armClient.GetDefaultSubscriptionAsync();
ResourceGroupResource resourceGroup = await subscription.GetResourceGroups().GetAsync("my-rg");

AvailabilitySetCollection collection = resourceGroup.GetAvailabilitySets();

await foreach (AvailabilitySetResource availabilitySet in collection.GetAllAsync())
{
    Console.WriteLine(availabilitySet.Data.Name);
}

このような基本コードで確認したいのは、単にビルドが通るかだけではありません。

  • GetAvailabilitySets()の戻り値が期待どおりか
  • GetAllAsync()の戻り値とページングが変わっていないか
  • availabilitySet.Data配下のプロパティ名や型が変わっていないか
  • AzureLocation、ResourceIdentifier、enumの扱いが既存コードと合うか
  • 既存の単体テストで使うModelFactoryと整合するか

よくある失敗パターン

PRを安定版リリースと勘違いする

今回の情報は、移行PRの内容を追うべき更新です。PRがあるからといって、ただちに本番のNuGetパッケージを更新する必要があるわけではありません。

正しい対応は、PR、CHANGELOG、Azure SDK Releases、NuGetのバージョン一覧を合わせて確認することです。

コンパイルエラーだけを見て安心する

TypeSpec移行では、プロパティのflatten、enum名、nullable、ModelFactory、ページングなど、実行時に差分が出る可能性があります。特に、VMやディスクの作成処理はAzureリソースを実際に作るため、ステージング環境や検証用リソースグループで確認してください。

非推奨APIを「まだ動く」と考える

CloudService classicのように、互換性維持のために型やメソッドが残っていても、実際の呼び出しがサポートされるとは限りません。[Obsolete]やEditorBrowsable(Never)相当の扱いがあるAPIは、今後の削除候補として棚卸ししましょう。

リフレクションや文字列参照を放置する

次のようなコードは、SDKの型名・プロパティ名変更に弱いです。

var property = model.GetType().GetProperty("DiskControllerType");

可能であれば、nameofや型安全なプロパティ参照に置き換えてください。

var propertyName = nameof(VirtualMachineScaleSetStorageProfile.DiskControllerType);

ただし、移行後にプロパティ自体の名前が変わる可能性もあるため、nameofにしただけで完全に安全になるわけではありません。ビルド時に検知できる形へ寄せることが目的です。

チームで使える確認チェックリスト

SDK更新前に、次のチェックリストをそのままレビュー項目として使えます。

チェック項目完了条件
利用バージョンを把握したAzure.ResourceManager.Computeの直接・推移的参照を確認済み
バージョンを固定した.csprojまたはDirectory.Packages.propsで固定済み
主要操作を洗い出したVM、Disk、Gallery、VMSS、SKUなど利用範囲を一覧化済み
単体テストを確認したModelFactory、Mockable、独自ラッパーのテストを実行済み
実行テストを行った検証用Azure環境で作成・更新・削除・一覧取得を確認済み
例外ログを確認したRequestFailedException、HTTPステータス、Azure側エラーコードを記録済み
非推奨APIを棚卸ししたCloudService classicなどの利用有無を確認済み
ロールバック手順を用意した旧パッケージバージョンへ戻す手順をCI/CDに反映済み

SDK生成や社内ラッパーを扱う人が見るべきポイント

通常のアプリ開発者よりも、Azure SDKの生成や社内標準ライブラリを扱う人は注意点が増えます。

特に確認すべきなのは次の項目です。

  • tsp-location.yamlが指すTypeSpec仕様のコミット
  • tspconfig.yamlのnamespace、emitter設定
  • C#向けdecoratorが旧AutoRest設定の意図を再現しているか
  • src/Customize/配下のpartial classが重複生成されていないか
  • ApiCompatの残課題が自社利用APIに当たっていないか
  • autorest.md前提の社内手順書やCIスクリプトが残っていないか
  • 生成コードを直接編集していないか

PRの現状説明では、ApiCompatの残り29件はジェネレーターレベルの課題であり、SDKカスタマイズ層だけでは修正できないとされています。内訳として、base type / interfaceの削除、Idプロパティの連鎖、ComputeWriteableSubResourceData.Idのvirtual性に関する差分が挙げられています。(GitHub)

更新を追うときの実務的な見方

この種のAzure SDK更新は、PR本文だけでなく、次の順番で確認すると判断しやすくなります。

見るもの目的
SDK PR実際に.NET SDKへ入る変更、ApiCompat、CHANGELOG予定を確認
Spec PRTypeSpec側の命名、型、decorator、API仕様の変更を確認
Azure SDK Releases安定版・ベータ版の公開状況を確認
NuGet実際にインストール可能なバージョンと依存関係を確認
CHANGELOG利用者向けのbreaking change、bug fix、deprecated情報を確認

今回の場合、SDK PRと仕様PRの両方を見ることが重要です。SDK PRはAzure.ResourceManager.Compute側の生成結果と互換性調整を示し、仕様PRはC#向けTypeSpecカスタマイズを示しています。(GitHub)

読者が次に取るべき行動

Azure.ResourceManager.Computeを使っている場合は、まず自分のプロジェクトがどの程度影響を受けるかを確認してください。最初にやることは、パッケージ参照の洗い出し、バージョン固定、主要操作のテスト項目化です。

本番運用中のシステムでは、PR段階の情報を見て急いで書き換えるよりも、次の流れが安全です。

  1. 現在のAzure.ResourceManager.Computeバージョンを固定する
  2. VM、Disk、Gallery、VMSS、SKUなど利用機能を一覧化する
  3. ModelFactory、Mock、リフレクション、非推奨APIの有無を確認する
  4. ベータ版または安定版リリース後に検証ブランチで更新する
  5. コンパイル、単体テスト、ステージング実行テストを通してから本番へ反映する

今回のTypeSpec移行は、Azure Computeの使い方を根本から変えるものではありません。しかし、SDKの生成方式が変わるため、既存コードの互換性を軽視すると、モデル型、メソッド名、オーバーロード、テスト用ファクトリで思わぬ差分が出る可能性があります。今のうちに利用箇所とテスト観点を整理しておけば、正式リリース時に慌てず安全に移行できます。

[4]: https://www.nuget.org/packages/Azure.ResourceManager.Compute “
NuGet Gallery
| Azure.ResourceManager.Compute 1.14.0
“

Azure
.NET Azure SDK TypeSpec Azure.ResourceManager.Compute Azure Compute

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次