Azure Batch client library for .NET - version 1.0.0-beta.3

Azure.Compute.Batch allows users to run large-scale parallel and high-performance computing (HPC) batch jobs efficiently in Azure.

Use the client library for to:

• Create and manage Batch jobs and tasks

• View and perform operations on nodes in a Batch pool

  Source code | Package (NuGet) | API reference documentation | Product documentation

Note: Azure.Compute.Batch replaces 'Microsoft.Azure.Batch`, see the Migration Guide for migration guidance.

Getting started

Install the package

Install the client library for .NET with NuGet:

dotnet add package Azure.Compute.Batch --prerelease

Prerequisites

• An Azure account with an active subscription. If you don't have one, create an account for free.

• A Batch account with a linked Azure Storage account. You can create the accounts by using any of the following methods: Azure CLI | Azure portal | Bicep | ARM template | Terraform.

• Visual Studio 2019 or later, or the .NET SDK version 6.0 or later.

Authenticate the client

Batch account access supports two methods of authentication: Shared Key and Microsoft Entra ID.

We strongly recommend using Microsoft Entra ID for Batch account authentication. Some Batch capabilities require this method of authentication, including many of the security-related features discussed here. The service API authentication mechanism for a Batch account can be restricted to only Microsoft Entra ID using the allowedAuthenticationModes property. When this property is set, API calls using Shared Key authentication will be rejected.

Authenticate using Microsoft Entra ID

Azure Batch provides integration with Microsoft Entra ID for identity-based authentication of requests. With Azure AD, you can use role-based access control (RBAC) to grant access to your Azure Batch resources to users, groups, or applications. The Azure Identity library provides easy Microsoft Entra ID support for authentication.

var credential = new DefaultAzureCredential();
BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), credential);

Authenticate using Shared Key

You can also use Shared Key authentication to sign into your Batch account. This method uses 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

az batch account keys list --name <your-batch-account> --resource-group <your-resource-group-name>

var credential = new AzureNamedKeyCredential("<your account>", "BatchAccountKey");
BatchClient batchClient = new BatchClient(
    new Uri("https://<your account>.eastus.batch.azure.com"),
    credential);

Key concepts

Azure Batch Overview

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

The Azure.Compute.Batch package supports synchronous and asynchronous APIs.

The following section provides several synchronous code snippets covering some of the most common Azure Batch related tasks:

• Pool Operations
  • Create a pool
  • Retrieve a pool
  • List pools
  • Delete Pool
  • Patch Pool
  • Update Pool
  • Resize Pool
  • Stop Pool Resize
  • Enable Pool Auto Scale
  • Disable Pool Auto Scale
  • Evaluate Pool Auto Scale
  • List Pool Node Counts
  • List Pool Usage Metrics
  • Get Supported Images
• Job Operations
  • Create a job
  • Retrieve a job
  • List jobs
  • Delete Job
  • Replace Job
  • Update Job
  • Disable Job
  • Enable Job
  • List Job Preparation And Release Task Status
  • Get Job Task Counts
  • Terminate Job
• Job Schedule Operations
  • Create Job Schedule
  • Get Job Schedule
  • List Job Schedules
  • Delete Job Schedule
  • Replace Job Schedule
  • Update Job Schedule
  • Disable Job Schedule
  • Enable Job Schedule
  • Terminate Job Schedule
• Task Operations
  • Create a task
  • Retrieve a task
  • List Tasks
  • Delete Task
  • Replace Task
  • Reactivate Task
  • Terminate Task
  • Retrieve an output file from a task
• Node Operations
  • Retrieve a Node
  • List Nodes
  • Reboot Node
  • ReImage Node
  • Start Node
  • Deallocate Node
  • Create Compute Node User
  • Delete Compute Node User
  • Get Node File
  • List Node Files
  • Delete Node File
  • Node File Properties
  • Get Remote Login Settings
  • Upload Compute Node BatchService Logs
• Certificate Operations
  • Create a Certificate
  • Get a Certificatec
  • List Certificates
  • Delete Certificate
  • Cancel Delete Certificate
• Application Operations
  • Get Application
  • List Applications
• Error Handling

Pool Operations

