CSharp.StratusSDK 1.3.1

.NET 10.0

dotnet add package CSharp.StratusSDK --version 1.3.1

NuGet\Install-Package CSharp.StratusSDK -Version 1.3.1

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="CSharp.StratusSDK" Version="1.3.1" />

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

<PackageVersion Include="CSharp.StratusSDK" Version="1.3.1" />
                    

                            Directory.Packages.props

<PackageReference Include="CSharp.StratusSDK" />
                    

                            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 CSharp.StratusSDK --version 1.3.1

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

#r "nuget: CSharp.StratusSDK, 1.3.1"

#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 CSharp.StratusSDK@1.3.1

#: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=CSharp.StratusSDK&version=1.3.1
                    

                            Install as a Cake Addin

#tool nuget:?package=CSharp.StratusSDK&version=1.3.1
                    

                            Install as a Cake Tool

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

Stratus SDK for .NET

Nuget Package Link: https://www.nuget.org/packages/CSharp.StratusSDK

A comprehensive .NET SDK for interacting with Zoho Catalyst Stratus cloud storage. Provides easy-to-use APIs for managing buckets, uploading/downloading objects, and performing advanced storage operations.

Features
Installation
SDK Initialization
- Option 1: Dependency Injection (ASP.NET Core)
- Option 2: Manual Initialization (Console Apps)
- Exception Handler (DI Only)
- Choosing Between Patterns
Samples
Quick Start
Configuration
- Required Settings
- Regions
Usage Examples
- Check Object Existence
- Copy Objects
- Delete Objects
- Download Specific Version
- Extract ZIP Files
- Generate Presigned URLs
- List Objects with Pagination
- Rename Objects
- Upload
Data Models Reference
- Configuration
  - StratusOptions
- Request Models
- Response Models
- Enumerations
- Interfaces
  - IStratusSDK
API Reference
- Object Operations
- Metadata & Information
- Bucket Operations
- Advanced Operations
Error Handling
- StratusException
- StratusAuthenticationException
Operation Stability
- Stable Operations
- Experimental Operations
Known Limitations & Improvements
Best Practices
Advanced Configuration
- Upload Options
- Download Options
Performance Tips
Troubleshooting
- Common Issues
Requirements
Support
License
Contributing
Changelog

Features

✨ Object Management

Upload and download files with metadata
Copy, rename, and delete objects
Version control support
Automatic compression

🔐 Security

OAuth 2.0 authentication
Presigned URLs for temporary access
Secure credential management

📦 Bucket Operations

List and manage buckets
Bucket metadata and configuration
Multi-region support

🚀 Advanced Features

ZIP file extraction in cloud
Pagination support for large listings
Custom metadata for objects
Automatic retry and error handling

Installation

Install the StratusSDK package via NuGet:

dotnet add package StratusSDK

Or via Package Manager Console:

Install-Package StratusSDK

SDK Initialization

The SDK supports two initialization patterns depending on your use case:

Option 1: Dependency Injection (Recommended for ASP.NET Core)

Use Case: ASP.NET Core applications, Web APIs, Blazor apps

Benefits:

Automatic lifetime management
Built-in exception handling middleware
Better testability with interfaces
Integration with ASP.NET Core logging
Proper HttpClient management

Setup:

using StratusSDK;

var builder = WebApplication.CreateBuilder(args);

// Add Stratus SDK with DI
builder.Services.AddStratusExtensions(options =>
{
    options.BucketName = "your-bucket-name";
    options.ProjectID = "your-project-id";
    options.Region = ERegion.US;
    options.Environment = EStratusEnvironment.Production; // Defaults to Development; override for production
    options.ClientID = builder.Configuration["Stratus:ClientID"];
    options.ClientSecret = builder.Configuration["Stratus:ClientSecret"];
    options.RefreshToken = builder.Configuration["Stratus:RefreshToken"];
    options.RedirectUrl = builder.Configuration["Stratus:RedirectUrl"];
});

// Optional: Add Stratus Exception Handler for automatic error handling
builder.Services.AddExceptionHandler<StratusExceptionHandler>();
builder.Services.AddProblemDetails();

var app = builder.Build();

// Enable exception handling middleware
app.UseExceptionHandler();

app.MapControllers();
app.Run();

Usage in Controllers/Services:

