azd拡張の更新スクリプトが動かない原因と直し方｜upgradeからupdate・source名制限

Azure Developer CLI（azd）を更新したあと、拡張機能や開発ツールの更新スクリプトが突然失敗する場合は、upgradeからupdateへの名称変更だけでなく、JSONの判定値、依存関係を制御するフラグ、テレメトリ識別子、拡張機能source名も確認してください。

正式な更新コマンドはazd extension updateとazd tool updateです。従来のupgradeも互換用aliasとして動作しますが、azd tool update --output jsonのactionは"update"を返します。そのため、コマンド自体は成功しているのに、後続のJSON判定でCIが失敗することがあります。source名に空白、ピリオド、大文字などが含まれている場合は、既存sourceを削除し、適合する名前で再登録する必要があります。([GitHub][1])

まず確認すべき変更点

2026年8月の変更で、拡張機能とtoolの更新処理に関係する名称が次のように整理されました。([GitHub][1])

確認箇所	従来	現在の正式な指定
拡張機能の更新	`azd extension upgrade`	`azd extension update`
toolの更新	`azd tool upgrade`	`azd tool update`
tool更新JSONの`action`	`"upgrade"`	`"update"`
依存関係の更新を止めるフラグ	`--no-dependency-upgrades`	`--no-dependency-updates`
拡張機能source名	空白やピリオドを含む名前も存在	小文字英数字、ハイフン、アンダースコアを使用
テレメトリ識別子	`upgrade`系	`update`系

旧コマンドと旧フラグは互換用aliasとして残っています。しかし、新しく作るスクリプトや修正するCIでは、正式なupdate表記へ統一するのが安全です。

upgradeコマンドが動くのにスクリプトが失敗する理由

今回の変更で注意したいのは、人が入力するコマンドの互換性と、プログラムが読み取る出力の互換性は別という点です。

たとえば、次の旧コマンドはaliasによって引き続き実行できます。

azd tool upgrade --all

しかし、JSON出力を取得するときは、旧aliasから実行した場合でもactionが"update"になります。

azd tool upgrade --all --output json

つまり、次のような処理では、コマンド実行後の判定だけが失敗します。

if [ "$action" = "upgrade" ]; then
  echo "更新処理が実行されました"
else
  echo "想定外のactionです"
  exit 1
fi

修正後は、比較値をupdateへ変更します。

if [ "$action" = "update" ]; then
  echo "更新処理が実行されました"
else
  echo "想定外のactionです"
  exit 1
fi

PowerShellで既にactionを抽出している場合も同様です。

# 修正前
if ($result.action -ne "upgrade") {
    throw "想定外のactionです"
}

# 修正後
if ($result.action -ne "update") {
    throw "想定外のactionです"
}

このaction変更は、azd tool update --output jsonの通常実行とdry-runの両方に適用され、旧azd tool upgradealiasから呼び出した場合も同じです。([GitHub][1])

azd拡張とtoolのコマンドをupdateへ変更する

スクリプト内のコマンドは、次の形へ変更します。

拡張機能を個別に更新する

azd extension update <extension-id>

インストール済み拡張機能をまとめて更新する

azd extension update --all

toolを個別に更新する

azd tool update <tool-name>

インストール済みtoolをまとめて更新する

azd tool update --all

azd extension updateは、更新対象の拡張機能ID、--all、--source、--versionなどを指定できます。azd tool updateでは、--allのほか、更新内容を事前確認する--dry-runも利用できます。([Microsoft Learn][2])

たとえば、toolの更新予定をJSONで確認する場合は次の形です。

azd tool update --all --dry-run --output json

既存のCIがJSONを保存して後続処理へ渡している場合は、コマンド名だけでなく、後続のaction判定まで確認してください。

–no-dependency-upgradesを修正する

拡張機能本体だけを更新し、依存する拡張機能を更新したくない場合の正式なフラグは、--no-dependency-updatesです。

azd extension update <extension-id> --no-dependency-updates

従来の指定は次のとおりでした。

azd extension upgrade <extension-id> --no-dependency-upgrades

