Azure batch updating changelog and migration guide#58400
Azure batch updating changelog and migration guide#58400
Conversation
There was a problem hiding this comment.
Pull request overview
Updates Azure Batch package documentation to better reflect the GA release by polishing the migration guide formatting and adding a consolidated list of breaking changes to the changelog.
Changes:
- Refines
MigrationGuide.mdformatting/structure (bullets, headings, whitespace) and minor text cleanup. - Adds a
### Breaking Changessection for1.0.0inCHANGELOG.md, documenting removed/renamed APIs and type changes.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| sdk/batch/Azure.Compute.Batch/MigrationGuide.md | Markdown formatting and content edits to improve migration guidance readability. |
| sdk/batch/Azure.Compute.Batch/CHANGELOG.md | Documents GA breaking changes (removed types/properties, renamed properties/parameters, type change). |
| - **Name Changes**: Many of the objects and operations names have changed in `Azure.Compute.Batch`. This guide below should highlight these but expect such differences as object names changing from `CloudPool` to `BatchPool` and operations such as `batchClient.JobOperations.ListTasks()` to `batchClient.GetTasks()` | ||
| - **API location**: In `Microsoft.Azure.Batch` all operations are grouped into operation classes whereas in `Azure.Compute.Batch` all operations are under the BatchClient. For example, in `Microsoft.Azure.Batch` all pool operations are under a PoolOperations class, Job operations are under a JobOperations class, and so on. For example, in `Microsoft.Azure.Batch` the method to create a pool would be under PoolOperations `batchClient.PoolOperations.CreatePool()` whereas in `Azure.Compute.Batch` the operation is under the client `batchClient.CreatePool()`. In addition, `Microsoft.Azure.Batch` allowed operations off of objects such as the case below where the user would retrieve a CloudPool object, modify it, then issue a `.Commit()` to update it. | ||
| - **API location**: In `Microsoft.Azure.Batch` all operations are grouped into operation classes whereas in `Azure.Compute.Batch` all operations are under the BatchClient. For example, in `Microsoft.Azure.Batch` all pool operations are under a PoolOperations class, Job operations are under a JobOperations class, and so on. For example, in `Microsoft.Azure.Batch` the method to create a pool would be under PoolOperations `batchClient.PoolOperations.CreatePool()` whereas in `Azure.Compute.Batch` the operation is under the client `batchClient.CreatePool()`. | ||
| - **Object operations** `Microsoft.Azure.Batch` allowed operations off of objects such as the case below where the user would retrieve a CloudPool object, modify it, then issue a `.Commit()` to update it. |
There was a problem hiding this comment.
In this list item, the bold label is missing punctuation/structure (e.g., **Object operations**:) which makes the bullet read awkwardly and inconsistent with the preceding bullets (**Name Changes**: / **API location**:).
| - **Object operations** `Microsoft.Azure.Batch` allowed operations off of objects such as the case below where the user would retrieve a CloudPool object, modify it, then issue a `.Commit()` to update it. | |
| - **Object operations**: `Microsoft.Azure.Batch` allowed operations off of objects such as the case below where the user would retrieve a CloudPool object, modify it, then issue a `.Commit()` to update it. |
| ### Authenticate with Shared Key Credentials | ||
|
|
||
| In `Azure.Compute.Batch` you can use AzureNamedKeyCredential with your Batch account access keys to authenticate Azure commands for the Batch service. You can find your batch account shared keys in the portal under the "keys" section or you can run the following [CLI command](https://learn.microsoft.com/cli/azure/batch/account/keys?view=azure-cli-latest) | ||
| In `Azure.Compute.Batch` you can use AzureNamedKeyCredential with your Batch account access keys to authenticate Azure commands for the Batch service. You can find your batch account shared keys in the portal under the "keys" section or you can run the following [CLI command](https://learn.microsoft.com/cli/azure/batch/account/keys?view=azure-cli-latest) |
There was a problem hiding this comment.
This sentence mentions the AzureNamedKeyCredential type but doesn't format it as code (backticks), unlike other type/method references in the guide. Also consider ending the sentence with punctuation after the link to avoid it reading like it continues into the code block.
| In `Azure.Compute.Batch` you can use AzureNamedKeyCredential with your Batch account access keys to authenticate Azure commands for the Batch service. You can find your batch account shared keys in the portal under the "keys" section or you can run the following [CLI command](https://learn.microsoft.com/cli/azure/batch/account/keys?view=azure-cli-latest) | |
| In `Azure.Compute.Batch` you can use `AzureNamedKeyCredential` with your Batch account access keys to authenticate Azure commands for the Batch service. You can find your batch account shared keys in the portal under the "keys" section or you can run the following [CLI command](https://learn.microsoft.com/cli/azure/batch/account/keys?view=azure-cli-latest). |
| ## Error Handling | ||
|
|
||
| In `Azure.Compute.Batch` when a command fails due to an error on the server side an exception of type RequestFailedException will be thrown. Inside that exception will an "ErrorCode" property which is a string representation of the error, a "Status" property which represents the HTTP status code, a "Message" which provides a summary of the error, and in some cases their will be additional information in the "Data" Dictionary. | ||
| In `Azure.Compute.Batch` when a command fails due to an error on the server side an exception of type RequestFailedException will be thrown. Inside that exception will an "ErrorCode" property which is a string representation of the error, a "Status" property which represents the HTTP status code, a "Message" which provides a summary of the error, and in some cases their will be additional information in the "Data" Dictionary. |
There was a problem hiding this comment.
Grammar issues in this paragraph: "will an "ErrorCode" property" should be "will be an", and "their will" should be "there will". These make the error-handling guidance harder to read.
| In `Azure.Compute.Batch` when a command fails due to an error on the server side an exception of type RequestFailedException will be thrown. Inside that exception will an "ErrorCode" property which is a string representation of the error, a "Status" property which represents the HTTP status code, a "Message" which provides a summary of the error, and in some cases their will be additional information in the "Data" Dictionary. | |
| In `Azure.Compute.Batch` when a command fails due to an error on the server side an exception of type RequestFailedException will be thrown. Inside that exception will be an "ErrorCode" property which is a string representation of the error, a "Status" property which represents the HTTP status code, a "Message" which provides a summary of the error, and in some cases there will be additional information in the "Data" Dictionary. |
| ``` | ||
|
|
||
| Going forward there are two options. Azure batch has two sdk, [`Azure.Compute.Batch`](https://learn.microsoft.com/dotnet/api/azure.compute.batch?view=azure-dotnet-preview&viewFallbackFrom=azure-dotnet) which interacts directly the azure batch service, and [`Azure.ResourceManager.Batch`](https://learn.microsoft.com/dotnet/api/overview/azure/resourcemanager.batch-readme?view=azure-dotnet) which interacts with the Azure Resource Manager. Both of these SDK's support batch pool operations such as create/get/update/list etc but only the `Azure.ResourceManager.Batch` sdk can create a pool with managed identities and for that reason its the recommend way to create a pool. | ||
| Going forward there are two options. Azure batch has two sdk, [`Azure.Compute.Batch`](https://learn.microsoft.com/dotnet/api/azure.compute.batch?view=azure-dotnet-preview&viewFallbackFrom=azure-dotnet) which interacts directly the azure batch service, and [`Azure.ResourceManager.Batch`](https://learn.microsoft.com/dotnet/api/overview/azure/resourcemanager.batch-readme?view=azure-dotnet) which interacts with the Azure Resource Manager. Both of these SDK's support batch pool operations such as create/get/update/list etc but only the `Azure.ResourceManager.Batch` sdk can create a pool with managed identities and for that reason its the recommend way to create a pool. |
There was a problem hiding this comment.
This paragraph has multiple grammatical/wording issues (e.g., "two sdk", "SDK's", "interacts directly the azure batch service", "its the recommend way"). Please adjust wording/capitalization (e.g., "two SDKs", "SDKs", "interacts directly with the Azure Batch service", "it's the recommended way") to keep the migration guide professional and unambiguous.
| Going forward there are two options. Azure batch has two sdk, [`Azure.Compute.Batch`](https://learn.microsoft.com/dotnet/api/azure.compute.batch?view=azure-dotnet-preview&viewFallbackFrom=azure-dotnet) which interacts directly the azure batch service, and [`Azure.ResourceManager.Batch`](https://learn.microsoft.com/dotnet/api/overview/azure/resourcemanager.batch-readme?view=azure-dotnet) which interacts with the Azure Resource Manager. Both of these SDK's support batch pool operations such as create/get/update/list etc but only the `Azure.ResourceManager.Batch` sdk can create a pool with managed identities and for that reason its the recommend way to create a pool. | |
| Going forward, there are two options. Azure Batch has two SDKs: [`Azure.Compute.Batch`](https://learn.microsoft.com/dotnet/api/azure.compute.batch?view=azure-dotnet-preview&viewFallbackFrom=azure-dotnet), which interacts directly with the Azure Batch service, and [`Azure.ResourceManager.Batch`](https://learn.microsoft.com/dotnet/api/overview/azure/resourcemanager.batch-readme?view=azure-dotnet), which interacts with Azure Resource Manager. Both of these SDKs support Batch pool operations such as create, get, update, and list; however, only the `Azure.ResourceManager.Batch` SDK can create a pool with managed identities, and for that reason it's the recommended way to create a pool. |
| Additionally you could refresh an existing clould pool object to issue a get pool command in the background and get a updaed version of it. | ||
| ``` C# | ||
| pool.Refresh() |
There was a problem hiding this comment.
Spelling/quality issues in this section: "clould"/"updaed" should be corrected, and the example call pool.Refresh() is missing a trailing semicolon, so it isn't valid C# as written.
| Additionally you could refresh an existing clould pool object to issue a get pool command in the background and get a updaed version of it. | |
| ``` C# | |
| pool.Refresh() | |
| Additionally you could refresh an existing cloud pool object to issue a get pool command in the background and get an updated version of it. | |
| ``` C# | |
| pool.Refresh(); |
Contributing to the Azure SDK
Please see our CONTRIBUTING.md if you are not familiar with contributing to this repository or have questions.
For specific information about pull request etiquette and best practices, see this section.