DS.Foundation 8.4.1

DS.Foundation

Núcleo de las librerías DS.Foundation: clases de opciones compartidas (SystemOptions, ApplicationOptions, integración de datos), registro de servicios por escaneo de ensamblados, mensajes de usuario y eventos de aplicación, una base para procesos de integración de datos (extracción, transformación y carga) y utilidades (colas, rangos de fechas, conversión de textos, recursos embebidos, ejecución de comandos).

Úselo como dependencia común de las aplicaciones y de los demás paquetes DS.Foundation.*. Los paquetes de dominio (Data, WebApi, Authentication, etc.) lo referencian.

• Target framework: netstandard2.0.
• Dependencias: Microsoft.Extensions.Configuration, Microsoft.Extensions.Logging.Abstractions y Microsoft.Extensions.Options.

Instalación

<PackageReference Include="DS.Foundation" Version="8.4.1" />

Registro

AddFoundationServices y AddApplicationServices recorren los ensamblados de los objetos IServiceRepository recibidos y registran como scoped cada clase que implementa IFoundationService o IApplicationService, respectivamente. Cada clase se registra por su tipo concreto, no por sus interfaces.

using DS.Foundation.Services;
using DS.Foundation.Services.Extensions;

builder.Services.AddFoundationServices(new IServiceRepository[]
{
    new DS.Foundation.Services.ServiceRepository(),                 // DsCryptographyService, SystemDateTimeProviderService
    new DS.Foundation.Authentication.Services.ServiceRepository(),  // si usa DS.Foundation.Authentication
});

// Servicios propios: cualquier clase de su ensamblado que implemente IApplicationService.
builder.Services.AddApplicationServices(new IServiceRepository[] { new MiApp.ServiceRepository() });

Para que su ensamblado sea escaneado, declare una clase vacía que implemente IServiceRepository:

namespace MiApp
{
    public class ServiceRepository : DS.Foundation.Services.IServiceRepository { }
}

Las clases de opciones (SystemOptions, ApplicationOptions, etc.) no se registran solas: la aplicación las enlaza con el patrón Options.

builder.Services.Configure<SystemOptions>(builder.Configuration.GetSection("System"));

// Obligatorio si la aplicación resuelve DsCryptographyService (ver Configuración).
builder.Services.Configure<CryptographyOptions>(builder.Configuration.GetSection(CryptographyOptions.SectionName));

Configuración

SystemOptions

ApplicationOptions

DataStoreOptions (integración de datos)

DataLaneOptions → DataTaskOptions → DataStepOptions describen la jerarquía carril → tarea → paso. Cada nivel tiene Code, Name, Type, Order y Enabled. Cada paso tiene Source y Destination (DataStoreOptions).

SystemDateTimeProviderService

Lee la clave System:Date de IConfiguration en el constructor.

GetNow() devuelve hora local del servidor (DateTime.Kind = Local), no UTC.

DsCryptographyService

Cifra y descifra textos con AES (Rijndael, clave de 256 bits) y calcula hashes SHA1. Recibe IOptions<CryptographyOptions> y no lee IConfiguration.

La aplicación que usa DS.Foundation debe cargar CryptographyOptions. No hay valores por defecto: si falta Key o InitializationVector, o alguno es inválido, el constructor lanza InvalidOperationException (el mensaje indica la propiedad) y el servicio no se puede resolver, ni siquiera para CreateHash.

Desde una sección de configuración (CryptographyOptions.SectionName es "System:Cryptography"; puede usar otra):

using DS.Foundation.Configuration.Options;

builder.Services.Configure<CryptographyOptions>(
    builder.Configuration.GetSection(CryptographyOptions.SectionName));

O con valores que la aplicación obtiene de otra fuente (por ejemplo, un almacén de secretos):

builder.Services.Configure<CryptographyOptions>(o =>
{
    o.Key = secretos.ObtenerClave();
    o.InitializationVector = secretos.ObtenerIV();
});

Cargue los valores desde variables de entorno (System__Cryptography__Key, System__Cryptography__InitializationVector) o un almacén de secretos, nunca desde un appsettings.json versionado. Para generarlos: Bytes.ByteArrayToHex(Bytes.GenerateKey()) y Bytes.ByteArrayToHex(Bytes.GenerateIV()) (DS.Foundation.Security.Cryptography.Effortless). Si cambia la clave, lo que se cifró con la anterior ya no se puede descifrar con el servicio.

