Batch breaking changes #28767

wiboris · 2025-10-28T21:48:57Z

Description

Updating the batch api's to 2024-07-01 and removing deprecated commands and parameters that were documented in the last release.

Removed command Get-AzBatchRemoteDesktopProtocolFile.
Removed command Get-AzBatchCertificate.
Removed command New-AzBatchCertificate.
Removed command Remove-AzBatchCertificate.
Removed command Stop-AzBatchCertificateDeletion.
Removed parameter CloudServiceConfiguration from New-AzBatchPool command.
Removed parameter CertificateReferences from New-AzBatchPool command.
Removed parameter TargetNodeCommunication from New-AzBatchPool command.
Removed parameter CurrentNodeCommunication from New-AzBatchPool command.
Removed parameter ResourceTag from New-AzBatchPool command.
Removed parameter ApplicationLicenses from New-AzBatchPool command.
Removed properties CloudServiceConfiguration, CertificateReferences, TargetNodeCommunication, CurrentNodeCommunication, ResourceTag, and ApplicationLicenses from PsCloudPool model.
Removed property CertificateReferences from PsComputeNode model.
Removed properties CloudServiceConfiguration, CertificateReferences, TargetNodeCommunication, CurrentNodeCommunication, ResourceTag, and ApplicationLicenses from PsPoolSpecification model.
Added new enum values Deallocated and Deallocating to PSNodeCounts model.
Added properties CommunityGalleryImageId and SharedGalleryImageId to PSImageReference model.
Added property SkipWithdrawFromVNet to PSJobNetworkConfiguration model.
Added property SecurityProfile to PSManagedDisk model.
Added property ContainerHostBatchBindMounts to PSTaskContainerSettings model.

Mandatory Checklist

Please choose the target release of Azure PowerShell. (⚠️Target release is a different concept from API readiness. Please click below links for details.)
- General release
- Public preview
- Private preview
- Engineering build
- No need for a release
Check this box to confirm: I have read the Submitting Changes section of CONTRIBUTING.md and reviewed the following information:

SHOULD update ChangeLog.md file(s) appropriately
- Update src/{{SERVICE}}/{{SERVICE}}/ChangeLog.md.
  - A snippet outlining the change(s) made in the PR should be written under the ## Upcoming Release header in the past tense.
- Should not change ChangeLog.md if no new release is required, such as fixing test case only.
SHOULD regenerate markdown help files if there is cmdlet API change. Instruction
SHOULD have proper test coverage for changes in pull request.
SHOULD NOT adjust version of module manually in pull request

azure-client-tools-bot-prd · 2025-10-28T21:49:00Z

Thanks for your contribution! The pull request validation has started. Please revisit this comment for updated status.

isra-fel · 2025-10-28T22:08:33Z

/azp run

azure-pipelines · 2025-10-28T22:08:51Z

Azure Pipelines successfully started running 3 pipeline(s).

isra-fel · 2025-10-29T00:08:13Z

/azp run

azure-pipelines · 2025-10-29T00:08:31Z

Azure Pipelines successfully started running 3 pipeline(s).

isra-fel · 2025-10-29T22:08:30Z

/azp run

azure-pipelines · 2025-10-29T22:08:47Z

Azure Pipelines successfully started running 3 pipeline(s).

Copilot

Pull Request Overview

This PR removes deprecated certificate-related cmdlets and deprecated pool configuration properties from the Az.Batch module as part of version 4.0.0. The changes align with Azure Batch service deprecations for certificate management and cloud service configuration features.

Key changes:

Removes 5 certificate-related cmdlets and their associated code
Removes deprecated pool configuration parameters including CloudServiceConfiguration, CertificateReferences, ApplicationLicenses, ResourceTags, and node communication mode properties
Adds new properties to support updated Azure Batch API features (deallocated node states, gallery images, VNet management, disk security, container bind mounts)
Updates SDK dependency from Microsoft.Azure.Batch 16.2.0 to 16.3.1
Updates test recordings to use new API version (2024-07-01.20.0)

Reviewed Changes

