CodeLogic.StorageS3 4.6.74

This package has a SemVer 2.0.0 package version: 4.6.74+6cf7e67.

dotnet add package CodeLogic.StorageS3 --version 4.6.74

NuGet\Install-Package CodeLogic.StorageS3 -Version 4.6.74

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="CodeLogic.StorageS3" Version="4.6.74" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="CodeLogic.StorageS3" Version="4.6.74" />
                    

                            Directory.Packages.props

<PackageReference Include="CodeLogic.StorageS3" />
                    

                            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 CodeLogic.StorageS3 --version 4.6.74

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: CodeLogic.StorageS3, 4.6.74"

#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 CodeLogic.StorageS3@4.6.74

#: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=CodeLogic.StorageS3&version=4.6.74
                    

                            Install as a Cake Addin

#tool nuget:?package=CodeLogic.StorageS3&version=4.6.74
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CodeLogic.StorageS3

S3-compatible object storage for CodeLogic 4 — one API across Amazon S3, MinIO, and Cloudflare R2.

Built on AWSSDK.S3. Configure one or more named connections, then upload, download, list, copy, and presign objects through a single S3StorageService. Every operation returns the framework Result<T> (existence checks return a plain bool), so failures surface as Error values instead of exceptions.

Install

dotnet add package CodeLogic.StorageS3

Quick start

await Libraries.LoadAsync<StorageS3Library>();
await CodeLogic.ConfigureAsync();
await CodeLogic.StartAsync();

var storage = Libraries.Get<StorageS3Library>();
var s3 = storage.DefaultService;            // S3StorageService for the "Default" connection

// Upload (byte array or stream)
using var file = File.OpenRead("photo.webp");
Result<S3ObjectInfo> put = await s3.PutObjectAsync(
    "my-bucket", "uploads/photo.webp", file,
    new UploadOptions { ContentType = "image/webp" });

if (put.IsSuccess)
    Console.WriteLine(put.Value!.PublicUrl);   // populated when PublicUrl is configured

// Download
Result<byte[]> data = await s3.GetObjectAsync("my-bucket", "uploads/photo.webp");
if (data.IsSuccess)
    File.WriteAllBytes("photo.webp", data.Value!);

// List with a prefix
Result<ListObjectsResult> list = await s3.ListObjectsAsync("my-bucket", prefix: "uploads/");
foreach (var obj in list.Value!.Objects)
    Console.WriteLine($"{obj.Key} ({obj.Size} bytes)");

// Delete
await s3.DeleteObjectAsync("my-bucket", "uploads/photo.webp");

Existence checks (BucketExistsAsync, ObjectExistsAsync) return a plain Task<bool> — no Result wrapper.

Features

Objects — upload and download by byte array or stream, copy, delete, metadata-only lookup, and existence checks.
Range & version downloads — DownloadOptions for byte-range reads and VersionId retrieval.
Upload options — UploadOptions for content type, cache-control, content-disposition, storage class, public-read ACL, and custom metadata.
Buckets — create, delete, list, and exists.
Listing — prefix filtering, pagination via continuation tokens, and common-prefix (virtual folder) detection.
Multiple connections — named connection IDs for multi-bucket or multi-provider setups; reach any via storage.GetService("id").
Presigned URLs — temporary GET access links with a configurable expiry.
Public URLs — optional public base URL auto-populated on S3ObjectInfo.PublicUrl.
Events — ObjectUploadedEvent, ObjectDeletedEvent, and BucketCreatedEvent on the CodeLogic event bus.
Health check — tests every configured connection inside its defaultBucket when available, so bucket-scoped credentials are sufficient (Healthy / Degraded / Unhealthy).

Configuration

Auto-generated on first run as config.storages3.json (section storages3):

{
  "enabled": true,
  "connections": [
    {
      "connectionId": "Default",
      "accessKey": "your-access-key",
      "secretKey": "your-secret-key",
      "serviceUrl": "https://s3.amazonaws.com",
      "publicUrl": "https://cdn.example.com",
      "region": "us-east-1",
      "defaultBucket": "my-bucket",
      "forcePathStyle": true,
      "useHttps": true,
      "timeoutSeconds": 30,
      "maxRetries": 3,
      "disablePayloadSigning": false
    }
  ]
}

Setting	Default	Description
`enabled`	`true`	Master switch; when `false` no connections are registered and health reports disabled.
`connections`	`[]`	One or more connection blocks. At least one is required when enabled; each `connectionId` must be unique.
`connectionId`	`"Default"`	Identifier used to look up the connection via `GetService`.
`accessKey`	`""`	Access key ID (secret).
`secretKey`	`""`	Secret access key (secret).
`serviceUrl`	`""`	Endpoint URL. AWS `https://s3.amazonaws.com`; MinIO `http://localhost:9000`; R2 `https://<account>.r2.cloudflarestorage.com`.
`publicUrl`	`""`	Optional public base URL for object links; leave blank for private buckets.
`region`	`"us-east-1"`	Request-signing region. Use `"auto"` for Cloudflare R2.
`defaultBucket`	`""`	Bucket used when code doesn't specify one.
`forcePathStyle`	`true`	Path-style addressing; required for MinIO and most non-AWS services.
`useHttps`	`true`	Use HTTPS for the connection.
`timeoutSeconds`	`30`	HTTP request timeout (1–600).
`maxRetries`	`3`	Retry attempts on transient failures (0–20).
`disablePayloadSigning`	`false`	Disables streaming payload signing; set `true` for Cloudflare R2.

