Cl.Core.Common 1.5.0-alpha

Acerca de Cl.Core.Common

Ofrece una serie de funciones a modo de utilería las cuales nos permiten realizar flujos que son habituales en todos los proyectos, como mapeo de genéricos, logs entre otros.

¿Qué resuelve?

La creación repetitiva de código de uso común a través de los distintos proyectos de los clientes y que a su vez en cada implementación presentan la posibilidad de no replicar el código con exactitud generando errores.

Resumen de versión

Características (Features)

• Ahora se puede trabajar con Azure Storage Blobs Rutinas, consulte en la documentación para saber sobre como implementarlas
• Ahora se puede agregar una lista de correos para copias al carbon ocultas en la funcion SendEmail

Rutinas de Core

FileToBase64( System.String ): System.String

Descripcion

Usado para convertir un archivo en base64

Parametros

• _filePath(Requerido): Ruta física del archivo

Ejemplo:

public static void MyFunction()
{
 System.String base64pdf = Cl.Core.Common.Core.FileToBase64("C:\mipdf.pdf");
}

---

GetExceptionMessage( System.Exception ): System.String

Descripcion

Obiene el detalle de la excepción y la retorna en un System.String.

Parametros

• _exception(Requerido): Objeto con la excepción a mapear

Ejemplo:

public static void MyFunction()
{
    try
    {
        //Your code
    }
    catch(Exception ex)
    {
        System.String message = Cl.Core.Common.Core.GetExceptionMessage(ex)
    }
}

---

InflateObject( System.Data.DataTable ): T

Descripcion

Los registros de un query cargados en System.Data.DataTable serán cargados en el objeto de tipo T.

Parametros

• _dt(Requerido): Origen de datos que van a ser cargados en T

Ejemplo:

public class MyClass
{
    public string Name { get; set; }
}

public class Process
{
    public static void MyFunction()
    {
        //Your code where you execute the query and get a DataTable

        MyClass oT = Cl.Core.Common.Core.InflateObject<MyClass>(oDataTable);
    }
}

---

InflateList( System.Data.DataTable ) :System.Collections.Generic.List<T>

Descripcion

Los registros de un query serán mapeados a una lista de tipo T.

Parametros

• _dt(Requerido): Origen de datos que van a ser cargados en T.

Ejemplo:

public class MyClass
{
    public string Name { get; set; }
}

public class Process
{
    public static void MyFunction()
    {
        //Your code where you execute the query and get a DataTable

        System.Collections.Generic.List<MyClass> tList = Cl.Core.Common.Core.InflateList<MyClass>(oDataTable);
    }
}

---

ParametersBuilder( System.String, T, System.String[] ):System.Collections.Generic.List<System.Data.Odbc.OdbcParameter>

Descripcion

Convierte las propieades de un objeto a una lista de string.

Parametros

• _invoker(Requerido): Usado para determinar desde donde se ha realizado la llamada a la funcion.
• _object(Requerido): Objeto del cual se van a mapear las propieadas a una lista.
• _toIgnore(Opcional): Lista de propiedades a incluir/excluir según el tipo de inteface que indiquemos.

Ejemplo

public class MyClass
{
    public string Name { get; set; }
    public string Name2 { get; set; }
}

public class Process
{
    public static void MyFunction()
    {
        MyClass _object = new MyClass()
        {
            Name = 'Clavis',
            Name2 = 'Consultores'
        };

        string[] _toIgnore = ['Name2'];
        
        // This example exclude the property 'Name2', so, the paremeters only will be '@Name' with the value 'Clavis'
        System.Collections.Generic.List<System.Data.Odbc.OdbcParameter> paramerters = Cl.Core.Common.Core.ParametersBuilder<MyClass, ICLExclude>(System.Reflection.MethodBase.GetCurrentMethod().Name, _object, _toIgnore)
    
        // This example include the property 'Name2', so, the paremeter only will be '@Name2' with the value 'Consultores' 
        System.Collections.Generic.List<System.Data.Odbc.OdbcParameter> paramerters2 = Cl.Core.Common.Core.ParametersBuilder<MyClass, ICLInclude>(System.Reflection.MethodBase.GetCurrentMethod().Name, _object, _toIgnore)

    }
}