In an Azure Batch workflow, a compute node (or node) is a virtual machine that processes a portion of your application's workload. A pool is a collection of these nodes for your application to runs on. For more information see Nodes and pools in Azure Batch.

Create a Pool

Azure batch has two SDKs, Azure.Compute.Batch which interacts directly the Azure Batch service, and Azure.ResourceManager.Batch which interacts with the Azure Resource Manager. Both of these SDKs 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.

Azure.ResourceManager.Batch pool create with managed identity. You create a pool by getting a reference to the batch account then issuing a CreateOrUpdate call from the GetBatchAccountPools() collection.

using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Batch;
using Azure.ResourceManager.Batch.Models;

    var credential = new DefaultAzureCredential();
    ArmClient _armClient = new ArmClient(credential);

    var batchAccountIdentifier = ResourceIdentifier.Parse("your-batch-account-resource-id");
    BatchAccountResource batchAccount = _armClient.GetBatchAccountResource(batchAccountIdentifier);

    var poolName = "HelloWorldPool";
    var imageReference = new Azure.ResourceManager.Batch.Models.BatchImageReference()
    {
        Publisher = "canonical",
        Offer = "0001-com-ubuntu-server-jammy",
        Sku = "22_04-lts",
        Version = "latest"
    };
    string nodeAgentSku = "batch.node.ubuntu 22.04";

    var batchAccountPoolData = new BatchAccountPoolData()
    {
        VmSize = "Standard_DS1_v2",
        DeploymentConfiguration = new BatchDeploymentConfiguration()
        {
            VmConfiguration = new BatchVmConfiguration(imageReference, nodeAgentSku)
        },
        ScaleSettings = new BatchAccountPoolScaleSettings()
        {
            FixedScale = new BatchAccountFixedScaleSettings()
            {
                TargetDedicatedNodes = 1
            }
        },
        Identity = new ManagedServiceIdentity(ManagedServiceIdentityType.UserAssigned)
        {
            UserAssignedIdentities = {
    [new ResourceIdentifier("Your Identity Azure Resource Manager ResourceId")] = new Azure.ResourceManager.Models.UserAssignedIdentity(),
},
        }
    };

    ArmOperation<BatchAccountPoolResource> armOperation = batchAccount.GetBatchAccountPools().CreateOrUpdate(
        WaitUntil.Completed, poolName, batchAccountPoolData);
    BatchAccountPoolResource pool = armOperation.Value;

As mentioned you can create a pool using Azure.Compute.Batch pool create just without support for managed identities. First you create a batch client with your credentials then you issue a CreatePool call directly from the batch client.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

string poolID = "HelloWorldPool";

BatchVmImageReference imageReference = new BatchVmImageReference()
{
    Publisher = "MicrosoftWindowsServer",
    Offer = "WindowsServer",
    Sku = "2019-datacenter-smalldisk",
    Version = "latest"
};

VirtualMachineConfiguration virtualMachineConfiguration = new VirtualMachineConfiguration(imageReference, "batch.node.windows amd64");

BatchPoolCreateOptions batchPoolCreateOptions = new BatchPoolCreateOptions(
poolID, "STANDARD_D1_v2")
{
    VirtualMachineConfiguration = virtualMachineConfiguration,
    TargetDedicatedNodes = 2,
};

// create pool
batchClient.CreatePool(batchPoolCreateOptions);

Retrieve a Pool

GetPool can be used to retrieve created pools.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchPool batchPool = batchClient.GetPool("poolID");

Console.WriteLine(batchPool.Id);
Console.WriteLine(batchPool.Uri);
Console.WriteLine(batchPool.AllocationState);

List Pools

GetPools can be used to list all pools under the Batch account.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchPool item in batchClient.GetPools())
{
    Console.WriteLine(item.Id);
}

Delete Pool

DeletePool can be used to delete a pool.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DeletePool("poolID");

Optionally you can use the returned DeletePoolOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

DeletePoolOperation operation = batchClient.DeletePool("poolID");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Patch Pool

UpdatePool can be used to patch a pool.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchPoolUpdateOptions updateOptions = new BatchPoolUpdateOptions();
updateOptions.Metadata.Add(new BatchMetadataItem("name", "value"));

