AWS.OCI.Builder 0.6.0

Prefix Reserved
dotnet add package AWS.OCI.Builder --version 0.6.0
                    
NuGet\Install-Package AWS.OCI.Builder -Version 0.6.0
                    
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="AWS.OCI.Builder" Version="0.6.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="AWS.OCI.Builder" Version="0.6.0" />
                    
Directory.Packages.props
<PackageReference Include="AWS.OCI.Builder" />
                    
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 AWS.OCI.Builder --version 0.6.0
                    
#r "nuget: AWS.OCI.Builder, 0.6.0"
                    
#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 AWS.OCI.Builder@0.6.0
                    
#: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=AWS.OCI.Builder&version=0.6.0
                    
Install as a Cake Addin
#tool nuget:?package=AWS.OCI.Builder&version=0.6.0
                    
Install as a Cake Tool

AWS.OCI.Builder

Warning: This library is intended for use by AWS tools and libraries. It is not intended for general use yet, and its API may change in any release, including in ways that break existing code.

A .NET library for building OCI container images programmatically, without a Docker daemon. It pulls a base image's manifest over the registry HTTP API, overlays a new layer containing local files at specified container paths, and pushes the resulting image to Amazon ECR.

Status

The version is kept below 1.0.0 while the API changes to meet the needs of AWS tools and libraries.

Authentication

Base images are pulled anonymously, so the base image must be publicly pullable. Pulling a base image that requires authentication, including one in a private ECR repository, is not supported yet.

This library has no AWS SDK dependency. Instead of resolving AWS credentials itself, it takes an ECR authorization token that you obtain and pass to PushToEcrAsync. This keeps the library free of AWSSDK.Core, so it will not conflict with the AWS SDK versions a host (for example an AWS Tools for PowerShell cmdlet) already loads.

The token is the value returned by the ECR GetAuthorizationToken API — a base64-encoded AWS:<password> string. The library decodes it into the Basic username/password the registry handshake needs. Obtaining and refreshing the token (it is valid for ~12 hours) is the caller's responsibility; the target region is taken from the ECR host in the target reference.

using Amazon.ECR;
using Amazon.ECR.Model;

// Caller obtains the token however it likes — directly via the SDK, or from an AWS Tools for PowerShell cmdlet.
using var ecr = new AmazonECRClient();  // region/credentials from the SDK default chain
var auth = await ecr.GetAuthorizationTokenAsync(new GetAuthorizationTokenRequest());
string authorizationToken = auth.AuthorizationData[0].AuthorizationToken;   // base64("AWS:<password>")

Usage

using AWS.OCI.Builder;

// Pull the base image (selects the right platform from a manifest list).
using var builder = await OciImageBuilder.FromBaseImageAsync(
    "mcr.microsoft.com/dotnet/aspnet:8.0",
    platform: "linux/amd64");

// Overlay local files as a new layer. Each call adds one layer.
await builder.AddLayerAsync(new FileManifest
{
    { "/local/publish/MyApp.dll", "/app/MyApp.dll" },
    { "/local/publish/config",    "/app/config"    },
});

// Setting Linux file permissions (see "File permissions" below):
var files = new FileManifest();
files.Add("/local/publish/MyApp.dll", "/app/MyApp.dll");                 // default 0644
files.AddExecutable("/local/scripts/entrypoint.sh", "/app/entrypoint.sh"); // 0755
files.Add("/local/secrets/key", "/app/key", UnixPermissions.FromOctal("600")); // explicit 0600
await builder.AddLayerAsync(files);

// Customize the image config.
builder.Config.SetWorkingDirectory("/app");
builder.Config.SetEntrypoint("dotnet", "/app/MyApp.dll");

// Environment variables are merged into the base image's existing config.Env. Setting a key the
// base image already defines (e.g. PATH) overrides it in place rather than duplicating it.
builder.Config.SetEnvironmentVariable("ASPNETCORE_URLS", "http://+:8080");
builder.Config.SetEnvironmentVariable("DOTNET_EnableDiagnostics", "0");

// Obtain an ECR authorization token (the library has no AWS SDK dependency — getting the token is the
// caller's job; see "Authentication" above), then push. The region is taken from the ECR host in the target.
string digest = await builder.PushToEcrAsync(
    "123456789012.dkr.ecr.us-west-2.amazonaws.com/myapp:latest",
    authorizationToken);

Tracking push progress

Pass an IProgress<LayerPushProgress> via EcrPushOptions.Progress to observe the push layer by layer — for example to render a progress bar. It is entirely opt-in; omit it and the push reports nothing.

