Ticomix.Attachments.Storage.AzureBlob

Purpose Statement

A .NET library that provides Azure Blob Storage implementation for the Ticomix attachments system, enabling secure and scalable cloud storage for application file attachments.

Technical Context

• Implements the IAttachments<TKey> interface from the Ticomix.Attachments.Common library
• Built on Azure.Storage.Blobs SDK version 12.21.2
• Supports .NET 8.0 and .NET 10.0 frameworks.
• Uses generics to support multiple key types for attachment identification
• Authenticates with a storage connection string (Shared Key / Azurite / SAS) or with a blob-service Uri plus TokenCredential (Entra ID / managed identity). This package does not reference Azure.Identity; the host app passes DefaultAzureCredential.

Key Capabilities

• Blob Container Management: Automatically creates and manages Azure Blob Storage containers with customizable access policies
• Hierarchical File Organization: Supports directory-like organization through virtual folder paths within blob storage
• Streaming Content Delivery: Provides optimized streaming download capabilities for efficient file retrieval
• Attachment Lifecycle Management: Implements complete attachment operations including upload, download, copy, and deletion

Integration Points

• Seamlessly integrates with the Ticomix attachments ecosystem via the standard IAttachments<TKey> interface
• Compatible with Entity Framework Core for database storage of attachment metadata
• Works alongside other storage providers in the Ticomix.Attachments namespace

Use Case Scenarios

• Enterprise applications requiring secure cloud storage for user-uploaded files
• Systems needing scalable attachment storage with metadata tracking
• Applications migrating from on-premises storage to cloud-based solutions
• Multi-tenant applications requiring isolation of attachment data

Database Models Used

• Attachment: Represents attachment metadata including file name, directory path, and other attributes stored in a database context that implements IAttachmentsDbContext<TKey>

Classes and Functions

AzureBlobAttachments

Main implementation class that provides Azure Blob Storage functionality for the attachment system.

Constructors:

• (db, connectionString, container, options) — Shared Key, account SAS connection string, or Azurite (UseDevelopmentStorage=true). A bare https://{account}.blob.core.windows.net URI is rejected; use the TokenCredential constructor instead.
• (db, blobServiceUri, credential, container, options) — Entra ID. Pass DefaultAzureCredential from the app. Keep Allow storage account key access disabled on the storage account.
• (db, blobServiceClient, container, options) — inject a pre-built BlobServiceClient (tests / advanced hosts).

Entra registration (app code):

services.AddScoped<IAttachments<int>>(sp =>
    new AzureBlobAttachments<int>(
        sp.GetRequiredService<ApplicationDbContext>(),
        new Uri("https://{account}.blob.core.windows.net"),
        new DefaultAzureCredential(),
        containerName,
        options));

RBAC: grant the App Service managed identity (and local az login / Visual Studio identity) Storage Blob Data Contributor on the storage account. CreateIfNotExists needs permission to create the container, or create attachmentsdev (or your container name) ahead of time.

CopyAsync streams through the authenticated clients (download + upload) and reapplies the source blob's HTTP headers and metadata via BlobUploadOptions, matching server-side copy for content-type and related properties. It does not use StartCopyFromUriAsync on a bare blob URI, which is anonymous and fails when Shared Key is disabled.

Key Functions:

• UploadAsync: Uploads a file stream to Azure Blob Storage
• DownloadStreamingAsync: Downloads file content as a stream
• DeleteAsync: Removes an attachment from blob storage
• CopyAsync: Creates a copy of an existing attachment
• GetContainerAsync: Retrieves or creates a blob container
• GetBlobClient: Gets a reference to a specific blob
• DownloadBlob: Retrieves blob content and metadata

AzureBlobLegacy provider (read-by-BlobId)

AzureBlobAttachments<TKey> resolves a blob by Directory+FileName. Applications that previously stored a GUID blob name in Attachment.BlobId (and never set AttachmentLocation) need AzureBlobLegacyAttachments<TKey> to read those blobs.

• AttachmentLocation = "AzureBlobLegacy".
• DownloadStreamingAsync/DeleteAsync resolve the blob via GetBlobName(attachment) (defaults to attachment.BlobId).
• CanHandle claims "AzureBlobLegacy" rows and null-location rows that have a BlobId.
• Read-only: UploadAsync/CopyAsync throw NotSupportedException — write new attachments through AzureBlobAttachments<TKey>.

Register it alongside the canonical provider (see the Common package README).

IAttachmentBlobStore (path-addressed blobs)

AzureBlobAttachments also implements IAttachmentBlobStore for low-level, row-less blob access (path download/upload/exists, bulk prefix delete) -- used by image thumbnail caches and container maintenance. The FileSystem provider deliberately does NOT implement it: the only consumers are Azure-blob-backed thumbnail caches; the FileSystem provider is the local-dev/ offline staging backend and maintains no such cache.