旧--no-dependency-upgradesは互換用の非表示aliasとして残されています。そのため、直ちにすべての実行が失敗するとは限りませんが、CI定義、シェルスクリプト、社内ドキュメント、テストコードは新しい表記へ変更しておくべきです。([GitHub][1])

特に、次のような文字列一致を使っている処理を見落とさないようにします。

コマンドラインを組み立てるコード
許可するオプションを列挙した設定ファイル
コマンド出力のスナップショットテスト
ヘルプ表示を検査するテスト
CIの禁止文字列・許可文字列ルール
READMEや運用手順書

upgradeを一括置換してはいけない

リポジトリ内のupgradeをすべてupdateへ一括置換する方法は避けてください。

今回の変更では、コマンド名、toolのJSONに含まれるaction、フラグ、テレメトリ識別子が変更されています。一方で、拡張機能更新のJSONに含まれるstatus: "upgraded"、dependencyUpgrades、summary.upgradedなどは、互換性を維持する対象として変更範囲外に置かれました。([GitHub][3])

そのため、次のように対象を分けて修正します。

文字列	対応
`azd extension upgrade`	`azd extension update`へ変更
`azd tool upgrade`	`azd tool update`へ変更
JSONの`action == "upgrade"`	`"update"`へ変更
`--no-dependency-upgrades`	`--no-dependency-updates`へ変更
`status == "upgraded"`	使用しているJSONの仕様を確認してから判断
`dependencyUpgrades`	機械的に変更しない
`summary.upgraded`	機械的に変更しない

Git管理下のファイルを調べる場合は、次のように候補を抽出できます。

git grep -nE 'azd (extension|tool) upgrade|no-dependency-upgrades|action.*upgrade'

テレメトリや監視設定も含めて探す場合は、次の文字列も検索します。

git grep -nE 'ext\.upgrade|extension\.upgrade|dependency_upgrade|tool\.upgrade'

検索結果を一律置換せず、コマンド、JSON、テレメトリ、表示文言のどれに該当するかを確認してから修正してください。

テレメトリの旧identifierを修正する

独自の監視クエリやダッシュボードでazdのテレメトリを集計している場合は、次のidentifier変更を確認します。([GitHub][1])

旧identifier	新identifier
`ext.upgrade`	`ext.update`
`extension.upgrade.*`	`extension.update.*`
`extension.dependency_upgrade_count`	`extension.dependency_update_count`
`tool.upgrade.*`	`tool.update.*`

影響を受けやすいのは、次のような設定です。

Application Insightsなどのカスタムクエリ
KQLで作成したダッシュボード
イベント名を条件にしたアラート
定期レポートの集計処理
データエクスポート後のETL処理
テレメトリ名を固定した単体テスト

移行期間中に旧版と新版のazdが混在する環境では、新旧両方を一時的に集計する方法もあります。

| where EventName in ("ext.upgrade", "ext.update")

すべての実行環境が新しいazdへ移行したことを確認してから、旧identifierを除外すると集計漏れを防げます。

source名エラーは削除して再追加する

拡張機能source名の検証が厳格化されたため、以前は登録できていた名前でも、更新時に読み込みエラーになることがあります。

代表的な対象は次の名前です。

空白を含む名前
ピリオドを含む名前
大文字を含む名前
その他の記号を含む名前

たとえば、次の名前は修正対象です。

My Source
team.registry
Internal Registry
PRODUCTION
team@example

既存の不正なsource名は、自動的に名前を変換されません。明示的に削除し、適合する名前で再追加します。([GitHub][4])

登録済みsourceを確認する

azd extension source list

削除前に、対象sourceの種類とlocationを控えてください。再追加時には、原則として同じレジストリURLまたはファイルパスを指定します。

不正な名前のsourceを削除する

空白やピリオドを含む名前は、引用符で囲みます。

azd extension source remove "My Source"

azd extension source remove "team.registry"

旧形式の不正な名前が通常のsource読み込みを妨げている場合でも、source removeは修復経路として利用できるよう設計されています。([GitHub][4])

適合する名前で再追加する

URLベースのsourceを再登録する例です。

azd extension source add -n my-source -t url -l "<registry-url>"