batchClient.UpdatePool("poolID", updateOptions);

Update Pool

ReplacePoolProperties can be used to update a pool.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchMetadataItem[] metadataItems = new BatchMetadataItem[] {
  new BatchMetadataItem("name", "value")};

BatchApplicationPackageReference[] batchApplicationPackageReferences = new BatchApplicationPackageReference[] {
        new BatchApplicationPackageReference("applicationPackage")
        {
            Version = "1"
        }
    };

BatchCertificateReference[] certificateReferences = new BatchCertificateReference[] {
        new BatchCertificateReference("thumbprint","thumbprintAlgorithm")
        {
            StoreLocation = "storeLocation",
            StoreName = "storeName"
        }
};

BatchPoolReplaceOptions replaceOptions = new BatchPoolReplaceOptions(certificateReferences, batchApplicationPackageReferences, metadataItems);
batchClient.ReplacePoolProperties("poolID", replaceOptions);

Resize Pool

ResizePool can be used to resize a pool.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchPoolResizeOptions resizeOptions = new BatchPoolResizeOptions()
{
    TargetDedicatedNodes = 1,
    ResizeTimeout = TimeSpan.FromMinutes(10),
};

batchClient.ResizePool("poolID", resizeOptions);

Stop ResizePool

StopPoolResize can be used to stop a pool resize in progress.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.StopPoolResize("poolId");

Enable AutoScalePool

EnablePoolAutoScale can be used to enable auto scale in a pool. Pass in a BatchPoolEnableAutoScaleOptions object.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());
TimeSpan evalInterval = TimeSpan.FromMinutes(6);
string poolASFormulaNew = "$TargetDedicated = 1;";

BatchPoolEnableAutoScaleOptions batchPoolEnableAutoScaleOptions = new BatchPoolEnableAutoScaleOptions()
{
    AutoScaleEvaluationInterval = evalInterval,
    AutoScaleFormula = poolASFormulaNew,
};

batchClient.EnablePoolAutoScale("poolId", batchPoolEnableAutoScaleOptions);

Disable AutoScalePool

DisablePoolAutoScale can be used to disable auto scale in a pool. Pass in a BatchPoolEnableAutoScaleOptions object.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DisablePoolAutoScale("poolId");

Evaluate AutoScalePool

EvaluatePoolAutoScale cand be used to evaluate an auto scale formula in a pool. Pass in a BatchPoolEvaluateAutoScaleOptions object.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

string poolASFormulaNew = "$TargetDedicated = 1;";
BatchPoolEvaluateAutoScaleOptions batchPoolEvaluateAutoScaleOptions = new BatchPoolEvaluateAutoScaleOptions(poolASFormulaNew);
AutoScaleRun eval = batchClient.EvaluatePoolAutoScale("poolId", batchPoolEvaluateAutoScaleOptions);

List PoolNodeCounts

GetPoolNodeCounts cand be used to list pool node counts.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchPoolNodeCounts item in batchClient.GetPoolNodeCounts())
{
    // do something
}

List PoolUsageMetrics

GetPoolUsageMetricsAsync can be used to list pool usage metrics.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchPoolUsageMetrics item in batchClient.GetPoolUsageMetrics())
{
    // do something
}

Get Supported Images

GetSupportedImagesAsync can be used to get a list of supported image.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchSupportedImage item in batchClient.GetSupportedImages())
{
    // do something
}

Job Operations

Create a Job

A job is a collection of tasks. It manages how computation is performed by its tasks on the compute nodes in a pool.

A job specifies the pool in which the work is to be run. You can create a new pool for each job, or use one pool for many jobs. You can create a pool for each job that is associated with a job schedule, or one pool for all jobs that are associated with a job schedule. For more information see Jobs and tasks in Azure Batch.

Use the CreateJob method with a BatchTaskCreateOptions instance to create a BatchJob.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.CreateJob(new BatchJobCreateOptions("jobId", new BatchPoolInfo() { PoolId = "poolName" }));

Retrieve a job

GetJob can be used to retrieve a created BatchJob.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJob batchJob = batchClient.GetJob("jobID");
Console.WriteLine(batchJob.Id);
Console.WriteLine(batchJob.State);

