SmartCoreHub.Core.SDK 20260718.424.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 (serviços básicos, proxy reverso, Data Protection, Application Insights, middleware, CORS, documentação OpenAPI, performance, health/readiness, JWT claims-based e 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: as implementações genéricas de hosting vivem em SmartCoreHub.Core.SDK.Service.API.DI: ASP.NET basics, Application Insights condicional, Forwarded Headers, Data Protection, performance, middleware transversal, documentação e health/readiness. O SmartCoreHub.Service mantém somente as fachadas de composição, branding, autenticação específica do produto, DI de features e startup do banco.

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, Application Insights, 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 (Result/Guard/exceptions/helpers, entidades base, DTOs), Infrastructure (cache Memory/Disk, repositórios Guid, abstrações NoSql), Service (HTTP leve, headers, helpers 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/ e Service/ (a pasta Others/ foi eliminada; os tipos nativos passaram para essas macros).

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

Exemplo de host genérico (sem dependências do monólito). O host continua responsável por registrar seu DbContext, autenticação, autorização e controllers de feature.

using Microsoft.EntityFrameworkCore;
using SmartCoreHub.Core.SDK.Service.API.DI;

var builder = WebApplication.CreateBuilder(args);

// Serviços básicos e infraestrutura de hosting.
builder.Services.AddAspNetCoreApiBasics();
builder.Services.AddSdkCorePrimitives(includeNullAppLogger: false); // host registra Serilog depois
builder.AddApplicationInsightsIfConfigured();
builder.AddApiPerformance();
builder.Services.AddForwardedHeadersFromConfiguration(
    builder.Configuration,
    builder.Environment);
builder.Services.AddFileSystemDataProtection(
    builder.Configuration,
    builder.Environment);

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" });
builder.Services.AddDbContext<MyDbContext>(options =>
{
    // Configure aqui o provider EF Core do host.
});
builder.Services.AddAuthentication();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseForwardedHeaders();
app.UseRouting();
app.UseSmartCoreHubCrossCuttingMiddleware();
app.UseApiPerformance();
CorsExtensions.SetupCors(app, new CorsHostingOptions { PrivatePolicyName = "AllowMyFrontend" });
app.UseAndMapApiDocumentation(docs);
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.MapBasicLiveness();
app.MapDatabaseReadiness<MyDbContext>();

app.Run();

Configurações reconhecidas pelas novas extensions:

Composição no monólito SmartCoreHub

O Service preserva as fachadas públicas usadas pelas duas APIs:

WebApplicationBuilderServicesConfigure.Configure(builder);

var app = builder.Build();
app.ConfigurePipeline();

Internamente, o registro é agrupado por AddSmartCoreHubHostingInfrastructure, AddSmartCoreHubApplicationServices, AddSmartCoreHubApiSurface e AddSmartCoreHubCrossCuttingServices. O pipeline usa UseSmartCoreHubNetworkAndCrossCutting, UseSmartCoreHubCorsAndDocumentation, UseSmartCoreHubSecurityAndEndpoints e UseSmartCoreHubStartupAndRequestLogging. Esses oito métodos são orquestração específica do produto e, portanto, permanecem no Service.

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 — hosting, documentação e health (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:

// Bundle padrão usado pelos hosts SmartCoreHub:
app.UseSmartCoreHubCrossCuttingMiddleware();

// Middlewares adicionais conforme a necessidade do host:
app.UseMiddleware<RequestLoggingMiddleware>();
app.UseMiddleware<RequestSizeLimitMiddleware>();

O bundle aplica, nesta ordem, LocalizationHeaderCultureMiddleware, SecurityHeadersMiddleware e CorrelationIdMiddleware.

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));

Domain — Result, validação, helpers e exceptions

Infrastructure — repositório Guid e cache leve

Service — 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.Domain.Common;
using SmartCoreHub.Core.SDK.Domain.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.
• Application Insights é condicional: sem connection string/instrumentation key, AddApplicationInsightsIfConfigured() não registra telemetria.
• Forwarded Headers deve receber proxies/redes confiáveis em ambientes não Development; não torne a configuração permissiva em produção.
• AddFileSystemDataProtection() cria o diretório do key ring. Em contêiner, monte volume persistente para evitar perda das chaves.
• 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
• Survey da refatoração DI/pipeline

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.