CL.COMMON 1.3.0

Acerca de CL.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

Cambios (Changes)

• Ahora la versión mínima de framework es 4.6.2

Rutinas de Core

GetConfigKeyValue( System.Reflection.MethodBase, System.String):System.Data.String

Descripcion

Usado para acceder a configuraciones del web.config.

Parametros

• _invoker(Requerido): Usado para determinar que función ha llamado este método
• _configKey(Requerido): Nombre de la llave en el config

Ejemplo:

public static void MyFunction()
{
    System.String valor = CL.COMMON.Core.GetConfigKeyValue(System.Reflection.MethodBase.GetCurrentMethod(), "webConfigKey");
}

---

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.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.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.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.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.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.COMMON.Core.ParametersBuilder<MyClass, ICLInclude>(System.Reflection.MethodBase.GetCurrentMethod().Name, _object, _toIgnore)

    }
}

---

ContextBroker:System.Net.Http.HttpResponseMessage

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.STRUCTURES.CLASES.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.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 HttpResponseMessage MyEndpoint()
{
    try
    {
        CL.STRUCTURES.CLASSES.Rebound.CLContext<MyType> response = new CL.STRUCTURES.CLASSES.Rebound.CLContext<MyType>
        {
            Code = HttpStatusCode.OK,
            Response = new CL.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.STRUCTURES.CLASSES.Email.EmailCredential, CL.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.COMMON.Core.SendEmail(
    new CL.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.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" },
        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.STRUCTURES.CLASSES.Email.EmailFile>()
        {
            new CL.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; }
} 


public class MyController : ApiController
{
    // En el controlador decoramos nuestro endpoint con el QueryStringExposer  
    [QueryStringExposer]  
    public async Task<HttpResponseMessage> Get(string ItemCode)  
    {  
        try  
        {  
            CLContext<Item> clContext = Process.GetItem();
            //your response
        }  
        catch (Exception ex)  
        {  
            return Core.ContextBroker(ex);  
        }  
        finally  
        { 
            LogManager.Commit(Request);  
        }
    }


    public static CL.STRUCTURES.CLASSES.PresentationEntities.ClUserContext GetContext(string _resource)
    {
        //your code
    }
}

public class Process
{
    public static CL.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.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.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}");
    }
}

---

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.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.STRUCTURES.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.COMMON.LogManger.Record("Este es un log de la sobrecarga 1");
    CL.COMMON.LogManger.Record("Este es un log de la sobrecarga 2", CL.STRUCTURES.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. Commit(System.Net.Http.HttpRequestMessage _httpRequestMessage, System.String _user = null)
2. Commit<T>(System.Net.Http.HttpRequestMessage _httpRequestMessage, T _oT = default, System.String _user = null)
3. Commit(System.String _fileName = "UNDEFINED", System.String _user = null)
4. Commit(System.String _user = null)
5. Commit()

Parametros

• Primera y segunda sobrecarga _httpRequestMessage(Requerido): Contexto actual de la petición.
• Primera, segunda, tercera y cuarta sobrecarga _user(Opcional): Usuario al que se le asignaran los logs.
• Segunda sobrecarga _oT(Opcional): Objeto que será serializado
• Tercera sobrecarga _fileName(Opcional): Nombre del archivo en el que se guardará el log

Ejemplo:

public HttpResponseMessage MyEndpoint(MyModel _object)
{
    try
    {
        //your code
    }
    catch
    {
        //your exception handler
    }
    finally
    {
        CL.COMMON.LogManager.Commit(Request);
        CL.COMMON.LogManager.Commit(Request, 'user@clavisco.com');
        CL.COMMON.LogManager.Commit(Request, _object);
        CL.COMMON.LogManager.Commit(Request, _object, 'user@clavisco.com');
        CL.COMMON.LogManager.Commit('MYENDPOINT', null);
        CL.COMMON.LogManager.Commit('MYENDPOINT', 'user@clavisco.com');
        CL.COMMON.LogManager.Commit('user@clavisco.com');
    }
}

---

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.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.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.COMMON.LogManger.Record puede ser llamando en la capa que ocupemos para poder registrar nuestros eventos.

public HttpResponseMessage MyEndpoint(MyModel document)
{
    try 
    {  
	    CL.COMMON.LogManager.Record("Controlador iniciado");  
	    CLContext<Document> oCLContext = PROCESS.Process.CreateDocument(document);  
	    CL.COMMON.LogManager.Record("Controlador terminado");  
	    return CL.COMMON.Core.ContextBroker(oCLContext);    
    }  
    catch(System.Exception exception) 
    {  
	    return CL.COMMON.Core.ContextBroker(ex);  
    } 
    finally 
    {  
	    CL.COMMON.LogManager.Commit(Request, 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.
• FilePrefix: 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.STRUCTURES.CLASSES.LogManager.ClLogManagerOption

Descripcion

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

Sobrecargas

1. Ctor(this CL.STRUCTURES.CLASSES.LogManager.ClLogManagerOption _logManagerOption)
2. Ctor(this System.Collections.Generic.IEnumerable<CL.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.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.STRUCTURES.CLASSES.LogManager.ClLogManagerOption ):CL.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.STRUCTURES.CLASSES.LogManager.ClLogManagerOption ):CL.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();
}

---

Resumen de versión

Correcciones (Fixes)

• Avisar sobre que se eliminara la LogManager option "FileName"
• Se utiliza "FilePrefix" en lugar de "FileName"

---

Solución de problemas (Troubleshooting)

Ninguna

Clavis Consultores ©