SmartCoreHub.Core.SDK 20260802.156.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.* (subnamespaces Documentation, Cors, Performance, Hosting, Observability, Security, Health, Mapping, Primitives): 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.IdeExtensions/ — VS Code/Cursor no Marketplace, snippets JSON, instalador.
6. Mapa estruturado: ../SmartCoreHub.Core.SDK.IdeExtensions/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.
FluentValidationBehavior vem com AddSmartCoreHubMediatRAdapter (opt-in por request via IHasValidationPayload + validators no DI). TransactionBehavior é opt-in via registro no host + 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.Cors.Extensions;
using SmartCoreHub.Core.SDK.Service.API.DI.Cors.Options;
using SmartCoreHub.Core.SDK.Service.API.DI.Documentation.Extensions;
using SmartCoreHub.Core.SDK.Service.API.DI.Documentation.Options;
using SmartCoreHub.Core.SDK.Service.API.DI.Health.Extensions;
using SmartCoreHub.Core.SDK.Service.API.DI.Hosting.Extensions;
using SmartCoreHub.Core.SDK.Service.API.DI.Observability.Extensions;
using SmartCoreHub.Core.SDK.Service.API.DI.Performance.Extensions;
using SmartCoreHub.Core.SDK.Service.API.DI.Primitives.Extensions;
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 (ConfigurePipeline) chama diretamente UseSdkNetworkAndCrossCutting, UseSdkCorsAndDocumentation, UseSdkSecurityAndEndpoints<SmartCoreHubDbContext>, InitializeDatabaseAtStartup e UseSdkRequestLogging, injetando só branding, DbContext e rotinas do produto.

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

Registro por convenção (todos os TFMs, em Service.DependenciesCollection.Extensions):

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.IdeExtensions/README.md
  • Publicação nas stores: ../SmartCoreHub.Core.SDK.IdeExtensions/docs/BUILD-DEPLOY-PUBLISH.md
  • Instalação manual: ../SmartCoreHub.Core.SDK.IdeExtensions/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.