ファイルベースのsourceなら、-t fileを指定します。

azd extension source add -n internal_registry -t file -l "<registry-file-path>"

再登録後は一覧を確認します。

azd extension source list

必要に応じて、sourceのレジストリ内容も検証できます。

azd extension source validate my-source

source validateは、レジストリの必須項目、バージョン形式、成果物構造、拡張機能IDなどを確認するコマンドです。([Microsoft Learn][2])

source名に使える文字と命名例

2026年8月のリリースノートでは、source名は1～64文字の小文字、数字、ハイフン、アンダースコアに制限されると説明されています。現在のMicrosoft Learnでは、さらに先頭と末尾を英数字にすること、予約名を使用しないことが明記されています。([GitHub][1])

使用できる名前

dev
team-registry
team_registry
internal01
registry-prod-01
a

使用できない名前

名前	問題点
`My Source`	大文字と空白を含む
`foo.bar`	ピリオドを含む
`TEAM`	大文字を含む
`dev/source`	スラッシュを含む
`-development`	先頭がハイフン
`development_`	末尾がアンダースコア
`azd`	予約済みの公式source名
`bundle`	予約名

CIや登録用スクリプトで事前検証する場合は、名前の形式を次の正規表現で確認できます。

^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$

さらに、azdとbundleを別条件で拒否します。

source_name="team-registry"

if [[ ! "$source_name" =~ ^[a-z0-9]([a-z0-9_-]{0,62}[a-z0-9])?$ ]] ||
   [[ "$source_name" == "azd" ]] ||
   [[ "$source_name" == "bundle" ]]; then
  echo "使用できないsource名です: $source_name"
  exit 1
fi

このチェックをsource登録前に入れておけば、本番環境で初めて命名エラーが発覚する事態を防ぎやすくなります。

azd updateと拡張・toolのupdateを混同しない

updateという名前が増えたため、何を更新するコマンドなのかを区別する必要があります。

コマンド	更新対象
`azd update`	Azure Developer CLI本体
`azd extension update`	インストール済みのazd拡張機能
`azd tool update`	azdが管理する開発tool

azd updateはCLI本体を最新バージョンへ更新するコマンドです。拡張機能やtoolの更新を代わりに実行するものではありません。反対に、azd extension updateを実行しても、azd本体は更新されません。([Microsoft Learn][2])

更新処理を自動化する場合は、目的に応じて処理を分けます。

# azd本体
azd update

# azd拡張機能
azd extension update --all

# azd管理下のtool
azd tool update --all

管理者がCLI本体のバージョンを固定しているCIでは、無条件にazd updateを追加するのではなく、使用バージョンを明示してから拡張機能とtoolの更新処理を修正してください。

2026年8月の変更を一つのバージョンとして扱わない

Microsoftの2026年8月まとめには、1.30.0、1.31.0、1.31.1、1.31.2、1.32.0の複数リリースが含まれています。今回のコマンド名、tool更新JSON、テレメトリ識別子、source名制限の変更は1.31.0のリリースノートに掲載されていますが、8月まとめに記載されたほかの機能追加や不具合修正は別バージョンに分かれています。([Microsoft for Developers][5])

最初に実行環境のバージョンを確認してください。

azd version

ローカルPC、開発コンテナ、セルフホストランナー、Microsoftホステッドランナーでバージョンが異なると、同じスクリプトでも結果が変わります。CIログにもazd versionを出力しておくと、将来のトラブル調査が容易になります。

よくある失敗と修正方法

症状	主な原因	修正方法
コマンドは成功するがCIが失敗する	JSONの`action == "upgrade"`が残っている	`"update"`へ変更
helpにはupdateと出るが旧コマンドも動く	`upgrade`がaliasとして残っている	新規スクリプトは正式名へ統一
オプションが見つからない	`--no-dependency-upgrades`を使用している	`--no-dependency-updates`へ変更
拡張機能更新時にsource読み込みエラーが出る	source名に空白、ピリオド、大文字がある	旧sourceを削除し、適合名で再追加
監視グラフの件数が減った	テレメトリクエリが旧identifierのみを検索している	`update`系identifierへ変更
JSONテストが別の箇所で失敗する	`upgraded`まで一括置換した	コマンド、toolの`action`、拡張JSONを分けて確認
`azd update`後も拡張機能が更新されない	CLI本体と拡張機能を混同している	`azd extension update`を別途実行
開発PCでは成功しCIだけ失敗する	azdのバージョン差	各環境で`azd version`を記録

