Pitasoft.Client 7.0.3

Pitasoft.Client

English | Castellano

English

Pitasoft.Client is a .NET library designed to simplify the consumption of RESTful services. It provides a robust base class and helpers to handle HTTP requests, JSON serialization, and common API patterns.

Features

• Base REST Service: RestServiceBase provides methods for GET, POST, PUT, and DELETE operations, including batch processing support.
• Modern HttpClient Management: Full support for IHttpClientFactory to ensure efficient connection management, socket pooling, and seamless integration with Dependency Injection.
• Result Handling: Integrated with Pitasoft.Result and Pitasoft.Error for consistent and expressive response handling.
• Query Helpers: Utilities to easily and safely manage query strings in URIs.
• Flexible Configuration: Multiple constructors to support custom HttpClient, IHttpClientFactory, Base URI, and JsonSerializerOptions.

Installation

Install via NuGet:

dotnet add package Pitasoft.Client

Basic Usage

1. Define your Service

Inherit from RestServiceBase to create your API client.

public class MyApiService : RestServiceBase
{
    // Recommended: Use IHttpClientFactory
    public MyApiService(IHttpClientFactory factory) 
        : base(factory, nameof(MyApiService)) { }

    public async Task<ResultEntity<MyData>> GetDataAsync(int id)
    {
        return await GetAsync<MyData>($"api/data/{id}");
    }

    public async Task<ResultEntities<MyData>> GetAllDataAsync(string filter)
    {
        // Use QueryHelpers to build the URI safely
        var uri = QueryHelpers.AddQueryString("api/data", "filter", filter);
        return await GetsAsync<MyData>(uri);
    }
}

2. Register in Dependency Injection

In your Program.cs or Startup.cs:

builder.Services.AddHttpClient(nameof(MyApiService), client => 
{
    client.BaseAddress = new Uri("https://api.example.com/");
});

builder.Services.AddScoped<MyApiService>();

3. Other Initialization Options

You can also initialize the service directly without DI (e.g., in legacy code or simple tools):

// Using a Base URI string
var service = new MyApiService("https://api.example.com/");

// Using an existing HttpClient
var client = new HttpClient { BaseAddress = new Uri("https://api.example.com/") };
var serviceFromClient = new MyApiService(client);

Castellano

Pitasoft.Client es una librería .NET diseñada para simplificar el consumo de servicios RESTful. Proporciona una clase base robusta y utilidades para manejar peticiones HTTP, serialización JSON y patrones comunes de API, siguiendo las mejores prácticas de .NET.

Características

• Servicio REST Base: RestServiceBase proporciona métodos para operaciones GET, POST, PUT y DELETE, incluyendo soporte para procesamiento por lotes (batch).
• Gestión Moderna de HttpClient: Soporte completo para IHttpClientFactory para asegurar una gestión eficiente de conexiones, pooling de sockets y una integración fluida con Inyección de Dependencias.
• Manejo de Resultados: Integrado con Pitasoft.Result y Pitasoft.Error para un manejo de respuestas consistente y expresivo.
• Helpers de Consulta: Utilidades para gestionar de forma fácil y segura cadenas de consulta (query strings) en URIs.
• Configuración Flexible: Múltiples constructores para soportar HttpClient personalizado, IHttpClientFactory, URI base y JsonSerializerOptions.

Instalación

Instalar a través de NuGet:

dotnet add package Pitasoft.Client

Uso Básico

1. Define tu Servicio

Hereda de RestServiceBase para crear tu cliente de API.

public class MyApiService : RestServiceBase
{
    // Recomendado: Usar IHttpClientFactory
    public MyApiService(IHttpClientFactory factory) 
        : base(factory, nameof(MyApiService)) { }

    public async Task<ResultEntity<MyData>> GetDataAsync(int id)
    {
        return await GetAsync<MyData>($"api/data/{id}");
    }

    public async Task<ResultEntities<MyData>> GetAllDataAsync(string filter)
    {
        // Usa QueryHelpers para construir la URI de forma segura
        var uri = QueryHelpers.AddQueryString("api/data", "filter", filter);
        return await GetsAsync<MyData>(uri);
    }
}

2. Registro en Inyección de Dependencias

En tu Program.cs o Startup.cs:

builder.Services.AddHttpClient(nameof(MyApiService), client => 
{
    client.BaseAddress = new Uri("https://api.example.com/");
});

builder.Services.AddScoped<MyApiService>();

3. Otras Opciones de Inicialización

También puedes inicializar el servicio directamente sin DI (por ejemplo, en código legado o herramientas simples):

// Usando una cadena de URI Base
var service = new MyApiService("https://api.example.com/");

// Usando un HttpClient existente
var client = new HttpClient { BaseAddress = new Uri("https://api.example.com/") };
var serviceDesdeClient = new MyApiService(client);

License

See LICENCE.txt for more details.