Table of Contents

Interface IR2ClientFactory

Namespace
Cloudflare.NET.R2
Assembly
Cloudflare.NET.R2.dll

Defines the contract for a factory that creates and caches IR2Client instances. Supports named configurations for multi-account scenarios and jurisdiction-specific clients for accessing buckets in different geographic regions.

public interface IR2ClientFactory

Examples

// Single account, multiple jurisdictions
var defaultClient = factory.GetClient(R2Jurisdiction.Default);
var euClient = factory.GetClient(R2Jurisdiction.EuropeanUnion);

// Multiple accounts
var prodClient = factory.GetClient("production");
var stagingClient = factory.GetClient("staging");

// Multiple accounts with jurisdiction override
var prodEuClient = factory.GetClient("production", R2Jurisdiction.EuropeanUnion);

Remarks

All clients created by this factory are cached and reused. The AWS S3 client is thread-safe and designed to be used as a singleton, so caching improves performance by avoiding repeated client construction.

Cache Keys:

  • GetClient(name) - Cached by (name, configured-jurisdiction)
  • GetClient(jurisdiction) - Cached by ("", jurisdiction)
  • GetClient(name, jurisdiction) - Cached by (name, jurisdiction)

Methods

GetClient(R2Jurisdiction)

Gets an IR2Client for the specified jurisdiction using the default (unnamed) credentials.

IR2Client GetClient(R2Jurisdiction jurisdiction)

Parameters

jurisdiction R2Jurisdiction

The target jurisdiction for R2 operations.

Returns

IR2Client

A cached IR2Client instance configured for the specified jurisdiction.

Examples

// Access buckets in different jurisdictions with the same credentials
var globalClient = factory.GetClient(R2Jurisdiction.Default);
var euClient = factory.GetClient(R2Jurisdiction.EuropeanUnion);
var fedRampClient = factory.GetClient(R2Jurisdiction.FedRamp);

// Upload to EU-jurisdictional bucket
await euClient.UploadAsync("my-eu-bucket", "file.txt", stream);

Remarks

This method uses the credentials from the default (unnamed) R2 configuration registered via AddCloudflareR2Client(IServiceCollection, Action<R2Settings>) .

The same R2 credentials work across all jurisdictions within an account; only the S3 endpoint differs. Clients are cached by jurisdiction and reused for subsequent calls.

Exceptions

CloudflareR2ConfigurationException

Thrown when the default R2 configuration is missing or invalid.

GetClient(string)

Gets or creates a named IR2Client instance configured with the specified named options.

IR2Client GetClient(string name)

Parameters

name string

The name of the client configuration to use. Must match the name used during registration with AddCloudflareR2Client(IServiceCollection, string, Action<R2Settings>) .

Returns

IR2Client

A cached IR2Client instance configured with the named options.

Examples

// Registration
services.AddCloudflareR2Client("primary", options => {
    options.AccessKeyId = "primary-key";
    options.SecretAccessKey = "primary-secret";
});
services.AddCloudflareR2Client("backup", options => {
    options.AccessKeyId = "backup-key";
    options.SecretAccessKey = "backup-secret";
});

// Usage via factory
public class MyService(IR2ClientFactory factory)
{
    public async Task DoSomething()
    {
        var primaryClient = factory.GetClient("primary");
        var backupClient = factory.GetClient("backup");
        // ...
    }
}

Remarks

The client uses the jurisdiction specified in the named configuration's Jurisdiction. To access a different jurisdiction with the same credentials, use GetClient(string, R2Jurisdiction).

Clients are cached by (name, configured-jurisdiction) and reused for subsequent calls.

Exceptions

ArgumentException

Thrown when name is null or whitespace.

CloudflareR2ConfigurationException

Thrown when the named configuration is missing or invalid.

GetClient(string, R2Jurisdiction)

Gets an IR2Client for the specified jurisdiction using named credentials.

IR2Client GetClient(string name, R2Jurisdiction jurisdiction)

Parameters

name string

The name of the client configuration providing credentials. Must match the name used during registration.

jurisdiction R2Jurisdiction

The target jurisdiction for R2 operations.

Returns

IR2Client

A cached IR2Client instance configured with the named credentials and specified jurisdiction.

Examples

// Production account has buckets in both default and EU jurisdictions
var prodDefault = factory.GetClient("production", R2Jurisdiction.Default);
var prodEu = factory.GetClient("production", R2Jurisdiction.EuropeanUnion);

// DR account uses FedRAMP jurisdiction
var drFedRamp = factory.GetClient("disaster-recovery", R2Jurisdiction.FedRamp);

Remarks

Use this method when you have multiple accounts (each with different credentials) and need to access buckets in specific jurisdictions within those accounts.

Clients are cached by (name, jurisdiction) tuple and reused for subsequent calls.

Exceptions

ArgumentException

Thrown when name is null or whitespace.

CloudflareR2ConfigurationException

Thrown when the named configuration is missing or invalid.

Edit this page