ASP.NET Core 통합

ASP.NET Core 애플리케이션에는 두 개의 NuGet 진입점이 있습니다. 이름이 비슷한 패키지로 보지 말고, 호스트 애플리케이션이 어떤 경계를 직접 관리할지에 따라 선택하세요.

.NET 호스트에 포함하지 않고 독립 서비스로 실행하려면 공식 Docker 이미지를 사용합니다.

HsSqlAgent.Hosting으로 전체 제품 포함

완전 구성 패키지를 설치합니다.

dotnet add package HsSqlAgent.Hosting

표준 호스트를 등록하고 사용합니다.

using HsSqlAgent.Hosting;

var builder = WebApplication.CreateBuilder(args);
builder.AddHsSqlAgentStandardHost();

var app = builder.Build();
app.UseHsSqlAgentStandardHost();
await app.RunAsync();

공식 ToolBox / Docker 호스트와 동일한 공식 기능 구성 및 설정 계약을 사용합니다. URL 바인딩과 로깅은 일반적인 ASP.NET Core 호스트 책임으로 남습니다.

HsSqlAgent.Hosting에는 표준 HsSqlAgent.Server 런타임과 공식 HsSqlAgent.Approvals.Webhook 어댑터가 포함됩니다. 런타임 NuGet 또는 DLL 플러그인 로딩은 추가하지 않습니다.

DML 승인 공급자 선택

기본 공식 승인 방식은 MCP Elicitation입니다.

{
  "DmlApproval": {
    "Provider": "McpElicitation"
  }
}

공식 범용 Webhook 어댑터를 사용하려면:

{
  "DmlApproval": {
    "Provider": "Webhook",
    "Webhook": {
      "Endpoint": "https://approval.example.com/hssqlagent/requests",
      "CallbackUrl": "https://sql-agent.example.com/api/hs-sql-agent/approvals/webhook",
      "SigningSecret": "replace-with-a-unique-secret-at-least-32-bytes"
    }
  }
}

환경 변수는 일반 ASP.NET Core 구성 이름을 사용합니다. 예: DmlApproval__Provider=Webhook. 알 수 없는 provider 이름은 시작 시 실패합니다.

사용자 정의 IDmlApprovalProvider가 필요하면 HsSqlAgent.Server를 사용하고 의존성 주입으로 등록하세요. 승인 시스템에 임의 SQL 실행 권한은 전달되지 않습니다. SQL 검증, 승인 fingerprint 결합, 현재 상태 재검증과 최종 commit은 계속 HsSqlAgent가 소유합니다.

HsSqlAgent.Server로 맞춤 통합 구성

모듈형 패키지를 설치합니다.

dotnet add package HsSqlAgent.Server

기존 애플리케이션의 인증과 권한 부여를 유지하면서 필요한 HsSqlAgent 기능만 추가할 수 있습니다.

var hs = builder.Services.AddHsSqlAgentCore();

hs.AddHsSqlAgentRuntime();
hs.AddHsSqlAgentAdminStore(options =>
{
    options.Provider = "Postgres";
    options.ConnectionString =
        builder.Configuration.GetConnectionString("HsSqlAgent")!;
});
hs.AddHsSqlAgentHostAuthorization("SqlAgentAdmin");
hs.AddHsSqlAgentAdminApi();

ASP.NET Core 파이프라인은 호스트가 관리합니다.

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.UseHsSqlAgentAdminApi();
app.MapControllers();

app.Run();

호스트 권한 부여 모드에서는 AddHsSqlAgentBuiltInAuth()를 호출하지 않습니다. HsSqlAgent는 인증된 HttpContext.User를 사용하며 내장 인증 컨트롤러나 HsSqlAgent 인증 스키마를 설치하지 않습니다.

/runtime/db-management.edit, /auth/role.view 같은 canonical permission은 안정적인 권한 리소스 식별자이며 URL 경로가 아닙니다. 호스트 policy에서 기존 권한 모델로 매핑할 수 있습니다.

필요할 때만 MCP 추가

MCP는 별도의 기계 접근 보안 경계입니다.

hs.AddHsSqlAgentMcp(options =>
{
    options.PublicEndpoint = "https://example.com/mcp";
    options.HmacSecretKey = builder.Configuration["HMAC_KEY"]!; // >= 32 bytes
});

애플리케이션을 만든 뒤 매핑합니다.

app.UseHsSqlAgentMcp();

MCP 키, 도구 범위, 테이블 범위, 속도 제한과 HMAC 검증은 사람/관리자 권한 부여와 독립적입니다.

필요할 때만 내장 인증 사용

HsSqlAgent 자체 JWT/member/role 모델이 필요하다면 호스트 권한 부여 대신 내장 인증을 선택합니다.

hs.AddHsSqlAgentBuiltInAuth(options =>
{
    options.Jwt.SecretKey = builder.Configuration["JWT_KEY"]!; // >= 32 bytes
});

내장 인증과 호스트 권한 부여는 함께 사용할 수 없습니다. 모듈형 호스트에서는 관리 UI도 생략할 수 있습니다.

기능별 설정 책임

선택하지 않은 기능의 설정은 할당되거나 검증되지 않습니다.

현재 HTTP 마운트

라우팅, 프런트엔드 base path/정적 자산, callback과 보안 경계를 함께 이동할 수 있기 전에는 임의 경로 이동을 지원한다고 안내하지 않습니다.

호환 API

기존 사용자는 AddHsSqlAgent()와 UseHsSqlAgent()를 계속 사용할 수 있습니다. 새 통합에서는 표준 HsSqlAgent.Hosting 또는 AddHsSqlAgentCore()와 명시적 기능 등록을 권장합니다.

관련 문서

• 배포
• 구성
• Safe DML