---

ContextBroker:Microsoft.AspNetCore.Mvc.IActionResult

Descripcion

Mediador entre el contexto de la aplicación y el contexto de la respuesta para poder retornar el código http correcto. Es recomendado mandar las excepciones con Cl.Core.Structures.Classes.CLException, para que el código de la respuesta se mapee de manera automática.

Sobrecargas

1. ContextBroker(System.Exception _target)
2. ContextBroker(System.Exception _target, System.Net.HttpStatusCode _code)
3. ContextBroker<T>(Cl.Core.Structures.Classes.Rebound.CLContext<T> _target)

Parametros

• Primera y segunda sobrecarga _target(Requerido): Excepción que será mapeada
• Segunda sobrecarga _code: Código de la excepción.
• Tercera sobrecarga _target(Requerido): Respuesta que será mapeada

Ejemplo:

public Microsoft.AspNetCore.Mvc.IActionResult MyEndpoint()
{
    try
    {
        Cl.Core.Structures.Classes.Rebound.CLContext<MyType> response = new Cl.Core.Structures.Classes.Rebound.CLContext<MyType>
        {
            Code = HttpStatusCode.OK,
            Response = new Cl.Core.Structures.Classes.Rebound.Response<MyType>()
            {
                Data = [1,2,3],
                Message = "Successfully obtained numbers"
            }
        };

        return ContextBroker(response);
    }
    catch(Exception ex)
    {
        // We can use this
        return ContextBroker(ex);
        // Or this
        return ContextBroker(ex, HttpStatusCode.BadRequest);
    }
}

---

SendEmail( Cl.Core.Structures.Classes.Email.EmailCredential, Cl.Core.Structures.Classes.Email.EmailDetails ): void

Descripcion

Permite realizar envio de correo de manera genérica, soporta copias y ajuntos.

Parametros

• _emailCredential(Requerido): Credenciales y configuración para envio de correos
• _emailDetails(Requerido): Detalles del correo a enviar, receptor, copias y adjuntos

Ejemplo:

Cl.Core.Common.Core.SendEmail(
    new Cl.Core.Structures.Classes.Email.EmailCredential()
    {
        Subject = "Recuperación de contraseña", // Se usa este asunto si no se especifica en los detalles
        Account = "exampleinfo@clavisco.com",
        Host = "outlook.office365.com",
        Password = "Contraseña para envio de correos",
        Port = 587,
        Ssl = true
    }, 
    new Cl.Core.Structures.Classes.Email.EmailDetails()
    {
        EmailsTo = new System.Collections.Generic.List<System.String>(){ "example@clavisco.com" },
        EmailsCC = new System.Collections.Generic.List<System.String>(){ "ccexample@clavisco.com" },
        EmailsBCC = new System.Collections.Generic.List<System.String>(){ "bccexample@clavisco.com" },
        Subject = "Asunto de ejemplo",
        Body = $"<p>Puede incluir html y enlaces como el siguiente <a href='example.clavisco.com/click-here'>[click aquí]</a></p>",
        EmailFiles = new System.Collections.Generic.List<Cl.Core.Structures.Classes.Email.EmailFile>()
        {
            new Cl.Core.Structures.Classes.Email.EmailFile()
            {
                Base64 = "Aqui va el string en base64 del archivo adjuntado",
                Extention = ".pdf",
                FileName = "Ejemplo",
                FileType = "application/pdf"
            }
        },
    };
); 

---

QueryStringExposer:void

Descripcion

