Class ServiceCollectionExtensions

Namespace

Cloudflare.NET.R2

Assembly

Cloudflare.NET.R2.dll

Provides extension methods for setting up the Cloudflare R2 client in an IServiceCollection.

public static class ServiceCollectionExtensions

Inheritance

object

ServiceCollectionExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

AddCloudflareR2Client(IServiceCollection, IConfiguration)

Registers the IR2Client and its dependencies using a configuration section.

This is a convenience method that binds to the "R2" section of the application's IConfiguration. It also requires the "Cloudflare" section for the Account ID.

public static IServiceCollection AddCloudflareR2Client(this IServiceCollection services, IConfiguration configuration)

Parameters

services IServiceCollection

The IServiceCollection to add the services to.

configuration IConfiguration

The application configuration, used to bind R2 settings.

Returns

IServiceCollection

The IServiceCollection so that additional calls can be chained.

AddCloudflareR2Client(IServiceCollection, Action<R2Settings>)

Registers the IR2Client and its dependencies, allowing for fine-grained programmatic configuration.

This method sets up the underlying S3-compatible client tailored for R2 and registers the high-level IR2Client as a singleton.

Configuration is validated at application startup. If required settings (AccessKeyId, SecretAccessKey, AccountId) are missing, an OptionsValidationException is thrown with a clear error message indicating what configuration is missing and how to fix it.

public static IServiceCollection AddCloudflareR2Client(this IServiceCollection services, Action<R2Settings> configureOptions)

Parameters

services IServiceCollection

The IServiceCollection to add the services to.

configureOptions Action<R2Settings>

An action to configure the R2Settings.

Returns

IServiceCollection

The IServiceCollection so that additional calls can be chained.

Exceptions

OptionsValidationException

Thrown at application startup if required configuration is missing or invalid.

AddCloudflareR2Client(IServiceCollection, string, IConfiguration)

Registers a named IR2Client configuration using a configuration section.

Named clients can be retrieved using IR2ClientFactory or via keyed services using [FromKeyedServices("name")].

public static IServiceCollection AddCloudflareR2Client(this IServiceCollection services, string name, IConfiguration configuration)

Parameters

services IServiceCollection

The IServiceCollection to add the services to.

name string

The unique name for this client configuration. Used to retrieve the client from the factory or via keyed services.

configuration IConfiguration

The application configuration. Will bind to the "R2:" section for R2 settings and "Cloudflare:" section for the Account ID.

Returns

IServiceCollection

The IServiceCollection so that additional calls can be chained.

Exceptions

ArgumentException

Thrown when name is null or whitespace.

AddCloudflareR2Client(IServiceCollection, string, Action<R2Settings>)

Registers a named IR2Client configuration with programmatic options.

Named clients can be retrieved using IR2ClientFactory or via keyed services using [FromKeyedServices("name")].

public static IServiceCollection AddCloudflareR2Client(this IServiceCollection services, string name, Action<R2Settings> configureOptions)

Parameters

services IServiceCollection

The IServiceCollection to add the services to.

name string

The unique name for this client configuration. Used to retrieve the client from the factory or via keyed services.

configureOptions Action<R2Settings>

An action to configure the R2Settings.

Returns

IServiceCollection

The IServiceCollection so that additional calls can be chained.

Examples

// Register multiple named clients
services.AddCloudflareApiClient("primary", options => {
    options.AccountId = "primary-account-id";
    options.ApiToken = "primary-token";
});
services.AddCloudflareR2Client("primary", options => {
    options.AccessKeyId = "primary-key";
    options.SecretAccessKey = "primary-secret";
    // Jurisdiction defaults to R2Jurisdiction.Default (global endpoint)
    // Set options.Jurisdiction = R2Jurisdiction.EuropeanUnion for EU buckets
});

// Use via factory
public class MyService(IR2ClientFactory factory)
{
    public async Task DoSomething()
    {
        var primaryClient = factory.CreateClient("primary");
        // ...
    }
}

// Or use via keyed services
public class MyService([FromKeyedServices("primary")] IR2Client client)
{
    // ...
}

Remarks

This method requires that the Cloudflare API options for the same name are also registered using AddCloudflareApiClient(IServiceCollection, string, Action<CloudflareApiOptions>) . The Account ID from those options is used to construct the R2 endpoint URL.

Unlike the default client registration, named clients are validated when first created via the factory or keyed services, not at application startup. This is because named configurations may be dynamically added or configured after startup.

Exceptions

ArgumentException

Thrown when name is null or whitespace.

CloudflareR2ConfigurationException

Thrown when the named client is created if required configuration is missing or invalid.