Source Generator Observability

C# Roslyn API로 로깅, 추적, 메트릭 코드를 자동 생성하는 실전 가이드

---

이 튜토리얼에 대하여

모든 Repository 메서드마다 로깅, 추적, 메트릭 코드를 손으로 복붙하고 있다면 — 소스 생성기가 그 반복 작업을 끝내줄 수 있습니다.

이 튜토리얼은 C# 소스 생성기(Source Generator)를 처음부터 배워 실전에서 활용할 수 있도록 안내합니다. Roslyn 컴파일러 플랫폼의 기초부터 시작하여, IIncrementalGenerator 패턴을 활용한 고성능 소스 생성기 개발까지 단계별로 학습합니다.

반복적인 보일러플레이트 코드를 자동화하고, 100% 일관된 관찰 가능성을 보장하는 소스 생성기를 직접 구현해보세요.

대상 독자

수준	대상	권장 학습 범위
초급	C# 기초 문법을 알지만 소스 생성기는 처음인 개발자	Part 0~1
중급	Roslyn API 경험이 없는 개발자	Part 2 전체
고급	반복적인 보일러플레이트 코드를 자동화하고 싶은 개발자	Part 3~4 + 부록

학습 목표

이 튜토리얼을 완료하면 다음을 할 수 있습니다:

1. Roslyn 컴파일러 플랫폼의 구조와 동작 원리 이해
2. IIncrementalGenerator 인터페이스를 구현한 소스 생성기 개발
3. 심볼 분석을 통한 코드 메타데이터 추출
4. 결정적(deterministic) 코드 생성 기법 적용
5. 소스 생성기 단위 테스트 작성

---

Part 0: 서론

Source Generator의 개념과 필요성을 이해합니다.

• 0.1 Source Generator란?
• 0.2 Hello World 생성기
• 0.3 Source Generator가 필요한 이유
• 0.4 Reflection vs Source Generator
• 0.5 프로젝트 개요

Part 1: 기초

개발 환경을 설정하고 Roslyn 컴파일러 플랫폼을 이해합니다.

장	주제	핵심 학습 내용
1	개발 환경	개발 환경 설정
2	프로젝트 구조	소스 생성기 프로젝트 구성
3	Debugging 설정	Debugging 환경 구축
4	Roslyn 아키텍처	컴파일러 플랫폼 구조
5	Syntax API	구문 트리 분석
6	Semantic API	의미 분석
7	Symbol Type	Symbol 유형 이해

Part 2: 핵심 개념

Incremental Source Generator 구현과 코드 생성 기법을 학습합니다.

장	주제	핵심 학습 내용
1	IIncrementalGenerator 인터페이스	Incremental Generator 인터페이스
2	Provider Pattern	데이터 Provider Pattern
3	ForAttributeWithMetadataName	속성 기반 필터링
4	Incremental Caching	성능 최적화
5	INamedTypeSymbol	Type Symbol 분석
6	IMethodSymbol	Method Symbol 분석
7	SymbolDisplayFormat	Symbol 표시 형식
8	Type 추출	Type 정보 추출
9	StringBuilder Pattern	코드 생성 기본
10	Template 설계	코드 Template 구조화
11	Namespace 처리	Namespace 관리
12	Deterministic Output	Deterministic 코드 생성

Part 3: 고급

복잡한 케이스 처리와 테스트 전략을 학습합니다.

장	주제	핵심 학습 내용
1	Constructor 처리	Constructor 분석 및 생성
2	Generic Type	Generic Type 처리
3	Collection Type	Collection Type 처리
4	LoggerMessage.Define 제한	Logger Message 제약
5	Unit Test 설정	Test 환경 구축
6	Verify Snapshot Test	Snapshot Test
7	Test Scenario	Test Case 작성

Part 4: 개발 절차서

다양한 실용적 예제를 통해 Source Generator 개발 절차를 학습합니다.

장	주제	핵심 학습 내용
1	Source Generator 개발 절차	개발 절차 개요
2	Entity ID Generator	DDD 강타입 Id (Ulid 기반)
3	EF Core Value Converter	ValueConverter 자동 생성
4	Validation 생성기	FluentValidation 규칙 생성
5	Custom Generator Template	새 프로젝트 시작 가이드

Part 5: 결론

전체 내용을 정리하고 다음 단계를 안내합니다.

• 5.1 정리
• 5.2 다음 단계

부록

• A. 개발 환경 준비
• B. API 레퍼런스
• C. Test Scenario Catalog
• D. 문제 해결

---

핵심 진화 과정

[Part 1] 기초 1장: 개발 환경 → 2장: 프로젝트 구조 → 3장: Debugging 설정 → 4장: Roslyn 아키텍처 → 5장: Syntax API → 6장: Semantic API → 7장: Symbol Type

[Part 2] 핵심 개념 1장: IIncrementalGenerator 인터페이스 → 2장: Provider Pattern → 3장: ForAttributeWithMetadataName → 4장: Incremental Caching → 5장: INamedTypeSymbol → 6장: IMethodSymbol → 7장: SymbolDisplayFormat → 8장: Type 추출 → 9장: StringBuilder Pattern → 10장: Template 설계 → 11장: Namespace 처리 → 12장: Deterministic Output