Copilot reviewed 33 out of 202 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
ChangeLog.md	Documents all breaking changes and new features for version 4.0.0
Help documentation files	Removes documentation for deprecated certificate commands and pool parameters
Command files	Removes certificate and RDP file command implementations
Model files	Removes deprecated model classes and properties from pool-related types
Utils.cs	Removes certificate reference conversion logic
BatchClient files	Removes certificate operations and deprecated pool property handling
Batch.csproj	Updates SDK version and package references
Az.Batch.psd1	Updates module manifest to remove deprecated cmdlets
Test files	Updates test recordings and removes deprecated test scenarios

src/Batch/Batch/ChangeLog.md

github-actions · 2025-10-30T01:32:31Z

To the author of the pull request,
This PR was labeled "Contains Breaking Change" because breaking changes have been detected by the static analysis pipeline.

According to our policy, breaking changes can only take place during major release and they must be preannounced.
Please follow our guide on the detailed steps.
Required: Please fill in the task below to facilitate our contact,you will receive notifications related to breaking changes.

isra-fel · 2025-10-30T18:38:13Z

/azp run

azure-pipelines · 2025-10-30T18:38:31Z

Azure Pipelines successfully started running 3 pipeline(s).

isra-fel · 2025-10-30T20:38:27Z

/azp run

azure-pipelines · 2025-10-30T20:38:46Z

Azure Pipelines successfully started running 3 pipeline(s).

isra-fel · 2025-11-03T21:43:21Z

/azp run

azure-pipelines · 2025-11-03T21:43:40Z

Azure Pipelines successfully started running 3 pipeline(s).

isra-fel · 2025-11-03T22:39:04Z

/azp run

azure-pipelines · 2025-11-03T22:39:31Z

Azure Pipelines successfully started running 3 pipeline(s).

isra-fel · 2025-11-04T01:10:55Z

/azp run

azure-pipelines · 2025-11-04T01:11:02Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

dolauli · 2025-11-04T01:39:51Z

/azp run

azure-pipelines · 2025-11-04T01:40:10Z

Azure Pipelines successfully started running 3 pipeline(s).

isra-fel · 2025-11-04T03:08:54Z

/azp run

azure-pipelines · 2025-11-04T03:09:00Z

Azure Pipelines will not run the associated pipelines, because the pull request was updated after the run command was issued. Review the pull request again and issue a new run command.

dolauli · 2025-11-04T03:15:20Z

/azp run

azure-pipelines · 2025-11-04T03:15:37Z

Azure Pipelines successfully started running 3 pipeline(s).

dolauli · 2025-11-04T06:04:00Z

@wiboris, Could you help authorize a markdown like this for each of the breaking change? We'll need it for publishing migration guides. Just leave a comment in the issue would be fine. Thank you!

## Az.Accounts

### `Get-AzAccessToken`

The default output type is changed from `PSAccessToken` to `PSSecureAccessToken`.That is to change plaintext `PSAccessToken.Token` to `SecureString PSSecureAccessToken.Token`

#### Before
```powershell
$authHeader = @{
    'Content-Type'  = 'application/json'
    'Authorization' = 'Bearer ' + (Get-AccessToken).Token
}
$response = Invoke-RestMethod -Method Get -Headers $authHeader -Uri $uri
```

#### After
```powershell
$secureToken = (Get-AzAccessToken).Token
$ssPtr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureToken)
try {
     $plaintextToken = [System.Runtime.InteropServices.Marshal]::PtrToStringBSTR($ssPtr)
} 
finally {
     [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ssPtr) 
}
$authHeader = @{
    'Content-Type'  = 'application/json'
    'Authorization' = 'Bearer ' + $plaintextToken
}
$response = Invoke-RestMethod -Method Get -Headers $authHeader -Uri $uri
```

wiboris · 2025-11-05T06:34:53Z

Az.Batch

`New-AzBatchCertificate`

Azure Batch account certificates feature has been retired and all certificate related commands have been removed from Batch. See https://learn.microsoft.com/en-us/azure/batch/batch-certificate-migration-guide

Before

New-AzBatchCertificate -FilePath "E:\Certificates\MyCert.cer" -BatchContext $Context

After

`Remove-AzBatchCertificate`