List jobs

GetJobs can be used to list all BatchJob allocated under a Batch Account.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchJob item in batchClient.GetJobs())
{
    Console.WriteLine(item.Id);
}

DeleteJob

DeleteJob can be used to delete a job.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DeleteJob("jobID");

Optionally you can use the returned DeleteJobOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

DeleteJobOperation operation = batchClient.DeleteJob("jobID");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Replace Job

ReplaceJob can be used to replace an existing job.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJob job = batchClient.GetJob("jobID");
job.AllTasksCompleteMode = BatchAllTasksCompleteMode.TerminateJob;
batchClient.ReplaceJob("jobID", job);

Update Job

UpdateJob with a parameter of type BatchJobUpdateOptions can be used to update a job

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJobUpdateOptions batchUpdateOptions = new BatchJobUpdateOptions();
batchUpdateOptions.Metadata.Add(new BatchMetadataItem("name", "value"));

batchClient.UpdateJob("jobID", batchUpdateOptions);

Disable Job

DisableJob with a parameter of type BatchJobDisableOptions can be used to disable a job.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJobDisableOptions options = new BatchJobDisableOptions(DisableBatchJobOption.Requeue);
batchClient.DisableJob("jobID", options);

Optionally you can use the returned DisableJobOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJobDisableOptions options = new BatchJobDisableOptions(DisableBatchJobOption.Requeue);
DisableJobOperation operation = batchClient.DisableJob("jobID", options);

// Optional, wait for operation to complete
operation.WaitForCompletion();

Enable Job

EnableJob can be used to enable a disabled job.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.EnableJob("jobID");

Optionally you can use the returned EnableJobOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

EnableJobOperation operation = batchClient.EnableJob("jobID");

// Optional, wait for operation to complete
operation.WaitForCompletion();

ListJobPreparationAndReleaseTaskStatus

GetJobPreparationAndReleaseTaskStatuses can be used to get a list of job preparation and release task status.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchJobPreparationAndReleaseTaskStatus item in batchClient.GetJobPreparationAndReleaseTaskStatuses("jobID"))
{
    // do something
}

GetJobTaskCounts

GetJobTaskCounts can be used to get a job task count.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchTaskCountsResult batchTaskCountsResult = batchClient.GetJobTaskCounts("jobID");

Terminate Job

TerminateJob can be used to terminate a job.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.TerminateJob("jobID");

Optionally you can use the returned TerminateJobOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

TerminateJobOperation operation = batchClient.TerminateJob("jobID");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Job Schedule Operations

CreateJobSchedule

CreateJobSchedule with a parameter of type BatchJobScheduleCreateOptions to create a Job Schedule.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJobScheduleConfiguration schedule = new BatchJobScheduleConfiguration();

BatchPoolInfo poolInfo = new BatchPoolInfo()
{
    PoolId = "poolID",
};
BatchJobManagerTask batchJobManagerTask = new BatchJobManagerTask("task1", "cmd / c echo Hello World");

BatchJobSpecification jobSpecification = new BatchJobSpecification(poolInfo)
{
    JobManagerTask = batchJobManagerTask,
};

BatchJobScheduleCreateOptions jobSchedule = new BatchJobScheduleCreateOptions("jobScheduleId", schedule, jobSpecification);

batchClient.CreateJobSchedule(jobSchedule);

GetJobSchedule

GetJobSchedule can be used to retrieve a BatchJobSchedule object.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJobSchedule batchJobSchedule = batchClient.GetJobSchedule("jobScheduleId");

ListJobSchedules

GetJobSchedules with a parameter of type BatchJobScheduleCreateOptions can be used to get a list of job schedules.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchJobSchedule item in batchClient.GetJobSchedules())
{
    // do something
}

DeleteJobSchedule

DeleteJobSchedule can be used to delete a Job Schedule.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DeleteJobSchedule("jobScheduleId");

Optionally you can use the returned DeleteJobScheduleOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

DeleteJobScheduleOperation operation = batchClient.DeleteJobSchedule("jobScheduleId");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Replace Job Schedule

ReplaceJobSchedule can be used to replace a job schedule.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJobSchedule batchJobSchedule = batchClient.GetJobSchedule("jobScheduleId");