[Part 3] 고급 1장: Constructor 처리 → 2장: Generic Type → 3장: Collection Type → 4장: LoggerMessage.Define 제한 → 5장: Unit Test 설정 → 6장: Verify Snapshot Test → 7장: Test Scenario

[Part 4] 개발 절차서 1장: Source Generator 개발 절차 → 2장: Entity ID Generator → 3장: EF Core Value Converter → 4장: Validation 생성기 → 5장: Custom Generator Template

---

실습 프로젝트: ObservablePortGenerator

이 튜토리얼에서는 ObservablePortGenerator라는 실제 Source Generator를 단계별로 구현합니다. 프로젝트의 설계 목표, 구조, 기대 효과에 대한 자세한 내용은 Part 0-05. 프로젝트 개요를 참고하세요.

// 개발자가 작성하는 코드 - 비즈니스 로직만 집중
[GenerateObservablePort]
public class UserRepository(ILogger<UserRepository> logger) : IObservablePort
{
    public FinT<IO, User> GetUserAsync(int id) => /* 순수 로직 */;
}

// 소스 생성기가 자동 생성 - 관찰 가능성 코드 포함
public class UserRepositoryObservable : UserRepository
{
    // 로깅, 추적, 메트릭이 모든 메서드에 자동 적용
}

---

필수 준비물

• .NET 10.0 SDK (Preview 또는 정식 버전)
• Visual Studio 2022 (17.12 이상) 또는 VS Code (C# Dev Kit 확장)
• C# 14 기초 문법 지식

---

프로젝트 구조

sourcegen-observability/
├── Part0-Introduction/         # Part 0: 서론
│   ├── 01-what-is-source-generator.md
│   ├── 02-hello-world-generator/
│   ├── 03-why-source-generator.md
│   ├── 04-reflection-vs-sourcegen/
│   └── 05-project-overview.md
├── Part1-Fundamentals/         # Part 1: 기초
│   ├── 01-development-environment.md
│   ├── 02-Data-Models/
│   ├── 03-Debugging-Setup/
│   ├── ...
│   └── 07-Symbol-Types/
├── Part2-Core-Concepts/        # Part 2: 핵심 개념
│   ├── 01-IIncrementalGenerator/
│   ├── ...
│   └── 12-Deterministic-Output/
├── Part3-Advanced/             # Part 3: 고급
│   ├── 01-Constructor-Handling/
│   ├── ...
│   └── 07-Test-Scenarios/
├── Part4-Cookbook/              # Part 4: 개발 절차서
│   ├── 01-Development-Workflow/
│   ├── ...
│   └── 05-Custom-Generator-Template/
├── Part5-Conclusion/           # Part 5: 결론
│   ├── 01-summary.md
│   └── 02-next-steps.md
└── Appendix/                   # 부록
    ├── A-development-environment.md
    ├── B-api-reference.md
    ├── C-test-scenario-catalog.md
    └── D-troubleshooting.md

---

테스트

모든 Part의 예제 프로젝트에는 단위 테스트가 포함되어 있습니다. 테스트는 단위 테스트 가이드를 따릅니다.

테스트 실행 방법

# 튜토리얼 전체 빌드
dotnet build sourcegen-observability.slnx

# 튜토리얼 전체 테스트
dotnet test --solution sourcegen-observability.slnx

테스트 프로젝트 구조

Part 4: 개발 절차서 (5개)

장	테스트 프로젝트	주요 테스트 내용
1	DevelopmentWorkflow.Tests.Unit	Source Generator 개발 절차 검증
2	EntityIdGenerator.Tests.Unit	DDD 강타입 Id (Ulid 기반) 생성
3	EfCoreValueConverter.Tests.Unit	ValueConverter 자동 생성 검증
4	ValidationGenerator.Tests.Unit	FluentValidation 규칙 생성 검증
5	CustomGeneratorTemplate.Tests.Unit	커스텀 Generator 템플릿 검증

테스트 명명 규칙

T1_T2_T3 명명 규칙을 따릅니다:

// Method_ExpectedResult_Scenario
[Fact]
public void Generate_ProducesExpectedOutput_WhenClassHasObservablePortAttribute()
{
    // Arrange
    var source = /* 입력 소스 코드 */;
    // Act
    var actual = GeneratorTestHelper.RunGenerator(source);
    // Assert
    actual.ShouldMatchExpected();
}

---

소스 코드

이 튜토리얼의 모든 예제 코드는 Functorium 프로젝트에서 확인할 수 있습니다:

• 소스 생성기: Src/Functorium.SourceGenerators/
• 어댑터 (속성, 네이밍): Src/Functorium.Adapters/
• 테스트: Tests/Functorium.Tests.Unit/AdaptersTests/SourceGenerators/
• 테스트 유틸리티: Src/Functorium.Testing/Actions/SourceGenerators/

---

이 튜토리얼은 Functorium 프로젝트의 실제 소스 생성기 개발 경험을 바탕으로 작성되었습니다.