Azure Batch account certificates feature has been retired and all certificate related commands have been removed from Batch. See https://learn.microsoft.com/en-us/azure/batch/batch-certificate-migration-guide

Before

Remove-AzBatchCertificate -ThumbprintAlgorithm "sha1" -Thumbprint "c1e494a415149c5f211c4778b52f2e834a07247c"

After

`Stop-AzBatchCertificateDeletion`

Azure Batch account certificates feature has been retired and all certificate related commands have been removed from Batch. See https://learn.microsoft.com/en-us/azure/batch/batch-certificate-migration-guide

Before

Stop-AzBatchCertificateDeletion -ThumbprintAlgorithm "sha1" -Thumbprint "c1e494a415149c5f211c4778b52f2e834a07247c" -BatchContext $Context

After

`Get-AzBatchCertificate`

Azure Batch account certificates feature has been retired and all certificate related commands have been removed from Batch. See https://learn.microsoft.com/en-us/azure/batch/batch-certificate-migration-guide

Before

Get-AzBatchCertificate -ThumbprintAlgorithm "sha1" -Thumbprint "C1******7C" -BatchContext $Context

After

`New-AzBatchPool`

The following parameters have been removed: ResourceTag, CloudServiceConfiguration, CertificateReferences, ApplicationLicenses, CurrentNodeCommunicationMode, and TargetNodeCommunicationMode. For CloudServiceConfiguration use VirtualMachineConfiguration instead, all other removed parameters don't have a replacement.

Before

$resourceTags = @{
"Tag1" = "value1"
"Tag2" = "Value2"
}

$certificate =  -Object -TypeName "Microsoft.Azure.Commands.Batch.Models.PSCertificate"
$certificatesRef =  -Object -TypeName "Microsoft.Azure.Commands.Batch.Models.PSCertificateReferenceNew" -ArgumentList @($certificate)
$configuration = New-Object -TypeName "Microsoft.Azure.Commands.Batch.Models.PSCloudServiceConfiguration" -ArgumentList @(4,"*")

New-AzBatchPool -Id "MyPool" -VirtualMachineSize "STANDARD_D1_V2" -CloudServiceConfiguration $configuration  -TargetDedicatedComputeNodes 3 -CertificateReferences $certificatesRef -ApplicationLicenses @('licenses1', 'licenses2') -CurrentNodeCommunicationMode Default -TargetNodeCommunicationMode Classic -ResourceTags @resourceTags -BatchContext $Context

After

$imageReference = New-Object -TypeName "Microsoft.Azure.Commands.Batch.Models.PSImageReference" -ArgumentList @("WindowsServer", "MicrosoftWindowsServer", "2016-Datacenter", "*")
$configuration = New-Object -TypeName "Microsoft.Azure.Commands.Batch.Models.PSVirtualMachineConfiguration" -ArgumentList @($imageReference, "batch.node.windows amd64")
New-AzBatchPool -Id "MyPool" -VirtualMachineSize "STANDARD_D1_V2" -VirtualMachineConfiguration $configuration -TargetDedicatedComputeNodes 3 -BatchContext $Context

`Set-AzBatchPool`

The following properties have been removed from the PSCloudPool parameter: ResourceTag, CloudServiceConfiguration, CertificateReferences, ApplicationLicenses, CurrentNodeCommunicationMode, and TargetNodeCommunicationMode.

Before

$Pool = Get-AzBatchPool "ContosoPool" -BatchContext $Context

$resourceTags = @{
"Tag1" = "value1"
"Tag2" = "Value2"
}

$certificate =  -Object -TypeName "Microsoft.Azure.Commands.Batch.Models.PSCertificate"
$certificatesRef =  -Object -TypeName "Microsoft.Azure.Commands.Batch.Models.PSCertificateReferenceNew" -ArgumentList @($certificate)

$StartTask = New-Object Microsoft.Azure.Commands.Batch.Models.PSStartTask
$StartTask.CommandLine = "cmd /c echo example"

$Pool.CertificateReferences = $certificatesRef
$Pool.ApplicationLicenses = @('licenses1', 'licenses2')
$Pool.ResourceTag = $resourceTags
$Pool.TargetNodeCommunicationMode = Classic
$Pool.StartTask = $StartTask
Set-AzBatchPool -Pool $Pool -BatchContext $Context

