[Change Safety] Generator: emit inline IDynamicParameters (-AcquirePolicyToken/-ChangeReference) on write cmdlets (Stage D)

[YangAn-microsoft]

Summary

Generator half of Change Safety for AutoRest management-plane modules, opt-in per module via an enable-change-safety config flag. Adds -AcquirePolicyToken and -ChangeReference to write-verb cmdlets and wires the pipeline step that acquires a policy token and stamps the x-ms-policy-external-evaluations header on write requests. Az.Accounts (Azure/azure-powershell#29840) fills the pipeline slot.

What it does

1. Parameter surfacing. implementChangeSafetyParameters() in cmdlets/class.ts adds an inline IDynamicParameters.GetDynamicParameters() to generated write cmdlets, emitting -AcquirePolicyToken (SwitchParameter) and -ChangeReference (string) — the same dynamic-parameter mechanism SDK cmdlets use. Names + help text are reused verbatim from azure-powershell-common's ChangeSafetyParameters (a contract pin test in Accounts.Test keeps them in sync).
2. Proxy forwarding. The public proxy function wraps the private cmdlet with a static param() block, so DynamicParamOutput (resources/psruntime/BuildTime/Models/PsProxyOutputs.cs) emits a dynamicparam block that forwards the wrapped cmdlet's dynamic parameters — self-gated on the wrapped cmdlet implementing IDynamicParameters. ExportProxyCmdlet.cs inserts it between the proxy param() block and begin{}.
3. Pipeline hook. module/module-class.ts declares the ChangeSafetyPolicyTokenDelegate alias + AddChangeSafetyPolicyTokenHandler VTable property and invokes it in CreatePipeline right after OnNewRequest; generators/psm1.ts maps it in the .psm1.

internal/project.ts reads enable-change-safety into Project.enableChangeSafety (default false); internal/powershell-declarations.ts adds the IDynamicParameters declaration.

Gating

All change-safety output — parameters, proxy dynamicparam, and the VTable plumbing — is gated on enable-change-safety (management-plane only). Flag off (default): zero generated-code diff. The proxy dynamicparam is additionally self-gated on IDynamicParameters, so cmdlets without dynamic parameters are unaffected. The only unconditional change is to the two build-time proxy runtime sources (PsProxyOutputs.cs, ExportProxyCmdlet.cs), which emit nothing extra for cmdlets without dynamic parameters.

Scope

Seven files: powershell/cmdlets/class.ts, powershell/module/module-class.ts, powershell/generators/psm1.ts, powershell/internal/project.ts, powershell/internal/powershell-declarations.ts, powershell/resources/psruntime/BuildTime/Models/PsProxyOutputs.cs, powershell/resources/psruntime/BuildTime/Cmdlets/ExportProxyCmdlet.cs, plus refreshed tests-emitter baselines.

Verification

• npm run build, npm run eslint, npm test, tests-sdk1-support (-AllowList -SkipCsharp): clean / all Equal.
• tests-emitter baselines refreshed for the 43 whitelisted cases: only the two build-time runtime sources change per case (no Module.cs / .psm1 diff). The refresh also picks up a pre-existing stale runtime/Context.cs comment-typo baseline (fixed in the generator resource by Fix typo in comment: PSBoundParamters -> PSBoundParameters #1514; 25 cases).
• Generated-module build + shape check (fresh regen of Az.ManagedServiceIdentity with --enable-change-safety): autorest → 425 files, exit 0; build-module.ps1 -NoDocs → exit 0. The emitted exports/ are correctly verb-gated — the dynamicparam block appears on all write cmdlets (New/Remove/Update-Az*, 6/6) and on none of the read cmdlets (Get-Az*, 0/4). The private write cmdlet's GetDynamicParameters() emits exactly -AcquirePolicyToken (SwitchParameter) and -ChangeReference (string) with help text matching azure-powershell-common's ChangeSafetyParameters; the public proxy re-declares them via the forwarding dynamicparam block.

Live end-to-end test (real Azure)

Re-validated on the latest upstream/main (merged into this branch) after rebuilding the generator (rush update && rush rebuild). Full flow on a real subscription with an opted-in module (Az.ManagedServiceIdentity, regenerated by this branch with enable-change-safety) plus the paired Az.Accounts build (Azure/azure-powershell#29840).

Command

New-AzUserAssignedIdentity -ResourceGroupName rg-cs-e2e -Name mi-cs-e2e -Location eastus -AcquirePolicyToken -Confirm:$false

The public proxy function accepted -AcquirePolicyToken — surfaced via the generated dynamicparam forwarding block this PR adds — and the identity was created (HTTP 200/201). A read cmdlet does not surface the parameter.

Pipeline trace (temporary token-safe debug hook; only metadata + a one-way SHA-256 hash of the stamped header are logged — never the raw token)

[PolicyTokenAcquirer] Intercept PUT .../userAssignedIdentities/mi-cs-e2e?api-version=2023-01-31
[PolicyTokenAcquirer] Payload prepared.
[PolicyTokenAcquirer] POST acquirePolicyToken .../Microsoft.Authorization/acquirePolicyToken?api-version=2025-03-01
[PolicyTokenAcquirer] Response 200 OK
[PolicyTokenAcquirer] Token acquired and header added.
writeRequest: PUT .../userAssignedIdentities/mi-cs-e2e?api-version=2023-01-31
  x-ms-policy-external-evaluations: sha256=789ed4cc92f969d73c3ad6d5004def21fdf381dce8998f822fd81802c1c7efb7 (len=4538)
  writeBody: { "location": "eastus" }

Note: the AutoRest -Debug dump prints the request at BeforeCall, before the appended change-safety step runs, so x-ms-policy-external-evaluations is not visible in that dump. The in-step trace above — a SHA-256 hash of the 4538-char token plus the stamped write request — confirms the token was acquired and the header stamped on the wire, and the write returned 200. Subscription/tenant IDs are redacted; test resources are provisioned in a BAMI subscription and removed after validation.

Dependencies

• Pairs with Az.Accounts: [Change Safety] Az.Accounts: AutoRest AcquirePolicyToken pipeline step (Stage A) azure-powershell#29840.
• Depends on shared core: Refactor: extract shared PolicyTokenAcquirer + ChangeSafetyParameters (Change Safety – Stage 0) azure-powershell-common#454.
• Design write-up: Azure/CLIPS#408.
• Kept draft: regenerated cmdlets take effect once this generator and Az.Accounts are released and modules opt in + regenerate.

[Yabo Hu (VeryEarly)]

I think the wiring of the runtime delegate to add headers is missing from this PR

[YangAn-microsoft]

Yabo Hu (@VeryEarly) re: "the wiring of the runtime delegate to add headers is missing from this PR" — that is intentional in this design. This is the static-parameter approach that replaced #1548 (which used a runtime-wired VTable delegate). Here the generator only emits the static -AcquirePolicyToken / -ChangeReference [Parameter] properties; their values flow through the cmdlet BoundParameters to the module-level HTTP pipeline step in Az.Accounts (Azure/azure-powershell#29840), which calls acquirePolicyToken and stamps the x-ms-policy-external-evaluations header. So there is deliberately no runtime-wired delegate in the generator anymore — that responsibility lives in Az.Accounts, keeping the generated cmdlet self-contained with no cross-repo runtime coupling. Design write-up: Azure/CLIPS#408.

[Copilot]

Pull request overview

Adds opt-in support to emit Change Safety dynamic parameters (-AcquirePolicyToken, -ChangeReference) on generated Azure management-plane write-verb cmdlets by generating an inline IDynamicParameters implementation directly in each cmdlet (avoiding any Module/VTable runtime wiring), controlled by a new enable-change-safety configuration flag.

Changes:

• Introduces enable-change-safety (default false) as a per-module configuration flag, exposed as Project.enableChangeSafety.
• Adds a PowerShell declarations entry for System.Management.Automation.IDynamicParameters.
• Updates cmdlet generation to (when gated conditions are met) implement IDynamicParameters and emit GetDynamicParameters() that returns a locally-built RuntimeDefinedParameterDictionary containing the two Change Safety parameters.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
powershell/internal/project.ts	Adds enableChangeSafety and loads enable-change-safety config (default off) to gate emission.
powershell/internal/powershell-declarations.ts	Declares IDynamicParameters so generated cmdlets can implement it.
powershell/cmdlets/class.ts	Emits inline IDynamicParameters.GetDynamicParameters() for eligible Azure management-plane write-verb cmdlets, adding the two dynamic parameters.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 118 changed files in this pull request and generated no new comments.