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
Dinaupinstalado. 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");| Constructor | Detalle |
|---|---|
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étodo | Qué 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_GetEnumerator | Archivos 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 OkSaludAsync 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étodo | Qué 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.