Omnia.FileAzure 9.0.3

Omnia.FileAzure — API Reference

Questo file documenta le API pubbliche esposte dal progetto Omnia.FileAzure. Contiene i namespace, le interfacce e le classi principali, con la descrizione dei metodi pubblici e esempi d'uso.

Namespaces

• Omnia.FileAzure.Interfaces — interfacce pubbliche per i servizi di file/Blob.
• Omnia.FileAzure.Implementations — implementazioni concrete fornite dal package.

Interfacce (namespace Omnia.FileAzure.Interfaces)

• IBlobConfig

  • Proprietà:
    • string ConnectionString { get; } — connection string per Azure Storage.
    • string ContainerName { get; } — nome del container blob da usare.

• IPrivateFile<IdFile>

  • Metodi:
    • Task<string> UploadFileAsync(IFormFile file)
      • Carica file su blob storage e restituisce l'id/nome del blob caricato.
    • Task<Stream> GetFileAsync(IdFile id)
      • Scarica il blob identificato da id e restituisce uno Stream con i dati.
    • Task DeleteFileAsync(IdFile id)
      • Elimina il blob identificato da id.

• IFileRepository<IdFile> : IPrivateFile<IdFile> — repository che implementa l'accesso diretto allo storage.

• IFileService<IdFile> : IPrivateFile<IdFile> — servizio che incapsula la logica attorno al repository.

• IFileUpperService<IdFile> : IFileService<IdFile> — upper service che aggiunge hook before/after.

• IFileBeforeService<in IdFile>

  • Metodi (default no-op):
    • Task UploadFileAsync(IFormFile file) — chiamato prima dell'upload principale.
    • Task GetFileAsync(IdFile id) — chiamato prima del get.
    • Task DeleteFileAsync(IdFile id) — chiamato prima della delete.

• IFileAfterService<in IdFile>

  • Metodi (default no-op):
    • Task UploadFileAsync(IFormFile file, IdFile idFile) — chiamato dopo l'upload principale e riceve l'id risultato.
    • Task AfterGetFileAsync(IdFile id, Stream file) — chiamato dopo il get con lo stream restituito.
    • Task AfterDeleteFileAsync(IdFile id) — chiamato dopo la delete.

Implementazioni (namespace Omnia.FileAzure.Implementations)

• BlobConfig : IBlobConfig

  • Costruttore: BlobConfig(IConfiguration configuration)
    • Legge Blob:ConnectionString e Blob:ContainerName da IConfiguration.
  • Proprietà:
    • ConnectionString — ritorna la connection string o string.Empty se non presente.
    • ContainerName — ritorna il container name o string.Empty se non presente.

• BlobRepository : IFileRepository<string>

  • Costruttore: BlobRepository(IBlobConfig blobConfig)
    • Crea BlobServiceClient con blobConfig.ConnectionString e BlobContainerClient per blobConfig.ContainerName.
  • Metodi pubblici:
    • Task<string> UploadFileAsync(IFormFile file)
      • Genera un nome univoco per il blob (FormFileID.CreateUniqueBlobNameAsync(file)), effettua UploadAsync e restituisce il blob name.
    • Task<Stream> GetFileAsync(string blobName)
      • Recupera BlobClient, chiama DownloadAsync() e ritorna downloadInfo.Value.Content.
    • Task DeleteFileAsync(string blobName)
      • Recupera BlobClient e chiama DeleteIfExistsAsync().

• BlobService : IFileService<string>

  • Costruttore: BlobService(IFileRepository<string> repository)
  • Metodi:
    • Task<string> UploadFileAsync(IFormFile file) — delega a repository.UploadFileAsync.
    • Task<Stream> GetFileAsync(string blobName) — delega a repository.GetFileAsync.
    • Task DeleteFileAsync(string blobName) — delega a repository.DeleteFileAsync.

• BlobUpperService : IFileUpperService<string>

  • Costruttore: BlobUpperService(IFileService<string> service, IFileBeforeService<string> beforeService, IFileAfterService<string> afterService)
  • Comportamento:
    • UploadFileAsync(IFormFile file)
      • chiama _beforeService.UploadFileAsync(file), poi _service.UploadFileAsync(file) e _afterService.UploadFileAsync(file, idFile).
    • GetFileAsync(string blobName)
      • chiama _beforeService.GetFileAsync(blobName), _service.GetFileAsync(blobName) e _afterService.AfterGetFileAsync(blobName, file).
    • DeleteFileAsync(string blobName)
      • chiama _beforeService.DeleteFileAsync(blobName), _service.DeleteFileAsync(blobName) e _afterService.AfterDeleteFileAsync(blobName).

• ServiceCollectionExtensions (static class)

  • Metodi di estensione:
    • IServiceCollection AddFileAzure(this IServiceCollection services, IConfiguration configuration, bool addDummies = true)
      • Registra IBlobConfig come new BlobConfig(configuration) e i servizi/repository (BlobRepository, BlobService, BlobUpperService). Se addDummies è true, registra le implementazioni dummy per IFileBeforeService e IFileAfterService.
    • IServiceCollection AddFileAzure(this IServiceCollection services, string connectionString, string containerName, bool addDummies = true)
      • Overload (non consigliato se hai già IConfiguration): registra IBlobConfig (con valori passati) e gli altri servizi.

Esempi d'uso

1. Registrazione preferita (legge da IConfiguration):

using Omnia.FileAzure.Implementations;

var builder = WebApplication.CreateBuilder(args);

// Registra tutto leggendo da appsettings / environment
builder.Services.AddFileAzure(builder.Configuration);

var app = builder.Build();

2. Registrazione esplicita (valori forniti):

builder.Services.AddFileAzure("UseDevelopmentStorage=true", "my-container");

Note operative

• BlobConfig legge i valori da Blob:ConnectionString e Blob:ContainerName in IConfiguration.
• Le eccezioni del client Azure (Azure.RequestFailedException) vengono propagate: gestiscile nel tuo codice chiamante.
• Le implementazioni Before/After sono opzionali: il pacchetto fornisce no-op dummy se non registri implementazioni custom.

Se vuoi, posso generare una sezione aggiuntiva che mostra esempi completi di appsettings.json, test di integrazione e un piccolo snippet per utilizzare il package in un'app console.