Microsoft.Azure.ContainerApps.Sandbox
1.0.0-beta.1
Prefix Reserved
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
<PackageReference Include="Microsoft.Azure.ContainerApps.Sandbox" Version="1.0.0-beta.1" />
<PackageVersion Include="Microsoft.Azure.ContainerApps.Sandbox" Version="1.0.0-beta.1" />
<PackageReference Include="Microsoft.Azure.ContainerApps.Sandbox" />
paket add Microsoft.Azure.ContainerApps.Sandbox --version 1.0.0-beta.1
#r "nuget: Microsoft.Azure.ContainerApps.Sandbox, 1.0.0-beta.1"
#:package Microsoft.Azure.ContainerApps.Sandbox@1.0.0-beta.1
#addin nuget:?package=Microsoft.Azure.ContainerApps.Sandbox&version=1.0.0-beta.1&prerelease
#tool nuget:?package=Microsoft.Azure.ContainerApps.Sandbox&version=1.0.0-beta.1&prerelease
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 Ownerrole.
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
- Review the Azure SDK for .NET documentation.
- Review the Azure Identity client library documentation.
| Product | Versions 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. |
-
.NETStandard 2.0
- Azure.Core (>= 1.63.0)
- System.IO.Pipelines (>= 10.0.10)
- System.Security.Cryptography.ProtectedData (>= 4.7.0)
-
net10.0
- Azure.Core (>= 1.63.0)
- System.Security.Cryptography.ProtectedData (>= 4.7.0)
-
net8.0
- Azure.Core (>= 1.63.0)
- System.IO.Pipelines (>= 10.0.10)
- System.Security.Cryptography.ProtectedData (>= 4.7.0)
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 |