using StratusSDK;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class FilesController : ControllerBase
{
    private readonly IStratusSDK _sdk;
    private readonly ILogger<FilesController> _logger;

    // SDK is injected automatically
    public FilesController(IStratusSDK sdk, ILogger<FilesController> logger)
    {
        _sdk = sdk;
        _logger = logger;
    }

    [HttpPost("upload")]
    public async Task<IActionResult> Upload(IFormFile file)
    {
        using var stream = file.OpenReadStream();

        // Exceptions are automatically handled by StratusExceptionHandler
        await _sdk.UploadAsync(
            $"uploads/{file.FileName}",
            UploadContent.FromStream(stream));

        return Ok(new { message = "File uploaded successfully" });
    }
}

Configuration in appsettings.json:

{
  "Stratus": {
    "BucketName": "your-bucket-name",
    "ProjectID": "your-project-id",
    "Region": "US",
    "ClientID": "your-client-id",
    "ClientSecret": "your-client-secret",
    "RefreshToken": "your-refresh-token",
    "RedirectUrl": "your-redirect-url"
  }
}

Option 2: Manual Initialization (For Console Apps & Non-DI Scenarios)

Use Case: Console applications, background services, legacy applications

Benefits:

Simple and straightforward
No DI container required
Full control over SDK lifecycle
Suitable for scripts and utilities

Setup:

using StratusSDK;

var options = new StratusOptions
{
    BucketName = "your-bucket-name",
    ProjectID = "your-project-id",
    Region = ERegion.US,
    // Environment defaults to EStratusEnvironment.Development; override if needed:
    // Environment = EStratusEnvironment.Production,
    ClientID = "your-client-id",
    ClientSecret = "your-client-secret",
    RefreshToken = "your-refresh-token",
    RedirectUrl = "your-redirect-url"
};

var sdk = StratusSDKFactory.Create(options);

Usage:

using StratusSDK;

class Program
{
    static async Task Main(string[] args)
    {
        var options = new StratusOptions
        {
            BucketName = Environment.GetEnvironmentVariable("STRATUS_BUCKET"),
            ProjectID = Environment.GetEnvironmentVariable("STRATUS_PROJECT_ID"),
            Region = ERegion.US,
            // Environment defaults to EStratusEnvironment.Development; override if needed:
            // Environment = EStratusEnvironment.Production,
            ClientID = Environment.GetEnvironmentVariable("STRATUS_CLIENT_ID"),
            ClientSecret = Environment.GetEnvironmentVariable("STRATUS_CLIENT_SECRET"),
            RefreshToken = Environment.GetEnvironmentVariable("STRATUS_REFRESH_TOKEN"),
            RedirectUrl = Environment.GetEnvironmentVariable("STRATUS_REDIRECT_URL")
        };

        var sdk = StratusSDKFactory.Create(options);

        try
        {
            // Upload
            await sdk.UploadAsync(
                "test/file.txt",
                UploadContent.FromString("Hello, Stratus!"));
            Console.WriteLine("Upload successful!");

            // Download
            var response = await sdk.DownloadObjectAsync(new DownloadObjectRequest
            {
                ObjectKey = "test/file.txt"
            });
            Console.WriteLine($"Downloaded {response.Data?.Length ?? 0} bytes");
        }
        catch (StratusException ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
            Console.WriteLine($"Status: {ex.StatusCode}");
        }
    }
}

Exception Handler (DI Only)

The StratusExceptionHandler provides automatic exception handling for ASP.NET Core applications:

Features:

Automatically catches StratusException from any SDK operation
Converts exceptions to standardized Problem Details (RFC 7807)
Logs errors with structured data
Returns proper HTTP status codes
Includes error codes and details in response

Registration:

// In Program.cs or Startup.cs
builder.Services.AddExceptionHandler<StratusExceptionHandler>();
builder.Services.AddProblemDetails();

var app = builder.Build();
app.UseExceptionHandler(); // Enable exception handling

Response Format:

When a StratusException occurs, the handler returns:

{
  "type": "https://api.catalyst.zoho.com/baas/v1/project/123/bucket/object",
  "title": "Stratus API Error",
  "status": 404,
  "detail": "Object not found: documents/report.pdf",
  "instance": "/api/files/download",
  "errorCode": "OBJECT_NOT_FOUND"
}

