SmartCoreHub.Core.SDK 20260717.454.0

SmartCoreHub.Core.SDK

Biblioteca NuGet central do SmartCoreHub: primitivas de domínio, Result/Guard, contratos de cache/NoSql/cloud, helpers e — nos TFMs modernos — implementações reutilizáveis de repositórios genéricos (EF Core / Dapper), providers de cache (Redis, Mongo, Cosmos, Disk), adapters Azure e banda ASP.NET (middleware, CORS, documentação OpenAPI, performance, JWT claims-based, BaseApiController).

Use este pacote quando precisar da mesma fonte de contratos e implementações genéricas entre APIs, hosts .NET e SDKs que optarem por referenciar o Core.

Hosts SmartCoreHub: SmartCoreHub.Service não contém mais wrappers de Cors / Swagger / OpenApi / Scalar / Redoc / RapiDoc / ApiPerformance. O host chama as extensions deste pacote (SmartCoreHub.Core.SDK.Service.API.DI) e só mantém branding em SmartCoreHubDocumentationOptions + composição de pipeline.

Localization.SDK: pacote público auto-isolado — não depende deste Core no NuGet. Tipos HTTP/cache leves usados pelo Localization são cópia owned. Ver Isolamento-Core.md.

Extração Service → Core: Service-Extracao.md.

Instalação

dotnet add package SmartCoreHub.Core.SDK

<PackageReference Include="SmartCoreHub.Core.SDK" Version="*" />

Frameworks suportados

Dependências pesadas (Dapper, EF Core, StackExchange.Redis, MongoDB.Driver, Azure SDKs, Swashbuckle, Scalar, ReDoc, RapiDoc, etc.) entram no grafo NuGet somente quando o projeto consumidor tem como alvo net8.0 ou net10.0.

Light vs heavy

• Light: todos os TFMs — Domain (interfaces/DTOs/entidades base), Others (Result, Guard, exceptions, HTTP leve), cache Memory/Disk, abstrações NoSql, password hashers, helpers de Service sem ASP.NET.
• Heavy (net8/net10): repositórios Dapper/EF, factories/adapters Azure, Redis/Mongo/Cosmos, Serilog adapter, AutoMapper adapter, sanitização HTML, banda ASP.NET completa.

CacheFactory (namespace Service) cria apenas o provider Memory. Em produção, registre Redis/Disk/Mongo/Cosmos pelos tipos deste pacote (ou via AddSdkCaching()).

Mapa de namespaces

Layout em disco: pastas Domain/, Infrastructure/, Service/ e Others/ (tipos nativos do SDK; ver Others/README.md).

Quick start — host ASP.NET (net8/net10)

Exemplo mínimo de host genérico (sem branding SmartCoreHub). No monólito, o Service passa SmartCoreHubDocumentationOptions.Create() / CreateCors().

using SmartCoreHub.Core.SDK.Service.API.DI;
using SmartCoreHub.Core.SDK.Service.API.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.AddApiPerformance(); // Kestrel, thread pool, JSON, compression, rate limit

var docs = new OpenApiDocumentationOptions
{
    Title = "My API",
    Description = "API reutilizando SmartCoreHub.Core.SDK",
    ContactName = "Team",
    ContactEmail = "support@example.com"
};

builder.Services.AddCustomSwagger(docs);
builder.Services.AddCustomOpenApi(docs); // efeito real em net10+
builder.Services.AddCustomCors(
    builder.Configuration,
    builder.Environment,
    new CorsHostingOptions { PrivatePolicyName = "AllowMyFrontend" });

var app = builder.Build();

app.UseMiddleware<CorrelationIdMiddleware>();
app.UseMiddleware<SecurityHeadersMiddleware>();
app.UseApiPerformance();
CorsExtensions.SetupCors(app, new CorsHostingOptions { PrivatePolicyName = "AllowMyFrontend" });
app.MapCustomOpenApi(docs);
app.MapCustomScalar(docs);
app.MapCustomRedoc(docs);
app.MapCustomRapiDoc(docs);

app.Run();

Branding no monólito SmartCoreHub

using SmartCoreHub.Core.SDK.Service.API.DI;
using SmartCoreHub.Service.API.DI; // SmartCoreHubDocumentationOptions

var docs = SmartCoreHubDocumentationOptions.Create();
var cors = SmartCoreHubDocumentationOptions.CreateCors();

builder.Services.AddCustomSwagger(docs);
builder.Services.AddCustomOpenApi(docs);
builder.Services.AddCustomCors(builder.Configuration, builder.Environment, cors);

// no pipeline:
CorsExtensions.SetupCors(app, cors);
app.MapCustomOpenApi(docs);
app.MapCustomScalar(docs);
app.MapCustomRedoc(docs);
app.MapCustomRapiDoc(docs);

Catálogo reutilizável (detalhado)

Cada tipo público listado abaixo pode ser reutilizado por consumidores do pacote. Tipos em pastas Internal não devem ser dependência estável.

Service.API.DI — documentação, CORS e performance (net8/net10)

Options

Extensions e métodos