DateTime unboundDNRU = DateTime.Parse("2026-08-18T00:00:00.0000000Z");
batchJobSchedule.Schedule = new BatchJobScheduleConfiguration()
{
    DoNotRunUntil = unboundDNRU,
};
batchClient.ReplaceJobSchedule("jobScheduleId", batchJobSchedule);

Update Job Schedule

UpdateJobSchedule with a parameter of type BatchJobScheduleUpdateOptions can be used to update a job schedule.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchJobScheduleUpdateOptions batchUpdateOptions = new BatchJobScheduleUpdateOptions();
batchUpdateOptions.Metadata.Add(new BatchMetadataItem("name", "value"));

batchClient.UpdateJobSchedule("jobID", batchUpdateOptions);

Disable Job Schedule

DisableJobSchedule can be used to to disable a job schedule.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DisableJobSchedule("jobScheduleId");

Enable Job Schedule

EnableJobSchedule can be used to enable a job schedule.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.EnableJobSchedule("jobScheduleId");

Terminate Job Schedule

TerminateJobSchedule cand be used to termainate a job schedule.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.TerminateJobSchedule("jobScheduleId");

Optionally you can use the returned TerminateJobScheduleOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

TerminateJobScheduleOperation operation = batchClient.TerminateJobSchedule("jobScheduleId");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Task Operations

Create a task

A task is a unit of computation that is associated with a job. It runs on a node. Tasks are assigned to a node for execution, or are queued until a node becomes free. Put simply, a task runs one or more programs or scripts on a compute node to perform the work you need done. For more information see Jobs and tasks in Azure Batch.

With Azure.Compute.Batch there are three ways to add a task to a job.

You can call CreateTask with a parameter of type BatchTaskCreateOptions to create a single task

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.CreateTask("jobId", new BatchTaskCreateOptions("taskId", $"echo Hello world"));

You can call CreateTaskCollection with a BatchTaskGroup param to create up to 100 tasks. This method represents the /jobs/{jobId}/addtaskcollection api

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchTaskGroup taskCollection = new BatchTaskGroup(
    new BatchTaskCreateOptions[]
    {
        new BatchTaskCreateOptions("task1", "cmd / c echo Hello World"),
        new BatchTaskCreateOptions("task2", "cmd / c echo Hello World")
    });

BatchCreateTaskCollectionResult batchCreateTaskCollectionResult = batchClient.CreateTaskCollection("jobID", taskCollection);

Lastly you can call CreateTasks which has no limit to the number of tasks. This method will package up the list of BatchTaskCreateOptions tasks passed in and repeatly call the batchClient.CreateTaskCollection() with groups of tasks bundled into BatchTaskGroup objects. This utility method allows you to select the number of parallel calls to batchClient.CreateTaskCollection(). See Creating multiple Task

int tasksCount = 1000;
List<BatchTaskCreateOptions> tasks = new List<BatchTaskCreateOptions>();
for (int i = 0; i < tasksCount; i++)
{
    tasks.Add(new BatchTaskCreateOptions($"task{i}", "cmd /c echo Hello World"));
}

// Create 1000 tasks in a single request using the default settings
CreateTasksResult result = await batchClient.CreateTasksAsync("jobId", tasks);

// Print the results
Console.WriteLine("{0} Tasks Passed, {1} Failed.", result.PassCount, result.FailCount);

Retrieve a task

GetTask can be used to retrieve a created BatchTask.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchTask batchTask = batchClient.GetTask("<jobId>", "<taskId>");
Console.WriteLine(batchTask.Id);
Console.WriteLine(batchTask.State);

ListTasks

GetTasks can be used to get a list of tasks.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchTask t in batchClient.GetTasks("jobId"))
{
    // do something with the task
}

Delete Task

DeleteTask can be called to get a delete a task.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DeleteTask("jobId", "taskId");

Replace Task

ReplaceTask with a BatchTaskConstraints parameter can be called to replace a task.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchTask task = batchClient.GetTask("jobId", "taskId");
BatchTaskConstraints batchTaskConstraints = new BatchTaskConstraints()
{
    MaxTaskRetryCount = 3,
};