Esta anotación debe ponerse en el controlador que recibe una serie de parámetros para ser mapeados a un modelo cuando usemos un Get hacia Service Layer. Lo que QueryStringExposer hace es leer los parámetros de la url y mapearlos a un modelo cuando hacemos uso del método de extensión Get<TObject>

Ejemplo:

public class MyItemModel
{
    public string ItemCode { get; set; }
} 

[ApiController]
public class MyController
{

    public GroupsController(Process.IProcess process)
    {
       _process = process;
    }
    // En el controlador decoramos nuestro endpoint con el QueryStringExposer  
    [QueryStringExposer]  
    public IActionResult Get(string ItemCode)  
    {  
        try  
        {  
            CLContext<Item> clContext = _process.GetItem();
            //your response
        }  
        catch (Exception ex)  
        {  
            return Core.ContextBroker(ex);  
        }  
        finally  
        { 
            LogManager.Commit(Request);  
        }
    }
}

public class Process
{
    public static Cl.Core.Structures.Classes.PresentationEntities.ClUserContext GetContext(string _resource)
    {
        //your code
    }

    public static CLContext<Item> GetItem()
    {
        // Aqui ya se deberia setear automaticamente el campo "ItemCode" de "MyItemModel"
        Cl.Core.Structures.Classes.PresentationEntities.ClUserContext context = GetContext("MyResource").Get<MyItemModel>();
        // ...more code
    }
}

---

StreamToBytes( System.IO.Stream ): byte[]

Descripcion

El objetivo principal de este método es leer los datos del flujo de entrada y almacenarlos en la memoria como una matriz de bytes.

Parametros

_input(Requerido): El stream para convertir en una matriz de bytes de memoria

Ejemplo:

public static void MyMethod()
{
    // Replace "path_to_your_file" with the actual path to the file on your local machine
    string filePath = "path_to_your_file";

    try
     {
        // Open the file using FileStream
        using (FileStream fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read))
        {
            // Call the StreamToBytes method to convert the FileStream to a byte array
            byte[] byteArray = Cl.Core.Common.Core.StreamToBytes(fileStream);

            // Do something with the byte array if needed
            // For example, you could print the length of the byte array
            Console.WriteLine($"Byte array length: {byteArray.Length}");
        }
    }
    catch (Exception ex)
    {
        // Handle exceptions, for example, file not found, permission issues, etc.
        Console.WriteLine($"An error occurred: {ex.Message}");
    }
}

---

Settings Rutinas

GetSetting<T>( System.Reflection.MethodBase, System.String ): T

Descripcion

Usado para acceder a configuraciones del appsettings.json.

Parametros

• _invoker: Usado para determinar que función ha llamado este método
• _jsonKey: Nombre de la llave en el settings.json

Ejemplo:

// Incluir en el Program.cs la siguiente linea para inyectar la interface de configuraciones
builder.Services.AddScoped<ISettings, Settings>();

// Debe inyecta la interface ISettings en el contructor de la clase donde la desee utilizar, en este caso el 
System.String valor = _settings.GetSetting(System.Reflection.MethodBase.GetCurrentMethod(), "DB:SpGetNameDbObjectApp");  

---

LogManager Rutinas

Esta funcionalidad requiere de ciertas configuraciones iniciales, como por ejemplo agregar una llave en el web.config con el nombre LogPath, para poder obtener la ruta donde se van a escribir los logs. De manera opcional se puede escoger el intervalo de generación de archivos, por defecto es diario. Puede ser cambiado agregando la propiedad SeriLogRollingInterval en en el webconfig. Posibles valores(Infinite, Year, Month, Day, Hour, Minute).

Todas las sobrecargas del método Commit intentan sacar el usuario del contexto del pipe, accediendo a un Claim llamado UserEmail, el cual puede ser configurado al momento de iniciar sesión en la la aplicación. En caso de no suministrar un usuario el valor por defecto de este será 'no_user_found'.

