SmartCoreHub.Core.SDK 20260725.502.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, CQRS/OpenTelemetry 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).

NuGet: https://www.nuget.org/packages/SmartCoreHub.Core.SDK/

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.

Documentação no pacote (humano + IA)

Contexto para IA (além do README)

1. Anexar no chat / @: AI-CONTEXT.md + API-CATALOG.md + MIGRATION-GUIDE.md.
2. Cursor Rule: .cursor/rules/smartcorehub-core-sdk-migration.mdc.
3. Pacote NuGet: markdowns na raiz do nupkg → %USERPROFILE%\.nuget\packages\smartcorehub.core.sdk\<versão>\.
4. XML-doc + .snupkg: IntelliSense sem clonar o monólito.
5. Extensões IDE (projeto separado): ../SmartCoreHub.Core.SDK.Extensions/ — VS Code/Cursor .vsix, snippets JSON, instalador.
6. Mapa estruturado: ../SmartCoreHub.Core.SDK.Extensions/shared/maps/legacy-to-sdk.json.

NuGet: https://www.nuget.org/packages/SmartCoreHub.Core.SDK/

Instalação

dotnet add package SmartCoreHub.Core.SDK

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

Versões: https://www.nuget.org/packages/SmartCoreHub.Core.SDK/

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: Domain/, Infrastructure/, Service/, Application/, Client/.

Catálogo exaustivo (todos os tipos + métodos): API-CATALOG.md.

Quick start — CQRS (net8/net10)

TResult é o payload. O dispatcher e os handlers retornam ServiceResponse<TResult>. Controllers usam apenas IApplicationDispatcher — nunca IMediator/ISender.

using SmartCoreHub.Core.SDK.Application.Cqrs.Abstractions;
using SmartCoreHub.Core.SDK.Application.Cqrs.MediatR;
using SmartCoreHub.Core.SDK.Domain.DTOs.Common;

// Registro (host/produto):
services.AddSmartCoreHubMediatRAdapter(typeof(CreateSomethingHandler).Assembly);

public sealed record CreateSomethingCommand(string Name) : ICommand<Guid>, IHasValidationPayload<CreateSomethingDto>
{
    public CreateSomethingDto Payload => new(Name);
}

public sealed class CreateSomethingHandler : ICommandHandler<CreateSomethingCommand, Guid>
{
    public Task<ServiceResponse<Guid>> HandleAsync(
        CreateSomethingCommand command,
        CancellationToken cancellationToken = default)
        => Task.FromResult(ServiceResponse<Guid>.Ok(Guid.NewGuid()));
}

// Controller / composition root:
public sealed class SomethingController(IApplicationDispatcher dispatcher)
{
    public Task<ServiceResponse<Guid>> Create(CreateSomethingCommand command, CancellationToken ct)
        => dispatcher.SendAsync(command, ct);
}

Pipeline efetivo (Fase 4): UnhandledException → Logging → Performance → Validation → Transaction → Handler.
TransactionBehavior é opt-in via ITransactionalCommand + ITransactionExecutor (EF na Infrastructure).
Na avaliação da Fase 8, CachingBehavior não foi ativado: não há queries CQRS com política estável de chave/TTL/invalidação, e o hot path de Localization continua no cache dedicado existente. ICacheableQuery permanece apenas como contrato de extensão para uma entrega futura com semântica explícita.

Envelope HTTP: o padrão é ServiceResponse<T>. Endpoints específicos de SmartCoreHub.Localization.API podem documentar respostas mais limpas sem o envelope quando a superfície HTTP exigir.

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;
using SmartCoreHub.Core.SDK.Service.Hosting;

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.AddSmartCoreHubOpenTelemetry();
builder.AddSmartCoreHubHttpClientDefaults();
builder.Services.AddForwardedHeadersFromConfiguration(
    builder.Configuration,
    builder.Environment);
builder.Services.AddFileSystemDataProtection(
    builder.Configuration,
    builder.Environment);

var docs = OpenApiDocumentationOptions.Create(
    builder.Configuration,
    defaults: new OpenApiDocumentationOptions
    {
        Title = "My API",
        Description = "API reutilizando SmartCoreHub.Core.SDK",
        ContactName = "Team",
        ContactEmail = "support@example.com"
    },
    configure: options =>
    {
        // Override final por host (opcional).
        // options.Title = "My API (override)";
    });

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.

Lista exaustiva (~291 tipos + métodos/propriedades): API-CATALOG.md.
Migração com IA: AI-CONTEXT.md.

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)

Client.Cloud — HTTP JWT client (net8/net10)

Cliente de aplicativo para a SmartCoreHub.API (Auth + Blob/Queue/Table via REST). Layout alinhado ao Localization.SDK (Abstred / Clients / Configuration / Extensions / Http / Models / Facade).

Não confundir com Infrastructure/Cloud/Azure (*Adapter = SDK Azure in-process). Aqui os tipos são *Client (HTTP).

using SmartCoreHub.Core.SDK.Client.Cloud.Configuration;
using SmartCoreHub.Core.SDK.Client.Cloud.Extensions;

services.AddSmartCoreHub(new SmartCoreHubOptions
{
    BaseUrl = "https://api.exemplo/"
});
// Resolve IAuthClient, IBlobStorageClient, etc.

O módulo Client/Cloud/ é autocontido (sem dependência de Cloud.Azure) e pode ser extraído no futuro para um NuGet irmão com troca mínima de namespaces.

Infrastructure — security / logging

Application.Cqrs — contratos, pipeline e factories (net8/net10)

Pipeline efetivo: UnhandledException → Logging → Performance → Validation → Transaction → Handler.

Service.Hosting — OpenTelemetry, HttpClient, health (net8/net10)

Domain — helpers e extensions (métodos)

Contratos com superfície completa de métodos

Client.Cloud — models (net8/net10)

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

• Requisitos / escopo / Extensões IDE: Documentation/Features/SmartCoreHub.Core.SDK-Extensões-IDE/SmartCoreHub.Core.SDK-Extensões-IDE-Requisitos.md
• Guia de migração: MIGRATION-GUIDE.md
• Catálogo completo da API: API-CATALOG.md
• Contexto IA: AI-CONTEXT.md
• Extensões IDE (projeto separado): ../SmartCoreHub.Core.SDK.Extensions/README.md
  • Publicação nas stores: ../SmartCoreHub.Core.SDK.Extensions/docs/BUILD-DEPLOY-PUBLISH.md
  • Instalação manual: ../SmartCoreHub.Core.SDK.Extensions/docs/INSTALL-MANUAL.md
• 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
• NuGet Gallery: https://www.nuget.org/packages/SmartCoreHub.Core.SDK/

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.