Rotas padrão resultantes (com options default ou branding SmartCoreHub):

Service.API.Middleware (net8/net10)

Ordem recomendada no pipeline:

app.UseMiddleware<CorrelationIdMiddleware>();
app.UseMiddleware<RequestLoggingMiddleware>();
app.UseMiddleware<SecurityHeadersMiddleware>();
app.UseMiddleware<RequestSizeLimitMiddleware>();
app.UseMiddleware<LocalizationHeaderCultureMiddleware>();

Service.API.Generic / Authentication / Helpers (net8/net10)

Service.Security — JWT claims-based (net8/net10)

services.AddScoped<IJwtAccessTokenService, JwtAccessTokenService>();

var claims = JwtAccessTokenService.BuildStandardAccessClaims(userId, name, email);
var access = jwt.GenerateAccessToken(claims);
var refresh = jwt.GenerateRefreshToken();

No monólito, JwtTokenService do Service continua como adapter de domínio (User → claims) sobre este serviço.

Service.Common / Configuration / Validation (mistos)

Infrastructure.Data.DependencyInjection (net8/net10)

services.AddConfiguredDbContext<MyDbContext>(options =>
    options.UseMySql(connectionString, serverVersion));

Others — Result, validação e exceptions

Others — repositório Guid e cache leve

Others — HTTP / headers

Domain — entidades e value objects

Domain — enums e DTOs

Domain — contratos comuns / data / Dapper

Domain — cloud, segurança e auditoria

Infrastructure — cache light (todos os TFMs)

CacheProviderHelper é internal e não faz parte da API pública estável.

Infrastructure — cache heavy (net8/net10)

Infrastructure — repositórios e dados

Infrastructure — NoSql

Infrastructure — Azure (net8/net10)

Infrastructure — security / logging

Exemplos adicionais

Result e Guard

using SmartCoreHub.Core.SDK.Others.Common;
using SmartCoreHub.Core.SDK.Others.Validation;

public Result<string> Normalize(string input)
{
    Guard.AgainstEmptyString(input, nameof(input));
    return Result.Success(input.Trim());
}

Cache Memory

using SmartCoreHub.Core.SDK.Infrastructure.Caching.Providers;
using Microsoft.Extensions.Caching.Memory;

services.AddMemoryCache();
services.AddSingleton<ICacheProvider, MemoryCacheProvider>();

Repositório Dapper ou EF (net8/net10)

using SmartCoreHub.Core.SDK.Dapper.Generic;
using SmartCoreHub.Core.SDK.EntityFrameworkCore.Repositories;
using SmartCoreHub.Core.SDK.Infrastructure.Repositories.Generic;

// EF
services.AddScoped(typeof(IGenericRepository<>), typeof(GenericRepository<>));

// Dapper open-generic
services.AddScoped(typeof(DapperAdpterGenericRepository<>));

Entidades usam LongEntityBase (long Id). Construtor Dapper: ISmartCoreHubDataBaseConnectionFactory, IAppLogger, string? tableName.

Azure Blob factory (net8/net10)

using SmartCoreHub.Core.SDK.Cloud.Azure;
using SmartCoreHub.Core.SDK.Domain.Interfaces.Cloud;

services.AddScoped<IBlobStorageAdapterFactory, BlobStorageAdapterFactory>();

O que permanece no host (não está neste pacote)

Constraints e breaking changes

• Generics EF/Dapper exigem where TEntity : LongEntityBase.
• Nomes históricos mantidos: DapperAdpterGenericRepository, CloudRessource.
• Cascas Obsolete em Domain/Infrastructure foram removidas. Use tipos deste pacote no monólito/host.
• Wrappers Service de documentação/CORS/performance foram removidos — chame SmartCoreHub.Core.SDK.Service.API.DI.* diretamente.
• SmartCoreHub.Localization.SDK é auto-isolado: não depende deste NuGet; contratos HTTP/cache leves do Localization são cópia owned.
• Um único PackageId=SmartCoreHub.Core.SDK — não existem pacotes companheiros .Dapper / .Caching.* / .Cloud.Azure.
• Tipos em namespaces/Internal (ex.: SqlIdentifierRegexHelper, DTOs de guarda) podem ser public por necessidade técnica — trate-os como API instável.
• AddCustomOpenApi / documento nativo /openapi/v1.json exigem net10; em net8 use Swagger JSON.

Documentação relacionada

• Service → Core — extração ASP.NET
• Extração de pendências
• Remoção de shims
• Isolamento Localization.SDK
• UIs de documentação das APIs
• Others/README.md — tipos nativos vs copiados

Desenvolvimento local (repositório)

cd backend
dotnet build Core\SmartCoreHub.Core.SDK\SmartCoreHub.Core.SDK.csproj -c Release
dotnet test Core\SmartCoreHub.Core.SDK.Tests\SmartCoreHub.Core.SDK.Tests.csproj -c Release
dotnet pack Core\SmartCoreHub.Core.SDK\SmartCoreHub.Core.SDK.csproj -c Release

Licença

Consulte o arquivo LICENSE incluído no pacote NuGet.