Además permite registrar encabezados de la petición, para esto es requerido que los mismos encabezados tengan el prefijo Cl- para que sean reconocidos por log manager. Ejemplo: Para indicar el momento en el que salió una petición desde el ui, agregar un encabezado a la petición en el interceptor con el nombre Cl-Ui-Request-Time.

Glosario

Para mantener el orden y simetría en los logs se han definido una serie de abreviaciones para estos.

• USR: Usuario al que se le relaciona con los logs(miusuario@correo.com)
• PTH: Dirección física del endpoint(/api/Item/GetItemInfo)
• QRS: Query string de la dirección física del endpoint(?param1=ejemplo&param2=1234)
• VRB: Verbo http de la petición(GET, POST, ...)
• MDL: Modelo contenido en la petición que solo es visible en operaciones de escritura ({"prop1": "value"}).
• AYV: Versión del emsamblado de Log Manager.

---

Enter:void

Descripcion

Agrega un enter los logs almacenados hasta el momento.

Ejemplo:

Cl.Core.Common.LogManager.Enter();

---

Record:void

Descripcion

Agrega un mensaje al contexto actual del log al final de este.

Sobrecargas

1. Record(System.String _message)
2. Record(System.String _message, Cl.Core.Structures.Classes.TabLevel _tabLevel)

Parametros

• Primera y segunda sobrecarga _message(Requerido): Mensage que será escrito un medio externo.
• Segunda sobrecarga _tabLevel(Requerido): Indica si el mensaje recién registrado va a tener un margen izquierdo(Cantidad de tabs).

Ejemplo:

public static void MyFunction()
{
    Cl.Core.Common.LogManger.Record("Este es un log de la sobrecarga 1");
    Cl.Core.Common.LogManger.Record("Este es un log de la sobrecarga 2", Cl.Core.Structures.Classes.TabLevel.One);
}

---

Commit:void

Descripcion

Este método es exclusivo para escenarios en donde no tenemos un contexto web claro, por ejemplo en un servicio en donde solo necesitamos registrar nuestros eventos y asignarlos al servicio. Por este motivo es requerido pasar estos parámetros de forma manual.

Sobrecargas

1. CommitCommit<TObject>(TObject tObject)
2. Commit()

Parametros

• Primera sobrecarga tObject(Requerido): Objeto que será serializado

Ejemplo:

public HttpResponseMessage MyEndpoint(MyModel _object)
{
    try
    {
        //your code
    }
    catch
    {
        //your exception handler
    }
    finally
    {
        Cl.Core.Common.LogManager.Commit(_object);
        Cl.Core.Common.LogManager.Commit();
    }
}

---

FlushSettings:void

Descripcion

Este método elimina toda configuración previa generada por alguna extensión de log manager.

Ejemplo

public static void MyFunction()
{
    new List<ClLogManagerOption>() {
            new ClLogManagerOption() { Key = "LogPath", Value = Cl.Core.Common.Core.GetConfigKeyValue(System.Reflection.MethodBase.GetCurrentMethod(),"LogPath") },
            new ClLogManagerOption() { Key = "FilePrefix", Value = "AUTH"},
            new ClLogManagerOption() { Key = "User",    Value = context.UserName},
    }.Ctor().Build().Dtor();

    Cl.Core.Common.LogManager.FlushSettings();
}

---

Código completo de implementación

Este código debe ponerse en el controlador o en el llamado de un servicio para que se haga el commit al final del proceso. Y ya luego el método Cl.Core.Common.LogManger.Record puede ser llamando en la capa que ocupemos para poder registrar nuestros eventos.

public HttpResponseMessage MyEndpoint(MyModel document)
{
    try 
    {  
	    Cl.Core.Common.LogManager.Record("Controlador iniciado");  
	    CLContext<Document> oCLContext = PROCESS.Process.CreateDocument(document);  
	    Cl.Core.Common.LogManager.Record("Controlador terminado");  
	    return Cl.Core.Common.Core.ContextBroker(oCLContext);    
    }  
    catch(System.Exception exception) 
    {  
	    return Cl.Core.Common.Core.ContextBroker(ex);  
    } 
    finally 
    {  
	    Cl.Core.Common.LogManager.Commit(document);
    }
}