Migración desde versiones anteriores a 8.4.0: esas versiones cifraban siempre con la clave y el IV por defecto que traía CryptographyOptions en DS.Foundation 8.3.2, y que ya no existen. Para seguir descifrando esos datos, cargue temporalmente esos valores (están en CryptographyOptions.cs de la versión 8.3.2). Son públicos, así que descifre los datos existentes y vuelva a cifrarlos con una clave propia.

Uso

Mensajes de usuario y eventos de aplicación

using DS.Foundation.Security;
using DS.Foundation.UserMessage;

public class MensajeDeUsuario : IUserMessage
{
    public string Code { get; set; } = "";
    public string Caption { get; set; } = "";
    public string Text { get; set; } = "";
    public string Type { get; set; } = "";
}

public class MensajesDeVentas : UserMessageSourceBase
{
    public MensajesDeVentas()
    {
        Add(new MensajeDeUsuario { Code = "VTA-001", Caption = "Ventas", Text = "El cliente no existe.", Type = "ERROR" });
    }
}

var repositorio = new UserMessageRepository();
repositorio.AddSource(new MensajesDeVentas());

var eventos = new AppEventFactory(repositorio);
AppEvent evento = eventos.Create("usuario", "VTA-001");

AppEvent puede completar un contrato de respuesta con FillWithAppEvent (paquete DS.Foundation.WebApi).

Integración de datos

DataLaneService, DataTaskService y DataStepService son clases base abstractas.

• Setup guarda el contexto y, si DataLaneContext.WorkingDirectory está vacío, crea un directorio temporal nuevo y lo asigna.
• DataTaskService.Execute() llama a Extract(), Transform() y Load() en ese orden. Cada uno toma de options.Steps el único paso con Type "E", "T" o "L" y lo ejecuta con el DataStepService correspondiente.
• La clase derivada debe asignar los campos protegidos extractor, transformer y loader antes de Execute().

Utilidades

var cola = new SmartQueue<int>(Enumerable.Range(1, 1000));
IList<int> lote = cola.Dequeue(100);            // hasta 100 elementos

using (var cmd = new RunCmd("git", "status"))
{
    int exitCode = cmd.Execute();   // espera a que termine; -1 si no pudo iniciarse
    string salida = cmd.GetOutput(); // salida estándar; la de errores se descarta
}

DateTimeRange hoy = DateTimeRange.GetTodayDateTimeRange();
DateTimeRange semana = DateTimeRange.GetThisWeekDateTimeRange(); // lunes 00:00:00 a domingo 23:59:59
string base64 = StringCodeConverter.ToBase64("texto");

// Seguro entre hilos; guarda hasta n - 1 elementos y Poner devuelve false si está lleno.
var buffer = new BufferProductorConsumidor<string>(n: 100, k: 10);
buffer.Poner("evento");
string[] loteDeDiez = buffer.Sacar();   // 10 elementos, o vacío si todavía hay menos de 10
string[] resto = buffer.SacarTodos();

Cifrado TripleDES con Cryptography

byte[] key = ...; // 16 o 24 bytes, desde configuración o un almacén de secretos
byte[] iv = ...;  // 8 bytes
string cifrado = Cryptography.Encrypt256("texto", key, iv);
string texto = Cryptography.Decrypt256(cifrado, key, iv);

Encrypt256 y Decrypt256 usan TripleDES (bloques de 64 bits, CBC, PKCS7); el "256" del nombre se conserva por compatibilidad. Lanzan ArgumentException si la clave no tiene 16 o 24 bytes o el IV no tiene 8, y CryptographicException si la clave es débil o, al descifrar, no coincide.

Errores frecuentes

Qué no hacer

• No cargar en CryptographyOptions la clave y el IV de versiones anteriores a 8.4.0 salvo para migrar datos antiguos: son públicos. DsCryptographyService.CreateHash usa SHA1, y los helpers MD5 de Cryptography tampoco sirven para contraseñas.
• No escribir en el código la clave ni el IV de Cryptography.Encrypt256/Decrypt256.
• No confiar en AddMapsterTypeAdapters: no realiza ningún registro (se conserva por compatibilidad).
• Los métodos de DateTimeRange usan DateTime.Now (hora local del servidor).
• No guardar en SystemOptions ni en DataSecurityOptions secretos en appsettings.json versionado: use variables de entorno o un almacén de secretos.

Cambios

Ver CHANGELOG.md.