task.Constraints = batchTaskConstraints;
batchClient.ReplaceTask("jobID", "taskID", task);

Reactivate Task

ReactivateTask can be called to reactive a task.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.ReactivateTask("jobID", "taskID");

Terminate Task

TerminateTask can be called to terminate a task.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.TerminateTask("jobID", "taskID");

Retrieve an output file from a task

In Azure Batch, each task has a working directory under which it can create files and directories. This working directory can be used for storing the program that is run by the task, the data that it processes, and the output of the processing it performs. All files and directories of a task are owned by the task user.

The Batch service exposes a portion of the file system on a node as the root directory. This root directory is located on the temporary storage drive of the VM, not directly on the OS drive.

Tasks can access the root directory by referencing the AZ_BATCH_NODE_ROOT_DIR environment variable. For more information see Files and directories in Azure Batch.

GetTasks can be used to list all BatchTask allocated under a BatchJob. GetTaskFile can be used to retrive files from a BatchTask

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

var completedTasks = batchClient.GetTasks("jobId", filter: "state eq 'completed'");
foreach (BatchTask t in completedTasks)
{
    var outputFileName = t.ExecutionInfo.ExitCode == 0 ? "stdout.txt" : "stderr.txt";

    Console.WriteLine("Task {0} exited with code {1}. Output ({2}):",
        t.Id, t.ExecutionInfo.ExitCode, outputFileName);

    BinaryData fileContents = batchClient.GetTaskFile("jobId", t.Id, outputFileName);
    using (var reader = new StreamReader(fileContents.ToStream()))
    {
        Console.WriteLine(reader.ReadLine());
    }
}

Node Operations

Retrieve a Node

A node is an Azure virtual machine (VM) that is dedicated to processing a portion of your application's workload. The size of a node determines the number of CPU cores, memory capacity, and local file system size that is allocated to the node. For more information see Nodes and pools in Azure Batch.

GetNode can be used to retrieve an allocated BatchNode from a pool.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchNode batchNode = batchClient.GetNode("<poolId>", "<nodeId>");
Console.WriteLine(batchNode.Id);
Console.WriteLine(batchNode.Uri);
Console.WriteLine(batchNode.State);

List Nodes

GetNodes can be used to list all BatchNode allocated under a pool.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchNode item in batchClient.GetNodes("poolID"))
{
    Console.WriteLine(item.Id);
}

Reboot Node

RebootNode can be used to reboot a node.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.RebootNode("poolId", "computeNodeId");

Optionally you can use the returned RebootNodeOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

RebootNodeOperation operation = batchClient.RebootNode("poolId", "computeNodeId");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Reimage Node

ReimageNode can be used to reimage a node.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

ReimageNodeOperation operation = batchClient.ReimageNode("poolId", "computeNodeId");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Optionally you can use the returned ReimageNodeOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

ReimageNodeOperation operation = batchClient.ReimageNode("poolId", "computeNodeId");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Start Node

StartNode can be used to start a node that has been Deallocate.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.StartNode("poolId", "computeNodeId");

Optionally you can use the returned StartNodeOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

StartNodeOperation operation = batchClient.StartNode("poolId", "computeNodeId");

// Optional, wait for operation to complete
operation.WaitForCompletion();

Deallocate Node

DeallocateNode can be used to Deallocate a node.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DeallocateNode("poolId", "computeNodeId");

Optionally you can use the returned DeallocateNodeOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

DeallocateNodeOperation operation = batchClient.DeallocateNode("poolId", "computeNodeId");

// Optional, wait for operation to complete
operation.WaitForCompletion();

CreateComputeNodeUser

CreateNodeUserAsync with a BatchNodeUserCreateOptions param can be used to create a node user.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchNodeUserCreateOptions user = new BatchNodeUserCreateOptions("userName")
{
    Password = "userPassWord"
};
batchClient.CreateNodeUser("poolID", "batchNodeID", user);

DeleteComputeNodeUser

DeleteNodeUser can be to delete a node user.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DeleteNodeUser("poolID", "batchNodeID", "userName");

GetNodeFile

GetNodeFile cand be used to get a file from a node.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BinaryData fileContents = batchClient.GetNodeFile("poolId", "computeNodeId", "filePath");