---

LogManager Rutinas de Extensión

Opciones disponibles para configurar log manager.

• User: Usuario por defecto que va a usar log manager para asociar logs.
• FileName: Nombre del archivo por defecto que va a contener los logs. Usualmente esto es para servicios.
• LogPath: Directorio por defecto en donde se van a guardar los logs.

Ctor:Cl.Core.Structures.Classes.LogManager.ClLogManagerOption

Descripcion

Este método permite configurar un parámetro de log manager.

Sobrecargas

1. Ctor(this Cl.Core.Structures.Classes.LogManager.ClLogManagerOption _logManagerOption)
2. Ctor(this System.Collections.Generic.IEnumerable<Cl.Core.Structures.Classes.LogManager.ClLogManagerOption> _source)

Ejemplo:

public static void MyFunction()
{
    (new ClLogManagerOption() { Key = "FilePrefix", Value = "AUTH"}).Ctor();

    new List<ClLogManagerOption>() {
            new ClLogManagerOption() { Key = "LogPath", Value = Cl.Core.Common.Core.GetConfigKeyValue(System.Reflection.MethodBase.GetCurrentMethod(),"LogPath") },
            new ClLogManagerOption() { Key = "FilePrefix", Value = "AUTH"},
            new ClLogManagerOption() { Key = "User",    Value = context.UserName},
    }.Ctor();
}

---

Build( this Cl.Core.Structures.Classes.LogManager.ClLogManagerOption ):Cl.Core.Structures.Classes.LogManager.ClLogManagerOption

Descripcion

Guarda las configuraciones realizadas con Ctor.

Ejemplo:

public static void MyFunction()
{
    (new ClLogManagerOption() { Key = "FilePrefix", Value = "AUTH"}).Ctor().Build();
}

---

Dtor( this Cl.Core.Structures.Classes.LogManager.ClLogManagerOption ):Cl.Core.Structures.Classes.LogManager.ClLogManagerOption

Descripcion

Limpia todas las configuraciones guardas en memoria

Ejemplo:

public static void MyFunction()
{
    (new ClLogManagerOption() { Key = "FilePrefix", Value = "AUTH"}).Ctor().Build().Dtor();
}

---

Azure Storage Blobs Rutinas

---

Descripcion

Es una clase que permite realizar operaciones en Azure Storage blob como:

• Subir un archivo o una lista de archivos
• Descargar un archivo o una lista como stream o en Base64
• Eliminar un archivo o una lista de archivos

Parametros

• CL.STRUCTURES.CLASSES.Azure.AzureCredentials _credentials(requerido): Credenciales de azure
• System.Boolean _overwriteFiles(opcional): Define si en el container al subir los archivos estos se pueden sobreescribir

Ejemplo

Es recomendable hacer una setting en la tabla de settings definido por la clase AzureCredentials que esta en el Cl.STRUCTURES. Una vez obtenidas las credenciales se crea una nueva instancia de la clase AzureStorage que recibe como parametro las credenciales.

 List<CL.STRUCTURES.CLASSES.Azure.AzureCredentials> azureSetting = GetSettingByCode<List<CL.STRUCTURES.CLASSES.Azure.AzureCredentials>>("AzureCredentials").Response.Data;
 
 CL.STRUCTURES.CLASSES.Azure.AzureCredentials azureCredentials = azureSetting.FirstOrDefault();

 CL.COMMON.AzureStorage storage = new CL.COMMON.AzureStorage(azureCredentials);

UploadFile: System.String

Descripcion

Permite subir un archivo al container de azure. Al subir al archivo se retorna la url de la ubicación.

