Microsoft.Azure.ContainerApps.Sandbox 1.0.0-beta.1

Prefix Reserved
This is a prerelease version of Microsoft.Azure.ContainerApps.Sandbox.
dotnet add package Microsoft.Azure.ContainerApps.Sandbox --version 1.0.0-beta.1
                    
NuGet\Install-Package Microsoft.Azure.ContainerApps.Sandbox -Version 1.0.0-beta.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Microsoft.Azure.ContainerApps.Sandbox" Version="1.0.0-beta.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Microsoft.Azure.ContainerApps.Sandbox" Version="1.0.0-beta.1" />
                    
Directory.Packages.props
<PackageReference Include="Microsoft.Azure.ContainerApps.Sandbox" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Microsoft.Azure.ContainerApps.Sandbox --version 1.0.0-beta.1
                    
#r "nuget: Microsoft.Azure.ContainerApps.Sandbox, 1.0.0-beta.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Microsoft.Azure.ContainerApps.Sandbox@1.0.0-beta.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Microsoft.Azure.ContainerApps.Sandbox&version=1.0.0-beta.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Microsoft.Azure.ContainerApps.Sandbox&version=1.0.0-beta.1&prerelease
                    
Install as a Cake Tool

Azure Container Apps Sandbox client library for .NET

The Azure Container Apps Sandbox client library for .NET provides data-plane operations for creating and managing sandboxes and their related resources, including volumes, snapshots, files, secrets, connections, credentials, content packages, egress policies, and disk images.

Getting started

Prerequisites

  • You must have a Microsoft Azure subscription.
  • You must have an Azure Container Apps sandbox group and know its Azure region or regional data-plane endpoint.
  • Your identity must have permission to access the sandbox group, such as the Container Apps SandboxGroup Data Owner role.

Authenticate the client

Azure Container Apps Sandbox uses Microsoft Entra ID authentication. Install the Azure.Identity package and create a SandboxGroupClient with a TokenCredential, such as DefaultAzureCredential.

using Microsoft.Azure.ContainerApps.Sandbox;
using Azure.Identity;

Uri endpoint = new Uri("<sandbox-group-endpoint>");
string subscriptionId = "<subscription-id>";
string resourceGroupName = "<resource-group-name>";
string sandboxGroupName = "<sandbox-group-name>";

SandboxGroupClient sandboxGroupClient = new SandboxGroupClient(
    endpoint,
    subscriptionId,
    resourceGroupName,
    sandboxGroupName,
    new DefaultAzureCredential());

Alternatively, pass the Azure region code instead of a Uri:

SandboxGroupClient sandboxGroupClient = new SandboxGroupClient(
    region: "eastus2",
    subscriptionId: subscriptionId,
    resourceGroupName: resourceGroupName,
    sandboxGroupName: sandboxGroupName,
    credential: new DefaultAzureCredential());

Key concepts

Sandbox group client

SandboxGroupClient is the entry point for a specific sandbox group. It contains the endpoint and Azure resource identifiers required by every request. Its read-only SubscriptionId, ResourceGroupName, and Name properties expose the identifiers supplied when the client was created. Id is the sandbox group's full Azure Resource Manager ResourceIdentifier; it does not represent an individual sandbox.

Resource operations

SandboxGroupClient exposes create and list operations for sandboxes and related resources. Its GetSandboxResource(id), GetVolumeResource(volumeName), GetConnectionResource(id), and other resource factory methods provide scoped resource objects. Operations on a known resource, including sandbox files, commands, lifecycle, and streams, are available on the corresponding resource object. The generated operation subclients are internal implementation details.

Scoped resources

For operations on a known resource, SandboxGroupClient offers scoped resource objects such as SandboxResource, VolumeResource, and SecretResource. Each resource object holds its identifier and delegates requests to the corresponding internal subclient. All resource factory methods use the GetXxxResource naming pattern:

Resource type Factory method
SandboxResource GetSandboxResource(id)
ConnectionResource GetConnectionResource(id)
ContentPackageResource GetContentPackageResource(id)
CredentialResource GetCredentialResource(credentialName)
DiskImageResource GetDiskImageResource(id)
PublicDiskImageResource GetPublicDiskImageResource(name)
EgressPolicyResource GetEgressPolicyResource(policyId)
SecretResource GetSecretResource(secretId)
SnapshotResource GetSnapshotResource(id)
VolumeResource GetVolumeResource(volumeName)

These factories do not send requests; a resource object obtained by identifier alone has Data == null. Create, list, and count operations keep their existing names. The group's create and list methods return resource objects with their Data populated from the service response. Where the service supports retrieval, Get() or GetAsync() returns a new resource object with the retrieved data, leaving the original object's Data unchanged. Mutating operations do not refresh Data. SandboxResource.Id is the sandbox's opaque string identifier, not an ARM resource identifier. SandboxResource also offers async exec and process WebSocket streams and an HTTP log stream scoped to its Id.

Models

Request and response models are in the Microsoft.Azure.ContainerApps.Sandbox.Models namespace.

File transfer streams

Sandbox file, volume file, and content package upload convenience methods accept readable, seekable Stream instances. The client does not dispose upload streams. File download convenience methods return unbuffered Stream instances that the caller must dispose.

Examples

Create a sandbox, execute a command, and delete it