After

$Pool = Get-AzBatchPool "ContosoPool" -BatchContext $Context

$StartTask = New-Object Microsoft.Azure.Commands.Batch.Models.PSStartTask
$StartTask.CommandLine = "cmd /c echo example"

$Pool.StartTask = $StartTask
Set-AzBatchPool -Pool $Pool -BatchContext $Context

`Get-AzBatchPool`

The following properties have been removed from the return type PSCloudPool: ResourceTag, CloudServiceConfiguration, CertificateReferences, ApplicationLicenses, CurrentNodeCommunicationMode, and TargetNodeCommunicationMode.

Before

$psCloudPool = Get-AzBatchPool -Id "MyPool" -BatchContext $Context

$var1 = $psCloudPool.Id
$var2 = $psCloudPool.ResourceTag
$var3 = $psCloudPool.CloudServiceConfiguration
$var4 = $psCloudPool.CertificateReferences
$var5 = $psCloudPool.ApplicationLicenses
$var6 = $psCloudPool.CurrentNodeCommunicationMode
$var7 = $psCloudPool.TargetNodeCommunicationMode

After

Get-AzBatchPool -Id "MyPool" -BatchContext $Context

$var1 = $psCloudPool.Id

`Get-AzBatchRemoteDesktopProtocolFile`

The command Get-AzBatchRemoteDesktopProtocolFile has been deprecated, use Get-AzBatchRemoteLoginSettings instead.

Before

Get-AzBatchRemoteDesktopProtocolFile -PoolId "Pool06" -ComputeNodeId "ComputeNode01" -DestinationPath "C:\PowerShell\ComputeNode01.rdp" -BatchContext $Context

After

Get-AzBatchRemoteLoginSetting -PoolId "Pool06" -ComputeNodeId "ComputeNode01" -BatchContext $Context

`Get-AzBatchJob`

The property PoolInformation of the return type PSCloudJob has the following properties removed in its sub object: ResourceTag, CloudServiceConfiguration, CertificateReferences, ApplicationLicenses, CurrentNodeCommunicationMode, and TargetNodeCommunicationMode.

Before

$psCloudJob =  Get-AzBatchJob -Id "Job01" -BatchContext $Context

$var1 = $psCloudJob.PoolInformation.AutoPoolSpecification.PoolSpecification.PoolId
$var2 = $psCloudJob.PoolInformation.AutoPoolSpecification.PoolSpecification.ResourceTag
$var3 = $psCloudJob.PoolInformation.AutoPoolSpecification.PoolSpecification.CloudServiceConfiguration
$var4 = $psCloudJob.PoolInformation.AutoPoolSpecification.PoolSpecification.CertificateReferences
$var5 = $psCloudJob.PoolInformation.AutoPoolSpecification.PoolSpecification.ApplicationLicenses
$var6 = $psCloudJob.PoolInformation.AutoPoolSpecification.PoolSpecification.CurrentNodeCommunicationMode
$var7 = $psCloudJob.PoolInformation.AutoPoolSpecification.PoolSpecification.TargetNodeCommunicationMode

After

$psCloudJob =  Get-AzBatchJob -Id "Job01" -BatchContext $Context

$var1 = $psCloudJob.PoolInformation.AutoPoolSpecification.PoolSpecification.PoolId

`Get-AzBatchComputeNode`

The property CertificateReferences has been removed from return type PSComputeNode

Before

$computeNode = Get-AzBatchComputeNode -PoolId "Pool06" -Id "tvm-2316545714_1-20150725t213220z" -BatchContext $Context

var1 = $computeNode.Id
var2 = $computeNode.CertificateReferences

After

$computeNode = Get-AzBatchComputeNode -PoolId "Pool06" -Id "tvm-2316545714_1-20150725t213220z" -BatchContext $Context

var1 = $computeNode.Id

wiboris marked this pull request as ready for review October 29, 2025 22:01

Copilot AI review requested due to automatic review settings October 29, 2025 22:01