Provider tips: AWS → forcePathStyle: false, disablePayloadSigning: false. MinIO → forcePathStyle: true, useHttps: false. R2 → disablePayloadSigning: true, forcePathStyle: false.

Documentation

Full guide: CL.StorageS3 documentation

Requirements

CodeLogic 4 · .NET 10
AWSSDK.S3 4.x

License

MIT — see LICENSE.

Product	Compatible and additional computed target framework versions.
.NET	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
- AWSSDK.S3 (>= 4.0.101.4)
- CodeLogic (>= 4.0.0 && < 5.0.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
4.6.74	48	7/25/2026
4.6.72	150	6/20/2026
4.6.69-preview	34	6/20/2026
4.5.2	101	5/24/2026
4.5.2-preview.68	58	6/20/2026
4.5.1	158	5/24/2026
4.5.1-preview.56	96	5/24/2026
4.4.2-preview.53	56	5/24/2026
4.4.1	101	5/24/2026
4.0.5	106	5/15/2026
4.0.4	112	5/9/2026
4.0.3	107	5/9/2026
3.3.1	803	4/18/2026
3.3.0	111	4/18/2026
3.2.11	131	4/18/2026
3.2.10	117	4/18/2026
3.2.9	111	4/18/2026
3.2.8	102	4/18/2026
3.2.7	104	4/18/2026
3.2.6	105	4/18/2026

# CL.StorageS3 — Changelog

All notable changes to **CodeLogic.StorageS3** are documented here. Versions follow
[Semantic Versioning](https://semver.org/).

## 2026-07-25

### Fixed

- Scope connection health checks to `defaultBucket` when configured, allowing
bucket-scoped Cloudflare R2 tokens without account-wide `ListBuckets` access.
- Bound health checks to ten seconds so a failing endpoint cannot accumulate
overlapping SDK retry pipelines.
- Apply `region` as the authentication region for custom service URLs.
- Reject malformed Cloudflare R2 endpoints whose account ID is not exactly 32
hexadecimal characters.

## 2026-06-20

### Documentation

- Full rewrite of the README and the `docs/libs/storages3.md` guide to the shared
house style: concise NuGet-rendered README (badges, tagline, install, quick
start, features, configuration table + JSON, requirements) and a single deep
documentation page covering the multi-provider story (AWS S3 / MinIO /
Cloudflare R2) with a provider-settings comparison, bucket and object
operations, byte/stream upload and download, `UploadOptions` / `DownloadOptions`
references, the `S3ObjectInfo` / `BucketInfo` / `ListObjectsResult` models,
pagination and prefixes, copy, presigned URLs, events, and the per-connection
health check. No API changes.

## [4.5.2] — 2026-06-20

### Documentation

- Rewrote the storage guide and Quick Start to match the real `S3StorageService`
API: every operation returns `Result` / `Result<T>` (existence checks return
`bool`), uploads/downloads take `UploadOptions` / `DownloadOptions`, and the
config file is `config.storages3.json` with camelCase keys and a `connections`
array.
- Documented previously undocumented surface: `GetService` / `DefaultService`
connection access, `CopyObjectAsync`, `GetObjectInfoAsync`,
`GetObjectStreamAsync`, byte-range and `VersionId` downloads, `UploadOptions`
fields (cache-control, content-disposition, storage class, public-read ACL,
metadata), paginated `ListObjectsResult`, the `ObjectUploadedEvent` /
`ObjectDeletedEvent` / `BucketCreatedEvent` events, low-level
`ConnectionManager.GetClient` access, and the per-connection health check
(Healthy / Degraded / Unhealthy).

## [4.5.0] — 2026-05-24

### Changed

- **Unified versioning.** All CodeLogic.Libs now share a single version line
controlled by `version.txt` in the repo root. This is a version alignment
release — no functional changes to this library.
## [4.0.4] — 2026-04-16

### Changed

- README + manifest refresh for the v4 baseline. No functional changes vs 4.0.3.
- `LibraryManifest.Version` now reads from assembly metadata.

## [4.0.2] — 2026-04-09

### Added

- `DisablePayloadSigning` option on `S3ConnectionConfig` for S3-compatible
endpoints (Backblaze B2, MinIO with signing off, etc.) that don't accept
signed payloads.

### Changed

- Annotated S3 configuration with `[ConfigField]` for the admin UI surface.
- Aligned with the v4 baseline across all libraries.

## [4.0.0] — 2026-04-09

Major rewrite. Republished as v4.0.0 to reset the version line under the
unified v4 baseline. S3-compatible object storage with multipart upload,
presigned URLs, and lifecycle helpers.

### Notes

- Earlier history is retained in the
[git log](https://github.com/Media2A/CodeLogic.Libs/commits/main/CL.StorageS3).