修正後に確認するチェックリスト

修正後は、次の順序で確認すると原因を切り分けやすくなります。

azd versionで実行環境ごとのバージョンを確認する
azd extension upgradeをazd extension updateへ変更する
azd tool upgradeをazd tool updateへ変更する
tool更新JSONのaction判定をupdateへ変更する
--no-dependency-upgradesを--no-dependency-updatesへ変更する
テレメトリのupgrade系identifierを確認する
source名に空白、ピリオド、大文字がないか確認する
不正なsourceは削除し、同じlocationを適合名で再登録する
upgradedやdependencyUpgradesを機械的に置換していないか確認する
CIでdry-runと本実行を分けて検証する

最初にリポジトリ内の旧コマンド、旧フラグ、旧テレメトリ名を検索し、その後にsource一覧を確認してください。コマンド名だけ直して終わりにせず、機械可読JSONとsource設定まで確認することが、azd更新スクリプトを安定して復旧させるポイントです。
[1]: https://github.com/Azure/azure-dev/releases/tag/azure-dev-cli_1.31.0 “Release azure-dev-cli_1.31.0 · Azure/azure-dev · GitHub”
[2]: https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference “Azure Developer CLI reference | Microsoft Learn”
[3]: https://github.com/Azure/azure-dev/pull/9370 “Rename azd extension/tool UPGRADE commands to UPDATE by hyoshis · Pull Request #9370 · Azure/azure-dev · GitHub”
[4]: https://github.com/Azure/azure-dev/pull/9451 “fix(extensions): validate source names by JeffreyCA · Pull Request #9451 · Azure/azure-dev · GitHub”
[5]: https://devblogs.microsoft.com/azure-sdk/azure-developer-cli-azd-august-2026/ “Azure Developer CLI (azd) – August 2026 – Azure SDK Blog”

この記事を書いた人

佐藤健司

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

azd拡張の更新スクリプトが動かない原因と直し方｜upgradeからupdate・source名制限

まず確認すべき変更点

upgradeコマンドが動くのにスクリプトが失敗する理由

azd拡張とtoolのコマンドをupdateへ変更する

拡張機能を個別に更新する

インストール済み拡張機能をまとめて更新する

toolを個別に更新する

インストール済みtoolをまとめて更新する

–no-dependency-upgradesを修正する

upgradeを一括置換してはいけない

テレメトリの旧identifierを修正する

source名エラーは削除して再追加する

登録済みsourceを確認する

不正な名前のsourceを削除する

適合する名前で再追加する

source名に使える文字と命名例

使用できる名前

使用できない名前

azd updateと拡張・toolのupdateを混同しない

2026年8月の変更を一つのバージョンとして扱わない

よくある失敗と修正方法

修正後に確認するチェックリスト

この記事を書いた人

コメント

コメントするコメントをキャンセル

azd拡張の更新スクリプトが動かない原因と直し方｜upgradeからupdate・source名制限

まず確認すべき変更点

upgradeコマンドが動くのにスクリプトが失敗する理由

azd拡張とtoolのコマンドをupdateへ変更する

拡張機能を個別に更新する

インストール済み拡張機能をまとめて更新する

toolを個別に更新する

インストール済みtoolをまとめて更新する

–no-dependency-upgradesを修正する

upgradeを一括置換してはいけない

テレメトリの旧identifierを修正する

source名エラーは削除して再追加する

登録済みsourceを確認する

不正な名前のsourceを削除する

適合する名前で再追加する

source名に使える文字と命名例

使用できる名前

使用できない名前

azd updateと拡張・toolのupdateを混同しない

2026年8月の変更を一つのバージョンとして扱わない

よくある失敗と修正方法

修正後に確認するチェックリスト

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

コメントするコメントをキャンセル