Example with Exception Handler:

using StratusSDK;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/storage")]
public class StorageController : ControllerBase
{
    private readonly IStratusSDK _sdk;

    public StorageController(IStratusSDK sdk)
    {
        _sdk = sdk;
    }

    [HttpGet("download/{*objectKey}")]
    public async Task<IActionResult> Download(string objectKey)
    {
        // No try-catch needed - StratusExceptionHandler handles it
        var response = await _sdk.DownloadObjectAsync(new DownloadObjectRequest
        {
            ObjectKey = objectKey
        });

        return File(response.Content, response.ContentType, Path.GetFileName(objectKey));
    }

    [HttpDelete("{*objectKey}")]
    public async Task<IActionResult> Delete(string objectKey)
    {
        // Exceptions are automatically converted to Problem Details
        await _sdk.DeleteObjectAsync(objectKey);

        return NoContent();
    }
}

Choosing Between Patterns

Feature	DI Pattern	Manual Pattern
Use Case	ASP.NET Core, Web APIs	Console apps, Scripts
Setup Complexity	Medium	Low
Exception Handling	Automatic (with handler)	Manual try-catch
Testability	Excellent (interface-based)	Good
HttpClient Management	Automatic (pooled)	Manual
Logging Integration	Built-in	Manual
Configuration	appsettings.json	Environment variables/code
Lifetime Management	Automatic (scoped)	Manual

Recommendation:

✅ Use DI Pattern for web applications, APIs, and long-running services
✅ Use Manual Pattern for console apps, scripts, and simple utilities

Samples

Ready-to-use examples are available as separate projects in the solution:

DIExampleApp/ (DIExampleApp) — An ASP.NET Core project demonstrating dependency injection setup with a full controller (StratusController.cs) wired up with Scalar/OpenAPI for interactive testing.
NonDIExampleApp/ — A console application demonstrating how to use the SDK without a DI container, using StratusSDKFactory.Create().

Feel free to copy these into your own project as a starting point.

Quick Start

Note: This quick start uses the manual initialization pattern. For ASP.NET Core applications, see the Dependency Injection setup above.

1. Configure the SDK

Create a StratusOptions instance with your Zoho Catalyst credentials:

using StratusSDK;

var options = new StratusOptions
{
    BucketName = "your-bucket-name",
    ProjectID = "your-project-id",
    Region = ERegion.US,
    // Environment defaults to EStratusEnvironment.Development; override if needed:
    // Environment = EStratusEnvironment.Production,
    ClientID = "your-client-id",
    ClientSecret = "your-client-secret",
    RefreshToken = "your-refresh-token",
    RedirectUrl = "your-redirect-url"
};

2. Initialize the SDK

var sdk = StratusSDKFactory.Create(options);

3. Start Using

// Upload a file from disk
await sdk.UploadAsync(
    "documents/report.pdf",
    UploadContent.FromFile("report.pdf"),
    EContentType.ApplicationPdf);

// Download a file
var response = await sdk.DownloadObjectAsync(new DownloadObjectRequest
{
    ObjectKey = "documents/report.pdf"
});

// List objects
var objects = await sdk.ListAllObjectsAsync(
    Prefix: "documents/");

Configuration

Required Settings

Property	Description	Example
`BucketName`	Your Stratus bucket name	`"my-storage-bucket"`
`ProjectID`	Catalyst project identifier	`"1234567890"`
`Region`	Data center region	`ERegion.US`
`Environment`	Stratus environment (defaults to `Development`; can be overridden to `Production`)	`EStratusEnvironment.Production`
`ClientID`	OAuth client ID	`"1000.XXXXX"`
`ClientSecret`	OAuth client secret	`"xxxxxxxxxxxxx"`
`RefreshToken`	OAuth refresh token	`"1000.xxxxx.xxxxx"`
`RedirectUrl`	OAuth redirect URL	`"https://your-app.com/callback"`

Regions

Available regions via ERegion enum:

ERegion.US - United States
ERegion.EU - European Union
ERegion.IN - India
ERegion.AU - Australia
ERegion.JP - Japan
ERegion.CA - Canada

Usage Examples

All examples below are shown in two patterns: Manual (for console apps) and Dependency Injection (for ASP.NET Core).