Skip to Content

Almacenamiento S3

DinaS3ClientC opera sobre un bucket S3 o MinIO y DinaS3MultiClientC replica, repara y detecta deriva entre varios buckets desde .NET.

El módulo Dinaup.S3 trabaja con cualquier almacén compatible con S3 (AWS S3, MinIO, Cloudflare R2, OVH): DinaS3ClientC para un bucket y DinaS3MultiClientC para replicar y reparar sobre varios. Los archivos de tus usuarios de Dinaup no pasan por aquí: van con File_UploadBytesAsync del Cliente Dinaup.

Antes de empezar

  • Paquete Dinaup instalado. Ver SDK .NET.
  • Clave de acceso, clave secreta, endpoint y bucket. Para no dejarlos en el código, guárdalos en el Vault.

Un bucket: DinaS3ClientC

using Dinaup.S3;

var s3 = new DinaS3ClientC("ACCESS_KEY", "SECRET_KEY", "s3.tu-dominio.com", "mi-bucket", "app/");   // prefijo opcional
var s3b = new DinaS3ClientC("s3://ACCESS:[email protected]/mi-bucket/app");
ConstructorDetalle
New(_s3Token, _s3Secret, _s3EndPoint, _Bucket, _BaseDir = "", _regionForazada = "")Parámetros sueltos. _regionForazada salta la detección de región.
New(_connectionString, _regionForazada = "")s3://ACCESS:SECRET@host[:puerto]/bucket[/prefijo]. Usa TLS salvo que empiece por http://.
New(param As Dictionary(Of String, String))Claves accessKey, secretKey, endpoint, bucketName, prefix, region.

La conexión se abre en la primera operación (Iniciar()). La región se deduce del endpoint en R2 (auto) y OVH. EntrarDir(dir) añade un subdirectorio al prefijo.

Operar con objetos

Las rutas son relativas al bucket y al prefijo.

MétodoQué hace
BytesUploadAsync(ruta, bytes)Sube bytes. Si falla, lo registra en el log y no lanza.
BytesUploadThrowAsync(ruta, bytes)Igual, pero lanza la excepción.
StreamUploadAsync(ruta, stream)Sube desde un Stream.
BytesReadAsync(ruta)Descarga el objeto como bytes.
FileUploadAsync(ruta, archivoLocal) / FileDownloadAsync(ruta, destinoLocal)Sube o descarga un archivo de disco.
FileUploadIfIsDifferentAsync(ruta, archivoLocal)Sube solo si el contenido cambió.
FileExistAsync(ruta)true si existe ese objeto (clave exacta, no prefijo).
FileRemoveAsync(ruta)Borra el objeto.
LastModified(ruta)Fecha de última modificación.
GetFileMetadataAsync(ruta)ObjectStat de Minio con tamaño, ETag y metadatos.
FileList(prefijo, recursive = true, limit = -1) / DirList(prefijo, recursive = true)Lista objetos o directorios bajo un prefijo.
ListAll(prefijo, files = true, directories = false, recursive = true) / ListAll_GetEnumeratorArchivos y directorios; el enumerador no carga todo en memoria.
JObjectWriteAsync<T>(ruta, objeto) / JObjectReadAsync<T>(ruta)Serializa y deserializa JSON.
NoSQL_WriteAsync(ruta, texto) / NoSQL_ReadAsync(ruta) / NoSQL_RemoveAsync(ruta)Texto plano como clave-valor.
SignGet(ruta) / SignPut(ruta)URL firmada de lectura o de subida directa desde el navegador. expirationSeconds vale 600 por defecto. SignGet admite NombreArchivo (nombre de descarga) y disposition: false (sin cabecera Content-Disposition).

TotalRead, TotalWrite, TotalList, TotalDelete, TotalStat, TotalFileUpload y TotalFileDownload cuentan intentos por operación; ResetCounters() los pone a cero.

Salud

var salud = await s3.SaludAsync();
// salud.Estado: Ok, SoloLectura, Credenciales, Bucket, Red, SinConfigurar o Desconocido
// salud.Motivo: el texto del fallo; salud.Ok: true solo con Estado Ok

SaludAsync lee el marcador HealthCheck.dat y, si no existe, lo escribe: así distingue una clave de solo lectura de un bucket inaccesible. HealthCheckAsync() devuelve un bool y Ping() escribe y relee una clave de prueba. Como IHealthCheck (AddHealthChecks().AddCheck("s3", s3)), responde Healthy, Degraded (solo lectura) o Unhealthy.

Varios buckets: DinaS3MultiClientC

Envuelve una lista de DinaS3ClientC: escribe en todos y lee de la réplica más reciente. Con AutoRepair, si a un bucket le falta el objeto o lo tiene atrasado, lo repara antes de devolver.

var multi = new DinaS3MultiClientC(new List<DinaS3ClientC> { s3Primario, s3Secundario }, _autoRepair: true);

var res = await multi.WriteBytesAsync("informes/2026-07.json", datos);
if (res.AllOk == false)
    Console.WriteLine($"Fallaron: {string.Join(", ", res.FailedHosts)}");

byte[] leido = await multi.ReadBytesAsync("informes/2026-07.json");
MétodoQué hace
WriteBytesAsync(ruta, bytes) / WriteObjectAsync<T>(ruta, objeto)Escribe en todas las réplicas en paralelo. Devuelve WriteResult con OkHosts, FailedHosts, AllOk y AnyOk. No es transaccional: repite en FailedHosts cuando vuelvan.
ReadBytesAsync(ruta) / ReadObjectAsync<T>(ruta) / ReadStringAsync(ruta)Lee de la réplica más reciente; null si ninguna lo tiene.
ExistsAsync(ruta)true si alguna réplica que responde lo tiene.
ListAsync(prefijo, recursive = true, limit = -1)Unión de todas las réplicas, sin duplicados. Ignora las caídas.
UploadFileAsync(ruta, archivoLocal) / DownloadFileAsync(destinoLocal, ruta)Archivos de disco. DownloadFileAsync recibe primero el destino.
DeleteAsync(ruta)Borra en todas, con dos intentos por réplica. true solo si todas confirman; si una falla, repite cuando vuelva.
ResyncAsync(ruta) / RepairAsync(ruta)Fuerza la sincronización de una ruta. ResyncAsync devuelve dónde quedó (WriteResult); RepairAsync, un bool, y no depende de AutoRepair.
CheckDriftAsync(prefijo, sampleCount = 50)Compara versiones entre réplicas en una muestra de rutas, sin corregir. Devuelve un DriftReport con TotalChecked, InSync, Drifted y Missing (por host). Para corregir, ResyncAsync por cada ruta de Drifted.
HealthCheckAsync()true solo si todas las réplicas responden.

Clients expone la lista de réplicas, AutoRepair activa o desactiva la reparación en lecturas y TotalRepairs cuenta las reparaciones.

En esta página