프로젝트 구조와 설정

이 장에서는 새 프로젝트에 들어 있는 파일을 살펴보고, 설정과 환경이 어떻게 동작하는지, 앱이 커질 때 코드를 어떻게 나누는지 알아봅니다.

새 프로젝트의 파일

dotnet new webapi -o TodoApi를 실행하면 다음 파일이 만들어집니다.

TodoApi/
├── Program.cs
├── TodoApi.csproj
├── TodoApi.http
├── appsettings.json
├── appsettings.Development.json
├── Properties/
│   └── launchSettings.json
├── bin/
└── obj/

프로젝트 파일

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

Microsoft.NET.Sdk.Web이 이 프로젝트를 ASP.NET Core 프로젝트로 만듭니다. 공유 ASP.NET Core 프레임워크를 참조하고 웹용 암시적 using을 추가합니다. TargetFramework에는 프로젝트를 만든 SDK에 맞는 값이 들어갑니다. 패키지는 CLI로 추가하며, 이때 이 파일에 PackageReference가 기록됩니다.

dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet list package

Program.cs의 두 부분

Program.cs는 늘 같은 모양입니다. 먼저 빌더에 서비스를 등록하고, 앱을 만든 다음 파이프라인을 구성합니다. 서비스 등록은 Build() 전에 끝내야 하며, 그 뒤에는 컨테이너를 바꿀 수 없습니다.

var builder = WebApplication.CreateBuilder(args);

// 1. 의존성 주입 컨테이너에 서비스 등록
builder.Services.AddOpenApi();

var app = builder.Build();

// 2. 미들웨어 파이프라인과 엔드포인트
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();
app.MapGet("/health", () => "ok");

app.Run();

appsettings.json과 환경

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ConnectionStrings": {
    "Default": "Data Source=todo.db"
  },
  "Todo": {
    "PageSize": 20
  }
}

환경 이름은 ASPNETCORE_ENVIRONMENT(또는 DOTNET_ENVIRONMENT)에서 읽습니다. 보통 Development, Staging, Production을 쓰며, 아무것도 정하지 않으면 Production으로 실행됩니다. appsettings.{환경}.json은 appsettings.json 위에 덧씌워지므로 달라지는 값만 적으면 됩니다.

기본 빌더는 다음 순서로 설정을 읽고, 뒤에 오는 값이 앞의 값을 덮어씁니다.

1. appsettings.json
2. appsettings.{Environment}.json
3. 사용자 비밀(Development 환경에서만)
4. 환경 변수
5. 명령줄 인수

중첩된 키는 코드와 명령줄에서는 :로, 환경 변수에서는 __(밑줄 두 개)로 구분합니다.

export ASPNETCORE_ENVIRONMENT=Staging
export Todo__PageSize=50
dotnet run

# 앱에 넘기는 인수로 지정할 수도 있습니다
dotnet run -- --Todo:PageSize=50

비밀 값은 appsettings.json에 넣지 않습니다. 개발 중에는 프로젝트 폴더 밖에 값을 저장하는 비밀 관리자(Secret Manager)를 씁니다.

dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:Default" "Host=localhost;Database=todo;Username=dev;Password=dev"

Properties/launchSettings.json에는 로컬 실행 프로필(주소, ASPNETCORE_ENVIRONMENT=Development 같은 환경 변수)이 들어 있습니다. 이 파일은 dotnet run과 IDE에서만 쓰이고 배포 결과물에는 포함되지 않으므로, 운영 설정은 환경 변수나 설정 파일로 지정합니다.

커지는 앱 정리하기

ASP.NET Core는 폴더 구조를 강제하지 않습니다. 흔히 쓰는 관례는 다음과 같습니다.

• Endpoints/ 또는 Controllers/: 기능별로 묶은 HTTP 진입점
• Services/: DI에 등록하는 업무 로직
• Data/: EF Core DbContext와 Migrations/
• Models/ 또는 Contracts/: 엔터티와 요청·응답 형식
• wwwroot/: 정적 파일 미들웨어가 제공하는 정적 파일

규모가 큰 솔루션은 앱을 src/에, 테스트를 tests/에 두고 솔루션 파일로 묶습니다(dotnet new sln 후 dotnet sln add). 기능별 엔드포인트는 확장 메서드로 빼내 Program.cs를 짧게 유지하는 경우가 많습니다.

// Endpoints/TodoEndpoints.cs
public static class TodoEndpoints
{
    public static RouteGroupBuilder MapTodoEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/todos");
        group.MapGet("/", () => Array.Empty<string>());
        return group;
    }
}

// Program.cs
app.MapTodoEndpoints();

정리

• Program.cs는 서비스를 등록한 뒤 미들웨어 파이프라인과 엔드포인트를 구성합니다.
• .csproj는 Web SDK를 사용하며, 패키지는 dotnet add package로 추가합니다.
• 설정은 JSON 파일, 사용자 비밀, 환경 변수, 명령줄 인수 순으로 겹쳐지고, 환경 이름이 appsettings.{Environment}.json을 고릅니다.
• 폴더 구조는 팀의 관례이며, 확장 메서드로 Program.cs를 짧게 유지합니다.