wiboris requested review from DanielMicrosoft, NoriZC, Pan-Qi, VeryEarly, YanaXu, dolauli, isra-fel, notyashhh, vidai-msft and wyunchi-ms as code owners October 29, 2025 22:01

Copilot AI reviewed Oct 29, 2025

View reviewed changes

src/Batch/Batch/ChangeLog.md Show resolved Hide resolved

src/Batch/Batch/ChangeLog.md Show resolved Hide resolved

dolauli self-assigned this Oct 30, 2025

dolauli added the Contains Breaking Change This PR contains breaking change label Oct 30, 2025

wiboris added 5 commits October 30, 2025 13:24

inital generation

41de5c8

2023-05-01 generation

42de1b6

updating test recordings

aa65763

batch managmeent 2023-11-01 generation

b1c2067

Batch managmenet 2024-02-01 generation

3da03ee

wiboris added 4 commits October 30, 2025 13:24

removing applicationlicense

85688f9

update help files

4c548ad

updating test recordings

795469a

test updates

9ccd9ff

wiboris force-pushed the BatchBreakingChanges2025 branch from c3c2145 to 9ccd9ff Compare October 30, 2025 20:25

updating generation

789133a

adding breaking change exception

a67f580

update format

950acb7

more exceptions

791734a

more breaking changes

e634189

dolauli approved these changes Nov 4, 2025

View reviewed changes

dolauli added the Breaking change PR reviewed Add this label after a PR with breaking change has been reviewed and approved. label Nov 4, 2025

dolauli added the Breaking change PR migration guide provided Add this label after the migration guide is provided by the PR owner label Nov 5, 2025

dolauli merged commit 0e7351a into Azure:main Nov 5, 2025
14 checks passed

Batch breaking changes #28767

Batch breaking changes #28767

Uh oh!

Conversation

wiboris commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Mandatory Checklist

Uh oh!

azure-client-tools-bot-prd bot commented Oct 28, 2025

Uh oh!

isra-fel commented Oct 28, 2025

Uh oh!

azure-pipelines bot commented Oct 28, 2025

Uh oh!

isra-fel commented Oct 29, 2025

Uh oh!

azure-pipelines bot commented Oct 29, 2025

Uh oh!

isra-fel commented Oct 29, 2025

Uh oh!

azure-pipelines bot commented Oct 29, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Oct 30, 2025

Uh oh!

isra-fel commented Oct 30, 2025

Uh oh!

azure-pipelines bot commented Oct 30, 2025

Uh oh!

isra-fel commented Oct 30, 2025

Uh oh!

azure-pipelines bot commented Oct 30, 2025

Uh oh!

isra-fel commented Nov 3, 2025

Uh oh!

azure-pipelines bot commented Nov 3, 2025

Uh oh!

isra-fel commented Nov 3, 2025

Uh oh!

azure-pipelines bot commented Nov 3, 2025

Uh oh!

isra-fel commented Nov 4, 2025

Uh oh!

azure-pipelines bot commented Nov 4, 2025

Uh oh!

dolauli commented Nov 4, 2025

Uh oh!

azure-pipelines bot commented Nov 4, 2025

Uh oh!

isra-fel commented Nov 4, 2025

Uh oh!

azure-pipelines bot commented Nov 4, 2025

Uh oh!

dolauli commented Nov 4, 2025

Uh oh!

azure-pipelines bot commented Nov 4, 2025

Uh oh!

dolauli commented Nov 4, 2025

Uh oh!

wiboris commented Nov 5, 2025

Az.Batch

New-AzBatchCertificate

Before

After

Remove-AzBatchCertificate

Before

After

Stop-AzBatchCertificateDeletion

Before

After

Get-AzBatchCertificate

Before

After

wiboris commented Oct 28, 2025 •

edited

Loading

`New-AzBatchCertificate`

`Remove-AzBatchCertificate`

`Stop-AzBatchCertificateDeletion`

`Get-AzBatchCertificate`

`New-AzBatchPool`

`Set-AzBatchPool`

`Get-AzBatchPool`

`Get-AzBatchRemoteDesktopProtocolFile`

`Get-AzBatchJob`

`Get-AzBatchComputeNode`