var progress = new Progress<LayerPushProgress>(p =>
{
    switch (p.Phase)
    {
        case LayerPushPhase.Started:
            Console.WriteLine($"[{p.LayerIndex}/{p.TotalLayers}] {p.Kind} {p.Digest} — uploading {p.LayerSizeBytes:N0} bytes");
            break;
        case LayerPushPhase.Uploading:
            Console.WriteLine($"[{p.LayerIndex}/{p.TotalLayers}] {p.BytesPushed:N0} / {p.LayerSizeBytes:N0} bytes");
            break;
        case LayerPushPhase.Completed when p.IsSkipped:
            Console.WriteLine($"[{p.LayerIndex}/{p.TotalLayers}] {p.Digest} — already present, skipped");
            break;
        case LayerPushPhase.Completed:
            Console.WriteLine($"[{p.LayerIndex}/{p.TotalLayers}] {p.Digest} — done");
            break;
    }
});

string digest = await builder.PushToEcrAsync(
    "123456789012.dkr.ecr.us-west-2.amazonaws.com/myapp:latest",
    authorizationToken,
    new EcrPushOptions { Progress = progress });

Each layer reports a Started event, zero or more Uploading events as its bytes are sent, and a terminal Completed event. A layer the registry already has reports a single Completed event with IsSkipped = true and BytesPushed = 0 — so "layer done" is always the one Completed phase, whether the layer was uploaded or skipped. Only image layers are reported (the config blob and manifest are not layers), so TotalLayers is exactly the number of layers.

Every event carries the layer's stable LayerIndex (1-based), TotalLayers, Digest and Kind (BaseLayer vs BuiltLayer), all fixed before any upload begins. Key your state by LayerIndex or Digest rather than the order events arrive: the contract is designed so that if the library later uploads layers in parallel — interleaving their events — consumers keep working unchanged. A custom IProgress<T> implementation must be thread-safe for that reason.

System.Progress<T> raises callbacks on the synchronization context it captured. Where there is none (console apps, services, PowerShell), it raises them on thread-pool threads, possibly several at once. To read events on your own thread instead, pass a LayerPushProgressQueue and drain it while the push runs:

var queue = new LayerPushProgressQueue();
Task<string> push = builder.PushToEcrAsync(target, authorizationToken, new EcrPushOptions { Progress = queue });
while (!push.IsCompleted)
{
    while (queue.TryDequeue(out LayerPushProgress p)) { /* render p */ }
    await Task.WhenAny(push, Task.Delay(200));
}
while (queue.TryDequeue(out LayerPushProgress p)) { /* render p */ }
string digest = await push;

File permissions

Each file in a layer carries a Unix mode. When you don't specify one:

  • On Linux/macOS the source file's own mode is preserved, so an already-executable file stays executable.
  • On Windows — which has no Unix mode bits to read — files default to 0644 and directories to 0755.

Because Windows can't carry an executable bit, set the mode explicitly when you need a script or binary to be runnable in the container regardless of the build host:

  • FileManifest.AddExecutable(local, container) — marks the entry 0755.
  • FileManifest.Add(local, container, mode) — any System.IO.UnixFileMode.
  • UnixPermissions.FromOctal("755") / FromOctal(755) — express a mode in chmod-style octal (C# has no octal literal, so FromOctal is how you write 0755). For a directory mapping, an explicit mode applies to every file it contains; directory entries themselves are always 0755.

Proxy and timeouts

By default requests use HttpClient.DefaultProxy, which reads HTTPS_PROXY, HTTP_PROXY and NO_PROXY, and have no client timeout, so the cancellation token is the deadline. To set them per build:

var proxy = new WebProxy("http://proxy.corp.example:8080");

using var builder = await OciImageBuilder.FromBaseImageAsync(
    "public.ecr.aws/lambda/provided:al2023", "linux/arm64",
    new BaseImagePullOptions { Proxy = proxy, Timeout = TimeSpan.FromMinutes(5) });

await builder.PushToEcrAsync(target, authorizationToken,
    new EcrPushOptions { Proxy = proxy, UploadTimeout = TimeSpan.FromMinutes(30) });

BaseImagePullOptions also applies to the base layer downloads during the push, and EcrPushOptions only to ECR.

Product Compatible and additional computed target framework versions.
.NET 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.
  • net8.0

    • No dependencies.

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
0.6.0 84 11/13/2026
0.5.0 77 11/13/2026