ListNodeFiles

GetNodeFiles can be used to get a list of files.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchNodeFile item in batchClient.GetNodeFiles("jobId", "nodeId"))
{
    // do something
}

DeleteNodeFile

DeleteNodeFile can be used to delete a file from a node.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DeleteNodeFile("jobId", "taskId", "filePath");

Get Node File Properties

GetNodeFileProperties can be used to get the properties of a file.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchFileProperties batchFileProperties = batchClient.GetNodeFileProperties("poolId", "nodeId", "filePath");

GetRemoteLoginSettings

GetNodeRemoteLoginSettings can be used to get the remote loging settings of a node.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchNodeRemoteLoginSettings batchNodeRemoteLoginSettings = batchClient.GetNodeRemoteLoginSettings("poolId", "computeNodeId");

UploadComputeNodeBatchServiceLogs

UploadNodeLogs with a param of type UploadBatchServiceLogsOptions can be used to upload logs to a node.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

UploadBatchServiceLogsOptions uploadBatchServiceLogsOptions = new UploadBatchServiceLogsOptions(new Uri("containerUrl"), DateTimeOffset.Parse("2026-05-01T00:00:00.0000000Z"));

UploadBatchServiceLogsResult uploadBatchServiceLogsResult = batchClient.UploadNodeLogs("poolId", "computeNodeId", uploadBatchServiceLogsOptions);

Certificate Operations

Note: Certificates has been [deprecated].

CreateCertificate

Call CreateCertificate with a BatchCertificate param to create a Certificate.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());
byte[] certData = File.ReadAllBytes("certPath");
BatchCertificate cerCertificate = new BatchCertificate("Thumbprint", "ThumbprintAlgorithm", BinaryData.FromBytes(certData))
{
    CertificateFormat = BatchCertificateFormat.Cer,
    Password = "",
};

Response response = batchClient.CreateCertificate(cerCertificate);

GetCertificate

Call GetCertificate to get the certificate which will return a GetCertificateResponse.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchCertificate cerCertificateResponse = batchClient.GetCertificate("ThumbprintAlgorithm", "Thumbprint");

ListCertificates

Call GetCertificates to get a list of certificates.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchCertificate item in batchClient.GetCertificates())
{
    // do something
}

DeleteCertificate

Call DeleteCertificate to delete a Certificate.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.DeleteCertificate("ThumbprintAlgorithm", "Thumbprint");

Optionally you can use the returned DeleteCertificateOperation object to wait for the operation to complete.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

DeleteCertificateOperation operation = batchClient.DeleteCertificate("ThumbprintAlgorithm", "Thumbprint");

// Optional, wait for operation to complete
operation.WaitForCompletion();

CancelDeleteCertificate

Call CancelCertificateDeletion to cancel a delete of a certificate.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

batchClient.CancelCertificateDeletion("ThumbprintAlgorithm", "Thumbprint");

Application Operations

Get Application

GetApplication can be used to get a BatchApplication object.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

BatchApplication application = batchClient.GetApplication("appID");

List Application

GetApplications can be used to list all BatchApplication allocated under a account.

BatchClient batchClient = new BatchClient(
new Uri("https://<your account>.eastus.batch.azure.com"), new DefaultAzureCredential());

foreach (BatchApplication item in batchClient.GetApplications())
{
    // do something
}

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. A list of common Batch error codes can be found in the BatchErrorCode class.

try
{
    batchClient.ResizePool("fakepool", resizeOptions);
}
catch (Azure.RequestFailedException e)
{
    if ((e.ErrorCode == BatchErrorCode.PoolNotFound) &&
        (e.Status == 404))
    {
        // write out the summary message
        Console.WriteLine(e.Message);

        // additional message details
        foreach (DictionaryEntry item in e.Data)
        {
            Console.WriteLine(item.Key);
            Console.WriteLine(item.Value);
        }
    }
}

Troubleshooting

Please see Troubleshooting common batch issues.

Next steps

View more https://github.com/Azure/azure-sdk-for-net/blob/Azure.Compute.Batch_1.0.0-beta.3/sdk/batch/Azure.Compute.Batch/samples here for common usages of the Batch client library: Batch Samples.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.