Parametros

• CL.STRUCTURES.CLASSES.Azure.AzureFile _azureFile(requerido): Objeto que contiene la información necesaria para subir el archivo

Ejemplo

   System.String url =  await storage.UploadFile(new CL.STRUCTURES.CLASSES.Azure.AzureFile()
    {
        Stream = new MemoryStream(Convert.FromBase64String(base64file)),
        StoragePath = "test",
        Name = "image1.png"
   });

UploadFiles: System.Collections.Generic.List<System.String>;

Descripcion

Permite subir una lista de archivos al container de azure. Se retorna la lista de urls de los archivos subidos en el orden que se envió en la lista.

Parametros

• System.Collections.Generic.List<CL.STRUCTURES.CLASSES.Azure.AzureFile> _azureFiles(requerido): Lista de objetos de tipo AzureFile que contiene la información necesaria para subir una lista de archivos archivo

Ejemplo

   System.Collections.Generic.List<CL.STRUCTURES.CLASSES.Azure.AzureFile> azureFilesList = new System.Collections.Generic.List<CL.STRUCTURES.CLASSES.Azure.AzureFile>();

   System.Collections.Generic.List<System.String> urls =  await storage.UploadFiles(azureFilesList);

DownLoadFileAsBase64: System.String

Descripcion

Permite descargar un archivo como Base64. Se retorna el string base64 del archivo

Parametros

• System.String _url(requerido): URL del archivo que se desea descargar de Azure.

Ejemplo:

  System.String base64 =  storage.DownLoadFileAsBase64(filepath);

DownLoadFileAsStream: System.IO.MemoryStream

Descripcion

Permite descargar un archivo como MemoryStream

Parametros

• System.String _url(requerido): URL del archivo que se desea descargar de Azure.

Ejemplo:

  System.IO.MemoryStreamstream = await storage.DownLoadFileAsStream(filepath);

DownloadFilesAsBase64 : System.Collections.Generic.List<System.String>

Descripcion

Permite descargar una lista de archivos como Base64

Parametros

System.Collections.Generic.List<System.String> _urls(requerido): URLs de los archivos que se desean descargar de Azure.

Ejemplo:

  System.Collections.Generic.List<System.String> filePathList = new System.Collections.Generic.List<System.String>();

  System.Collections.Generic.List<System.String> base64List =  await storage.DownloadFilesAsBase64(filePathList);

DownloadFilesAsStream: System.Collections.Generic.List<System.IO.MemoryStream>

Descripcion

Permite descargar una lista de archivos como stream

Parametros

System.Collections.Generic.List<System.String> _urls(requerido): URLs de los archivos que se desean descargar de Azure.

Ejemplo:

  System.Collections.Generic.List<System.String> filePathList = new System.Collections.Generic.List<System.String>();

  System.Collections.Generic.List<System.IO.MemoryStream> memoryStreamList =  await storage.DownloadFilesAsStream(filePathList);

DeleteFile: System.Boolean

Descripcion

Función para eliminar un archivo en azure. Retorna true o false en caso de que el archivo haya sido eliminado o no con éxito

Parametros

System.String _url(requerido): URL del archivo que se desea eliminar

Ejemplo:

  System.Boolean isSuccess =  await storage.DeleteFile(filePath);

DeleteFiles: System.Boolean

Descripcion

Función para eliminar un archivo en azure. Retorna true o false en caso de que todos los archivos hayan sido eliminados o no con éxito

Parametros

System.Collections.Generic.List<System.String> _urls(requerido): URLs de los archivos que se desean eliminar de Azure.

Ejemplo:

   System.Collections.Generic.List<System.String> filePathList = new System.Collections.Generic.List<System.String>();

   System.Boolean isSuccess =  await storage.DeleteFiles(filePathList);

---

Resumen de versión

---

Solución de problemas (Troubleshooting)

Ninguna

Clavis Consultores ©