The following example also uses types from Microsoft.Azure.ContainerApps.Sandbox.Models.

var sandboxGroup = new SandboxGroupClient(
    new Uri("<sandbox-group-endpoint>"),
    "<subscription-id>",
    "<resource-group-name>",
    "<sandbox-group-name>",
    new DefaultAzureCredential());
CreateSandboxContent content = new CreateSandboxContent
{
    SourcesRef = new SandboxSource
    {
        DiskImage = new SandboxSourceDiskImage { Name = "ubuntu", IsPublic = true }
    },
    Resources = new SandboxResources("1000m", "2048Mi")
};

SandboxResource sandbox = (await sandboxGroup.CreateSandboxAsync(content)).Value;
try
{
    ExecuteSandboxCommandContent command = new ExecuteSandboxCommandContent("/bin/echo");
    command.Arguments.Add("sandbox-command");
    SandboxExecuteCommandResult result = (await sandbox.ExecuteCommandAsync(command)).Value;
    if (result.ExitCode != 0)
    {
        throw new InvalidOperationException($"Command failed with exit code {result.ExitCode}: {result.StandardError}");
    }
    Console.WriteLine(result.StandardOutput);
}
finally
{
    await sandbox.DeleteAsync();
}

For synchronous usage and end-to-end examples of files, web ports, snapshots, shared volumes, lifecycle policies, egress, labels and pagination, disk images, streams, and secrets, see the samples.

List sandboxes

IDictionary<string, string> labels = new Dictionary<string, string>
{
    ["env"] = "dev",
    ["team"] = "sdk"
};

await foreach (SandboxResource sandbox in sandboxGroupClient.GetSandboxesAsync(
    labels: labels,
    states: new[] { SandboxStateFilter.Running }))
{
    Console.WriteLine($"{sandbox.Id}: {sandbox.Data.State}");
}

Work with a sandbox resource

SandboxResource sandbox = sandboxGroupClient.GetSandboxResource("sandbox-id");
Response<SandboxResource> current = await sandbox.GetAsync();
Console.WriteLine($"{current.Value.Id}: {current.Value.Data.State}");

await foreach (SandboxResource item in sandboxGroupClient.GetSandboxesAsync())
{
    Console.WriteLine($"{item.Id}: {item.Data.State}");
}

List sandbox-group volumes

await foreach (VolumeResource volume in sandboxGroupClient.GetVolumesAsync())
{
    Console.WriteLine($"{volume.VolumeName}: {volume.Data.ProvisioningState}");
}

Write a sandbox file

Write UTF-8 text to a file in a running sandbox. Set createDirs to true to create missing parent directories.

using System.IO;
using System.Text;

SandboxResource sandbox = sandboxGroupClient.GetSandboxResource("<sandbox-id>");
using MemoryStream content = new MemoryStream(Encoding.UTF8.GetBytes("Hello, ACA Sandboxes!"));
var result = (await sandbox.WriteSandboxFileAsync(
    "/workspace/hello.txt",
    content,
    createDirs: true)).Value;
if (!result.Success)
{
    throw new InvalidOperationException($"File write failed: {result.Error}");
}

Execute an interactive command

Use StartSandboxExecSessionAsync to start an interactive command, SendInputAsync to send input, and ReceiveAsync to read output and completion events. Dispose the session when finished.

using Microsoft.Azure.ContainerApps.Sandbox.Models;

SandboxExecStartRequest request = new SandboxExecStartRequest("/bin/sh")
{
    AllocateTerminal = false,
    EnableStandardInput = false
};
request.Arguments.Add("-c");
request.Arguments.Add("echo hello");
SandboxResource sandbox = sandboxGroupClient.GetSandboxResource("<sandbox-id>");
await using SandboxExecSession session = await sandbox.StartSandboxExecSessionAsync(request);
SandboxExecEvent execEvent;
while ((execEvent = await session.ReceiveAsync()).Type != SandboxExecEventType.Closed)
{
    if (execEvent.Type == SandboxExecEventType.StandardOutput)
        Console.WriteLine(execEvent.Data);
    if (execEvent.Type == SandboxExecEventType.Error)
        throw new InvalidOperationException(execEvent.Text);
}

Read sandbox logs

Log streaming is HTTP chunked transfer, not WebSocket. Dispose the returned Stream when finished; it is not buffered. The default format is plain text; SandboxLogFormat.Json returns newline-delimited JSON with timestamp, stream, and message fields.

SandboxResource sandbox = sandboxGroupClient.GetSandboxResource("<sandbox-id>");
Response<Stream> response = await sandbox.OpenSandboxLogStreamAsync(
    logFormat: SandboxLogFormat.Json, follow: false);
using StreamReader reader = new StreamReader(response.Value);
string line;
while ((line = await reader.ReadLineAsync()) != null)
    Console.WriteLine(line);

Troubleshooting

HTTP service failures throw RequestFailedException and include an HTTP status code and service error details. WebSocket connection and frame failures can instead throw WebSocketException. For authentication failures, verify that the credential can obtain a token and that the identity has access to the sandbox group. For endpoint or routing failures, verify that the endpoint belongs to the same region as the sandbox group.

To inspect requests and responses during development, enable Azure SDK logging before creating the client.

Next steps

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0-beta.1 372 11/5/2026