Skip to content

README.md

Latest commit

 

History

History
241 lines (181 loc) · 5.79 KB

README.md

File metadata and controls

241 lines (181 loc) · 5.79 KB
Raw

AzureStorage.Standard.Blobs

A simplified, modern .NET client library for Azure Blob Storage with built-in retry policies, comprehensive error handling, and intuitive APIs.

NuGet License: MIT

Features

Simplified API - Easy-to-use wrapper around Azure.Storage.Blobs SDK Built-in Resilience - Automatic retry policies using Polly Comprehensive Operations - Upload, download, delete, copy, and more Streaming Support - Efficient handling of large files Container Management - Full CRUD operations for containers Metadata Management - Easy blob and container metadata handling Access Tier Management - Hot, Cool, and Archive tier support Lease Operations - Blob leasing for distributed locking SAS Token Generation - Secure delegated access Extensive Documentation - Full XML documentation for IntelliSense

Installation

dotnet add package AzureStorage.Standard.Blobs

Or via Package Manager Console:

Install-Package AzureStorage.Standard.Blobs

Quick Start

1. Configure the Client

using AzureStorage.Standard.Blobs;
using AzureStorage.Standard.Core;

var options = new StorageOptions
{
    ConnectionString = "DefaultEndpointsProtocol=https;AccountName=..."
};

var blobClient = new AzureBlobClient(options);

2. Upload a Blob

// Upload from file
await blobClient.UploadBlobAsync(
    containerName: "documents",
    blobName: "report.pdf",
    filePath: "C:\\reports\\report.pdf"
);

// Upload from stream
using var stream = File.OpenRead("image.jpg");
await blobClient.UploadBlobAsync(
    containerName: "images",
    blobName: "profile.jpg",
    content: stream
);

3. Download a Blob

// Download to file
await blobClient.DownloadBlobAsync(
    containerName: "documents",
    blobName: "report.pdf",
    filePath: "C:\\downloads\\report.pdf"
);

// Download to stream
using var downloadStream = await blobClient.DownloadBlobToStreamAsync(
    containerName: "images",
    blobName: "profile.jpg"
);

4. Container Operations

// Create container
await blobClient.CreateContainerIfNotExistsAsync("my-container");

// List containers
var containers = await blobClient.ListContainersAsync();

// Delete container
await blobClient.DeleteContainerAsync("my-container");

5. List Blobs

var blobs = await blobClient.ListBlobsAsync(
    containerName: "documents",
    prefix: "reports/"
);

foreach (var blob in blobs)
{
    Console.WriteLine($"Blob: {blob.Name}, Size: {blob.Size} bytes");
}

Advanced Usage

Metadata Management

// Set blob metadata
var metadata = new Dictionary<string, string>
{
    { "Author", "John Doe" },
    { "Department", "Engineering" }
};
await blobClient.SetBlobMetadataAsync("container", "document.pdf", metadata);

// Get blob metadata
var retrievedMetadata = await blobClient.GetBlobMetadataAsync("container", "document.pdf");

Access Tier Management

// Change blob access tier
await blobClient.SetBlobAccessTierAsync(
    containerName: "archives",
    blobName: "old-data.zip",
    accessTier: AccessTier.Archive
);

Copy Blobs

// Copy blob within storage account
await blobClient.CopyBlobAsync(
    sourceContainerName: "source-container",
    sourceBlobName: "original.pdf",
    destinationContainerName: "backup-container",
    destinationBlobName: "backup-original.pdf"
);

Generate SAS Token

var sasToken = await blobClient.GenerateBlobSasTokenAsync(
    containerName: "documents",
    blobName: "report.pdf",
    permissions: BlobSasPermissions.Read,
    expiresOn: DateTimeOffset.UtcNow.AddHours(2)
);

// Use the SAS token
var sasUrl = $"https://mystorageaccount.blob.core.windows.net/documents/report.pdf?{sasToken}";

Authentication Options

Connection String (Development)

var options = new StorageOptions
{
    ConnectionString = "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=..."
};

Account Key

var options = new StorageOptions
{
    AccountName = "myaccount",
    AccountKey = "your-account-key"
};

Service URI (Managed Identity)

var options = new StorageOptions
{
    ServiceUri = new Uri("https://myaccount.blob.core.windows.net")
};

Supported Frameworks

  • .NET Standard 2.0
  • .NET Standard 2.1
  • .NET 8.0
  • .NET 9.0

Error Handling

All operations throw AzureStorageException with detailed error information:

try
{
    await blobClient.DownloadBlobAsync("container", "missing-file.pdf", "output.pdf");
}
catch (AzureStorageException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
    Console.WriteLine($"Error Code: {ex.ErrorCode}");
    Console.WriteLine($"Status Code: {ex.StatusCode}");
}

Related Packages

Documentation

For complete documentation, visit the GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or suggestions, please open an issue on GitHub.