Emiliano Montesdeoca

Blazor 처음부터: 3장 — 확장 가능한 컴포넌트

Mon, 01 Jun 2026 00:00:00 +0000

Blazor 처음부터 3장에 오신 것을 환영합니다. 아직 2장을 읽지 않았다면 먼저 읽고 기본 프로젝트를 준비해 주세요.

2장에서는 앱을 실행했습니다. 3장에서는 앱을 유지보수 가능한 구조 로 바꿉니다.

Blazor 프로젝트는 페이지마다 거대한 .razor 파일이 되면 금방 복잡해집니다. 컴포넌트는 이를 막아줍니다. 일관성, 재사용성, 그리고 UI 책임 분리가 좋아집니다.

Blazor 컴포넌트란 무엇인가

컴포넌트는 다음을 할 수 있는 .razor 파일입니다.

마크업 렌더링
로컬 상태 보관
파라미터로 입력 받기
부모 컴포넌트로 이벤트 전달
자식 콘텐츠 렌더링

런타임에서 Blazor는 각 컴포넌트를 작은 상태 머신처럼 다룹니다. 상태가 바뀌면 다시 렌더링하고 DOM diff를 적용합니다.

즉, 명확한 입력과 예측 가능한 동작을 설계하는 것이 핵심입니다.

1단계: 목적이 분명한 컴포넌트부터 시작

Components/Common/SectionHeader.razor를 만듭니다.

<header class="section-header">
 <h2>@Title</h2>
 @if (!string.IsNullOrWhiteSpace(Subtitle))
 {
 <p>@Subtitle</p>
 }
</header>

@code {
 [Parameter] public string Title { get; set; } = string.Empty;
 [Parameter] public string? Subtitle { get; set; }
}

Components/Pages/Home.razor에서 사용:

@page "/"

<PageTitle>Blazor 처음부터</PageTitle>

<SectionHeader
 Title="Blazor 처음부터"
 Subtitle="3장은 컴포넌트를 다룹니다." />

작은 예제지만 핵심은 분명합니다. 컴포넌트는 파라미터만 봐도 의도를 이해할 수 있어야 합니다.

2단계: 파라미터로 동작을 명시적으로 표현

재사용 가능한 버튼 컴포넌트를 만들어 봅니다.

Components/Common/AppButton.razor:

<button class="app-button @VariantCssClass" @onclick="OnClick">
 @Text
</button>

@code {
 [Parameter] public string Text { get; set; } = "Button";
 [Parameter] public string Variant { get; set; } = "primary";
 [Parameter] public EventCallback OnClick { get; set; }

 private string VariantCssClass => Variant.ToLowerInvariant() switch
 {
 "secondary" => "app-button--secondary",
 "danger" => "app-button--danger",
 _ => "app-button--primary"
 };
}

사용 예:

@code {
 private int _savedCount;

 private void Save()
 {
 _savedCount++;
 }
}

<AppButton Text="Save" Variant="primary" OnClick="Save" />
<p>저장 횟수: @_savedCount</p>

핵심은 계약(Contract) 설계입니다.

적고 명확한 파라미터
암묵적 동작 대신 명시적 이름
안전한 기본값

3단계: `RenderFragment`로 레이아웃 컴포지션

RenderFragment를 사용하면 부모가 자식에게 UI 블록을 전달할 수 있습니다.

Components/Common/Card.razor 생성:

<article class="card">
 <header class="card__header">@Title</header>
 <section class="card__body">
 @ChildContent
 </section>
</article>

@code {
 [Parameter] public string Title { get; set; } = string.Empty;
 [Parameter] public RenderFragment? ChildContent { get; set; }
}

사용 예:

<Card Title="Roadmap">
 <ul>
 <li>컴포넌트</li>
 <li>Data binding</li>
 <li>Routing</li>
 </ul>
</Card>

이 패턴은 래퍼 마크업 반복 없이 일관된 페이지 구조를 만드는 데 매우 유용합니다.

4단계: 거대한 페이지보다 컴포지션

페이지가 커지면 책임 기준으로 분리하세요.

ProfileSummary (상단 요약)
ProfileStats (지표)
ProfileActivityList (최근 활동)

그 결과 페이지는 구현 상세가 아니라 조합/오케스트레이션 역할을 하게 됩니다.

5단계: 마크업과 로직의 균형

단순한 컴포넌트는 inline @code로 충분합니다.

커지기 시작하면 code-behind로 분리하세요.

UserCard.razor
UserCard.razor.cs

마크업과 C# 로직 모두 읽기 쉬워집니다.

6단계: 실용적인 폴더 구조

확장에 유리한 구조 예시:

Components/Pages/ -> 라우팅 가능한 페이지
Components/Layout/ -> 앱 셸/내비게이션
Components/Common/ -> 공용 범용 컴포넌트
Components/Features/<FeatureName>/ -> 기능별 컴포넌트

초기에 자주 하는 실수

전용 모델 없이 파라미터를 너무 많이 전달
페이지 컴포넌트에 비즈니스 규칙을 직접 작성
수백 줄짜리 “God component” 생성
반복되는 마크업을 추출하지 않음

다음 장

4장에서는 데이터 바인딩과 이벤트를 다룹니다. @bind, 이벤트 처리, 양방향 바인딩의 트레이드오프, 예측 가능한 상태 관리 패턴을 살펴봅니다.

Blazor 기초부터: 챕터 2 — 첫 번째 Blazor 앱

Thu, 14 May 2026 00:00:00 +0000

Blazor 기초부터 챕터 2에 오신 것을 환영합니다. 챕터 1을 아직 읽지 않았다면 먼저 확인하세요.

이번 챕터에서는 새 Blazor 앱을 만들고, 로컬에서 실행하고, 중요한 파일들의 역할을 이해합니다.

1단계: 프로젝트 생성

터미널에서 실행:

dotnet new blazor -o BlazorFromScratch
cd BlazorFromScratch

이 명령은 .NET 9 Blazor Web App을 기본 구조로 생성합니다.

도구가 상호작용 모델을 물어보면 Interactive Server로 시작하세요.

2단계: 로컬 실행

앱 실행:

dotnet watch

터미널에 표시된 URL(보통 https://localhost:5xxx)을 엽니다. Home, Counter, Weather 페이지가 보이면 정상입니다.

여기까지 되면 개발 환경은 준비 완료입니다.

3단계: 프로젝트 구조 이해

처음에는 아래 파일/폴더만 알면 충분합니다.

Program.cs — 서비스 등록 및 HTTP 파이프라인 설정.
Components/App.razor — 앱 루트 컴포넌트.
Components/Routes.razor — 페이지 라우트 매핑.
Components/Pages/ — Home, Counter 같은 라우팅 페이지.
Components/Layout/ — 공통 레이아웃(MainLayout.razor, 메뉴).
wwwroot/ — 정적 리소스(CSS, 이미지, favicon).
appsettings.json — 설정 값.

지금은 모든 파일을 깊게 알 필요 없습니다. UI 위치와 시작 설정 위치를 파악하는 것이 핵심입니다.

4단계: 첫 변경 만들기

Components/Pages/Home.razor를 열고 내용을 아래로 바꾸세요.

@page "/"

<PageTitle>Blazor 기초부터</PageTitle>

<h1>Blazor 기초부터</h1>
<p>챕터 2가 로컬에서 실행 중입니다.</p>

저장 후 브라우저를 새로고침합니다. dotnet watch를 사용 중이면 즉시 반영됩니다.

이 작은 수정으로 전체 흐름(edit -> build -> render)을 확인할 수 있습니다.

5단계: Program.cs 한 번 읽기

외울 필요는 없지만, 다음 줄은 알아두세요.

AddRazorComponents() Razor 컴포넌트 활성화.
AddInteractiveServerComponents() 서버 상호작용 컴포넌트 활성화.
MapRazorComponents<App>() 루트 컴포넌트를 엔드포인트에 매핑.

이 줄들이 앱 부팅 방식과 활성화된 렌더링 기능을 설명합니다.

자주 발생하는 문제

문제가 생기면 보통 다음 중 하나입니다.

SDK 버전 문제: dotnet --version으로 .NET 9 확인.
HTTPS 인증서 경고: dotnet dev-certs https --trust 실행.
포트 충돌: 기존 dotnet 프로세스를 종료 후 재실행.

다음 챕터

챕터 3에서는 컴포넌트를 깊이 다룹니다: 파라미터, 조합, 재사용 가능한 UI 구조.

Blazor 처음부터: 1장 — Blazor란 무엇인가?

Fri, 08 May 2026 00:00:00 +0000

Blazor 처음부터 시리즈의 1장에 오신 것을 환영합니다. 이 시리즈의 목적과 대상 독자를 설명한 소개 포스트를 놓치셨다면 먼저 읽어보세요 — 짧습니다.

이 챕터에서는 근본적인 질문에 답할 것입니다: Blazor란 무엇인가? 단순해 보이지만, 특히 “Blazor"가 수년에 걸쳐 약간씩 다른 의미를 갖게 되었기 때문에 답변에는 여러 층이 있습니다. 이 포스트가 끝날 때쯤 여러분은 Blazor가 무엇인지, .NET 생태계에서 어떻게 자리 잡는지, 다양한 렌더링 모델이 무엇인지, 그리고 왜 JavaScript 프레임워크 대신 이것을 선택할 수도 있는지 알게 될 것입니다.

간략한 역사

Blazor는 2017년경 Microsoft의 Steve Sanderson이 진행한 실험적 프로젝트로 시작되었습니다. 아이디어는 도발적이었습니다: WebAssembly를 사용하여 브라우저에서 C#을 실행하여 JavaScript의 필요성을 완전히 없애는 것이었습니다. 개념 증명이었으며, 이름은 Blazer와 Razor를 의도적으로 합친 것이었습니다 — Razor는 Blazor가 결국 위에 구축될 템플릿 엔진입니다.

실험은 Microsoft가 진지하게 받아들일 만큼 충분한 관심을 불러일으켰습니다. Blazor는 2019년 9월 ASP.NET Core 3.0의 일부로 출시되었으며, 처음에는 Blazor Server — 서버에서 C# 코드를 실행하고 실시간 SignalR 연결을 사용하여 브라우저에 UI 업데이트를 전송하는 모델이었습니다. Blazor WebAssembly는 ASP.NET Core 3.1의 일부로 2020년 5월에 뒤따라, 프레임워크에 진정한 클라이언트 측 실행을 가져왔습니다.

.NET 6과 7은 개발자 경험을 다듬었습니다. 그런 다음 2023년 11월에 출시된 .NET 8은 Microsoft가 풀스택 웹 UI라고 부르는 것으로 렌더링 모델을 근본적으로 재고했습니다. 정적 서버 사이드 렌더링, 스트리밍 렌더링, 인터랙티브 서버, 인터랙티브 WebAssembly, 그리고 새로운 Auto 모드가 단일 프로젝트의 동일한 지붕 아래 공존하게 되었습니다. .NET 9는 이 기반 위에 구축하고 거친 부분을 다듬었습니다.

오늘날 우리가 있는 곳이 바로 여기입니다.

Blazor가 실제로 무엇인가

핵심적으로, Blazor는 .NET을 위한 컴포넌트 기반 UI 프레임워크입니다. 컴포넌트로 UI를 구축합니다 — 상태를 유지하고, 이벤트에 반응하며, 더 큰 구조로 구성될 수 있는 C#과 HTML 마크업의 자기 완결적 조각들입니다. React나 Vue로 작업해본 적이 있다면 이 멘탈 모델이 익숙하게 느껴질 것입니다. 핵심 차이점은 JavaScript 대신 C#을 작성한다는 것입니다.

Blazor의 컴포넌트는 .razor 파일로 작성됩니다. .razor 파일은 ASP.NET MVC 뷰에서 이미 알고 있을 수 있는 Razor 구문을 사용하여 HTML 마크업과 C# 코드를 혼합합니다. 간단한 컴포넌트는 다음과 같습니다:

@page "/counter"

<h1>카운터</h1>
<p>현재 카운트: @currentCount</p>
<button @onclick="IncrementCount">클릭하세요</button>

@code {
 private int currentCount = 0;

 private void IncrementCount()
 {
 currentCount++;
 }
}

JavaScript는 보이지 않습니다. @onclick 지시자는 버튼 클릭을 C# 메서드에 연결합니다. @currentCount 표현식은 현재 값을 렌더링합니다. 상태가 변경되면 Blazor는 DOM에서 무엇을 업데이트할지 파악합니다.

그것이 핵심입니다. 그 외 모든 것 — 라우팅, 의존성 주입, 폼, HTTP 호출 — 이 컴포넌트 모델 위에 구축됩니다.

렌더링 모델

여기에 많은 혼란이 존재하므로 정확히 살펴보겠습니다. 오늘날 “Blazor"는 단일 배포 모델이 아닌 렌더링 모드의 계열을 의미합니다. 차이를 이해하는 것이 중요한 이유는 성능, 인프라 요구 사항, 그리고 컴포넌트가 할 수 있는 것과 없는 것에 영향을 미치기 때문입니다.

정적 SSR

가장 간단한 모드입니다. Razor 컴포넌트가 서버에서 HTML로 렌더링되고 그 HTML이 브라우저로 전송됩니다. 영구적인 연결도, WebAssembly도, 기본적으로 클라이언트 측 인터랙티비티도 없습니다. 이것은 본질적으로 Razor Pages가 하는 일이지만, 컴포넌트 모델을 사용합니다.

콘텐츠가 많은 페이지, 랜딩 페이지, 실시간 인터랙티비티가 필요 없는 모든 것에 사용하세요.

인터랙티브 서버

컴포넌트 코드가 서버에서 실행됩니다. 브라우저와 서버 사이에 SignalR WebSocket 연결이 설정됩니다. 버튼을 클릭하거나 입력 필드에 타이핑하면 이벤트가 WebSocket을 통해 서버로 전달되고, C#이 실행되며, 차이가 계산되고, DOM 업데이트가 브라우저로 다시 전송됩니다.

장점: 서버 리소스(데이터베이스, 파일 시스템, 시크릿)에 대한 완전한 접근. 빠른 초기 로드. 작은 다운로드 크기. WebAssembly 지원 없이도 브라우저에서 작동합니다.

단점: 모든 사용자 인터랙션이 서버 왕복을 필요로 하여 지연이 추가됩니다. 서버 리소스는 활성 연결 수에 따라 확장됩니다. 연결이 끊기면 앱이 저하됩니다.

비즈니스 앱, 내부 도구, 오프라인 기능보다 서버 측 데이터 접근이 더 중요한 앱에 사용하세요.

인터랙티브 WebAssembly

.NET 런타임이 브라우저에 다운로드되고 앱이 완전히 클라이언트에서 실행됩니다. 초기 다운로드 후, 앱은 완전히 오프라인으로 작동하고 모든 인터랙션이 즉각적입니다 — UI 로직을 위한 서버 왕복이 없습니다.

장점: 진정한 클라이언트 측 실행. 오프라인 작동. 앱 로드 후 서버 부하 감소.

단점: 더 큰 초기 다운로드(.NET 런타임 + 앱). 더 느린 첫 번째 로드. 서버 측 데이터에 접근하려면 API가 필요합니다.

오프라인 기능이 있는 앱, 즉각적인 반응성이 필요한 도구, UI에 서버 처리가 필요하지 않은 시나리오에 사용하세요.

Auto 모드

.NET 8에서 도입되었습니다. 앱은 인터랙티브 서버 모드로 시작합니다(빠른 초기 로드, WebAssembly 다운로드를 기다리지 않음). WebAssembly 파일이 백그라운드에서 다운로드되면 이후 방문은 자동으로 WebAssembly 모드로 전환됩니다.

이것은 서버 모드의 빠른 첫 번째 로드와 결국 WebAssembly의 완전한 클라이언트 측 실행을 모두 제공합니다. 이해하기 가장 복잡한 모델이지만 많은 앱에 실용적인 기본값입니다.

동일한 앱에서 모드 혼합

.NET 8 이상에서는 전체 앱에 대해 단일 렌더링 모드에 고정되지 않습니다. 마케팅 랜딩 페이지는 정적 SSR일 수 있고, 인증된 대시보드는 인터랙티브 서버일 수 있으며, 데이터 시각화 위젯은 인터랙티브 WebAssembly일 수 있습니다. 프레임워크가 전환을 처리합니다.

이 시리즈에서는 인터랙티브 서버로 시작할 것입니다. 가장 간단하게 작동시킬 수 있고 가장 직관적인 멘탈 모델을 가지고 있기 때문입니다. 다른 모드는 진행하면서 탐색하겠습니다.

Blazor와 JavaScript 프레임워크 비교

React, Angular, 또는 Vue로 개발해본 적이 있다면 아마도 이 비교가 궁금할 것입니다.

유사점은 실재합니다. Blazor의 컴포넌트 모델은 의도적으로 React와 유사합니다. props(Blazor에서는 Parameters), 로컬 상태(@code 블록의 필드), 라이프사이클 훅, 그리고 동일한 단방향 데이터 흐름 / 이벤트 업 통신 패턴이 있습니다. React를 안다면 몇 시간 안에 익숙해질 것입니다.

핵심 차이점은 언어입니다. Blazor에서는 C#을 작성합니다. 비즈니스 로직, 유효성 검사 규칙, 데이터 모델을 Blazor 프론트엔드와 ASP.NET Core 백엔드 사이에 모두 공유할 수 있습니다. 이미 C#에 있는 User 클래스를 TypeScript에서 중복 작성할 필요가 없습니다.

생태계 격차는 실재하지만 좁혀지고 있습니다. npm 생태계는 방대합니다. UI 컴포넌트를 위한 NuGet 생태계는 더 작지만 상당히 성장했습니다. 특정 차트 라이브러리나 드래그 앤 드롭 위젯이 필요하다면 JavaScript에 더 많은 옵션이 있습니다. 하지만 대부분의 비즈니스 애플리케이션의 경우 .NET 세계에서 사용 가능한 것이 충분합니다.

JavaScript 상호 운용성은 필요할 때 존재합니다. Blazor는 C#에서 JavaScript를 호출하고 JavaScript에서 C#을 호출할 수 있게 합니다. .NET 래퍼가 없는 브라우저 API나 기존 JS 라이브러리를 사용하고 싶을 때 상호 운용이 가능합니다. 레이어를 추가하지만 고통스럽지는 않습니다.

솔직한 답변: 팀 전체가 JavaScript 개발자이고 SEO, 성능, npm 생태계가 중요한 공개 제품을 만들고 있다면 JavaScript를 고수하세요. 팀이 .NET 개발자이고, 내부 또는 비즈니스 애플리케이션을 만들거나, 프론트엔드와 백엔드 사이의 코드 공유가 중요하다면 Blazor는 설득력 있는 선택입니다.

따라하기 위해 필요한 것

이 시리즈의 나머지 부분을 위해 필요한 것:

.NET 9 SDK — dot.net에서 다운로드
IDE — Visual Studio 2022(Community 에디션 무료), C# Dev Kit 확장이 있는 VS Code, 또는 JetBrains Rider
C# 기초 지식 — 클래스, 속성, 인터페이스, async/await

그것뿐입니다. Node, npm, webpack 없음.

다음 편

2장에서는 첫 번째 Blazor 앱을 스캐폴딩하고, 프로젝트 구조를 살펴보며, 로컬에서 실행할 수 있는지 확인할 것입니다. 끝에는 작동하는 앱과 각 파일이 무엇을 하는지에 대한 명확한 그림을 갖게 될 것입니다.

거기서 뵙겠습니다.

Blazor 처음부터: 새 시리즈

Mon, 04 May 2026 00:00:00 +0000

저는 한동안 Blazor에 대해 글을 써왔습니다 — 컴포넌트 생명 주기, 스코프 CSS, 인터랙티비티 모델, 인증. 각각의 글은 나름 유용했지만, 항상 기반이 빠져 있다는 느낌이 들었습니다. Blazor가 무엇인지, 왜 존재하는지, .NET 생태계에 어떻게 맞는지를 이미 알고 있다고 가정하고 있었죠. 모두가 그렇지는 않고, 그건 완전히 괜찮습니다.

그래서 새로운 것을 시작합니다: Blazor 처음부터. 제대로 된 시리즈로, 기초부터 쌓아올려, 자신이 무엇을 만들고 있는지 정말로 이해하고 싶은 개발자를 위해 — 그냥 작동할 때까지 복사-붙여넣기만 하는 것이 아니라.

이 시리즈는 누구를 위한 것인가

이 시리즈는 다음에 해당하는 분을 위한 것입니다:

Blazor에 대해 들어봤지만 깊이 파고들 시간이나 적절한 시작점을 찾지 못한 .NET 개발자
Blazor를 시도해보고 돌아가게는 했지만, 왜 작동하는지 짐작만 하고 있는 것 같은 분
JavaScript/React/Angular 세계에서 와서 Microsoft의 모던 프론트엔드에 대한 답이 어떤 모습인지 이해하고 싶은 분
흩어진 문서와 블로그 글들 대신 하나의 일관된 리소스를 원하는 분

시니어 개발자일 필요는 없습니다. 다만 C# 기본기 — 클래스, 인터페이스, async/await — 는 익숙해야 합니다. ASP.NET Core에서 간단한 CRUD API를 작성할 수 있다면 준비된 것입니다.

무엇을 다룰 것인가

다음은 제가 계획한 대략적인 로드맵입니다. 필요에 따라 일부 주제는 여러 글로 확장될 수 있습니다:

Blazor란 무엇인가? — 호스팅 모델, 역사, 전통적인 웹 개발과의 비교
첫 번째 Blazor 앱 — 스캐폴딩, 프로젝트 구조, 로컬 실행
컴포넌트 — 모든 Blazor UI의 기본 블록
데이터 바인딩과 이벤트 — UI를 반응형으로 만들기
컴포넌트 간 통신 — 파라미터, EventCallbacks, 캐스케이딩 값
라우팅과 네비게이션 — Blazor가 URL과 페이지 전환을 처리하는 방법
의존성 주입 — 서비스, 스코프, Blazor의 DI 컨테이너
폼과 유효성 검사 — EditForm, DataAnnotations, 커스텀 유효성 검사기
HTTP와 외부 데이터 — Blazor 앱에서 API 호출하기
인증과 인가 — 앱을 올바르게 보호하기
JavaScript 인터롭 — 브라우저에 직접 접근해야 할 때
성능과 최적화 — 가상화, 지연 로딩, 렌더 전략
Blazor 컴포넌트 테스트 — bUnit과 탄탄한 테스트의 모습
배포 — Azure, IIS, 정적 호스트에 게시하기

이 목록은 발전할 것입니다. 일부 주제는 여러 글로 나뉘고, 다른 것들은 합쳐질 수 있습니다. 시리즈가 진행되면서 이 글을 업데이트하고 각 항목이 게시될 때 링크를 추가하겠습니다.

왜 시리즈를, 왜 지금

Blazor는 많이 성숙했습니다. .NET 8과 9에서 렌더링 모델이 크게 개편되었습니다 — 정적 SSR, 스트리밍 렌더링, 인터랙티브 서버, 인터랙티브 WebAssembly, 오토 모드가 이제 한 지붕 아래 공존합니다. 진정으로 흥미롭고 유능한 프레임워크이지만, 복잡성의 증가로 인해 시작 경험이 혼란스러울 수 있습니다.

여러분이 있는 곳에서 만나 전체를 체계적으로 안내하는 리소스를 만들고 싶습니다. 공식 문서의 대체물이 아닙니다 — 그것은 좋고 읽어야 합니다 — 하지만 무엇 뒤에 있는 왜를 설명하는 동반자입니다.

시리즈를 따라가는 방법

시리즈의 각 글은 단독으로 읽기에 충분히 독립적이지만, 서로 쌓아올리는 방식으로 구성됩니다. 처음부터 시작한다면 순서대로 읽을 것을 권장합니다. 특정 부분을 채우러 들어오는 경우에도 괜찮습니다 — 중요한 경우 선행 글에 대한 링크를 달겠습니다.

각 글의 코드는 GitHub에서 제공됩니다. 진행하면서 링크를 공유하겠습니다.

다음 글에서 만나요.

C# Union 유형: 차별된 Union이 마침내 등장합니다.

Wed, 01 Apr 2026 00:00:00 +0000

상당한 시간 동안 C#을 작성해 왔다면 “여러 가지 중 하나"가 될 수 있는 것을 모델링하려고 할 때 벽에 부딪혔을 가능성이 높습니다. 어쩌면 성공 값이나 오류를 반환하는 메서드가 필요할 수도 있습니다. 어쩌면 각각 완전히 다른 데이터를 사용하는 신용카드, 은행 송금, 디지털 지갑을 처리하는 결제 시스템을 구축하고 있었을 수도 있습니다. 아니면 그냥 F#이나 Rust를 보고 “왜 C#에서는 그걸 가질 수 없지?“라고 생각했을 수도 있습니다.

기다림이 거의 끝났습니다. 차별화된 노동조합이 C#으로 출시됩니다.

이는 수년간 가장 많이 요청된 언어 기능 중 하나였으며 커뮤니티 토론은 2017년 이전부터 이어졌습니다. C# 언어 디자인 팀은 철저한 패턴 일치를 통해 폐쇄형 계층 구조를 정의하기 위해 union 키워드를 도입하는 제안을 작업해 왔습니다. 이 게시물에서는 차별적 공용체(discriminated Union)가 무엇인지, 왜 그렇게 중요한지, 지금까지 우리가 이를 어떻게 속였는지, 그리고 제안된 구문이 실제로 어떤 모습인지에 대해 각각에 대한 실제 코드 예제를 통해 안내하고 싶습니다.

시작하기 전에 간단히 알아두어야 할 점은 이 글을 쓰는 시점에서 통합 유형 기능은 아직 제안 및 미리 보기 단계에 있다는 것입니다. 여기서 설명하는 구문과 동작은 공개적으로 사용 가능한 최신 디자인 문서와 C# 언어 디자인 팀의 토론을 기반으로 합니다. 최종 출시 이전에는 상황이 변경될 수 있습니다. 확정된 사항과 아직 논의 중인 사항에 대해 명확히 말씀드리겠습니다.

차별적 노동조합이란 무엇입니까?

본질적으로 구별된 공용체(때때로 “태그된 공용체” 또는 “합계 유형"이라고도 함)는 각 변형이 서로 다른 데이터를 전달할 수 있는 고정된 가능한 값 세트 중 하나를 보유할 수 있는 유형입니다. “구별된” 부분은 런타임이 항상 어떤 변형인지 알고 있음을 의미합니다. 이를 식별하는 태그가 있습니다.

enum처럼 생각하면 되지만, 각 구성원은 자신만의 데이터 페이로드를 운반할 수 있습니다.

다른 언어를 사용해 본 적이 있다면 아마도 이전에 이 개념을 본 적이 있을 것입니다.

**F#**는 첫날부터 차별적인 노동조합을 운영해 왔습니다.

type Shape =
 | Circle of radius: float
 | Rectangle of width: float * height: float
 | Triangle of base: float * height: float

Rust는 동일한 아이디어로 enum를 사용합니다.

enum Shape {
 Circle { radius: f64 },
 Rectangle { width: f64, height: f64 },
 Triangle { base: f64, height: f64 },
}

TypeScript는 태그된 공용체와 비슷한 결과를 얻습니다.

type Shape =
 | { kind: "circle"; radius: number }
 | { kind: "rectangle"; width: number; height: number }
 | { kind: "triangle"; base: number; height: number };

이러한 모든 경우에 컴파일러는 가능한 모든 변형을 알고 있으며 사용자가 이를 모두 처리하도록 강제할 수 있습니다. 이것이 초능력입니다: 완전성 검사. 새로운 변형을 추가하면 컴파일러는 이를 처리하는 것을 잊어버린 모든 곳에서 알려줍니다.

C#에서는 이를 표현하는 최고의 방법이 없었습니다. 지금까지.

오늘날 노동조합을 시뮬레이션하는 방법

수년에 걸쳐 C# 커뮤니티에서는 각각 고유한 장단점이 있는 여러 가지 해결 방법을 생각해 냈습니다. 가장 일반적인 접근 방식을 살펴보겠습니다.

상속이 포함된 추상 레코드

최신 C#에서 가장 관용적인 해결 방법은 봉인된 파생 유형이 있는 추상 레코드를 사용하는 것입니다.

public abstract record Shape
{
 public sealed record Circle(double Radius) : Shape;
 public sealed record Rectangle(double Width, double Height) : Shape;
 public sealed record Triangle(double Base, double Height) : Shape;

 private Shape() { } // Prevent external inheritance
}

이것은 합리적으로 잘 작동합니다. 불변성, 값 평등을 얻고 패턴 일치를 사용할 수 있습니다.

double Area(Shape shape) => shape switch
{
 Shape.Circle c => Math.PI * c.Radius * c.Radius,
 Shape.Rectangle r => r.Width * r.Height,
 Shape.Triangle t => 0.5 * t.Base * t.Height,
 _ => throw new InvalidOperationException("Unknown shape")
};
```그러나 중요한 단점이 있습니다. 컴파일러는 계층 구조가 닫혀 있다는 것을 모르므로 항상 `_` 폐기 팔이 필요합니다. 그렇지 않으면 경고가 표시됩니다. 새로운 변형을 추가하면 컴파일러는 이를 처리하는 것을 잊은 모든 위치에 대해 알려주지 않습니다. 폐기 시 자동으로 이를 삼켜버립니다. 그것은 목적을 완전히 무너뜨립니다.

### 원오브 도서관

또 다른 인기 있는 접근 방식은 [OneOf](https://github.com/mcintyre321/OneOf) NuGet 패키지입니다.

```csharp
public OneOf<Success<Order>, NotFound, ValidationError> ProcessOrder(OrderRequest request)
{
 // ...
}

// Usage
var result = ProcessOrder(request);
result.Switch(
 success => Console.WriteLine($"Order {success.Value.Id} processed"),
 notFound => Console.WriteLine("Order not found"),
 error => Console.WriteLine($"Validation failed: {error.Message}")
);

OneOf는 일반 유형 매개변수를 통해 컴파일 타임에 완전성 검사를 제공합니다. 그러나 위치 일치(첫 번째 유형, 두 번째 유형 등)에 의존하고 일반 시그니처는 다루기 힘들 정도로 빠르며 언어의 패턴 일치와 통합되지 않습니다. 영리한 해킹이지만 여전히 해킹입니다.

수동 열거형 + 데이터 패턴

일부 개발자는 enum 태그와 데이터 컨테이너를 사용하여 클래식 경로를 사용합니다.

public enum PaymentType { CreditCard, BankTransfer, DigitalWallet }

public class Payment
{
 public PaymentType Type { get; init; }
 public CreditCardInfo? CreditCard { get; init; }
 public BankTransferInfo? BankTransfer { get; init; }
 public DigitalWalletInfo? DigitalWallet { get; init; }
}

이것은 깨지기 쉽습니다. Type를 CreditCard로 설정하는 것 외에는 BankTransfer 속성을 채우는 것을 막을 수 없습니다. 컴파일러는 도움을 줄 수 없으며 모든 곳에서 런타임 오류와 null 검사가 발생하게 됩니다. 이는 유형 모델링에 대한 “문자열 유형” 접근 방식이며 확장되지 않습니다.

이러한 접근 방식은 모두 근본적인 문제를 공유합니다. 언어를 사용하는 대신 언어와 싸우고 있습니다. 컴파일러는 닫힌 가능성 집합에 대해 추론할 수 없으므로 차별 공용체의 가장 귀중한 속성인 철저한 검사를 잃게 됩니다.

C# 제안: `union` 키워드

C# 언어 팀의 제안에는 각각 선택적으로 데이터를 전달하는 명명된 멤버의 닫힌 집합을 정의하는 전용 union 키워드가 도입되었습니다. 제안된 기본 구문은 다음과 같습니다.

union Shape
{
 Circle(double Radius),
 Rectangle(double Width, double Height),
 Triangle(double Base, double Height)
}

그게 다야. 깔끔하고 간결하며 즉시 읽을 수 있습니다. 공용체 내부의 각 구성원은 자체 데이터를 사용하여 고유한 변형을 정의합니다. 컴파일러는 Shape가 이 세 가지 중 하나만 될 수 있다는 것을 알고 있습니다.

내부적으로 컴파일러는 추상 레코드를 사용하여 직접 작성하는 것과 유사하지만 컴파일러가 유형의 폐쇄적 특성을 완전히 인식하는 봉인된 유형 계층 구조를 생성합니다. 이는 컴파일러가 패턴 일치에 철저함을 적용할 수 있다는 것을 의미하며, 이것이 주요 이점입니다.

가치 전용 회원

조합원은 데이터를 가지고 다닐 필요가 없습니다. 데이터를 전달하는 멤버와 단순 값 멤버를 혼합할 수 있습니다.

union Option<T>
{
 Some(T Value),
 None
}

이는 기능적 프로그래머가 수년간 C#에서 요구해 왔던 고전적인 Option/Maybe 유형입니다. None에는 데이터가 없습니다. 단지 태그일 뿐입니다.

일반 공용체

위의 Option<T> 예제에서 볼 수 있듯이 공용체는 제네릭을 지원합니다. 다음은 좀 더 관련된 예입니다.

union Result<T, E>
{
 Ok(T Value),
 Error(E Err)
}

이는 예상되는 실패 사례에 대한 예외에 의존하지 않는 전체 오류 처리 스타일을 열어줍니다. 이는 수년간 Rust 및 함수형 언어의 표준 관행이었습니다.

메소드가 있는 공용체

또한 이 제안은 공용체가 다른 유형과 마찬가지로 메소드, 계산된 속성 및 구현 인터페이스를 가질 수 있도록 허용합니다.```csharp union Shape { Circle(double Radius), Rectangle(double Width, double Height), Triangle(double Base, double Height);

public double Area => this switch
{
Circle(var r) => Math.PI * r * r,
Rectangle(var w, var h) => w * h,
Triangle(var b, var h) => 0.5 * b * h
};
public double Perimeter => this switch
{
Circle(var r) => 2 * Math.PI * r,
Rectangle(var w, var h) => 2 * (w + h),
Triangle(var b, var h) => b + h + Math.Sqrt(b * b + h * h)
};

}


`switch` 내부의 `Area` 및 `Perimeter` 표현식에는 기본 arm이 필요하지 않습니다. 컴파일러는 통합이 철저하다는 것을 알고 있습니다. 즉, 세 가지 변형만 있고 세 가지 모두 처리됩니다. 나중에 네 번째 변형을 추가하면 컴파일러는 이를 처리하지 않는 모든 `switch`에 플래그를 지정합니다.

## 패턴 매칭 통합

패턴 일치는 버전 7.0부터 C#에서 발전해 왔으며 공용체 형식은 해당 시스템의 일급 시민으로 설계되었습니다.

### 철저한 스위치 표현

가장 영향력 있는 기능은 철저한 스위치 확인입니다. 공용체를 사용하면 컴파일러는 가능한 모든 경우를 **알고** 있습니다.

```csharp
string Describe(Shape shape) => shape switch
{
 Circle(var r) => $"A circle with radius {r}",
 Rectangle(var w, var h) => $"A {w}x{h} rectangle",
 Triangle(var b, var h) => $"A triangle with base {b} and height {h}"
};

폐기 팔이 없습니다. 아니요 _ => throw new NotImplementedException(). 대소문자를 잊어버린 경우 컴파일러는 경고가 아닌 오류를 내보냅니다. 이는 안전성이 근본적으로 개선된 것입니다.

중첩 패턴 일치

공용체는 중첩된 패턴으로 자연스럽게 구성됩니다.

union Expr
{
 Literal(double Value),
 Add(Expr Left, Expr Right),
 Multiply(Expr Left, Expr Right),
 Negate(Expr Inner)
}

double Evaluate(Expr expr) => expr switch
{
 Literal(var v) => v,
 Add(var left, var right) => Evaluate(left) + Evaluate(right),
 Multiply(var left, var right) => Evaluate(left) * Evaluate(right),
 Negate(var inner) => -Evaluate(inner)
};

이러한 종류의 재귀적 데이터 구조는 컴파일러, 인터프리터, 규칙 엔진 및 수학적 모델링에서 매우 일반적입니다. 현재 C#에서는 깊은 클래스 계층 구조와 방문자 패턴이 필요합니다. 공용체를 사용하면 코드가 훨씬 더 간단해집니다.

보호 조항

공용체와의 패턴 일치는 예상한 대로 when 가드를 지원합니다.

string Classify(Shape shape) => shape switch
{
 Circle(var r) when r > 100 => "Large circle",
 Circle(var r) when r > 10 => "Medium circle",
 Circle(_) => "Small circle",
 Rectangle(var w, var h) when w == h => "Square",
 Rectangle _ => "Rectangle",
 Triangle _ => "Triangle"
};

실제 예

공용체 유형이 코드를 극적으로 향상시키는 몇 가지 실제 시나리오를 살펴보겠습니다.

결과 패턴: 예상되는 오류에 대한 예외 교체

최신 애플리케이션 개발에서 가장 일반적인 패턴 중 하나는 제어 흐름에 대한 예외를 사용하지 않고 성공하거나 실패할 수 있는 작업을 나타내는 것입니다. 예외는 예외적이어야 합니다(예: 네트워크 오류 또는 메모리 부족 상태 등). 유효성 검사 오류 또는 “찾을 수 없음” 결과는 예상된 결과이며 예외는 아닙니다.

union Result<T, E>
{
 Ok(T Value),
 Error(E Err)
}

union OrderError
{
 NotFound(Guid OrderId),
 InsufficientStock(string ProductId, int Requested, int Available),
 PaymentDeclined(string Reason),
 ValidationFailed(IReadOnlyList<string> Errors)
}

Result<Order, OrderError> ProcessOrder(OrderRequest request)
{
 if (!Validate(request, out var errors))
 return new ValidationFailed(errors);

 var product = catalog.Find(request.ProductId);
 if (product is null)
 return new NotFound(request.OrderId);

 if (product.Stock < request.Quantity)
 return new InsufficientStock(request.ProductId, request.Quantity, product.Stock);

 var paymentResult = paymentGateway.Charge(request.Payment);
 if (!paymentResult.Success)
 return new PaymentDeclined(paymentResult.Message);

 var order = CreateOrder(request, product);
 return new Ok(order);
}

그런 다음 호출자는 가능한 모든 결과를 처리해야 합니다.

var result = ProcessOrder(request);

var response = result switch
{
 Ok(var order) => Results.Created($"/orders/{order.Id}", order),
 Error(NotFound(var id)) => Results.NotFound($"Order {id} not found"),
 Error(InsufficientStock(var pid, var req, var avail)) =>
 Results.Conflict($"Product {pid}: requested {req}, only {avail} available"),
 Error(PaymentDeclined(var reason)) =>
 Results.UnprocessableEntity($"Payment declined: {reason}"),
 Error(ValidationFailed(var errors)) =>
 Results.BadRequest(new { Errors = errors })
};

try-catch 블록도 없고, 잊어버린 예외 유형도 없고, 런타임에 예상치 못한 일도 없습니다. 모든 실패 모드는 유형 서명에 표시되며 컴파일러에 의해 적용됩니다. 이는 API 안정성이 크게 향상되었습니다.

도메인 모델링: 결제 유형

다음은 전자상거래 시스템에서 다양한 결제 방법을 처리하는 실제 도메인 모델링 예입니다.

union PaymentMethod
{
 CreditCard(string CardNumber, string Expiry, string Cvv),
 BankTransfer(string Iban, string Bic),
 DigitalWallet(string Provider, string Token),
 CashOnDelivery
}

decimal CalculateProcessingFee(PaymentMethod method, decimal amount) => method switch
{
 CreditCard _ => amount * 0.029m + 0.30m,
 BankTransfer _ => 1.50m,
 DigitalWallet(provider: "PayPal", _) => amount * 0.034m + 0.35m,
 DigitalWallet _ => amount * 0.025m,
 CashOnDelivery => 4.99m
};

string FormatForReceipt(PaymentMethod method) => method switch
{
 CreditCard(var num, _, _) => $"Credit Card ending in {num[^4..]}",
 BankTransfer(var iban, _) => $"Bank Transfer ({iban[..4]}****)",
 DigitalWallet(var provider, _) => $"Digital Wallet ({provider})",
 CashOnDelivery => "Cash on Delivery"
};

이를 5개의 파일에 분산된 5개의 서로 다른 구현이 있는 인터페이스 또는 추상 클래스가 있고 방문자 패턴이 맨 위에 있을 수 있는 현재 접근 방식과 비교해 보세요. 통합 접근 방식은 데이터 정의와 작업을 함께 유지하고 읽기 가능하며 철저하게 검사합니다.

상태 머신

상태 머신은 주문 처리, 워크플로 엔진, 연결 관리, UI 상태 등 소프트웨어의 모든 곳에 있습니다. 노동조합은 이를 명시적이고 안전하게 만듭니다.

union ConnectionState
{
 Disconnected,
 Connecting(string Host, int Port, DateTime StartedAt),
 Connected(string Host, int Port, TcpClient Client),
 Reconnecting(string Host, int Port, int Attempt, TimeSpan Delay),
 Failed(string Host, Exception Error)
}

ConnectionState HandleEvent(ConnectionState state, ConnectionEvent evt) => (state, evt) switch
{
 (Disconnected, Connect(var host, var port)) =>
 new Connecting(host, port, DateTime.UtcNow),

 (Connecting(var h, var p, _), ConnectionSucceeded(var client)) =>
 new Connected(h, p, client),

 (Connecting(var h, var p, _), ConnectionFailed(var ex)) =>
 new Reconnecting(h, p, Attempt: 1, Delay: TimeSpan.FromSeconds(1)),

 (Reconnecting(var h, var p, var attempt, _), ConnectionSucceeded(var client)) =>
 new Connected(h, p, client),

 (Reconnecting(var h, var p, var attempt, _), ConnectionFailed(var ex)) when attempt >= 5 =>
 new Failed(h, ex),

 (Reconnecting(var h, var p, var attempt, _), ConnectionFailed(_)) =>
 new Reconnecting(h, p, attempt + 1, TimeSpan.FromSeconds(Math.Pow(2, attempt))),

 (Connected(_, _, var client), Disconnect) =>
 new Disconnected,

 _ => state // Ignore events that don't apply to current state
};

각 상태는 해당 상태와 관련된 데이터를 정확하게 전달합니다. 해당 변형에 존재하지 않기 때문에 Connecting 상태에 있을 때 실수로 TcpClient에 액세스할 수 없습니다. 유형 시스템은 상태 시스템의 불변성을 적용합니다.

직렬화 및 상호 운용성 고려 사항공용체 유형과 관련하여 즉시 떠오르는 실용적인 질문 중 하나는 다음과 같습니다. 이를 어떻게 직렬화합니까? API를 구축하거나 데이터를 저장하는 경우 올바르게 작동하려면 JSON 직렬화가 필요합니다.

디자인 팀은 공용체 유형에 대한 기본 제공 System.Text.Json 지원을 논의해 왔습니다. 예상되는 접근 방식에는 판별자 속성을 사용한 직렬화가 포함됩니다.

{
 "$type": "Circle",
 "radius": 5.0
}

{
 "$type": "Rectangle",
 "width": 10.0,
 "height": 20.0
}

이는 JsonDerivedType 특성을 사용하여 .NET 7에 도입된 기존 다형성 직렬화 지원과 일치합니다. 기본적으로 변형 이름을 유형 판별자로 사용하여 공용체는 기본적으로 System.Text.Json와 함께 작동할 것으로 예상됩니다.

Entity Framework Core의 경우 TPH(계층별 테이블) 상속 매핑이 이미 작동하는 방식과 유사하게 판별자 열을 사용하여 공용체 값을 저장하는 접근 방식이 있을 가능성이 높습니다. 정확한 EF Core 통합은 아직 설계 중이지만 폐쇄형 계층 구조를 처리하기 위한 인프라는 이미 존재합니다.

공용체가 내부적으로 표준 IL 클래스 계층 구조로 컴파일되기 때문에 다른 .NET 언어와의 상호 운용이 원활해야 한다는 점은 주목할 가치가 있습니다. C# 공용체를 사용하는 F# 코드는 이를 표준 형식 계층 구조로 간주하고 그 반대의 경우도 마찬가지입니다.

사용 방법

작성 시점을 기준으로 공용체 유형은 최신 .NET SDK 미리 보기에서 미리 보기 기능으로 사용할 수 있습니다. 제안된 구문을 실험하려면 다음을 수행해야 합니다.

최신 .NET 미리보기 SDK 설치
프로젝트 파일에서 미리보기 언어 버전을 활성화합니다.

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
 <TargetFramework>net10.0</TargetFramework>
 <LangVersion>preview</LangVersion>
 </PropertyGroup>
</Project>

미리보기 기능은 변경될 수 있다는 점에 유의하세요. 구문, 동작 및 컴파일러 진단은 최종 릴리스 이전에 크게 발전할 수 있습니다. 미리 보기 언어 기능에 의존하는 프로덕션 코드를 출시하지 마세요. 하지만 반드시 이를 실험하고 피드백을 제공하세요. C# 팀은 csharplang 저장소 토론을 적극적으로 모니터링합니다.

제안의 진행 상황을 확인하고 싶다면 주요 시청 장소는 다음과 같습니다.

언어 디자인 토론을 위한 dotnet/csharplang 저장소
컴파일러 구현 진행 상황을 위한 dotnet/roslyn 저장소
공식 공지를 위한 .NET 블로그

기존 접근방식과의 비교

다양한 접근 방식이 어떻게 결합되어 있는지 확인할 수 있도록 간단한 비교를 해보겠습니다.

기능	초록기록	OneOf<T1,T2>	열거형 + 데이터	노동조합 유형
완전성 검사	❌ 아니요	✅ 예	❌ 아니요	✅ 예
패턴 매칭	✅ 예	❌ 한정	❌ 매뉴얼	✅ 네이티브
컴파일러 강제 종료	❌ 아니요	✅ 예	❌ 아니요	✅ 예
변형별 데이터	✅ 예	✅ 예	⚠️ 깨지기 쉬움	✅ 예
가독성	⚠️ 자세한 내용	⚠️ 위치	❌ 가난	✅ 우수
직렬화	✅ 매뉴얼	⚠️ 복합	✅ 매뉴얼	✅ 내장
상용구	⚠️ 보통	✅ 낮음	⚠️ 높음	✅ 최소
외부 종속성 없음	✅ 예	❌ 누겟	✅ 예	✅ 예

이것이 .NET 생태계에 미치는 영향

차별적인 공용체의 도입은 전체 .NET 생태계에 파급력을 미칠 것입니다. 내가 기대하는 내용은 다음과 같습니다.

라이브러리 디자인은 개선될 것입니다. 현재 “찾을 수 없음"을 나타내거나 유효성 검사 실패에 대한 예외를 발생시키기 위해 null를 반환하는 API는 대신 Result<T, E> 유형을 반환할 수 있습니다. 이는 유형 서명에서 오류 모드를 명시적으로 만듭니다. 문서나 소스 코드를 읽는 것이 아니라 메서드 서명을 보면 무엇이 잘못될 수 있는지 알 수 있습니다.

도메인 모델링의 표현력이 더욱 풍부해졌습니다. 문제 도메인과 코드 표현 사이의 격차가 극적으로 줄어듭니다. 도메인 전문가가 “지불은 신용 카드, 은행 송금 또는 대금 상환이 될 수 있습니다"라고 말하면 이를 상속 계층 구조로 변환하는 대신 통합으로 직접 모델링할 수 있습니다.

C# 개발자는 F# 아이디어에 접근할 수 있습니다. 많은 C# 개발자는 멀리서 F#의 형식 시스템을 존경했지만 조직에서 F#을 채택할 수 없었습니다. Union 형식은 F#의 가장 강력한 기능 중 하나를 C#에 가져오며 이는 전체 .NET 생태계에 도움이 됩니다.

런타임 오류가 줄어듭니다. 완전성 검사만으로도 전체 버그 범주를 방지할 수 있습니다. 새로운 변형을 공용체에 추가할 때마다 컴파일러는 업데이트가 필요한 코드베이스의 모든 위치를 안내합니다. 더 이상 잊어버린 switch 사례가 없으며, 프로덕션에서만 나타나는 기본 분기에 더 이상 NotImplementedException가 없습니다.

결론

차별적인 공용체는 거의 10년 동안 C# 커뮤니티의 희망 목록 1위에 올랐으며 그럴 만한 이유가 있습니다. 이는 유형 시스템의 근본적인 격차, 즉 컴파일러 강제 안전을 통해 “여러 가지 중 하나"가 될 수 있는 데이터를 모델링하는 기능을 해결합니다.

제안된 union 키워드는 C#의 패턴 일치와 긴밀하게 통합되고, 제네릭과 함께 작동하고, 메서드 및 인터페이스를 지원하고, 런타임이 아닌 컴파일 타임에 버그를 잡는 철저한 검사를 가능하게 하는 깔끔하고 간결한 구문을 제공합니다.

도메인 모델을 구축하든, 명시적 오류 유형으로 API를 설계하든, 상태 머신을 구현하든, 아니면 어색한 상속 계층 구조를 좀 더 자연스러운 것으로 대체하려고 하든 공용체 유형은 C# 작성 방식을 바꿀 것입니다.

우리는 이것을 오랫동안 기다려왔습니다. 구문은 우아하고 기존 언어 기능과의 통합은 사려 깊으며 전체 .NET 생태계에 실질적인 영향을 미칠 것입니다.

미리 보기 릴리스를 주시하고, 기능을 실험하고, 언어 디자인 팀에 피드백을 제공하세요. 이것은 일단 사용해 보면 이 기능 없이 어떻게 살았는지 궁금해하게 되는 기능 중 하나입니다.

시맨틱 커널을 사용하여 C#으로 RAG 시스템 구축

Wed, 18 Mar 2026 00:00:00 +0000

소개

회사 문서, 제품 사양, 내부 지식 기반 등 자신의 데이터에 대한 질문에 답하기 위해 LLM을 사용해 본 적이 있다면 아마도 환각을 느끼거나 “그 내용에 대한 정보가 없습니다.“라고만 말하는 것을 눈치챘을 것입니다. 모델은 자신이 훈련받은 내용만 알고 있기 때문입니다.

RAG(Retrieval-Augmented Generation)가 이 문제를 해결합니다. 데이터에 대한 모델을 미세 조정하는 대신 쿼리 시 문서의 관련 청크를 검색하여 LLM에 컨텍스트로 전달합니다. 그런 다음 모델은 실제 데이터를 기반으로 답변을 생성합니다.

이 게시물에서는 Semantic Kernel을 사용하여 C#으로 완전한 RAG 파이프라인을 구축하는 과정을 안내하겠습니다.

RAG 작동 방식

흐름은 간단합니다.

수집: 문서를 청크로 분할하고, 각 청크에 대한 임베딩을 생성하고, 이를 벡터 데이터베이스에 저장합니다.
쿼리: 사용자가 질문을 하면 쿼리에 대한 임베딩을 생성하고 벡터 데이터베이스에서 유사한 청크를 검색합니다.
생성: 검색된 청크를 사용자의 질문과 함께 LLM에 컨텍스트로 전달합니다.

그게 다야. 마법은 임베딩에 있습니다. 임베딩은 텍스트의 의미론적 의미를 벡터로 캡처하므로 정확한 단어가 일치하지 않는 경우에도 관련 콘텐츠를 찾을 수 있습니다.

전제 조건

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI
dotnet add package Microsoft.Extensions.VectorData.Abstractions
dotnet add package Microsoft.SemanticKernel.Connectors.InMemory

프로덕션의 경우 Azure AI Search, Qdrant, Pinecone 또는 기타 지원되는 벡터 데이터베이스에 대한 메모리 내 저장소를 교체합니다. 하지만 인메모리는 학습과 프로토타입 제작에 적합합니다.

커널 설정

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.InMemory;
using Microsoft.SemanticKernel.Embeddings;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"]);

builder.AddAzureOpenAITextEmbeddingGeneration(
 deploymentName: "text-embedding-3-small",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"]);

var kernel = builder.Build();

두 가지 모델이 필요합니다. 하나는 채팅 완료(질문에 답변)용이고 다른 하나는 임베딩 생성(텍스트를 벡터로 변환)용입니다.

데이터 모델 정의

벡터 저장소에서 문서 청크를 나타내려면 클래스가 필요합니다.

using Microsoft.Extensions.VectorData;

public class DocumentChunk
{
 [VectorStoreRecordKey]
 public string Id { get; set; } = Guid.NewGuid().ToString();

 [VectorStoreRecordData]
 public string Content { get; set; } = string.Empty;

 [VectorStoreRecordData]
 public string Source { get; set; } = string.Empty;

 [VectorStoreRecordData]
 public int ChunkIndex { get; set; }

 [VectorStoreRecordVector(1536)]
 public ReadOnlyMemory<float> Embedding { get; set; }
}

VectorStoreRecordVector(1536) 속성은 벡터 저장소에 임베딩의 차원을 알려줍니다. text-embedding-3-small 모델은 1536차원 벡터를 생성합니다.

문서 청킹

임베딩을 생성하기 전에 문서를 관리 가능한 덩어리로 분할해야 합니다. 다음은 간단한 텍스트 분할기입니다.

public static class TextChunker
{
 public static List<string> SplitText(string text, int maxChunkSize = 500, int overlap = 50)
 {
 var chunks = new List<string>();
 var paragraphs = text.Split("\n\n", StringSplitOptions.RemoveEmptyEntries);
 var currentChunk = new System.Text.StringBuilder();

 foreach (var paragraph in paragraphs)
 {
 if (currentChunk.Length + paragraph.Length > maxChunkSize && currentChunk.Length > 0)
 {
 chunks.Add(currentChunk.ToString().Trim());

 // Keep overlap from the end of the previous chunk
 var overlapText = currentChunk.ToString();
 currentChunk.Clear();
 if (overlapText.Length > overlap)
 {
 currentChunk.Append(overlapText[^overlap..]);
 currentChunk.Append(' ');
 }
 }

 currentChunk.Append(paragraph);
 currentChunk.Append("\n\n");
 }

 if (currentChunk.Length > 0)
 {
 chunks.Add(currentChunk.ToString().Trim());
 }

 return chunks;
 }
}

겹치는 부분은 중요합니다. 이는 청크 사이의 경계에 있는 컨텍스트가 손실되지 않도록 보장합니다. 관련 문장이 두 개의 덩어리로 분할되는 경우 중복은 그 중 적어도 하나에 완전히 표시된다는 것을 의미합니다.

문서 수집 중

이제 벡터 저장소에 문서를 수집하기 위해 모든 것을 하나로 묶어 보겠습니다.

var vectorStore = new InMemoryVectorStore();
var collection = vectorStore.GetCollection<string, DocumentChunk>("documents");
await collection.CreateCollectionIfNotExistsAsync();

var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

async Task IngestDocument(string content, string source)
{
 var chunks = TextChunker.SplitText(content);

 for (int i = 0; i < chunks.Count; i++)
 {
 var embedding = await embeddingService.GenerateEmbeddingAsync(chunks[i]);

 var chunk = new DocumentChunk
 {
 Content = chunks[i],
 Source = source,
 ChunkIndex = i,
 Embedding = embedding
 };

 await collection.UpsertAsync(chunk);
 }

 Console.WriteLine($"✅ Ingested {chunks.Count} chunks from {source}");
}

// Ingest some documents
var doc1 = await File.ReadAllTextAsync("docs/product-guide.md");
var doc2 = await File.ReadAllTextAsync("docs/faq.md");
var doc3 = await File.ReadAllTextAsync("docs/troubleshooting.md");

await IngestDocument(doc1, "product-guide.md");
await IngestDocument(doc2, "faq.md");
await IngestDocument(doc3, "troubleshooting.md");

상황에 맞는 답변 생성

이제 RAG 부분입니다. 검색된 청크를 가져와서 프롬프트에 컨텍스트로 포함시킵니다.

using Microsoft.SemanticKernel.ChatCompletion;

var chatService = kernel.GetRequiredService<IChatCompletionService>();

async Task<string> AskAsync(string question)
{
 // Step 1: Retrieve relevant chunks
 var relevantChunks = await SearchAsync(question);

 // Step 2: Build context from chunks
 var context = string.Join("\n\n---\n\n",
 relevantChunks.Select(c => $"[Source: {c.Source}]\n{c.Content}"));

 // Step 3: Generate answer with context
 var history = new ChatHistory();
 history.AddSystemMessage($$"""
 You are a helpful assistant that answers questions based on the provided context.
 Use ONLY the information from the context to answer. If the context doesn't contain
 enough information to answer the question, say "I don't have enough information
 to answer that question."

 Do not make up information. Always cite the source document when possible.

 Context:
 {{context}}
 """);

 history.AddUserMessage(question);

 var response = await chatService.GetChatMessageContentAsync(history);
 return response.Content ?? "No response generated.";
}

사용하기

// Ask questions about your documents
var answer1 = await AskAsync("How do I reset my password?");
Console.WriteLine($"Q: How do I reset my password?\nA: {answer1}\n");

var answer2 = await AskAsync("What are the system requirements?");
Console.WriteLine($"Q: What are the system requirements?\nA: {answer2}\n");

var answer3 = await AskAsync("What's the capital of France?");
Console.WriteLine($"Q: What's the capital of France?\nA: {answer3}\n");
// Should respond with "I don't have enough information" since it's not in the docs

프로덕션으로 이동

인메모리 벡터 저장소는 프로토타입 제작에 적합하지만 프로덕션에는 영구 벡터 데이터베이스가 필요합니다. Semantic Kernel에는 여러 옵션에 대한 커넥터가 있습니다.

# Azure AI Search
dotnet add package Microsoft.SemanticKernel.Connectors.AzureAISearch

# Qdrant
dotnet add package Microsoft.SemanticKernel.Connectors.Qdrant

# Redis
dotnet add package Microsoft.SemanticKernel.Connectors.Redis

모두 동일한 IVectorStore 인터페이스를 구현하므로 스와핑은 간단합니다.

// Instead of InMemoryVectorStore, use:
using Azure;
using Microsoft.SemanticKernel.Connectors.AzureAISearch;

var vectorStore = new AzureAISearchVectorStore(
 new Azure.Search.Documents.Indexes.SearchIndexClient(
 new Uri(config["AzureAISearch:Endpoint"]),
 new AzureKeyCredential(config["AzureAISearch:ApiKey"])));
```다른 모든 것은 동일하게 유지됩니다. 그것이 바로 추상화의 아름다움이다.

## RAG 시스템 구축 팁

제가 힘들게 배운 몇 가지 사항은 다음과 같습니다.

- **청크 크기가 매우 중요합니다.** 너무 작으면 맥락을 잃게 됩니다. 너무 크면 관련 없는 콘텐츠에 토큰을 낭비하게 됩니다. 500-800개의 토큰으로 시작하고 데이터에 따라 조정하세요.
- **겹침은 경계 문제를 방지합니다.** 일반적으로 청크 사이에 50-100개의 토큰이 겹치는 것으로 충분합니다.
- **생각보다 더 많은 것을 검색합니다.** `topK = 5`로 시작하고 노이즈가 너무 많으면 줄이세요. 관련 부분을 놓치는 것보다 추가적인 맥락을 갖는 것이 더 낫습니다.
- **시스템 프롬프트가 중요합니다.** 제공된 컨텍스트만 사용하는 것에 대해 매우 명시적으로 설명하세요. 해당 지침이 없으면 모델은 "훈련 데이터를 기반으로" 즐거운 환각을 느낄 것입니다.
- **소스를 추적하세요.** 답변의 출처를 인용할 수 있도록 항상 청크와 함께 메타데이터를 저장하세요. 사용자는 출처를 확인할 수 있을 때 답변을 더 신뢰합니다.
- **필요한 경우 순위를 다시 지정하세요.** 벡터 유사성이 완벽하지 않습니다. 중요한 애플리케이션의 경우 크로스 인코더 모델을 사용하여 순위 재지정 단계를 추가하면 정밀도가 향상됩니다.

## 결론

RAG는 현재 AI에서 가장 실용적인 패턴 중 하나입니다. 미세 조정 없이 자체 데이터에 대해 AI 기반 Q&A 시스템을 구축할 수 있으며, Semantic Kernel을 사용하면 C#에서 놀라울 정도로 깔끔하게 정리됩니다. 인메모리 저장소로 시작하여 청크와 프롬프트를 올바르게 얻은 다음, 제작 준비가 되면 실제 벡터 데이터베이스로 교체하세요.

즐거운 코딩하세요!

## 리소스

- [의미론적 커널 벡터 저장소 문서](https://learn.microsoft.com/en-us/semantic-kernel/concepts/vector-store-connectors/)
- [Azure AI Search를 사용한 RAG 패턴](https://learn.microsoft.com/en-us/azure/search/retrieval-augmented-generation-overview)
- [텍스트 임베딩 모델](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embeddings)

Microsoft Agent Framework를 사용하여 에이전트 워크플로 구축

Tue, 10 Feb 2026 00:00:00 +0000

소개

Microsoft의 에이전트 프레임워크에 대한 이전 게시물을 읽어보셨다면 개별 에이전트는 물론 다중 에이전트 그룹 채팅을 만드는 방법도 아실 것입니다. 그러나 실제 시나리오에서는 에이전트가 특정 순서로 실행하고, 결과를 서로 전달하고, 결과에 따라 분기 논리를 처리하는 워크플로와 같이 좀 더 구조화된 작업이 필요한 경우가 많습니다.

이것이 바로 Agent Framework의 워크플로 기능이 제공하는 것입니다. 에이전트를 그룹 채팅에 투입하고 에이전트가 해결하기를 바라는 대신 에이전트 간의 명시적인 단계, 종속성 및 데이터 흐름을 정의합니다.

상담사 워크플로란 무엇인가요?

에이전트 워크플로를 파이프라인처럼 생각하세요. 각 단계는 전문 에이전트에 의해 처리되며 한 단계의 출력이 다음 단계로 전달됩니다. 단계를 순차적으로, 병렬로 실행하거나 결과에 따라 조건부로 실행할 수 있습니다.

몇 가지 예:

콘텐츠 파이프라인: 연구 → 초안 → 검토 → 게시
데이터 처리: 추출 → 변환 → 검증 → 로드
고객지원 : 분류 → 전달 → 대응 → 후속 조치

전제 조건

최신 Agent Framework 패키지가 있는지 확인하세요.

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core

그리고 Azure OpenAI 또는 OpenAI 엔드포인트가 구성되었습니다.

순차 워크플로 구축

연구원, 작가, 편집자라는 세 명의 에이전트로 콘텐츠 제작 워크플로를 구축해 보겠습니다.

에이전트 정의

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;

var kernel = Kernel.CreateBuilder()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: config["AzureOpenAI:Endpoint"],
 apiKey: config["AzureOpenAI:ApiKey"])
 .Build();

var researcher = new ChatCompletionAgent
{
 Name = "Researcher",
 Instructions = """
 You are a research specialist. Given a topic, find key facts, statistics,
 and talking points. Return a structured research brief with bullet points.
 Be thorough but concise.
 """,
 Kernel = kernel
};

var writer = new ChatCompletionAgent
{
 Name = "Writer",
 Instructions = """
 You are a technical blog writer. Given a research brief, write a clear
 and engaging blog post. Use a conversational tone, include code examples
 where relevant, and structure the post with clear headings.
 """,
 Kernel = kernel
};

var editor = new ChatCompletionAgent
{
 Name = "Editor",
 Instructions = """
 You are a senior editor. Review the blog post for clarity, accuracy,
 grammar, and flow. Return the corrected version with a summary of
 changes made at the end.
 """,
 Kernel = kernel
};

순차적으로 실행 중

가장 간단한 워크플로는 순차적입니다. 각 에이전트는 이전 에이전트의 출력을 처리합니다.

using Microsoft.SemanticKernel.Agents.Chat;
using Microsoft.SemanticKernel.ChatCompletion;

async Task<string> RunSequentialWorkflow(string topic)
{
 var history = new ChatHistory();
 string currentInput = $"Research the following topic: {topic}";

 var agents = new[] { researcher, writer, editor };

 foreach (var agent in agents)
 {
 history.AddUserMessage(currentInput);

 var response = new System.Text.StringBuilder();
 await foreach (var message in agent.InvokeAsync(history))
 {
 response.Append(message.Content);
 }

 currentInput = response.ToString();
 Console.WriteLine($"✅ {agent.Name} completed");
 }

 return currentInput;
}

var result = await RunSequentialWorkflow("Blazor render modes in .NET 9");
Console.WriteLine(result);

각 에이전트는 축적된 컨텍스트를 가져와 처리하고 그 결과는 다음 단계로 이동합니다.

병렬 실행

때로는 상담원이 독립적으로 작업할 수도 있습니다. 예를 들어, 여러 하위 주제를 동시에 조사하고 싶을 수 있습니다.

async Task<List<string>> RunParallelResearch(string[] topics)
{
 var tasks = topics.Select(async topic =>
 {
 var history = new ChatHistory();
 history.AddUserMessage($"Research: {topic}");

 var response = new System.Text.StringBuilder();
 await foreach (var message in researcher.InvokeAsync(history))
 {
 response.Append(message.Content);
 }

 Console.WriteLine($"✅ Research completed: {topic}");
 return response.ToString();
 });

 var results = await Task.WhenAll(tasks);
 return results.ToList();
}

var topics = new[]
{
 "Blazor SSR streaming",
 "Enhanced navigation in .NET 9",
 "Render mode boundaries"
};

var briefs = await RunParallelResearch(topics);

그런 다음 모든 연구 개요를 단일 작가 에이전트에 공급하여 하나의 응집력 있는 게시물을 생성할 수 있습니다.

조건부 분기

실제 워크플로에는 결정이 필요합니다. 게시물이 충분하지 않은 경우 작성자에게 다시 전달하는 품질 확인 단계를 원할 수도 있습니다.

var qualityChecker = new ChatCompletionAgent
{
 Name = "QualityChecker",
 Instructions = """
 You are a quality assurance reviewer. Evaluate the blog post on:
 1. Technical accuracy
 2. Clarity and readability
 3. Completeness

 Respond with either:
 - "APPROVED" if the post meets all criteria
 - "REVISION NEEDED: [specific feedback]" if changes are required

 Be strict. Only approve posts that are truly ready to publish.
 """,
 Kernel = kernel
};

async Task<string> RunWithQualityLoop(string topic, int maxRevisions = 3)
{
 var history = new ChatHistory();

 // Step 1: Research
 history.AddUserMessage($"Research: {topic}");
 string research = await InvokeAgent(researcher, history);

 // Step 2: Write
 history.AddUserMessage(research);
 string draft = await InvokeAgent(writer, history);

 // Step 3: Quality loop
 for (int i = 0; i < maxRevisions; i++)
 {
 var qaHistory = new ChatHistory();
 qaHistory.AddUserMessage($"Review this post:\n\n{draft}");
 string qaResult = await InvokeAgent(qualityChecker, qaHistory);

 if (qaResult.Contains("APPROVED", StringComparison.OrdinalIgnoreCase))
 {
 Console.WriteLine($"✅ Approved after {i + 1} review(s)");
 return draft;
 }

 Console.WriteLine($"🔄 Revision {i + 1}: {qaResult[..Math.Min(100, qaResult.Length)]}...");

 // Send back to writer with feedback
 history.AddUserMessage($"Please revise based on this feedback:\n{qaResult}");
 draft = await InvokeAgent(writer, history);
 }

 Console.WriteLine("⚠️ Max revisions reached, returning latest draft");
 return draft;
}

async Task<string> InvokeAgent(ChatCompletionAgent agent, ChatHistory history)
{
 var response = new System.Text.StringBuilder();
 await foreach (var message in agent.InvokeAsync(history))
 {
 response.Append(message.Content);
 }
 return response.ToString();
}

이 패턴은 매우 유용합니다. 품질 검사기는 게이트 역할을 하며, 출력이 충분하거나 최대 개정 제한에 도달할 때까지 작업 흐름이 반복됩니다.

워크플로 에이전트에 플러그인 추가

워크플로의 에이전트는 독립형 에이전트처럼 플러그인을 사용할 수 있습니다. 에이전트가 워크플로 단계의 일부로 API를 호출하거나, 데이터베이스를 쿼리하거나, 파일 작업을 수행할 수 있는 것은 매우 강력합니다.

var researcherWithTools = new ChatCompletionAgent
{
 Name = "Researcher",
 Instructions = "Research the topic using available tools. Summarize findings.",
 Kernel = kernel
};

// Add a web search plugin
kernel.Plugins.AddFromType<WebSearchPlugin>();

// Add a database plugin
kernel.Plugins.AddFromObject(new DatabasePlugin(connectionString), "Database");

public class WebSearchPlugin
{
 [KernelFunction, Description("Search the web for information")]
 public async Task<string> SearchAsync(
 [Description("The search query")] string query)
 {
 // Your search implementation
 using var httpClient = new HttpClient();
 var response = await httpClient.GetStringAsync(
 $"https://api.search.example.com?q={Uri.EscapeDataString(query)}");
 return response;
 }
}

워크플로의 오류 처리

여러 에이전트를 연결하는 경우 오류 처리가 중요해집니다. 하나의 실패한 단계로 인해 전체 워크플로가 자동으로 중단되는 것을 원하지 않습니다.

async Task<WorkflowResult> RunResilientWorkflow(string input)
{
 var result = new WorkflowResult();

 try
 {
 result.Research = await InvokeAgent(researcher, new ChatHistory(input));
 }
 catch (Exception ex)
 {
 result.Errors.Add($"Research failed: {ex.Message}");
 return result;
 }

 try
 {
 var writeHistory = new ChatHistory(result.Research);
 result.Draft = await InvokeAgent(writer, writeHistory);
 }
 catch (Exception ex)
 {
 result.Errors.Add($"Writing failed: {ex.Message}");
 result.Draft = result.Research; // Fallback to research output
 }

 result.Success = result.Errors.Count == 0;
 return result;
}

class WorkflowResult
{
 public string Research { get; set; } = "";
 public string Draft { get; set; } = "";
 public List<string> Errors { get; set; } = new();
 public bool Success { get; set; }
}

모범 사례

여러 에이전트 워크플로를 구축한 후 배운 내용은 다음과 같습니다.- 상담원 지시에 집중하세요 — 각 상담원은 한 가지 일을 잘 수행해야 합니다. 스위스 군용 칼 요원을 만들려고 하지 마세요.

컨텍스트 제한 - 전체 대화 기록을 모든 상담원에게 전달하지 마세요. 각 단계에 필요한 것만 제공하십시오.
수정 제한 설정 — 품질 루프는 훌륭하지만 주의하지 않으면 영원히 실행될 수 있습니다. 항상 최대 반복 횟수 제한을 유지하세요.
모든 것을 기록 — 에이전트 출력은 예측할 수 없습니다. 디버깅을 위해 모든 단계의 입력 및 출력을 기록합니다.
병렬 실행을 현명하게 사용하세요 — 속도는 빨라지지만 API 속도 제한과 토큰 비용을 주의하세요.
더 작은 모델로 먼저 테스트 — 프로덕션을 위해 GPT-4o로 전환하기 전에 GPT-3.5로 워크플로 논리를 개발하고 테스트하세요.

결론

에이전트 워크플로를 사용하면 각 에이전트가 전문가인 복잡한 다단계 AI 파이프라인을 구축할 수 있습니다. 순차 워크플로로 시작하고, 단계가 독립적인 병렬 실행을 추가하고, 품질 게이트에 조건부 분기를 사용하세요. 패턴은 구성 가능합니다. 일단 익숙해지면 매우 정교한 자동화를 구축할 수 있습니다.

즐거운 코딩하세요!

리소스

Blazor 구성 요소 수명 주기: 전체 가이드

Thu, 15 Jan 2026 00:00:00 +0000

저는 한동안 Blazor를 사용해 왔는데 솔직히 처음에는 수명 주기 방법이 저를 혼란스럽게 했습니다. OnInitialized 대 OnInitializedAsync? OnParametersSet 대 OnAfterRender? StateHasChanged는 실제로 언제 다시 렌더링을 실행합니까? 수많은 시행착오 끝에 마침내 나는 이 모든 것에 대한 견고한 정신 모델을 갖게 되었습니다.

라이프사이클을 한눈에

Blazor 구성 요소가 렌더링되면 다음 메서드를 순서대로 진행합니다.

SetParametersAsync
OnInitialized / OnInitializedAsync
OnParametersSet / OnParametersSetAsync
OnAfterRender / OnAfterRenderAsync
Dispose / DisposeAsync

각각을 살펴보겠습니다.

SetParametersAsync

이것이 가장 먼저 호출되는 메소드입니다. 상위 구성 요소로부터 원시 ParameterView를 받습니다. 대부분의 경우 이를 재정의하지 않습니다. Blazor는 매핑 매개 변수를 자동으로 처리합니다. 하지만 할당하기 전에 맞춤 매개변수 처리 또는 유효성 검사가 필요한 경우:

public override async Task SetParametersAsync(ParameterView parameters)
{
 // Custom logic before parameters are set
 if (parameters.TryGetValue<string>("Title", out var title))
 {
 Console.WriteLine($"Title is being set to: {title}");
 }

 await base.SetParametersAsync(parameters);
}

나는 이것을 실제 프로젝트에서 정확히 한 번 사용했습니다. 대부분의 경우 건너뛰게 됩니다.

OnInitialized / OnInitializedAsync

여기에서 데이터 로드, 서비스 초기화, 기본값 설정 등의 설정 작업을 수행할 수 있습니다. 구성요소가 처음 생성될 때 한 번 실행됩니다.

@code {
 private List<Product> products = new();

 protected override async Task OnInitializedAsync()
 {
 products = await Http.GetFromJsonAsync<List<Product>>("api/products");
 }
}

나를 당황하게 만든 한 가지: Blazor Server에서는 사전 렌더링 중에 OnInitializedAsync가 두 번 호출됩니다. 서버 측 사전 렌더링 중 처음이고 SignalR 연결이 설정될 때 두 번째입니다. API 호출 비용이 많이 드는 경우 이를 처리하는 것이 좋습니다.

private bool isPrerendering = true;

protected override async Task OnInitializedAsync()
{
 products = await Http.GetFromJsonAsync<List<Product>>("api/products");
 isPrerendering = false;
}

또는 이중 호출을 완전히 피하려면 PersistentComponentState를 사용하는 것이 더 좋습니다.

OnParametersSet / OnParametersSetAsync

이는 상위 구성요소가 다시 렌더링되고 새 매개변수 값을 전달할 때마다 실행됩니다. 또한 OnInitialized 이후에도 실행됩니다. 매개변수 변경에 반응하는 적절한 위치는 다음과 같습니다.

[Parameter]
public int CategoryId { get; set; }

private int previousCategoryId;
private List<Product> products = new();

protected override async Task OnParametersSetAsync()
{
 if (CategoryId != previousCategoryId)
 {
 previousCategoryId = CategoryId;
 products = await Http.GetFromJsonAsync<List<Product>>(
 $"api/products?category={CategoryId}");
 }
}

CategoryId != previousCategoryId에 대한 확인이 중요합니다. 이것이 없으면 카테고리가 변경되지 않았더라도 상위 항목이 다시 렌더링될 때마다 데이터를 다시 로드하게 됩니다.

OnAfterRender / OnAfterRenderAsync

이는 구성 요소가 DOM에 렌더링된 후에 실행됩니다. firstRender 매개변수는 초기 렌더링인지 여부를 알려줍니다. 이 시점에 DOM 요소가 존재하므로 JS Interop 호출을 위한 위치는 다음과 같습니다.

[Inject]
private IJSRuntime JS { get; set; }

protected override async Task OnAfterRenderAsync(bool firstRender)
{
 if (firstRender)
 {
 await JS.InvokeVoidAsync("initializeChart", chartElement);
 }
}

나는 다시 렌더링할 때마다 JavaScript 라이브러리를 다시 초기화하는 것을 피하기 위해 firstRender를 많이 사용합니다. 이벤트 리스너, 차트 라이브러리 또는 DOM에 직접 닿는 모든 것을 설정하는 경우 여기로 이동합니다.

#렌더링해야함

이것은 덜 알려져 있지만 매우 유용합니다. StateHasChanged가 호출될 때 구성 요소를 다시 렌더링할지 여부를 제어합니다.

private bool shouldRender = true;

protected override bool ShouldRender() => shouldRender;

private void HeavyOperation()
{
 shouldRender = false;

 // Do a bunch of state changes without triggering renders
 for (int i = 0; i < 1000; i++)
 {
 items[i].Process();
 }

 shouldRender = true;
 StateHasChanged(); // Now render once with all changes
}

나는 이것을 큰 목록을 처리하는 구성 요소를 최적화하는 데 사용했습니다. 항목이 변경될 때마다 다시 렌더링하는 대신 업데이트를 일괄 처리하고 마지막에 한 번 렌더링합니다.

폐기 / DisposeAsync

UI에서 구성요소가 제거되면 모든 리소스를 정리해야 합니다. IDisposable 또는 IAsyncDisposable 구현:

@implements IAsyncDisposable

@code {
 private Timer? timer;
 private IJSObjectReference? jsModule;

 protected override void OnInitialized()
 {
 timer = new Timer(OnTick, null, 0, 1000);
 }

 protected override async Task OnAfterRenderAsync(bool firstRender)
 {
 if (firstRender)
 {
 jsModule = await JS.InvokeAsync<IJSObjectReference>("import", "./timer.js");
 }
 }

 public async ValueTask DisposeAsync()
 {
 timer?.Dispose();

 if (jsModule is not null)
 {
 await jsModule.DisposeAsync();
 }
 }
}

일반적으로 폐기해야 할 항목: 타이머, 이벤트 구독, JS 모듈 참조, CancellationTokenSource 및 생성한 모든 IDisposable 서비스.

StateHasChanged이는 수명주기 방법은 아니지만 밀접하게 관련되어 있습니다. Blazor에게 “안녕하세요, 내 상태가 변경되었습니다. 다시 렌더링해 주세요.“라고 알려줍니다. Blazor는 이벤트 핸들러 후에 자동으로 호출하지만 수동으로 호출해야 하는 경우도 있습니다. 일반적으로 일반 Blazor 이벤트 흐름 외부에서 상태가 변경되는 경우입니다.

private async Task StartPolling()
{
 while (!cts.Token.IsCancellationRequested)
 {
 data = await Http.GetFromJsonAsync<Data>("api/data");
 StateHasChanged(); // Manual call needed since this isn't a Blazor event
 await Task.Delay(5000, cts.Token);
 }
}

한 가지 중요한 참고 사항: Blazor Server의 백그라운드 스레드에서 업데이트하는 경우 InvokeAsync를 사용하세요.

await InvokeAsync(() =>
{
 data = newData;
 StateHasChanged();
});

전체 사진

모든 일이 일어나는 순서는 다음과 같습니다.

Component created
 └─ SetParametersAsync
 └─ OnInitialized / OnInitializedAsync
 └─ OnParametersSet / OnParametersSetAsync
 └─ Render
 └─ OnAfterRender(firstRender: true)

Parameter change from parent
 └─ SetParametersAsync
 └─ OnParametersSet / OnParametersSetAsync
 └─ ShouldRender?
 └─ Render
 └─ OnAfterRender(firstRender: false)

Component removed
 └─ Dispose / DisposeAsync

이 흐름이 머릿속에 있으면 수명주기 문제 디버깅이 훨씬 쉬워집니다.

게시물이 마음에 드셨기를 바랍니다! @emimontesdeoca로 소셜 미디어를 통해 언제든지 저에게 연락해주세요.

리소스

크리스마스를 저장하는 Microsoft의 에이전트 프레임워크

Tue, 16 Dec 2025 00:00:00 +0000

소개

완벽한 크리스마스 선물을 찾는 것은 스트레스가 될 수 있습니다. 선물 아이디어를 브레인스토밍하고, 매장 간 가격을 비교하고, 모든 것이 제 시간에 도착하는지 확인하는 과정에서 연말연시 쇼핑은 순식간에 부담스러워집니다. 함께 일하는 전문 AI 에이전트에게 이러한 작업을 위임할 수 있다면 어떨까요? 이 게시물에서는 Microsoft의 에이전트 프레임워크를 사용하여 각 에이전트가 선물 아이디어 생성부터 가격 비교까지 워크플로를 통해 조정되는 특정 작업을 전문으로 하는 다중 에이전트 시스템을 구축하는 방법을 살펴보겠습니다.

축제 기술 달력 2025

이 프로젝트는 연휴 기간 동안 기술을 기념하는 멋진 커뮤니티 이벤트인 Festive Tech Calendar 2025 세션의 일부입니다. Sessionize에서 이벤트에 대한 자세한 내용을 확인할 수 있습니다.

Microsoft의 에이전트 프레임워크란 무엇입니까?

에이전트 프레임워크는 AI 에이전트 및 다중 에이전트 시스템을 구축, 조정 및 배포하기 위한 Microsoft의 솔루션입니다. 이는 순차적으로, 동시에 또는 핸드오프 패턴을 통해 작업할 수 있는 에이전트를 생성하기 위한 유연한 기반을 제공합니다. 이 프레임워크는 OpenAI, Azure OpenAI 및 Microsoft Foundry 모델을 지원하므로 매우 다양합니다.

주요 기능은 다음과 같습니다:

다중 에이전트 오케스트레이션: 그룹 채팅, 순차, 동시 및 핸드오프 패턴
플러그인 생태계: 기본 기능, OpenAPI 및 MCP(모델 컨텍스트 프로토콜)로 확장
워크플로 지원: 실행기와 에지를 사용하여 복잡한 에이전트 파이프라인 구축

전제 조건

코드를 살펴보기 전에 다음 사항을 확인하세요.

.NET 9
Azure OpenAI 액세스(또는 OpenAI API 키)
비주얼 스튜디오 또는 비주얼 스튜디오 코드

필수 패키지를 설치합니다(미리보기에서는 --prerelease 플래그가 필요합니다).

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
dotnet add package Microsoft.Agents.AI.Workflows --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Azure.AI.Agents.Persistent --prerelease

선물 쇼핑 에이전트

우리의 크리스마스 선물 찾기는 함께 일하는 세 명의 전문 에이전트로 구성됩니다.

선물 아이디어 에이전트 - 받는 사람의 프로필을 기반으로 창의적인 선물 제안 생성
가격 비교 에이전트 - 여러 매장에서 가장 좋은 가격을 찾아줍니다.
요약 에이전트 - 최종 권장 사항을 컴파일합니다.

모델

에이전트 파이프라인을 통해 흐를 데이터 모델을 정의하는 것부터 시작해 보겠습니다.

public class GiftRecipient
{
 public string Name { get; set; } = string.Empty;
 public int Age { get; set; }
 public List<string> Interests { get; set; } = [];
 public decimal Budget { get; set; }
}

public class GiftIdea
{
 public string Name { get; set; } = string.Empty;
 public string Description { get; set; } = string.Empty;
 public string Category { get; set; } = string.Empty;
 public decimal EstimatedPrice { get; set; }
}

public class PriceResult
{
 public string GiftName { get; set; } = string.Empty;
 public string Store { get; set; } = string.Empty;
 public decimal Price { get; set; }
 public string Url { get; set; } = string.Empty;
}

public class GiftRecommendation
{
 public GiftIdea Gift { get; set; } = new();
 public List<PriceResult> Prices { get; set; } = [];
 public PriceResult? BestDeal { get; set; }
}

에이전트 구축

에이전트 프레임워크의 장점은 전문 에이전트를 생성하는 것이 얼마나 쉬운가입니다. 각 에이전트는 전문 지식을 정의하는 특정 시스템 프롬프트가 있는 단순한 ChatClientAgent입니다.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

public static class ChristmasAgentFactory
{
 public static AIAgent CreateGiftIdeaAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a creative Christmas gift advisor. When given information about a person
 (age, interests, budget), you suggest thoughtful and personalized gift ideas.

 For each suggestion, provide:
 - Gift name
 - Brief description of why it's a good fit
 - Category (Electronics, Books, Fashion, Home, Experience, etc.)
 - Estimated price range

 Always suggest 3-5 gift options within the specified budget.
 Format your response as a structured list.");
 }

 public static AIAgent CreatePriceComparisonAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a price comparison specialist. Given a list of gift ideas,
 you research and compare prices from different online retailers.

 For each gift, provide:
 - Store name (Amazon, Best Buy, Target, Walmart, etc.)
 - Current price
 - Any available discounts or deals

 Always highlight the best deal for each item.
 Consider shipping costs and delivery times for Christmas.");
 }

 public static AIAgent CreateSummaryAgent(IChatClient chatClient)
 {
 return new ChatClientAgent(
 chatClient,
 @"You are a gift recommendation summarizer. Take the gift ideas and price
 comparisons and create a final recommendation report.

 Your summary should:
 - Rank gifts by value (quality vs price)
 - Highlight the top pick with reasoning
 - Include total cost estimate
 - Add any tips for holiday shopping

 Make the summary cheerful and festive!");
 }
}

워크플로 만들기

이제 에이전트를 순차적인 워크플로에 연결하는 재미있는 부분이 나옵니다. 에이전트 프레임워크는 에이전트를 다양한 패턴으로 구성하기 위해 WorkflowBuilder 및 AgentWorkflowBuilder를 제공합니다.

public static class ChristmasGiftWorkflow
{
 public static async Task RunAsync()
 {
 // Set up the Azure OpenAI client
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
 ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
 ?? "gpt-4o-mini";

 var chatClient = new AzureOpenAIClient(
 new Uri(endpoint),
 new DefaultAzureCredential())
 .GetChatClient(deploymentName)
 .AsIChatClient();

 // Create our specialized agents
 AIAgent giftIdeaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
 AIAgent priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
 AIAgent summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

 // Build a sequential workflow: Ideas -> Prices -> Summary
 var workflow = AgentWorkflowBuilder.BuildSequential(
 "ChristmasGiftFinder",
 [giftIdeaAgent, priceAgent, summaryAgent]);

 // Define our gift recipient
 var recipient = new GiftRecipient
 {
 Name = "Mom",
 Age = 55,
 Interests = ["gardening", "cooking", "reading", "yoga"],
 Budget = 100
 };

 var prompt = $@"Find Christmas gifts for {recipient.Name},
 age {recipient.Age}, who enjoys {string.Join(", ", recipient.Interests)}.
 Budget: ${recipient.Budget}";

 // Execute the workflow with streaming
 await using StreamingRun run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, prompt));

 // Send the turn token to start processing
 await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

 // Watch for workflow events
 await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
 if (evt is AgentRunUpdateEvent agentUpdate)
 {
 Console.Write(agentUpdate.Data);
 }
 else if (evt is WorkflowOutputEvent outputEvent)
 {
 Console.WriteLine("\n🎄 Final Recommendations:");
 Console.WriteLine(outputEvent.Data);
 }
 }
 }
}

동시에 에이전트 실행

여러 사람에게 줄 선물을 동시에 검색하고 싶다면 어떻게 해야 할까요? 에이전트 프레임워크는 동시 실행을 지원하며 이는 다음 시나리오에 적합합니다.

public static async Task FindGiftsForEveryoneAsync(IChatClient chatClient, List<GiftRecipient> recipients)
{
 // Create an agent for each recipient
 var agents = recipients.Select(r => new ChatClientAgent(
 chatClient,
 $@"Find the perfect Christmas gift for {r.Name} (age {r.Age}),
 who loves {string.Join(", ", r.Interests)}. Budget: ${r.Budget}.
 Provide one well-researched recommendation with price."
 )).ToList();

 // Build a concurrent workflow - all agents run in parallel
 var workflow = AgentWorkflowBuilder.BuildConcurrent(
 "FamilyGiftFinder",
 agents);

 await using StreamingRun run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, "Find gifts now!"));

 await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

 await foreach (WorkflowEvent evt in run.WatchStreamAsync())
 {
 if (evt is WorkflowOutputEvent output)
 {
 Console.WriteLine("🎁 All gift recommendations ready!");
 Console.WriteLine(output.Data);
 }
 }
}

더 많은 제어를 위한 맞춤형 실행기보다 복잡한 시나리오의 경우 워크플로를 세밀하게 제어할 수 있는 사용자 지정 실행기를 만들 수 있습니다.

public sealed class GiftValidatorExecutor : Executor<List<ChatMessage>, List<ChatMessage>>
{
 public GiftValidatorExecutor() : base("GiftValidator") { }

 public override async ValueTask<List<ChatMessage>> HandleAsync(
 List<ChatMessage> messages,
 IWorkflowContext context,
 CancellationToken cancellationToken = default)
 {
 var lastMessage = messages.LastOrDefault()?.Text ?? "";

 // Validate that suggestions are within budget
 if (lastMessage.Contains("over budget", StringComparison.OrdinalIgnoreCase))
 {
 Console.WriteLine("⚠️ Some suggestions exceeded budget, filtering...");
 // Add validation logic here
 }

 Console.WriteLine("✅ Gift suggestions validated!");
 return messages;
 }
}

그런 다음 이 실행자를 워크플로에 삽입할 수 있습니다.

var validator = new GiftValidatorExecutor();

var workflow = new WorkflowBuilder(giftIdeaAgent)
 .AddEdge(giftIdeaAgent, validator)
 .AddEdge(validator, priceAgent)
 .AddEdge(priceAgent, summaryAgent)
 .WithOutputFrom(summaryAgent)
 .Build();

Bing Grounding으로 실제 웹 검색 추가

지금까지 에이전트는 AI 모델의 지식을 기반으로 응답을 생성합니다. 하지만 실제 제품 가격과 재고 여부를 웹에서 검색하고 싶다면 어떻게 해야 할까요? Bing Search를 통한 접지가 필요한 곳입니다. 이는 에이전트가 응답을 생성할 때 실시간 공개 웹 데이터를 통합할 수 있도록 해주는 Microsoft Foundry(이전의 Azure AI Foundry)에서 사용할 수 있는 도구입니다.

먼저 Azure Portal에서 Bing Search를 통한 접지 리소스를 만들어야 합니다. AI 프로젝트와 동일한 리소스 그룹에 만들어야 합니다.

Bing Search를 사용하여 접지 설정

Bing Search를 통한 Grounding의 장점은 Azure AI 에이전트와 직접 통합된다는 것입니다. 에이전트는 사용자의 쿼리를 기반으로 검색 도구를 언제 사용할지 결정하고, 웹을 검색하고, 그 결과를 바탕으로 근거 있는 응답을 생성합니다.

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public static class BingGroundingSetup
{
 public static async Task<PersistentAgent> CreateAgentWithBingGroundingAsync(
 string projectEndpoint,
 string modelDeploymentName,
 string bingConnectionId)
 {
 // Create the Persistent Agents client
 var agentClient = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());

 // Configure the Bing Grounding tool
 var bingGroundingTool = new BingGroundingToolDefinition(
 new BingGroundingSearchToolParameters(
 [new BingGroundingSearchConfiguration(bingConnectionId)]
 )
 );

 // Create the agent with Bing Grounding enabled
 var agent = await agentClient.Administration.CreateAgentAsync(
 model: modelDeploymentName,
 name: "ChristmasPriceHunter",
 instructions: @"You are a Christmas gift price comparison specialist.

 When given gift ideas, use Bing to search for:
 - Current prices at major retailers (Amazon, Best Buy, Target, Walmart)
 - Available discounts and holiday deals
 - Shipping times to ensure delivery before Christmas

 Always provide URLs to the products you find.
 Highlight the best deals and recommend where to buy.",
 tools: [bingGroundingTool]
 );

 return agent;
 }
}

실제 검색으로 가격비교 에이전트 만들기

이제 웹에서 실제 제품 정보를 검색하는 완전한 가격 비교 에이전트를 만들어 보겠습니다.

using Azure.AI.Agents.Persistent;
using Azure.Identity;

public class ChristmasPriceAgent
{
 private readonly PersistentAgentsClient _client;
 private readonly string _modelDeployment;
 private readonly string _bingConnectionId;

 public ChristmasPriceAgent(string projectEndpoint, string modelDeployment, string bingConnectionId)
 {
 _client = new PersistentAgentsClient(projectEndpoint, new DefaultAzureCredential());
 _modelDeployment = modelDeployment;
 _bingConnectionId = bingConnectionId;
 }

 public async Task<string> FindGiftPricesAsync(string giftIdeas)
 {
 // Create agent with Bing Grounding
 var bingTool = new BingGroundingToolDefinition(
 new BingGroundingSearchToolParameters(
 [new BingGroundingSearchConfiguration(_bingConnectionId)]
 )
 );

 var agent = await _client.Administration.CreateAgentAsync(
 model: _modelDeployment,
 name: "PriceHunter",
 instructions: @"Search the web for current prices on the given gift ideas.
 For each gift, find prices from at least 2-3 different stores.
 Include direct links to the products.
 Note any Christmas sales or discounts available.",
 tools: [bingTool]
 );

 try
 {
 // Create a thread for the conversation
 var thread = await _client.Threads.CreateThreadAsync();

 // Add the gift ideas as a message
 await _client.Messages.CreateMessageAsync(
 thread.Id,
 MessageRole.User,
 $"Find current prices for these gift ideas: {giftIdeas}"
 );

 // Run the agent
 var run = await _client.Runs.CreateRunAsync(thread.Id, agent.Id);

 // Wait for completion
 do
 {
 await Task.Delay(500);
 run = await _client.Runs.GetRunAsync(thread.Id, run.Id);
 }
 while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

 // Get the response
 var messages = _client.Messages.GetMessages(thread.Id);
 var response = messages
 .Where(m => m.Role == MessageRole.Agent)
 .SelectMany(m => m.ContentItems)
 .OfType<MessageTextContent>()
 .FirstOrDefault();

 // Clean up
 await _client.Threads.DeleteThreadAsync(thread.Id);

 return response?.Text ?? "No results found.";
 }
 finally
 {
 // Clean up the agent
 await _client.Administration.DeleteAgentAsync(agent.Id);
 }
 }
}

Bing Grounding을 작업 흐름에 통합

전체 선물 찾기 워크플로에서 Bing 기반 가격 에이전트를 사용하는 방법은 다음과 같습니다.

public static async Task RunWithBingGroundingAsync()
{
 var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")!;
 var modelDeployment = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
 var bingConnectionId = Environment.GetEnvironmentVariable("BING_CONNECTION_ID")!;
 // Connection ID format: /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}/connections/{connection}

 Console.WriteLine("🔍 Searching the web for real prices with Bing Grounding...\n");

 var priceAgent = new ChristmasPriceAgent(projectEndpoint, modelDeployment, bingConnectionId);

 // First, generate gift ideas (could come from another agent)
 var giftIdeas = "1. Milwaukee cordless drill set, 2. Weber portable grill, 3. Carhartt beanie";

 // Search for real prices
 var priceResults = await priceAgent.FindGiftPricesAsync(giftIdeas);

 Console.WriteLine("📊 Price Comparison Results:");
 Console.WriteLine(priceResults);
 Console.WriteLine("\n🎁 Happy Shopping! 🎁");
}

Bing 결과에서 인용 처리

Bing Search를 통한 접지의 중요한 측면 중 하나는 응답에 소스 웹 사이트에 대한 링크가 포함된 인용이 포함된다는 것입니다. 이를 추출하고 표시하는 방법은 다음과 같습니다.

public static void ProcessBingGroundingResponse(IEnumerable<PersistentThreadMessage> messages)
{
 foreach (var message in messages.Where(m => m.Role == MessageRole.Agent))
 {
 foreach (var content in message.ContentItems)
 {
 if (content is MessageTextContent textContent)
 {
 var response = textContent.Text;

 // Process URL citations
 if (textContent.Annotations != null)
 {
 foreach (var annotation in textContent.Annotations)
 {
 if (annotation is MessageTextUriCitationAnnotation uriAnnotation)
 {
 // Replace citation placeholder with markdown link
 response = response.Replace(
 uriAnnotation.Text,
 $" [{uriAnnotation.UriCitation.Title}]({uriAnnotation.UriCitation.Uri})"
 );
 }
 }
 }

 Console.WriteLine(response);
 }
 }
 }
}

이제 가격 비교 에이전트가 실행되면 Bing Search를 통한 접지를 사용하여 실제 제품 목록, 현재 가격 및 라이브 웹에서 사용 가능한 거래를 찾습니다. 에이전트는 쿼리를 기반으로 언제 검색할지 자동으로 결정하고 적절한 인용과 함께 근거 있는 응답을 반환합니다.

완전한 프로그램

Program.cs에서 모든 것이 하나로 합쳐지는 방법은 다음과 같습니다.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

Console.WriteLine("🎄 Christmas Gift Finder - Powered by AI Agents 🎄\n");

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
var deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
 .GetChatClient(deployment)
 .AsIChatClient();

// Create the agent team
var ideaAgent = ChristmasAgentFactory.CreateGiftIdeaAgent(chatClient);
var priceAgent = ChristmasAgentFactory.CreatePriceComparisonAgent(chatClient);
var summaryAgent = ChristmasAgentFactory.CreateSummaryAgent(chatClient);

// Build the workflow
var workflow = AgentWorkflowBuilder.BuildSequential(
 "ChristmasGiftWorkflow",
 [ideaAgent, priceAgent, summaryAgent]);

Console.Write("Who are you shopping for? ");
var recipientName = Console.ReadLine() ?? "Someone special";

Console.Write("What are their interests? ");
var interests = Console.ReadLine() ?? "general";

Console.Write("What's your budget? $");
var budget = Console.ReadLine() ?? "50";

var prompt = $"Find Christmas gifts for {recipientName} who enjoys {interests}. Budget: ${budget}";

Console.WriteLine("\n🔍 Searching for the perfect gifts...\n");

await using var run = await InProcessExecution.StreamAsync(
 workflow,
 new ChatMessage(ChatRole.User, prompt));

await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

await foreach (var evt in run.WatchStreamAsync())
{
 switch (evt)
 {
 case AgentRunUpdateEvent update:
 Console.Write(update.Update.Text);
 break;
 case WorkflowOutputEvent output:
 Console.WriteLine("\n\n🎁 Happy Shopping! 🎁");
 break;
 }
}

결론

Microsoft의 에이전트 프레임워크를 사용하면 각 에이전트가 특정 작업을 전문으로 하는 다중 에이전트 시스템을 놀라울 정도로 쉽게 구축할 수 있습니다. 워크플로를 통해 이러한 에이전트를 조정함으로써 구조적이고 효율적인 방식으로 크리스마스 쇼핑과 같은 복잡한 문제를 해결할 수 있습니다.

이를 더욱 강력하게 만드는 것은 도구를 통해 실제 기능을 추가할 수 있는 능력입니다. Microsoft Foundry의 Grounding with Bing Search를 통합함으로써 당사의 가격 비교 에이전트는 실제로 웹에서 현재 가격, 거래 및 가용성을 검색할 수 있습니다. 이를 통해 간단한 AI 챗봇을 적절한 인용을 통해 진정으로 유용한 쇼핑 도우미로 탈바꿈시킬 수 있습니다.

순차, 동시 및 핸드오프 패턴에 대한 프레임워크의 지원은 사용자의 정확한 요구 사항에 맞는 에이전트 시스템을 설계할 수 있음을 의미합니다. 선물 찾기, 여행 계획 또는 기타 다단계 작업 등 무엇이든 에이전트 프레임워크는 이를 실현하는 데 필요한 구성 요소를 제공합니다.이번 휴가철에는 AI 에이전트에게 연구를 맡기고 선물 포장에 집중하고 가족과 함께 즐거운 시간을 보내세요!

소스 코드

이 게시물에 표시된 개념은 공식 Agent Framework 샘플을 기반으로 합니다. Microsoft Agent Framework GitHub 리포지토리에서 더 많은 예제를 탐색할 수 있습니다.

즐거운 휴일 보내시고 즐거운 코딩하세요! 🎄

AI 기반 RSS 피드 수집기 구축

Fri, 12 Dec 2025 00:00:00 +0000

Microsoft MVP이자 기술 애호가로서 저는 Microsoft DevBlog에 게시된 놀라운 콘텐츠의 바다에 끊임없이 빠져들고 있습니다. .NET 발표부터 Visual Studio 업데이트, Azure 혁신부터 의미 체계 커널 심층 분석까지 Microsoft 생태계에는 항상 새롭고 흥미로운 일이 일어나고 있습니다.

문제? 모든 것을 따라잡는 것은 거의 불가능합니다.

최신 공지 사항을 파악하고 이를 내 네트워크와 공유하고 싶었지만 7개의 서로 다른 RSS 피드를 수동으로 확인하고, 기사를 읽고, 흥미로운 소셜 미디어 게시물을 작성하고, 이미 공유한 내용을 추적하는 것이 그 자체로 정규직이 되었습니다. 매일 아침 나는 여러 개의 브라우저 탭을 열고, 수십 개의 기사를 훑어보고, 내가 이미 공유한 기사를 기억하려고 노력한 다음, 내 관심을 끌었던 기사에 대한 게시물을 작성하는 데 소중한 시간을 보냈습니다.

그래서 나는 개발자라면 누구나 할 법한 일을 했습니다. 자동화했습니다.

이 종합 가이드에서는 새 콘텐츠에 대한 여러 Microsoft DevBlogs RSS 피드를 모니터링하고, Azure OpenAI 및 Semantic Kernel을 사용하여 기사를 분석하고 매력적인 게시물을 생성하고, 분석된 각 기사에 대한 자세한 마크다운 문서를 생성하고, 콘텐츠를 검토 및 공유할 수 있도록 Telegram을 통해 알림을 보내고, 중복 게시물을 피하기 위해 모든 것을 추적하고, GitHub Actions를 통해 자동으로 실행하는 AI 기반 RSS 피드 수집기를 구축하는 방법을 안내합니다.

이 솔루션의 모든 측면을 자세히 살펴보겠습니다.

이 프로젝트의 비하인드 스토리

정보 과잉 속에서 살아가기

이 도구를 만들기 전의 전형적인 아침 모습을 그려보겠습니다. 저는 일어나서 커피를 들고 노트북을 열어 Microsoft 개발자 생태계의 새로운 소식을 확인했습니다. 먼저 주요 DevBlogs 사이트로 이동하여 주요 공지 사항이 있는지 확인했습니다. 그런 다음 .NET 블로그가 나의 주요 기술 스택이기 때문에 구체적으로 확인하겠습니다. 그 후에는 AI가 점점 더 중요해지고 있기 때문에 Semantic Kernel 블로그를 방문하겠습니다. IDE 업데이트가 일상적인 워크플로에 큰 영향을 미칠 수 있기 때문에 Visual Studio 블로그가 그 다음 목록에 포함되었습니다. 그런 다음 CI/CD 및 GitHub 관련 뉴스를 위한 DevOps 블로그가 나왔고, 클라우드 인프라 업데이트를 위한 All Things Azure 블로그, 마지막으로 데이터베이스 혁신을 위한 Azure SQL 블로그가 나왔습니다.

확인해야 할 7가지 피드가 있습니다. 이러한 각 블로그는 매주 여러 개의 기사를 게시하며 때로는 .NET Conf 또는 Build와 같은 주요 발표 기간 동안 하루에 여러 개를 게시합니다. 추적하고 읽고 공유할 수 있는 기사가 수십 개에 달할 수 있습니다. 그리고 여기에 문제가 있습니다. 커뮤니티와의 지식 공유를 중요하게 생각하는 사람으로서 저는 이 기사를 그냥 읽고 싶지 않았습니다. 저는 가장 가치 있는 정보를 LinkedIn의 네트워크와 공유하여 다른 개발자에게도 정보를 제공하고 싶었습니다.하지만 좋은 LinkedIn 게시물을 작성하려면 시간이 걸립니다. 기사를 철저하게 읽고, 핵심 사항을 이해하고, 기사가 청중에게 왜 중요한지 생각하고, 흥미로운 내용을 작성하고, 모든 내용을 멋지게 구성해야 합니다. 여기에 일주일에 여러 기사를 곱하면 작업 시간이 표시됩니다.

내가 정말 원했던 것

몇 달 동안 이 문제를 처리한 후 저는 이상적인 솔루션이 어떤 모습일지 생각해 보았습니다. 무엇보다도 중요한 공지를 다시는 놓치고 싶지 않았습니다. 시스템은 새 기사가 게시되는 즉시 자동으로 이를 포착해야 합니다. 또한 AI가 매력적인 게시물을 작성하는 데 도움을 주어 콘텐츠 제작 시간을 절약하고 싶었습니다. 이는 제 목소리를 완전히 대체하는 것이 아니라 맞춤 설정할 수 있는 확실한 출발점을 제공하기 위함이었습니다.

일관성은 또 다른 큰 요소였습니다. 매일 수동으로 수행할 필요 없이 정기적으로 콘텐츠를 공유하고 싶었습니다. 추적 측면도 매우 중요했습니다. 중복된 게시물을 게시하고 팔로어를 짜증나게 하는 것을 피하기 위해 이미 공유한 내용을 알 수 있는 방법이 필요했습니다. 마지막으로, 내가 처리한 모든 내용을 영구적으로 기록하여 체계적으로 정리하여 내가 다룬 주제가 무엇인지 되돌아보고 확인할 수 있기를 원했습니다.

솔루션의 형태가 바뀌다

제가 구상한 솔루션은 완전히 핸즈프리인 GitHub Actions를 사용하여 일정에 따라 실행됩니다. 단일 브라우저 탭을 열지 않고도 자동으로 7개의 피드를 모두 가져올 수 있습니다. AI 구성 요소는 실제로 콘텐츠를 읽고 이해한 다음 청중에게 유용한 방식으로 요약합니다. 처음부터 게시물을 작성하는 대신, 필요할 경우 수정할 수 있는 즉시 공유 가능한 소셜 미디어 콘텐츠가 생성됩니다. 검토를 위해 모든 것이 내 텔레그램으로 전송되므로 신속하게 휴대폰을 살펴보고 무엇을 공유할지 결정할 수 있었습니다. 그리고 물론, 나중에 참고할 수 있도록 모든 것을 영구적으로 기록해 둘 것입니다.

구축을 시작하기 전에

컴퓨터에 필요한 것

이 튜토리얼을 진행하려면 개발 컴퓨터에 몇 가지 항목을 설치해야 합니다. 가장 중요한 것은 .NET SDK 버전 9.0 이상입니다. 이것은 우리의 런타임이며 필요한 모든 빌드 도구를 제공합니다. 아직 설치되어 있지 않다면 dot.net으로 가서 최신 버전을 다운로드하세요. 설치는 Windows, macOS 또는 Linux에서 간단합니다.

또한 버전 제어를 위해 Git을 설치해야 합니다. 우리는 코드를 GitHub에 푸시하고 자동화를 위해 GitHub Actions를 사용할 것이므로 Git을 로컬로 설정하는 것이 필수적입니다. 최신 버전이면 모두 잘 작동합니다.

개발 환경으로는 Visual Studio 또는 VS Code를 권장합니다. 개인적으로 저는 요즘 대부분의 작업에 VS Code를 사용합니다. VS Code는 가볍고 C# Dev Kit 확장을 통해 뛰어난 C# 지원을 제공하기 때문입니다. 그러나 전체 Visual Studio에 더 익숙하다면 그것도 완벽하게 작동합니다.

필요한 서비스 및 계정로컬 도구 외에도 몇 가지 서비스가 포함된 계정이 필요합니다. 가장 중요한 것은 AI 분석을 지원하는 Azure OpenAI입니다. 이는 종량제 서비스이지만 이 사용 사례에서는 비용이 최소화됩니다. 분석된 기사당 센트를 말하는 것입니다. Azure 계정이 없으면 시작할 수 있는 크레딧이 포함된 무료 평가판에 등록할 수 있습니다.

알림을 위해 Telegram Bot을 사용합니다. Telegram의 가장 큰 장점은 봇 API를 완전히 무료로 사용할 수 있다는 것입니다. 원하는 만큼 봇을 만들고 메시지를 무제한으로 보낼 수 있습니다. 이 가이드 뒷부분에서 설정 과정을 안내해 드리겠습니다.

마지막으로, 코드를 호스팅하고 GitHub Actions를 실행하려면 GitHub 계정이 필요합니다. 이 프로젝트에는 무료 등급이면 충분합니다. GitHub는 개인 저장소에서 매월 2,000분의 Actions 런타임을 제공하고 공용 저장소에서는 무제한(분)을 제공합니다.

이것을 가능하게 하는 라이브러리

우리 프로젝트는 각각 특정 목적을 수행하는 세 가지 주요 NuGet 패키지를 사용합니다.

첫 번째는 .NET의 HTML 구문 분석에 대한 표준인 HtmlAgilityPack입니다. 블로그에서 기사를 가져올 때 탐색 메뉴, 바닥글, 광고 및 관심 없는 모든 종류의 요소를 포함하여 페이지의 전체 HTML을 다시 가져옵니다. HtmlAgilityPack을 사용하면 해당 HTML을 구문 분석하고 필요한 기사 콘텐츠만 추출할 수 있습니다.

두 번째 패키지는 AI 모델을 애플리케이션에 통합하기 위한 Microsoft의 SDK인 Microsoft.SemanticKernel입니다. 이를 .NET 코드와 GPT-4와 같은 대규모 언어 모델 사이의 다리로 생각하십시오. API 호출, 토큰 관리 및 응답 구문 분석의 모든 복잡성을 처리하므로 AI가 실제로 수행하기를 원하는 작업에 집중할 수 있습니다.

세 번째 패키지는 RSS 및 Atom 피드 구문 분석을 기본적으로 지원하는 System.ServiceModel.Syndication입니다. RSS는 오래된 기술처럼 보일 수도 있지만 여전히 블로그와 뉴스 사이트에서 구조화된 업데이트를 얻는 가장 좋은 방법입니다. 이 패키지는 원시 XML 피드를 작업하기 쉬운 강력한 형식의 C# 개체로 변환합니다.

아키텍처 이해

조각이 서로 맞는 방법

코드를 살펴보기 전에 모든 구성 요소가 어떻게 함께 작동하는지 설명하겠습니다. 큰 그림을 이해하면 구현 세부 사항이 훨씬 더 명확해집니다.

최고 수준에는 오케스트레이터 역할을 하는 기본 Program.cs 파일이 있습니다. 이는 애플리케이션의 진입점이며 다른 모든 구성요소를 조정합니다. 애플리케이션이 실행되면 먼저 API 키 및 Telegram 자격 증명과 같은 환경 변수에서 구성을 로드합니다. 그런 다음 나가서 7개의 Microsoft DevBlogs 소스 모두에서 RSS 피드를 가져옵니다. 이러한 피드를 처리하면서 동일한 기사가 여러 피드에 나타나는 경우를 처리하기 위해 기사의 중복을 제거합니다. 추적 파일과 비교하여 각 기사를 확인하여 이미 처리되었는지 확인합니다. 새로운 기사의 경우 처리를 위해 AI 분석기에 전달합니다.ArticleAnalyzer 클래스는 AI 마법이 일어나는 곳입니다. 이 구성 요소는 기사를 수신하고 기사로 여러 가지 작업을 수행합니다. 먼저 기사의 URL에서 전체 HTML 콘텐츠를 가져옵니다. 그런 다음 해당 HTML에서 깨끗한 텍스트를 추출하여 필요하지 않은 모든 탐색 요소, 스크립트 및 스타일을 제거합니다. 깨끗한 텍스트가 있으면 신중하게 제작된 프롬프트와 함께 Semantic Kernel을 통해 이를 Azure OpenAI로 보냅니다. AI는 기사를 분석하고 요약, 주요 주제, 관련성 설명, 가장 중요하게는 즉시 사용 가능한 LinkedIn 게시물을 포함하는 구조화된 응답을 반환합니다. 분석기는 이 응답을 구문 분석하고 이 모든 정보가 포함된 ArticleAnalytic 개체를 반환합니다.

MarkdownGenerator 클래스는 해당 ArticleAnalytic 개체를 가져와 이에 대한 영구 기록을 만듭니다. 모든 기사 메타데이터, AI 분석 및 생성된 게시물을 포함하는 적절한 형식의 마크다운 파일을 생성합니다. 이러한 파일은 생성된 게시물 디렉터리에 저장되어 처리한 모든 내용에 대한 검색 가능한 아카이브를 제공합니다.

마지막으로 Telegram 통합은 생성된 게시물 콘텐츠를 휴대폰으로 보냅니다. 이것은 인간으로서 AI의 작업을 검토하고 공유할지 여부를 결정하는 지점입니다. 봇은 게시물 내용이 포함된 메시지를 보내며, 게시물 내용을 LinkedIn에 직접 복사하거나 먼저 수정할 수 있습니다.

데이터의 흐름

.NET 블로그에 새 기사가 게시되면 어떤 일이 발생하는지 안내해 드리겠습니다. GitHub Actions가 일정에 따라 애플리케이션을 트리거할 때 워크플로가 시작됩니다(예: 6시간마다). 애플리케이션이 깨어나서 7개의 RSS 피드를 모두 가져오기 시작합니다. 각 피드는 해당 블로그의 최신 기사가 포함된 XML 문서를 반환합니다.

각 피드를 구문 분석하면서 개별 기사를 추출하여 목록에 저장합니다. 하지만 여기에 까다로운 부분이 있습니다. 기본 DevBlogs 피드에는 개별 카테고리 피드에도 나타나는 기사가 포함되는 경우가 많습니다. 따라서 “.NET 10"에 대한 기사가 기본 피드와 .NET 관련 피드 모두에 표시될 수 있습니다. 우리는 중복을 자동으로 방지하는 HashSet의 URL을 추적하여 이를 처리합니다.

중복 제거된 기사 목록이 있으면 최근 기사(일반적으로 마지막 날 정도에 게시된 기사)로만 필터링합니다. 이전 실행에서 이미 처리한 오래된 기사를 처리하고 싶지 않습니다. 그런 다음 추적 파일과 비교하여 각 최근 기사를 확인합니다. 기사에 대해 이미 처리하고 게시한 경우 해당 기사를 건너뜁니다.

새로운 기사가 나올 때마다 AI 분석 파이프라인이 시작됩니다. 분석기는 전체 기사 HTML을 가져와 정리한 후 프롬프트와 함께 GPT-4로 보냅니다. AI는 기사를 읽고 LinkedIn 게시물과 함께 포괄적인 분석을 생성합니다. 우리는 기록을 위해 이 분석을 마크다운 파일에 저장합니다.분석이 완료되면 메시지 형식을 지정하고 Telegram을 통해 보냅니다. 메시지에는 URL과 해시태그가 추가된 생성된 게시물 콘텐츠가 포함됩니다. 휴대폰으로 알림을 받고 게시물을 검토한 후 마음에 들면 몇 번의 탭만으로 복사하여 LinkedIn에 공유할 수 있습니다.

마지막으로 추적 파일을 업데이트하여 이 기사를 처리된 것으로 표시하므로 향후 실행에서는 다시 처리하지 않습니다. 파일이 생성되거나 수정된 경우 GitHub Actions는 이러한 변경 사항을 저장소에 다시 커밋하여 모든 것을 동기화합니다.

처음부터 프로젝트 설정하기

솔루션 구조 만들기

건축을 시작합시다. 터미널을 열고 프로젝트를 생성하려는 위치로 이동합니다. 나는 개발 폴더에 프로젝트를 정리하는 것을 좋아하지만, 원하는 곳에 배치할 수 있습니다.

먼저 새 솔루션 파일을 만듭니다. .NET에서 솔루션은 여러 프로젝트를 보유할 수 있는 컨테이너입니다. 지금은 프로젝트가 하나뿐이지만 솔루션부터 시작하면 나중에 필요한 경우 프로젝트를 더 쉽게 추가할 수 있습니다. dotnet new sln -n vs-feed-linkedin 명령을 실행하여 vs-feed-linkedin이라는 솔루션을 생성합니다.

다음으로 콘솔 애플리케이션 프로젝트를 생성해야 합니다. 정리된 상태를 유지하기 위해 이것을 src 하위 디렉터리에 넣을 것입니다. dotnet new console -n VsFeedLinkedin -o src를 실행하여 src 폴더에 VsFeedLinkedin이라는 콘솔 프로젝트를 만듭니다. 그런 다음 dotnet sln add src/VsFeedLinkedin.csproj를 사용하여 이 프로젝트를 솔루션에 추가합니다.

이제 cd src를 사용하여 src 디렉터리로 이동합니다. 여기에서 NuGet 패키지를 추가하고 대부분의 개발을 수행합니다.

필수 패키지 추가

프로젝트가 생성되면 앞서 언급한 세 가지 NuGet 패키지를 추가해야 합니다. 다음 명령을 각각 순서대로 실행하세요.

dotnet add package System.ServiceModel.Syndication --version 9.0.9
dotnet add package Microsoft.SemanticKernel --version 1.30.0
dotnet add package HtmlAgilityPack --version 1.11.72

이 명령을 실행한 후 프로젝트 파일은 다음과 같아야 합니다.

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

 <PropertyGroup>
 <OutputType>Exe</OutputType>
 <TargetFramework>net9.0</TargetFramework>
 <ImplicitUsings>enable</ImplicitUsings>
 <Nullable>enable</Nullable>
 </PropertyGroup>

 <ItemGroup>
 <PackageReference Include="HtmlAgilityPack" Version="1.11.72" />
 <PackageReference Include="Microsoft.SemanticKernel" Version="1.30.0" />
 <PackageReference Include="System.ServiceModel.Syndication" Version="9.0.9" />
 </ItemGroup>

</Project>

프로젝트 파일은 .NET 9.0을 대상으로 실행 파일(OutputType은 Exe)을 빌드하고 암시적 using 및 null 허용 참조 유형과 같은 최신 C# 기능을 사용하고 있음을 .NET에 알려줍니다. ItemGroup 섹션에는 정확한 버전과 함께 세 가지 패키지 종속성이 나열되어 있습니다.

RSS 피드 심층 분석

RSS란 정확히 무엇인가요?

피드를 가져오는 코드 작성을 시작하기 전에 우리가 작업 중인 내용을 확실히 이해하도록 합시다. RSS는 Really Simple Syndication의 약어이며 콘텐츠 업데이트 배포를 위한 표준화된 XML 형식입니다. 아이디어는 간단합니다. 사용자에게 새 콘텐츠가 있는지 확인하기 위해 웹사이트를 방문하도록 요구하는 대신 최신 콘텐츠를 나열하는 기계 판독 가능 파일을 게시합니다. 그런 다음 애플리케이션은 이 파일을 주기적으로 폴링하여 새 기사를 검색할 수 있습니다.

RSS는 1990년대 후반과 2000년대 초반부터 존재해왔습니다. 오래된 기술이라고 생각할 수도 있지만 실제로는 특히 블로그, 뉴스 사이트, 팟캐스트에서 여전히 널리 사용되고 있습니다. RSS의 장점은 단순성에 있습니다. 이는 정의된 구조를 가진 XML일 뿐이며 모든 애플리케이션에서 이를 구문 분석할 수 있습니다.

DevBlogs 피드의 구조Microsoft DevBlogs에서 RSS 피드를 가져오면 특정 구조를 따르는 XML 문서를 다시 가져옵니다. 최상위 수준에는 단일 채널 요소를 포함하는 RSS 요소가 있습니다. 채널은 블로그 자체를 나타내며 블로그 제목, URL, 설명과 같은 메타데이터를 포함합니다.

채널 내에는 각각 개별 블로그 게시물을 나타내는 여러 항목 요소가 있습니다. 각 항목에는 제목(기사 헤드라인), 링크(전체 기사를 읽을 수 있는 URL), pubDate(기사가 게시된 시기), dc:creator 요소(작성자 이름), 하나 이상의 카테고리 요소(기사 태그) 및 설명(일반적으로 기사 요약 또는 발췌)이 포함됩니다.

다음은 이것이 어떻게 보이는지에 대한 간단한 예입니다.

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
 <channel>
 <title>.NET Blog</title>
 <link>https://devblogs.microsoft.com/dotnet</link>
 <description>The latest news about .NET</description>
 <item>
 <title>Announcing .NET 10</title>
 <link>https://devblogs.microsoft.com/dotnet/announcing-dotnet-10</link>
 <pubDate>Mon, 10 Dec 2025 12:00:00 GMT</pubDate>
 <dc:creator>Microsoft</dc:creator>
 <category>Announcements</category>
 <category>.NET</category>
 <description>Article summary...</description>
 </item>
 </channel>
</rss>

.NET System.ServiceModel.Syndication 패키지의 가장 큰 장점은 이 패키지가 이 모든 것을 구문 분석한다는 것입니다. XML 노드를 수동으로 탐색하거나 다른 RSS 버전에 대해 걱정할 필요가 없습니다. 우리는 피드를 로드하고 강력한 유형의 개체를 다시 가져옵니다.

우리가 모니터링하는 7가지 피드

저는 구현 시 7개의 서로 다른 Microsoft DevBlogs 피드를 모니터링합니다. devblogs.microsoft.com/feed의 기본 DevBlogs 피드에서는 Microsoft가 모든 개발자 블로그에 게시하는 모든 내용을 폭넓게 볼 수 있습니다. devblogs.microsoft.com/dotnet/feed의 .NET 관련 피드는 특히 .NET 릴리스, 기능 및 모범 사례에 중점을 두고 있습니다. devblogs.microsoft.com/semantic-kernel/feed의 Semantic Kernel 피드에서는 AI 오케스트레이션 및 통합을 다룹니다. AI가 현대 개발의 중심이 되면서 점점 더 중요해지고 있습니다.

devblogs.microsoft.com/visualstudio/feed의 Visual Studio 피드에서는 IDE 개선 사항 및 생산성 기능에 대한 최신 정보를 계속해서 받아볼 수 있습니다. devblogs.microsoft.com/devops/feed의 DevOps 피드에서는 Azure DevOps, GitHub 및 CI/CD 주제를 다룹니다. devblogs.microsoft.com/all-things-azure/feed의 All Things Azure 피드는 클라우드 서비스 및 아키텍처 패턴에 중점을 둡니다. 마지막으로 devblogs.microsoft.com/azure-sql/feed의 Azure SQL 피드에서는 데이터베이스 혁신과 기능을 다룹니다.

왜 제가 메인피드와 개별 카테고리 피드를 모두 확인하는지 궁금하실 겁니다. 기본 피드를 통해 폭넓은 정보를 얻을 수 있습니다. 내가 알지 못하는 내용을 포함하여 모든 Microsoft 개발자 블로그의 기사를 볼 수 있습니다. 카테고리 피드는 나에게 깊이를 줍니다. 새로운 콘텐츠로 인해 해당 기사가 기본 피드에서 밀려나더라도 핵심 관심 분야에서 중요한 내용을 놓치지 않도록 해줍니다.

RSS 가져오기 논리 구축

코어 가져오기 기능

이제 몇 가지 코드를 작성해 보겠습니다. 우리 애플리케이션의 기초는 RSS 피드를 가져오고 구문 분석하는 기능입니다. 이를 처리하는 함수는 다음과 같습니다.

static async Task<SyndicationFeed?> FetchRssFeedAsync(string url)
{
 using var httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Add("User-Agent", "VsFeedLinkedin/1.0");

 var response = await httpClient.GetStringAsync(url);

 using var stringReader = new StringReader(response);

 var settings = new XmlReaderSettings
 {
 DtdProcessing = DtdProcessing.Parse,
 MaxCharactersFromEntities = 1024
 };

 using var xmlReader = XmlReader.Create(stringReader, settings);

 return SyndicationFeed.Load(xmlReader);
}

이 코드의 기능을 살펴보겠습니다. HTTP 요청을 만들기 위한 .NET의 기본 제공 클래스인 HttpClient를 만드는 것부터 시작합니다. 일부 서버는 자신을 식별하지 않는 요청을 차단하기 때문에 User-Agent 헤더를 설정합니다. 서버에서 필요하지 않은 경우에도 이를 설정하는 것이 좋습니다.그런 다음 피드 URL에 대해 GET 요청을 보내고 응답을 문자열로 받습니다. 이 문자열에는 RSS 피드의 원시 XML이 포함되어 있습니다.

이 XML을 구문 분석하기 위해 StringReader를 만들어 응답 문자열을 래핑한 다음 일부 XmlReaderSettings를 구성합니다. DtdProcessing 설정은 중요합니다. RSS 피드에는 처리해야 하는 DTD(문서 유형 정의) 선언이 포함되는 경우가 있습니다. MaxCharactersFromEntities 설정은 엔터티 확장이 발생할 수 있는 정도를 제한하여 XML 폭탄 공격을 방지하는 보안 조치입니다.

마지막으로 이러한 설정을 사용하여 XmlReader를 만들고 SyndicationFeed.Load를 사용하여 XML을 강력한 형식의 SyndicationFeed 개체로 구문 분석합니다. 이를 통해 원시 XML 탐색 대신 멋진 C# 속성을 통해 피드의 메타데이터와 모든 항목에 액세스할 수 있습니다.

오류 처리를 통해 여러 피드 가져오기

실제 세계에서는 네트워크 요청이 실패합니다. 서버가 다운되고 연결 시간이 초과되며 XML 형식이 잘못될 수 있습니다. 우리는 이러한 경우를 우아하게 처리해야 합니다. 실패에 대한 복원력을 유지하면서 모든 피드를 가져오는 방법은 다음과 같습니다.

var allArticles = new List<(SyndicationItem item, string feedUrl)>();
var seenUrls = new HashSet<string>();

foreach (var feedUrl in feedUrls)
{
 try
 {
 Console.WriteLine($" 📡 Fetching {feedUrl}...");
 var feed = await FetchRssFeedAsync(feedUrl);

 if (feed?.Items != null && feed.Items.Any())
 {
 foreach (var item in feed.Items)
 {
 var itemUrl = item.Links.FirstOrDefault()?.Uri.ToString() ?? "";
 if (!string.IsNullOrEmpty(itemUrl) && seenUrls.Add(itemUrl))
 {
 allArticles.Add((item, feedUrl));
 }
 }
 }
 }
 catch (Exception ex)
 {
 Console.WriteLine($" ⚠️ Failed to fetch {feedUrl}: {ex.Message}");
 }
}

우리는 여기서 두 개의 컬렉션을 유지합니다. allArticles 목록에는 우리가 찾은 모든 기사와 해당 기사의 출처가 포함됩니다. visibleUrls HashSet은 우리가 이미 본 기사 URL을 추적하여 중복을 방지하는 데 도움이 됩니다.

각 피드 URL을 반복하고 try-catch 블록에서 가져오기 작업을 래핑합니다. 특정 피드를 가져오는 데 실패하면(서버가 일시적으로 다운되었을 수 있음) 경고를 기록하고 다음 피드를 계속 진행합니다. 이렇게 하면 하나의 피드에 문제가 있어도 다른 피드를 처리하는 데 방해가 되지 않습니다.

성공적으로 가져온 각 피드에 대해 해당 항목을 반복합니다. 항목의 Links 컬렉션에서 기사 URL을 추출합니다. HashSet.Add 메서드는 URL이 이미 세트에 있는 경우 false를 반환하며 이는 중복 제거 논리에 적합합니다. 기사가 새로운 경우에만 목록에 기사를 추가합니다.

이 정보는 나중에 유용할 수 있으므로 각 기사와 함께 피드 URL을 저장합니다. 예를 들어 디버깅 또는 로깅 목적으로 기사가 어떤 특정 피드에서 왔는지 알고 싶을 수 있습니다.

중복 처리 및 상태 추적

중복 제거 과제

앞서 언급했듯이 Microsoft DevBlogs에는 흥미로운 문제를 일으키는 계층적 피드 구조가 있습니다. .NET 팀 구성원이 .NET 10의 성능 향상에 대한 기사를 게시하면 해당 기사가 기본 DevBlogs 피드와 .NET 관련 피드 모두에 나타날 가능성이 높습니다. 때로는 IDE 기능과 관련된 경우 Visual Studio 피드에 나타날 수도 있습니다.

모든 피드의 모든 기사를 순진하게 처리했다면 결국 동일한 기사에 대해 여러 번 분석하고 게시하게 될 것입니다. 그러면 Azure OpenAI에 대한 API 호출이 낭비되고, 텔레그램에 중복 알림이 발송되며, 중복된 알림을 게시하면 팔로어가 잠재적으로 짜증을 낼 수 있습니다.해결책은 URL 기반 중복 제거입니다. 각 기사에는 고유한 URL이 있으므로 이를 식별자로 사용할 수 있습니다. HashSet 데이터 구조는 O(1) 조회 시간을 제공하고 자동으로 중복을 방지하므로 이에 적합합니다. 이미 집합에 있는 URL을 추가하려고 하면 Add 메서드는 단순히 false를 반환하여 해당 항목을 건너뛰어야 한다는 것을 알려줍니다.

마크다운을 사용한 지속 상태

중복 제거는 단일 실행 내에서 중복을 처리하지만 전체 실행에서는 어떻습니까? 애플리케이션이 6시간마다 실행될 때 이미 처리한 기사를 기억하여 다시 처리하지 않도록 해야 합니다.

나는 이 상태를 Posted-articles.md라는 마크다운 파일에 저장하기로 결정했습니다. 왜 마크다운인가? 몇 가지 이유. 첫째, 사람이 읽을 수 있습니다. 파일을 열고 내가 어떤 글을 공유했는지 즉시 확인할 수 있습니다. 둘째, 버전 관리입니다. 이 파일은 Git 저장소에 있으므로 기사가 처리된 시점에 대한 완전한 기록을 가지고 있습니다. 셋째, 문서화 역할을 합니다. 저장소를 보는 사람은 누구나 애플리케이션이 수행한 작업을 볼 수 있습니다.

이 파일의 형식은 간단합니다. 여기에는 헤더, 애플리케이션이 마지막으로 실행된 시간을 보여주는 타임스탬프, 마크다운 링크 형식의 기사 목록이 있습니다.

# Posted Articles

*Last run: 2025-12-10 15:30:00*

List of articles posted to LinkedIn:

- [Announcing .NET 10](https://devblogs.microsoft.com/dotnet/announcing-dotnet-10?wt.mc_id=DT-MVP-5004972) - Posted on 2025-12-10 15:30:00 (Published: 2025-12-10)
- [Visual Studio 2026 Preview](https://devblogs.microsoft.com/visualstudio/vs-2026-preview?wt.mc_id=DT-MVP-5004972) - Posted on 2025-12-09 10:15:00 (Published: 2025-12-09)

추적 파일 로드 및 구문 분석

기사를 이미 처리했는지 확인하려면 이 파일을 로드하고 URL을 추출해야 합니다. 이 작업을 수행하는 함수는 다음과 같습니다.

static HashSet<string> LoadPostedArticles(string filePath)
{
 var postedUrls = new HashSet<string>();

 if (!File.Exists(filePath))
 {
 return postedUrls;
 }

 var lines = File.ReadAllLines(filePath);
 foreach (var line in lines)
 {
 var match = System.Text.RegularExpressions.Regex.Match(line, @"\(([^)]+)\)");
 if (match.Success)
 {
 var url = match.Groups[1].Value;

 if (url.Contains("?wt.mc_id="))
 {
 url = url.Substring(0, url.IndexOf("?wt.mc_id="));
 }
 else if (url.Contains("?"))
 {
 url = url.Substring(0, url.IndexOf("?"));
 }

 url = url.TrimEnd('/');
 postedUrls.Add(url);
 }
 }

 return postedUrls;
}

이 함수는 우리가 이미 처리한 모든 URL을 포함하는 HashSet을 반환합니다. 파일이 존재하는지 확인하는 것부터 시작합니다. 처음 실행하면 존재하지 않으므로 빈 세트를 반환합니다.

파일의 각 줄에 대해 정규식을 사용하여 마크다운 링크 형식에서 URL을 추출합니다. 정규식 $([^)]+)$은 마크다운 링크가 URL을 저장하는 괄호 안의 모든 항목과 일치합니다.

그런 다음 중요한 단계인 URL 정규화를 수행합니다. 동일한 기사에 대한 URL의 형식은 다를 수 있습니다. RSS 피드는 https://devblogs.microsoft.com/dotnet/article를 제공할 수 있지만 저장된 버전에는 추적 매개변수 https://devblogs.microsoft.com/dotnet/article?wt.mc_id=DT-MVP-5004972가 추가되어 있습니다. 일부 URL에는 뒤에 슬래시가 있지만 다른 URL에는 없습니다.

이를 처리하기 위해 모든 쿼리 매개변수(? 뒤의 모든 항목)를 제거하고 후행 슬래시를 제거합니다. 이러한 정규화를 통해 기사의 URL이 표면적으로 다르더라도 기사를 중복으로 인식할 수 있습니다.

새 기사 저장

기사를 성공적으로 처리하면 이를 추적 파일에 추가해야 합니다.

static void SavePostedArticle(string filePath, string url, string title, DateTimeOffset publishDate)
{
 var markdownEntry = $"- [{title}]({url}) - Posted on {DateTime.Now:yyyy-MM-dd HH:mm:ss} (Published: {publishDate:yyyy-MM-dd})\n";

 if (!File.Exists(filePath))
 {
 File.WriteAllText(filePath, "# Posted Articles\n\n*Last run: {DateTime.Now:yyyy-MM-dd HH:mm:ss}*\n\nList of articles posted:\n\n");
 }

 File.AppendAllText(filePath, markdownEntry);
}

이 기능은 기사 제목을 링크로 사용하고 그 뒤에 기사를 게시한 시기와 원래 게시된 시기를 보여주는 타임스탬프가 포함된 마크다운 형식의 항목을 생성합니다. 파일이 아직 존재하지 않으면 먼저 헤더를 사용하여 파일을 만듭니다.

AI 분석 엔진

시맨틱 커널 이해하기이제 우리 애플리케이션의 가장 흥미로운 부분인 AI 분석에 들어갑니다. Semantic Kernel은 대규모 언어 모델을 애플리케이션에 통합하기 위한 Microsoft의 오픈 소스 SDK입니다. 이는 API 호출을 둘러싼 래퍼 그 이상입니다. 플러그인, 플래너, 메모리와 같은 기능을 갖춘 정교한 AI 애플리케이션을 구축하기 위한 프레임워크를 제공합니다.

사용 사례에서는 Semantic Kernel의 채팅 완료 기능을 사용하고 있습니다. Azure OpenAI에 메시지를 보내면 모델이 기사를 분석하고 응답을 생성합니다. 시맨틱 커널은 API 인증, 요청 형식화 및 응답 구문 분석의 모든 복잡성을 처리합니다.

기사 분석기 설정

분석기 클래스를 설정하는 방법을 살펴보겠습니다.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using HtmlAgilityPack;

namespace VsFeedLinkedin.Services;

public class ArticleAnalyzer
{
 private readonly Kernel _kernel;
 private readonly IChatCompletionService _chatService;

 public ArticleAnalyzer(string endpoint, string apiKey, string deploymentName)
 {
 var builder = Kernel.CreateBuilder();

 builder.AddAzureOpenAIChatCompletion(
 deploymentName: deploymentName,
 endpoint: endpoint,
 apiKey: apiKey
 );

 _kernel = builder.Build();
 _chatService = _kernel.GetRequiredService<IChatCompletionService>();
 }

시맨틱 커널은 구성을 위해 빌더 패턴을 사용합니다. KernelBuilder를 만들고 필요한 자격 증명을 사용하여 Azure OpenAI 채팅 완료 서비스를 추가한 다음 커널을 빌드합니다. 빌드된 커널에서 프롬프트를 보내고 응답을 받는 데 사용할 IChatCompletionService 인터페이스를 검색합니다.

생성자는 Azure OpenAI 엔드포인트(예: https://your-resource.openai.azure.com/), API 키 및 배포 이름(예: gpt-4o)의 세 가지 매개 변수를 사용합니다. 이는 환경 변수에서 전달되어 자격 증명을 안전하게 유지합니다.

완벽한 프롬프트 만들기

우리가 AI에 보내는 메시지는 매우 중요합니다. 잘 만들어진 프롬프트는 일관된 고품질 출력을 생성합니다. 모호하거나 잘못 구성된 프롬프트는 일관성이 없고 평범한 결과를 낳습니다. 나는 만족스러운 결과를 얻기 위해 이 프롬프트를 반복하는 데 상당한 시간을 보냈습니다.

var prompt = $"""
 You are a professional tech content analyst and LinkedIn content creator.
 Analyze the following Microsoft DevBlogs article and create an engaging LinkedIn post.

 Article Title: {title}
 Author: {author}
 URL: {url}
 Tags: {string.Join(", ", tags)}

 Article Content:
 {cleanContent}

 Please provide:
 1. A brief summary (2-3 sentences) of the key points
 2. The main technologies or topics covered
 3. Why this is relevant for developers/tech professionals
 4. An engaging LinkedIn post (max 1300 characters) that:
 - Starts with a hook or attention-grabbing statement
 - Highlights the key value for readers
 - Includes a call to action
 - Uses appropriate emojis (but not too many)
 - Maintains a professional yet approachable tone
 - DO NOT include hashtags in the post (they will be added separately)
 - DO NOT include the URL in the post (it will be added separately)

 Format your response as follows:
 ## Summary
 [Your summary here]

 ## Key Topics
 [List of main topics/technologies]

 ## Relevance
 [Why this matters]

 ## LinkedIn Post
 [Your engaging LinkedIn post here]
 """;

여기서 디자인 결정을 설명하겠습니다. 우리는 AI에게 “당신은 전문 기술 콘텐츠 분석가이자 LinkedIn 콘텐츠 제작자입니다.“라는 명확한 역할을 부여하는 것부터 시작합니다. 이는 모델이 적절한 스타일과 목소리로 반응하도록 준비시킵니다.

기사 제목, 작성자, URL, RSS 피드의 태그, 전체 기사 콘텐츠 등 AI에 필요한 모든 컨텍스트를 제공합니다. 더 많은 맥락을 제공할수록 분석이 더 좋아질 것입니다.

그런 다음 우리가 원하는 것을 정확히 지정합니다. 요약, 핵심 주제, 관련성 설명, LinkedIn 게시물의 네 가지를 요청합니다. 특히 LinkedIn 게시물의 경우 좋은 게시물을 만드는 방법에 대한 자세한 지침을 제공합니다. 즉, 관심을 끌 수 있어야 하고, 가치를 강조해야 하며, 클릭 유도 문구를 포함하고, 이모티콘을 적절하게 사용하고, 전문적인 분위기를 유지해야 합니다.

부정적인 지시도 마찬가지로 중요합니다. 나는 AI에게 게시물에 해시태그나 URL을 포함하지 말라고 명시적으로 지시합니다. 왜? 왜냐하면 저는 이것을 별도로 추가하고 AI가 이를 포함했다면 중복된 내용을 갖게 되기 때문입니다. 이런 종류의 명시적인 지시는 흔히 발생하는 실수를 방지합니다.

마지막으로 정확한 출력 형식을 지정합니다. ## 헤더로 표시된 섹션을 요청함으로써 프로그래밍 방식으로 응답을 쉽게 구문 분석할 수 있습니다. AI는 형식 지정 지침을 매우 잘 따르며 이러한 일관성으로 인해 구문 분석 코드가 더 간단하고 안정적이게 됩니다.

분석 실행

모든 것을 종합하는 방법은 다음과 같습니다.

public async Task<ArticleAnalysis> AnalyzeArticleAsync(
 string title,
 string url,
 string htmlContent,
 string author,
 List<string> tags)
{
 var cleanContent = ExtractTextFromHtml(htmlContent);

 if (cleanContent.Length > 8000)
 {
 cleanContent = cleanContent.Substring(0, 8000) + "...";
 }

 var chatHistory = new ChatHistory();
 chatHistory.AddUserMessage(prompt);

 var response = await _chatService.GetChatMessageContentAsync(chatHistory);
 var responseText = response.Content ?? "";

 return ParseAnalysisResponse(responseText, title, url, author, tags);
}
```먼저 HTML 콘텐츠에서 깨끗한 텍스트를 추출합니다(다음 섹션에서 이에 대해 설명하겠습니다). 그런 다음 내용이 너무 길면 내용을 자릅니다. 대규모 언어 모델에는 토큰 제한이 있으며 매우 긴 기사가 이를 초과할 수 있습니다. 8,000자로 제한함으로써 상당한 맥락을 제공하면서도 한도 내에서 유지되도록 보장합니다.

ChatHistory 개체를 만들고 프롬프트를 사용자 메시지로 추가합니다. 이는 채팅 기반 상호작용을 위한 Semantic Kernel의 추상화입니다. 이를 채팅 완료 서비스로 보내고 응답을 받습니다. 마지막으로 응답을 구문 분석하여 개별 섹션을 추출합니다.

### AI 응답 구문 분석

AI는 요청한 구조에 따라 형식이 지정된 텍스트로 응답을 반환합니다. 이를 개별 필드로 구문 분석해야 합니다.

```csharp
private static ArticleAnalysis ParseAnalysisResponse(
 string response,
 string title,
 string url,
 string author,
 List<string> tags)
{
 var analysis = new ArticleAnalysis
 {
 Title = title,
 Url = url,
 Author = author,
 Tags = tags,
 RawAnalysis = response
 };

 var sections = response.Split("##", StringSplitOptions.RemoveEmptyEntries);

 foreach (var section in sections)
 {
 var lines = section.Trim().Split('\n', 2);
 if (lines.Length < 2) continue;

 var sectionTitle = lines[0].Trim().ToLower();
 var sectionContent = lines[1].Trim();

 switch (sectionTitle)
 {
 case "summary":
 analysis.Summary = sectionContent;
 break;
 case "key topics":
 analysis.KeyTopics = sectionContent;
 break;
 case "relevance":
 analysis.Relevance = sectionContent;
 break;
 case "linkedin post":
 analysis.LinkedInPost = sectionContent;
 break;
 }
 }

 return analysis;
}

응답을 ## 마커로 분할하여 각 섹션을 제공합니다. 각 섹션에 대해 헤더와 콘텐츠를 분리하기 위해 줄바꿈으로 분할했습니다. 그런 다음 switch 문을 사용하여 각 섹션의 콘텐츠를 적절한 속성에 할당합니다.

또한 구문 분석되지 않은 원시 응답도 저장합니다. 이는 디버깅에 유용합니다. 구문 분석에 문제가 있는 경우 AI가 실제로 반환한 내용을 확인할 수 있습니다.

HTML에서 콘텐츠 추출

HTML을 정리해야 하는 이유

블로그에서 기사를 가져올 때 페이지의 전체 HTML을 얻습니다. 여기에는 기사 콘텐츠 그 이상을 포함합니다. 탐색 메뉴, 머리글, 바닥글, 사이드바, 관련 기사 위젯, 댓글 섹션, 분석 및 추적용 스크립트, 스타일시트 및 모든 종류의 기타 요소가 포함됩니다.

이 모든 것을 AI에 보내면 몇 가지 나쁜 일이 일어날 것입니다. AI는 관련 없는 텍스트를 많이 처리해야 하고 토큰을 낭비하며 잠재적으로 분석을 혼란스럽게 해야 합니다. 탐색 및 바닥글 텍스트가 요약에 포함될 수 있습니다. 스크립트와 CSS는 콘텐츠로 취급되어 분석을 더욱 오염시킵니다.

우리는 인간 독자가 실제로 읽을 부분인 기사 내용만 추출해야 합니다.

HtmlAgilityPack 사용

HtmlAgilityPack은 .NET용 강력한 HTML 구문 분석 라이브러리입니다. XML과 달리 HTML은 형식이 잘못된 경우가 많습니다. 태그가 제대로 닫히지 않거나 속성이 올바르게 인용되지 않을 수 있습니다. HtmlAgilityPack은 이 모든 것을 우아하게 처리하여 쿼리하고 조작할 수 있는 DOM과 같은 구조를 제공합니다.

추출 기능은 다음과 같습니다.

private static string ExtractTextFromHtml(string html)
{
 if (string.IsNullOrWhiteSpace(html))
 return string.Empty;

 var doc = new HtmlDocument();
 doc.LoadHtml(html);

 var nodesToRemove = doc.DocumentNode.SelectNodes("//script|//style|//nav|//footer|//header");
 if (nodesToRemove != null)
 {
 foreach (var node in nodesToRemove)
 {
 node.Remove();
 }
 }

 var text = doc.DocumentNode.InnerText;

 text = System.Text.RegularExpressions.Regex.Replace(text, @"\s+", " ");
 return text.Trim();
}

HTML을 HtmlDocument에 로드하여 트리 구조로 구문 분석합니다. 그런 다음 XPath를 사용하여 제거하려는 모든 노드를 선택합니다. XPath 표현식 //script|//style|//nav|//footer|//header는 모든 스크립트 요소(필요하지 않은 JavaScript 코드), 스타일 요소(필요하지 않은 CSS), nav 요소(탐색 메뉴), 바닥글 요소 및 헤더 요소를 선택합니다.

이러한 노드를 제거한 후 HTML 태그를 제거하는 동안 모든 텍스트 내용을 추출하는 InnerText 속성을 얻습니다. 이는 기사의 일반 텍스트를 제공합니다.마지막으로 공백을 정리합니다. HTML에는 서식 지정을 위해 공백, 탭, 줄 바꿈 등 많은 추가 공백이 있는 경우가 많습니다. 정규식을 사용하여 일련의 공백 문자를 단일 공백으로 바꾼 다음 결과를 자릅니다.

전체 기사 가져오기

RSS 피드는 전체 기사 내용이 아닌 요약만 제공합니다. 전체 텍스트를 얻으려면 기사의 웹 페이지를 가져와야 합니다.

public static async Task<string> FetchArticleContentAsync(string url)
{
 using var httpClient = new HttpClient();
 httpClient.DefaultRequestHeaders.Add("User-Agent", "VsFeedLinkedin/1.0");

 try
 {
 return await httpClient.GetStringAsync(url);
 }
 catch (Exception ex)
 {
 Console.WriteLine($"⚠️ Failed to fetch article content: {ex.Message}");
 return string.Empty;
 }
}

이는 간단합니다. 기사 URL에 대해 HTTP GET 요청을 하고 HTML 응답을 반환합니다. 네트워크 요청이 실패할 수 있으므로 try-catch로 래핑하고 전체 애플리케이션을 충돌시키는 것보다 빈 문자열을 반환하는 것이 좋습니다.

영구 문서 만들기

마크다운 파일을 생성하는 이유

기사를 분석할 때마다 해당 분석을 문서화하는 상세한 마크다운 파일을 생성합니다. 이는 여러 가지 목적으로 사용됩니다.

먼저 검색 가능한 아카이브를 생성합니다. 시간이 지남에 따라 분석된 기사 모음을 구축하게 됩니다. 이러한 파일을 검색하여 특정 주제에 대한 과거 콘텐츠를 찾을 수 있습니다.

둘째, 투명성을 제공합니다. 전체 분석 및 LinkedIn 게시물을 포함하여 각 기사에 대해 AI가 생성한 내용을 정확하게 확인할 수 있습니다.

셋째, 디버깅에 유용합니다. 게시물에 문제가 있는 경우 마크다운 파일을 보고 무슨 일이 일어났는지 이해할 수 있습니다.

마크다운 생성기 클래스

public class MarkdownGenerator
{
 private readonly string _outputDirectory;

 public MarkdownGenerator(string outputDirectory)
 {
 _outputDirectory = outputDirectory;

 if (!Directory.Exists(_outputDirectory))
 {
 Directory.CreateDirectory(_outputDirectory);
 }
 }

 public string GenerateMarkdownFile(ArticleAnalysis analysis)
 {
 var sb = new StringBuilder();

 var safeTitle = GenerateSafeFileName(analysis.Title);
 var fileName = $"{analysis.AnalyzedAt:yyyy-MM-dd}_{safeTitle}.md";
 var filePath = Path.Combine(_outputDirectory, fileName);

 sb.AppendLine($"# {analysis.Title}");
 sb.AppendLine();
 sb.AppendLine("## Article Information");
 sb.AppendLine();
 sb.AppendLine($"- **Author:** {analysis.Author}");
 sb.AppendLine($"- **URL:** [{analysis.Url}]({analysis.Url})");
 sb.AppendLine($"- **Published:** {analysis.PublishDate:yyyy-MM-dd}");
 sb.AppendLine($"- **Analyzed:** {analysis.AnalyzedAt:yyyy-MM-dd HH:mm:ss}");
 sb.AppendLine($"- **Tags:** {string.Join(", ", analysis.Tags)}");
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("## AI Analysis");
 sb.AppendLine();
 sb.AppendLine("### Summary");
 sb.AppendLine();
 sb.AppendLine(analysis.Summary);
 sb.AppendLine();
 sb.AppendLine("### Key Topics");
 sb.AppendLine();
 sb.AppendLine(analysis.KeyTopics);
 sb.AppendLine();
 sb.AppendLine("### Relevance for Developers");
 sb.AppendLine();
 sb.AppendLine(analysis.Relevance);
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("## Generated LinkedIn Post");
 sb.AppendLine();
 sb.AppendLine("```");
 sb.AppendLine(분석.LinkedInPost);
 sb.AppendLine("```");
 sb.AppendLine();
 sb.AppendLine("");
 sb.AppendLine();
 sb.AppendLine("*This analysis was generated using AI (Semantic Kernel with Azure OpenAI)*");

 File.WriteAllText(filePath, sb.ToString());
 return filePath;
 }

생성자는 출력 디렉터리 경로를 가져와서 존재하지 않는 경우 생성합니다. generateMarkdownFile 메서드는 ArticleAnalytic 개체를 사용하여 적절한 형식의 마크다운 문서를 생성합니다.

파일 이름에는 날짜와 제목의 삭제된 버전이 포함됩니다. 이를 통해 파일을 시간순으로 쉽게 정렬하고 한눈에 식별할 수 있습니다.

안전하지 않은 파일 이름 처리

기사 제목에는 파일 이름에 허용되지 않는 문자(콜론, 슬래시, 물음표, 따옴표 등)가 포함될 수 있습니다. 우리는 다음을 소독해야 합니다:

private static string GenerateSafeFileName(string title)
{
 var invalidChars = Path.GetInvalidFileNameChars();
 var safeTitle = new string(title
 .Where(c => !invalidChars.Contains(c))
 .ToArray());

 safeTitle = safeTitle.Replace(" ", "-").Replace("--", "-");

 if (safeTitle.Length > 50)
 {
 safeTitle = safeTitle.Substring(0, 50);
 }

 return safeTitle.TrimEnd('-').ToLowerInvariant();
}

Path.GetInvalidFileNameChars()를 사용하여 현재 운영 체제에서 파일 이름에 나타날 수 없는 문자 목록을 가져옵니다. 이를 필터링하고, 가독성을 위해 공백을 하이픈으로 바꾸고, 길이를 50자로 제한하고, 일관성을 위해 소문자로 변환합니다.

텔레그램 알림 설정

내가 텔레그램을 선택한 이유

알림 구성 요소의 경우 이메일, SMS, Slack, Discord 및 Telegram과 같은 여러 옵션을 고려했습니다. 저는 여러 가지 이유로 궁극적으로 Telegram을 선택했습니다.

API는 합리적인 사용을 위해 속도 제한 없이 완전 무료입니다. 많은 알림 서비스에는 무료로 보낼 수 있는 메시지 수에 제한이 있지만 Telegram은 봇 메시지를 개별 사용자에게 제한하지 않습니다.

봇 API는 놀라울 정도로 간단합니다. JSON 페이로드가 포함된 HTTP 요청일 뿐입니다. 복잡한 인증 흐름이 없으며 기본 기능에 웹후크가 필요하지 않습니다.텔레그램은 휴대폰, 데스크톱, 웹 브라우저 등 어디에서나 작동합니다. 내가 어디에 있든 알림을 받고 즉시 응답할 수 있습니다.

메시지는 다양한 형식을 지원합니다. 굵은 텍스트, 기울임꼴, 심지어 코드 블록을 사용하여 알림을 더 읽기 쉽게 만들 수 있습니다.

텔레그램 봇 만들기

텔레그램 봇을 설정하는 것은 놀라울 정도로 쉽습니다. Telegram을 열고 @BotFather를 검색하세요. 이는 봇 생성 및 관리를 위한 Telegram의 공식 봇입니다. BotFather와 대화를 시작하고 /newbot 명령을 보냅니다. BotFather는 봇의 이름(표시 이름)과 사용자 이름(고유해야 하며 “bot"으로 끝나야 함)을 묻습니다. 이를 제공하면 BotFather가 봇을 생성하고 API 토큰을 제공합니다. 이 토큰은 비밀번호와 같습니다. 비밀로 유지하고 공개 저장소에 커밋하지 마세요.

봇이 메시지를 보낼 위치를 알 수 있도록 채팅 ID를 찾으려면 검색하고 시작을 눌러 새 봇과 대화를 시작하세요. 그런 다음 브라우저에서 또는 컬을 사용하여 URL https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates에 액세스합니다. 응답에서 chat 개체를 찾으세요. id 필드는 채팅 ID입니다.

API를 통해 메시지 보내기

텔레그램 메시지를 보내는 기능은 다음과 같습니다.

static async Task SendToTelegramAsync(string botToken, string chatId, string message)
{
 using var httpClient = new HttpClient();

 var telegramApiUrl = $"https://api.telegram.org/bot{botToken}/sendMessage";

 var payload = new
 {
 chat_id = chatId,
 text = message,
 parse_mode = "HTML"
 };

 var jsonContent = JsonSerializer.Serialize(payload);
 var content = new StringContent(jsonContent, Encoding.UTF8, "application/json");

 var response = await httpClient.PostAsync(telegramApiUrl, content);

 if (!response.IsSuccessStatusCode)
 {
 var errorContent = await response.Content.ReadAsStringAsync();
 throw new Exception($"Telegram API error: {response.StatusCode} - {errorContent}");
 }
}

Telegram Bot API는 REST 기반입니다. 채팅 ID(보내는 위치), 메시지 텍스트(보내는 내용) 및 선택적으로 구문 분석 모드(서식 지정용)가 포함된 JSON 본문을 사용하여 sendMessage 엔드포인트에 대한 POST 요청을 수행합니다.

parse_mode를 “HTML"로 설정하면 메시지에 <b>bold</b> 및 <i>italic</i>와 같은 기본 HTML 태그를 사용할 수 있습니다. 이렇게 하면 알림을 더 읽기 쉽게 만들 수 있지만 현재 사용 사례에서는 일반 텍스트를 보냅니다.

요청이 실패하면 무엇이 잘못되었는지에 대한 세부정보와 함께 예외가 발생합니다. 이는 무언가가 작동하지 않는 경우 디버깅에 도움이 됩니다.

애플리케이션 구성

환경 변수

우리 애플리케이션에는 API 키, 봇 토큰, 엔드포인트 URL 등 여러 가지 민감한 정보가 필요합니다. 우리는 이것을 하드코딩하거나 버전 관리에 커밋해서는 안 됩니다. 대신 애플리케이션이 실행되는 각 환경에서 안전하게 설정할 수 있는 환경 변수를 사용합니다.

텔레그램의 경우 TELEGRAM_BOT_TOKEN(BotFather가 제공한 토큰)과 TELEGRAM_CHAT_ID(메시지를 보내야 하는 채팅 ID)가 필요합니다.

Azure OpenAI의 경우 AZURE_OPENAI_ENDPOINT(리소스 URL), AZURE_OPENAI_API_KEY(API 키) 및 AZURE_OPENAI_DEPLOYMENT(“gpt-4o"와 같은 배포된 모델 이름)가 필요합니다.

코드에서 구성 로드

애플리케이션 시작 시 이러한 값을 로드하는 방법은 다음과 같습니다.

var telegramBotToken = Environment.GetEnvironmentVariable("TELEGRAM_BOT_TOKEN");
var telegramChatId = Environment.GetEnvironmentVariable("TELEGRAM_CHAT_ID");

var azureOpenAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
var azureOpenAiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");
var azureOpenAiDeployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT") ?? "gpt-4o";

var aiAnalysisEnabled = !string.IsNullOrWhiteSpace(azureOpenAiEndpoint) &&
 !string.IsNullOrWhiteSpace(azureOpenAiKey);

Environment.GetEnvironmentVariable을 사용하여 각 값을 읽습니다. 배포 이름에는 값이 설정되지 않은 경우 기본값인 “gpt-4o"가 제공됩니다.

그런 다음 엔드포인트와 API 키가 모두 있는지 확인하여 AI 분석을 활성화해야 하는지 여부를 확인합니다. 이를 통해 Azure OpenAI가 구성되지 않은 경우 애플리케이션이 저하된 모드에서 실행될 수 있습니다. AI 분석 없이도 여전히 피드를 가져오고 기사를 추적합니다.### 우아한 저하

이러한 우아한 저하 개념은 중요합니다. 하나의 선택적 기능이 구성되지 않았기 때문에 애플리케이션이 충돌하는 것을 원하지 않습니다.

ArticleAnalyzer? articleAnalyzer = null;
MarkdownGenerator? markdownGenerator = null;

if (aiAnalysisEnabled)
{
 Console.WriteLine("🤖 AI Analysis enabled - Using Azure OpenAI with Semantic Kernel");
 articleAnalyzer = new ArticleAnalyzer(azureOpenAiEndpoint!, azureOpenAiKey!, azureOpenAiDeployment);
 markdownGenerator = new MarkdownGenerator(articlesOutputDir);
}
else
{
 Console.WriteLine("ℹ️ AI Analysis disabled - Set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY to enable");
}

AI가 활성화되면 분석기와 마크다운 생성기를 만듭니다. 그렇지 않은 경우 null로 두고 처리 중에 AI 관련 단계를 건너뜁니다. AI 향상 없이도 애플리케이션은 피드를 가져오고 기본 알림을 보내 여전히 가치를 제공합니다.

GitHub Actions로 자동화

GitHub Action을 사용해야 하는 이유

이 솔루션의 진정한 힘은 자동화에서 나옵니다. 우리는 애플리케이션을 몇 시간마다 수동으로 실행하고 싶지 않고 백그라운드에서 자동으로 실행되기를 원합니다.

GitHub Actions가 이에 적합합니다. GitHub에 내장되어 있으므로 추가로 설정할 서비스가 없습니다. 공용 저장소의 경우 무료이며 개인 저장소의 경우 넉넉한 무료 시간이 포함되어 있습니다. 일정에 따라 실행되어 정기적으로 애플리케이션을 트리거할 수 있습니다. API 키를 안전하게 저장하기 위한 비밀 관리 기능이 내장되어 있습니다. 그리고 변경 사항을 저장소에 다시 커밋하여 추적 파일을 최신 상태로 유지할 수 있습니다.

워크플로 파일

.github/workflows/fetch-and-notify.yml에 다음 내용이 포함된 파일을 만듭니다.

name: Fetch DevBlogs and Notify

on:
 schedule:
 - cron: '0 */6 * * *'
 workflow_dispatch:

jobs:
 fetch-and-notify:
 runs-on: ubuntu-latest

 steps:
 - name: Checkout repository
 uses: actions/checkout@v4

 - name: Setup .NET
 uses: actions/setup-dotnet@v4
 with:
 dotnet-version: '9.0.x'

 - name: Restore dependencies
 run: dotnet restore src/VsFeedLinkedin.csproj

 - name: Build
 run: dotnet build src/VsFeedLinkedin.csproj --no-restore

 - name: Run application
 env:
 TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
 TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
 AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
 AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
 AZURE_OPENAI_DEPLOYMENT: ${{ secrets.AZURE_OPENAI_DEPLOYMENT }}
 run: dotnet run --project src/VsFeedLinkedin.csproj

 - name: Commit and push changes
 run: |
 git config user.name "GitHub Actions Bot"
 git config user.email "actions@github.com"

 if [[ -n $(git status --porcelain posted-articles.md generated-posts/) ]]; then
 TIMESTAMP=$(date +%Y%m%d_%H%M%S)
 git add posted-articles.md generated-posts/
 git commit -m "chore($TIMESTAMP): processed new articles"
 git push
 else
 echo "No changes to commit"
 fi

각 부분을 설명하겠습니다. on 섹션은 워크플로가 실행되는 시기를 정의합니다. 일정 트리거는 cron 구문을 사용합니다. 0 */6 * * *는 “매 6시간의 0분에"를 의미합니다. 따라서 워크플로는 UTC 기준 자정, 오전 6시, 정오 및 오후 6시에 실행됩니다. Workflow_dispatch 트리거를 사용하면 GitHub UI에서 수동으로 실행할 수 있어 테스트에 유용합니다.

작업은 Linux 가상 머신인 ubuntu-latest에서 실행됩니다. 저장소를 확인하고, .NET 9를 설정하고, NuGet 패키지를 복원하고, 프로젝트를 빌드합니다.

애플리케이션 실행 단계에서는 마법 같은 일이 일어납니다. ${{ secrets.SECRET_NAME }} 구문을 사용하여 비밀을 환경 변수로 전달합니다. 이러한 비밀은 GitHub에 안전하게 저장되며 로그에 노출되지 않습니다.

마지막으로 모든 변경 사항을 저장소에 다시 커밋합니다. 봇 ID로 Git을 구성하고, 추적 파일이나 생성된 게시물 디렉터리에 변경 사항이 있는지 확인하고, 그렇다면 커밋을 생성하여 푸시합니다.

비밀 설정

GitHub 저장소에 비밀을 추가하려면 저장소의 설정, 비밀 및 변수, 작업으로 이동하세요. “새 저장소 비밀"을 클릭하고 각 환경 변수를 추가하십시오. 이름은 워크플로 파일에서 참조하는 이름과 정확히 일치해야 합니다.

마무리

우리가 만든 것

우리가 다룬 모든 내용을 되돌아보면, 우리는 지루한 수동 프로세스였던 것을 자동화하는 포괄적인 AI 기반 RSS 피드 수집기를 구축했습니다. 이 애플리케이션은 7개의 Microsoft DevBlog 피드를 자동으로 모니터링하여 모든 새 기사가 게시되는 즉시 이를 포착합니다. 동일한 기사가 여러 피드에 나타나는 경우를 인식하여 중복 제거의 복잡성을 처리합니다.Semantic Kernel 및 Azure OpenAI를 기반으로 하는 AI 분석은 기사 콘텐츠를 읽고 이해하고, 요약을 생성하고, 주요 주제를 식별하고, 관련성을 설명하는 작업을 모두 자동으로 수행합니다. 가장 중요한 점은 최소한의 편집만으로 공유할 수 있는 매력적인 LinkedIn 게시물을 생성한다는 것입니다.

Telegram 통합은 검토할 새 콘텐츠가 있을 때마다 휴대폰으로 알림을 받을 수 있음을 의미합니다. 메시지를 보고 공유할지 결정하고 즉시 조치를 취할 수 있습니다.

그리고 일정에 따라 GitHub Actions에서 실행되기 때문에 어떤 작업도 기억할 필요가 없습니다. 시스템은 백그라운드에서 작동하며 공유할 가치가 있는 내용이 있을 때만 참여합니다.

이를 가능하게 한 기술

이 프로젝트는 각각 중요한 역할을 하는 여러 기술을 통합했습니다. .NET 9는 최신 언어 기능과 뛰어난 성능으로 견고한 기반을 제공했습니다. Semantic Kernel은 API 호출 및 응답 관리의 모든 복잡성을 처리하여 AI 통합을 간단하게 만들었습니다. Azure OpenAI는 기술 콘텐츠를 실제로 이해하고 분석하는 능력인 인텔리전스를 제공했습니다. HtmlAgilityPack은 웹 페이지에서 깨끗한 텍스트를 추출하는 복잡한 문제를 해결했습니다. System.ServiceModel.Syndication을 사용하면 RSS 구문 분석이 쉬워졌습니다. Telegram Bot API는 우리에게 신뢰할 수 있는 무료 알림을 제공했습니다. 그리고 GitHub Actions는 자동화된 예약 실행을 통해 이 모든 것을 하나로 묶었습니다.

비용에 대한 생각

여러분이 가질 수 있는 한 가지 질문은 다음과 같습니다. 이 작업을 실행하는 데 드는 비용은 얼마입니까? 대답은: 전혀 많지 않습니다.

텔레그램은 완전히 무료입니다. 봇을 통해 메시지를 보내는 데 비용이 들지 않습니다.

GitHub Actions는 공개 저장소에 무료로 제공됩니다. 프라이빗 리포지토리의 경우 무료 등급으로 월 2,000분을 이용할 수 있으며 이는 우리 사용 사례에 충분합니다.

Azure OpenAI는 유일한 유료 구성 요소이며 비용은 최소화됩니다. GPT-4o를 사용하면 일반적인 블로그 기사를 분석하는 데 1센트에서 3센트 정도의 비용이 듭니다. 한 달에 수십 개의 기사를 처리하더라도 AI 비용은 1달러 미만으로 보고 있습니다.

다음에는 어디로 갈 수 있나요?

이 솔루션은 내 요구 사항에 매우 적합하지만 이를 확장할 수 있는 방법은 많습니다. 여러 소셜 플랫폼에 대한 지원을 추가할 수 있습니다. LinkedIn 외에도 Twitter/X, Mastodon 또는 Bluesky에 게시할 수도 있습니다. 감정 분석을 구현하여 시간 경과에 따른 기사의 분위기를 추적하고 추세를 파악할 수 있습니다. 다양한 피드에 대해 다양한 프롬프트 템플릿을 허용하여 다양한 주제에 대해 다양한 스타일의 게시물을 생성할 수 있습니다. 텔레그램을 사용하는 대신 게시물을 검토하고 관리하기 위한 웹 대시보드를 구축할 수 있습니다. 게시된 콘텐츠에 대한 참여 지표를 추적하여 어떤 주제가 청중에게 가장 큰 공감을 불러일으키는지 확인할 수 있습니다.

최종 생각이 프로젝트에서 제가 가장 좋아하는 점은 제가 강력하게 믿는 철학을 구현한다는 것입니다. 자동화는 지루한 부분을 처리하고 창의적이고 의사결정적인 부분은 인간에게 맡겨야 한다는 것입니다. 시스템은 가져오기, 구문 분석, 분석, 생성 등 모든 힘든 작업을 수행하지만 공유하기 전에 모든 것을 검토합니다. AI가 생성한 게시물은 내가 맞춤화하고 개인화할 수 있는 출발점입니다.

.NET, Semantic Kernel 및 Azure OpenAI의 강력한 기능을 결합하여 품질과 일관성을 유지하면서 매주 수동 작업 시간을 절약하는 도구를 만들었습니다. 이는 일상 생활에 실질적인 변화를 가져오는 일종의 실용적인 자동화입니다.

비슷한 것을 만들거나 개선할 아이디어가 있다면 알려주시면 감사하겠습니다. LinkedIn에 언제든지 문의하세요!

즐거운 코딩 보내시고, 즐거운 크리스마스 보내세요! 🎄

Microsoft의 에이전트 프레임워크를 사용하여 다중 에이전트 AI 시스템 구축

Mon, 01 Dec 2025 00:00:00 +0000

소개

우리는 멀티 에이전트 AI 시스템 시대에 들어섰습니다. 모든 것을 처리하는 단일 모놀리식 AI 대신, 업계는 잘 조직된 전문가 팀처럼 복잡한 문제를 해결하기 위해 협력하는 전문 에이전트로 전환하고 있습니다. 한 에이전트는 조사하고, 다른 에이전트는 분석하고, 세 번째 에이전트는 작성하고, 코디네이터는 모든 사람의 정보를 추적합니다.

대규모 언어 모델로 작업한 경우 단일 프롬프트로 수행할 수 있는 작업의 한계에 도달했을 가능성이 높습니다. 컨텍스트 창이 가득 차고 지침이 엉키며 품질이 저하됩니다. 다중 에이전트 아키텍처는 복잡한 작업을 각 에이전트가 한 분야의 전문가인 집중된 책임으로 분해하여 이 문제를 해결합니다.

광범위한 Semantic Kernel 에코시스템의 일부인 Microsoft Agent Framework는 .NET 개발자에게 이러한 종류의 시스템을 구축하기 위한 최고의 도구 키트를 제공합니다. 이 게시물에서는 시작하는 데 필요한 핵심 개념, 오케스트레이션 패턴 및 실제 코드를 다루면서 완전하게 작동하는 다중 에이전트 파이프라인으로 이동합니다.

Microsoft의 에이전트 프레임워크란 무엇입니까?

에이전트 프레임워크는 .NET에서 AI 에이전트 및 다중 에이전트 시스템을 구축, 조정 및 배포하기 위한 Microsoft의 답변입니다. 이는 2023년부터 Microsoft의 AI 오케스트레이션을 위한 오픈 소스 SDK인 Semantic Kernel과 나란히 위치하며 긴밀하게 통합됩니다.

이렇게 생각해보세요. 의미론적 커널은 기본 요소(커널, 플러그인, 메모리, 플래너)를 제공하는 반면 에이전트 프레임워크는 에이전트 간 통신 및 조정을 위해 특별히 설계된 상위 수준 추상화를 제공합니다.

프레임워크는 Azure OpenAI, OpenAI 및 Azure AI Foundry에서 호스팅되는 모델을 포함한 여러 모델 공급자를 지원합니다. 디자인 면에서는 모델에 구애받지 않지만 Azure 에코시스템과 긴밀하게 통합되어 있어 엔터프라이즈 시나리오에 특히 매력적입니다.

주요 기능은 다음과 같습니다.

여러 에이전트 유형: 다양한 백엔드에 대한 ChatCompletionAgent, OpenAIAssistantAgent 및 AzureAIAgent
오케스트레이션 패턴: 순차, 동시, 핸드오프 및 그룹 채팅 워크플로
플러그인 에코시스템: 기본 C# 기능, OpenAPI 사양 및 MCP(Model Context Protocol) 도구를 사용하여 에이전트 확장
대화 관리: 스레딩, 이력 관리, 종료 전략 내장
관찰 가능성: 에이전트 상호 작용 추적을 위해 OpenTelemetry와 통합

주요 개념

코드를 작성하기 전에 어휘를 설정해 보겠습니다. 에이전트 프레임워크는 몇 가지 핵심 추상화를 중심으로 진행됩니다.

에이전트

에이전트는 특정 지침(시스템 프롬프트), 이름 및 선택적으로 플러그인 또는 도구 세트로 구성된 AI 모델의 지원을 받는 엔터티입니다. 각 에이전트는 전문가입니다. 에이전트가 무엇을 알고 있는지, 무엇을 할 수 있는지, 어떻게 행동해야 하는지 정의할 수 있습니다.

ChatCompletionAgent가장 간단한 에이전트 유형입니다. 채팅 완료 엔드포인트(Azure OpenAI, OpenAI 등)를 래핑하고 대화를 유지 관리합니다. 호출 간에는 상태 비저장입니다. 기록을 제공하면 응답합니다. 이렇게 하면 가볍고 추론하기 쉽습니다.

ChatCompletionAgent agent = new()
{
 Name = "Reviewer",
 Instructions = "You are a senior code reviewer. Analyze the provided code for bugs, security issues, and style violations. Be concise and actionable.",
 Kernel = kernel
};

OpenAIAssistantAgent

이 에이전트 유형은 서버 측 대화 상태, 파일 처리 및 코드 해석을 제공하는 OpenAI Assistants API를 활용합니다. 더 무겁지만 지속적인 스레드와 코드 해석기 및 파일 검색과 같은 내장 도구를 제공합니다.

OpenAIAssistantAgent agent = await OpenAIAssistantAgent.CreateAsync(
 clientProvider: clientProvider,
 definition: new OpenAIAssistantDefinition("gpt-4o")
 {
 Name = "DataAnalyst",
 Instructions = "You analyze datasets and produce statistical summaries."
 }
);

에이전트그룹채팅

오케스트레이터입니다. AgentGroupChat는 여러 에이전트 간의 다단계 대화를 관리하여 다음에 말할 사람, 대화 종료 시기 및 기록 공유 방법을 제어합니다. 다중 에이전트 협업의 마법이 일어나는 곳입니다.

오케스트레이션 패턴

프레임워크는 각기 다른 문제에 적합한 네 가지 기본 오케스트레이션 패턴을 지원합니다.

순차

에이전트는 정의된 순서에 따라 하나씩 실행됩니다. 에이전트 A의 출력은 에이전트 B로 공급되고, 에이전트 B의 출력은 에이전트 C로 공급됩니다. 이는 초안 → 검토 → 편집 → 게시와 같은 파이프라인에 이상적입니다.

// Conceptual flow
var draft = await writerAgent.InvokeAsync("Write a blog post about .NET 9");
var reviewed = await reviewerAgent.InvokeAsync($"Review this: {draft}");
var edited = await editorAgent.InvokeAsync($"Edit based on feedback: {reviewed}");

동시

여러 에이전트가 동일한 입력에 대해 동시에 작업합니다. 작업을 펼치고 결과를 집계합니다. 세 명의 검토자가 동일한 끌어오기 요청을 보는 것과 같이 다양한 관점을 얻는 데 적합합니다.

핸드오프

에이전트는 대화 컨텍스트를 기반으로 다른 에이전트에게 제어권을 이전하기로 결정합니다. 이는 고객 서비스 팀의 업무 방식을 모방합니다. 일선 상담원이 기본 쿼리를 처리하고 필요할 때 전문가에게 에스컬레이션합니다.

그룹 채팅

여러 에이전트가 선택 전략에 따라 차례로 공개 대화에 참여합니다. AgentGroupChat 클래스는 구성 가능한 차례 진행 및 종료 논리를 사용하여 이 패턴을 구현합니다.

첫 번째 에이전트 구축

실습해 봅시다. 첫 번째 에이전트를 단계별로 구축하는 방법은 다음과 같습니다.

전제조건

다음이 필요합니다.

.NET 9 SDK
배포된 모델이 있는 Azure OpenAI 리소스(예: gpt-4o)
비주얼 스튜디오 또는 VS 코드

프로젝트 설정

새 콘솔 애플리케이션을 만들고 필요한 패키지를 설치합니다.

dotnet new console -n AgentDemo
cd AgentDemo
dotnet add package Microsoft.SemanticKernel --prerelease
dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity

단순 에이전트 만들기

먼저 Azure OpenAI 구성으로 커널을 설정합니다.

using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 credentials: new DefaultAzureCredential()
);

Kernel kernel = builder.Build();

이제 에이전트를 생성하고 호출합니다.

ChatCompletionAgent agent = new()
{
 Name = "TechWriter",
 Instructions = """
 You are a technical writer specializing in software documentation.
 Write clear, concise content aimed at experienced developers.
 Use code examples when appropriate.
 Always structure your output with headings and bullet points.
 """,
 Kernel = kernel
};

ChatHistory history = new();
history.AddUserMessage("Explain dependency injection in .NET in 200 words.");

await foreach (ChatMessageContent response in agent.InvokeAsync(history))
{
 Console.WriteLine(response.Content);
}

그게 다야. 근무 중인 에이전트가 있습니다. 하지만 진정한 힘은 상담원들이 함께 일할 때 나옵니다.

AgentGroupChat을 사용한 다중 에이전트 오케스트레이션

여러 에이전트가 협업하는 그룹 채팅이라는 좀 더 흥미로운 것을 만들어 보겠습니다. AgentGroupChat 클래스는 다음에 말할 사람과 중지할 시간을 포함하여 대화 흐름을 관리합니다.

에이전트 정의

작가, 리뷰어, 편집자의 세 가지 에이전트를 만듭니다.

ChatCompletionAgent writer = new()
{
 Name = "Writer",
 Instructions = """
 You are a content writer. When given a topic, produce a well-structured
 draft. Focus on clarity and technical accuracy.
 When you receive feedback from the Reviewer, incorporate it into a
 revised draft.
 """,
 Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
 Name = "Reviewer",
 Instructions = """
 You are a content reviewer. Analyze drafts for technical accuracy,
 clarity, and completeness. Provide specific, actionable feedback.
 Do NOT rewrite the content — only provide feedback.
 When the content meets your standards, respond with: APPROVED
 """,
 Kernel = kernel
};

ChatCompletionAgent editor = new()
{
 Name = "Editor",
 Instructions = """
 You are an editor. Once content is approved by the Reviewer,
 polish it for grammar, tone, and formatting.
 Output only the final polished version.
 When you have produced the final version, respond with: COMPLETE
 """,
 Kernel = kernel
};

그룹 채팅 설정하기

AgentGroupChat에는 선택 전략(다음에 말할 사람)과 종료 전략(중지할 시기)이라는 두 가지 핵심 구성이 필요합니다.

AgentGroupChat chat = new(writer, reviewer, editor)
{
 ExecutionSettings = new()
 {
 SelectionStrategy = new SequentialSelectionStrategy(),
 TerminationStrategy = new ApprovalTerminationStrategy()
 {
 Agents = [editor],
 MaximumIterations = 12
 }
 }
};

맞춤형 종료 전략종료 전략은 대화가 끝나는 시기를 정의합니다. 다음은 “COMPLETE” 키워드를 찾는 사용자 정의입니다.

class ApprovalTerminationStrategy : TerminationStrategy
{
 protected override Task<bool> ShouldAgentTerminateAsync(
 Agent agent,
 IReadOnlyList<ChatMessageContent> history,
 CancellationToken cancellationToken = default)
 {
 bool isComplete = history
 .Last()
 .Content?
 .Contains("COMPLETE", StringComparison.OrdinalIgnoreCase) ?? false;

 return Task.FromResult(isComplete);
 }
}

대화 실행하기

사용자 메시지로 대화를 시작하고 상담원이 협업할 수 있도록 하세요.

chat.AddChatMessage(
 new ChatMessageContent(AuthorRole.User,
 "Write a 300-word technical overview of gRPC vs REST for microservices.")
);

await foreach (ChatMessageContent message in chat.InvokeAsync())
{
 Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
 Console.WriteLine("---");
}

흐름은 다음과 같습니다.

작가가 초안을 작성합니다.
검토자가 피드백을 제공합니다.
작가는 피드백을 바탕으로 수정합니다.
검토자가 “승인됨"이라고 말합니다.
편집자가 다듬고 “완료"라고 말합니다.
대화가 종료됩니다

이러한 앞뒤 이동은 종료 조건이 충족되거나 MaximumIterations에 도달할 때까지 자동으로 계속됩니다.

플러그인 및 도구

에이전트는 외부 시스템과 상호 작용할 수 있을 때 진정으로 강력해집니다. Agent Framework는 세 가지 주요 확장 메커니즘을 지원합니다.

기본 기능(커널 플러그인)

에이전트에 도구로 C# 메서드에 대한 액세스 권한을 부여할 수 있습니다. 에이전트는 필요하다고 판단되면 다음 함수를 호출합니다.

public class ContentToolsPlugin
{
 [KernelFunction("word_count")]
 [Description("Counts the number of words in the provided text.")]
 public int WordCount([Description("The text to count words in")] string text)
 {
 return text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
 }

 [KernelFunction("check_readability")]
 [Description("Calculates a readability score for the given text.")]
 public string CheckReadability([Description("The text to analyze")] string text)
 {
 var words = text.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length;
 var sentences = text.Split(['.', '!', '?'], StringSplitOptions.RemoveEmptyEntries).Length;

 if (sentences == 0) return "Unable to calculate — no sentences found.";

 double avgWordsPerSentence = (double)words / sentences;

 return avgWordsPerSentence switch
 {
 < 15 => $"Easy to read (avg {avgWordsPerSentence:F1} words/sentence)",
 < 25 => $"Moderate difficulty (avg {avgWordsPerSentence:F1} words/sentence)",
 _ => $"Difficult to read (avg {avgWordsPerSentence:F1} words/sentence). Consider shorter sentences."
 };
 }
}

에이전트를 만들기 전에 커널에 플러그인을 등록하세요.

kernel.Plugins.AddFromType<ContentToolsPlugin>();

ChatCompletionAgent analyst = new()
{
 Name = "ContentAnalyst",
 Instructions = "Analyze content using available tools. Report word count and readability.",
 Kernel = kernel,
 Arguments = new KernelArguments(
 new PromptExecutionSettings
 {
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
 })
};

모델 컨텍스트 프로토콜(MCP)

MCP는 AI 모델을 외부 도구 및 데이터 소스에 연결하기 위한 개방형 표준입니다. 에이전트 프레임워크는 MCP를 지원합니다. 즉, 에이전트는 모든 MCP 호환 서버에서 제공하는 도구를 사용할 수 있습니다. 이는 표준화된 인터페이스를 통해 파일 시스템, 데이터베이스, API 등에 대한 문을 열어줍니다.

// Example: Adding an MCP server for file operations
kernel.Plugins.AddFromMcpServer("filesystem",
 new Uri("http://localhost:3000/mcp"));

이는 귀하의 에이전트가 귀하가 구축한 것에 국한되지 않고 다른 사람들이 개발하고 공유하는 MCP 도구 생태계를 활용할 수 있다는 것을 의미하기 때문에 특히 흥미롭습니다.

실제 사례: 콘텐츠 검토 파이프라인

실용적인 시나리오로 모든 것을 하나로 묶어 봅시다. 문서화 팀의 콘텐츠 검토를 자동화하는 내부 도구를 구축한다고 상상해 보십시오. 파이프라인에는 4단계가 있습니다.

연구원 — 관련 기술 정보 수집
작가 — 연구를 바탕으로 초안을 작성합니다.
검토자 — 정확성과 완전성을 확인합니다.
게시자 — 최종 출력 형식을 지정하고 준비합니다.

요약된 구현은 다음과 같습니다.

using Azure.Identity;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.ChatCompletion;

// Build the kernel
var builder = Kernel.CreateBuilder();
builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 credentials: new DefaultAzureCredential()
);
Kernel kernel = builder.Build();

// Define specialized agents
ChatCompletionAgent researcher = new()
{
 Name = "Researcher",
 Instructions = """
 You are a technical researcher. Given a topic, identify the key
 concepts, recent developments, and important details that should
 be covered. Output a structured research brief.
 """,
 Kernel = kernel
};

ChatCompletionAgent writer = new()
{
 Name = "Writer",
 Instructions = """
 You are a technical writer. Using the research brief provided,
 write a comprehensive, well-structured article. Include code
 examples where relevant. Target audience: experienced developers.
 """,
 Kernel = kernel
};

ChatCompletionAgent reviewer = new()
{
 Name = "Reviewer",
 Instructions = """
 You are a senior technical reviewer. Check the article for:
 - Technical accuracy
 - Completeness relative to the research brief
 - Code correctness
 - Clarity and structure
 If everything looks good, respond with APPROVED.
 Otherwise, provide specific feedback for revision.
 """,
 Kernel = kernel
};

ChatCompletionAgent publisher = new()
{
 Name = "Publisher",
 Instructions = """
 You are a content publisher. Once the article is approved,
 format it with proper markdown, add a summary at the top,
 and ensure consistent formatting throughout.
 End your response with COMPLETE.
 """,
 Kernel = kernel
};

// Configure the group chat
AgentGroupChat chat = new(researcher, writer, reviewer, publisher)
{
 ExecutionSettings = new()
 {
 SelectionStrategy = new SequentialSelectionStrategy(),
 TerminationStrategy = new ApprovalTerminationStrategy()
 {
 Agents = [publisher],
 MaximumIterations = 15
 }
 }
};

// Start the pipeline
chat.AddChatMessage(new ChatMessageContent(
 AuthorRole.User,
 "Create a technical article about implementing health checks in ASP.NET Core microservices."
));

await foreach (ChatMessageContent message in chat.InvokeAsync())
{
 Console.ForegroundColor = message.AuthorName switch
 {
 "Researcher" => ConsoleColor.Cyan,
 "Writer" => ConsoleColor.Green,
 "Reviewer" => ConsoleColor.Yellow,
 "Publisher" => ConsoleColor.Magenta,
 _ => ConsoleColor.White
 };

 Console.WriteLine($"\n{'='new string('=', 60)}");
 Console.WriteLine($"[{message.AuthorName}]");
 Console.WriteLine(new string('=', 60));
 Console.WriteLine(message.Content);
}

Console.ResetColor();

이 파이프라인은 에이전트 협업을 통해 완벽하게 조사하고, 작성하고, 검토하고, 형식화된 기사를 생성합니다. 각 에이전트는 자신이 가장 잘하는 일에 집중하고 AgentGroupChat는 워크플로를 조정합니다.

모범 사례

여러 다중 에이전트 시스템을 구축한 후 가장 가치 있다고 생각한 패턴과 사례는 다음과 같습니다.

오류 처리

종료 전략에 항상 MaximumIterations를 설정하세요. 이것이 없으면 상담원은 무한 루프에 빠질 수 있습니다. 특히 검토자가 계속 문제를 찾고 작성자가 개선 없이 계속 수정하는 경우에는 더욱 그렇습니다.

TerminationStrategy = new ApprovalTerminationStrategy()
{
 MaximumIterations = 12 // Safety net
}

에이전트 호출을 try-catch 블록으로 래핑합니다. API 속도 제한, 네트워크 문제 및 모델 오류는 모두 프로덕션 시스템의 현실입니다.

try
{
 await foreach (var message in chat.InvokeAsync(cancellationToken))
 {
 // Process messages
 }
}
catch (HttpOperationException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
{
 // Implement retry with exponential backoff
 await Task.Delay(TimeSpan.FromSeconds(30), cancellationToken);
}

관찰 가능성Agent Framework는 OpenTelemetry와 통합되어 모든 에이전트 상호 작용, 도구 호출 및 토큰 사용을 추적할 수 있습니다. 이는 어떤 에이전트가 문제를 일으켰는지 항상 명확하지 않은 다중 에이전트 워크플로를 디버깅하는 데 필수적입니다.

Semantic Kernel 원격 분석 패키지를 추가하고 기본 내보내기 도구(Application Insights, Jaeger 등)를 구성하여 기본 원격 분석을 설정합니다.

builder.Services.AddOpenTelemetry()
 .WithTracing(tracing =>
 {
 tracing.AddSource("Microsoft.SemanticKernel*");
 tracing.AddOtlpExporter();
 });

비용 관리

다중 에이전트 시스템은 API 비용을 배가시킵니다. 모든 에이전트 차례는 API 호출이며 그룹 채팅은 많은 차례를 생성할 수 있습니다. 비용을 통제하기 위한 몇 가지 전략:

간단한 에이전트를 위해 더 저렴한 모델을 사용하세요: 모든 에이전트에 GPT-4o가 필요한 것은 아닙니다. 평론가는 더 작은 모델로 작업할 수 있지만 작성자에게는 강력한 모델이 필요합니다.
기록 제한: 실행 설정에서 ReducedHistoryCount를 사용하여 각 에이전트가 수신하는 대화 컨텍스트의 양을 제한합니다.
엄격한 반복 제한 설정: 합리적인 MaximumIterations 값으로 폭주 대화를 방지합니다.
가능한 경우 캐시: 에이전트가 동일한 조회를 반복적으로 수행하는 경우 결과를 플러그인에 캐시합니다.

에이전트 디자인

지침에 집중: 각 상담원은 하나의 명확한 책임을 져야 합니다. 광범위한 지침은 모든 작업에서 평범한 성능으로 이어집니다.
출력 형식을 명시하세요: 상담원에게 응답 구성 방법을 정확하게 알려줍니다. 이는 다운스트림 구문 분석을 안정적으로 만듭니다.
종료 키워드 사용: 상담원이 완료되었음을 나타내기 위해 사용하는 명확한 신호(예: “승인됨” 또는 “완료”)를 정의합니다. 이는 종료 전략을 간단하고 예측 가능하게 만듭니다.

결론

다중 에이전트 AI 시스템은 지능형 애플리케이션 구축 방법의 근본적인 변화를 나타냅니다. 모든 것을 처리하기 위해 단일 프롬프트로 씨름하는 대신 문제를 전문적인 역할로 분해하고 상담원이 협업할 수 있도록 할 수 있습니다.

Microsoft의 Agent Framework를 사용하면 .NET 개발자에게 이러한 기능이 실용적으로 제공됩니다. 에이전트, 그룹 채팅, 선택 및 종료 전략 등 추상화는 깨끗하며 자연스럽게 구성됩니다. Semantic Kernel의 플러그인 에코시스템과 Azure의 모델 호스팅이 결합되어 프로덕션 수준의 다중 에이전트 시스템을 구축하기 위한 전체 스택을 갖게 됩니다.

프레임워크는 계속 발전하고 있지만(많은 패키지가 미리 보기 상태임) 핵심 패턴은 견고하고 방향은 명확합니다. .NET에서 AI 기반 애플리케이션을 구축하고 있다면 이제 다중 에이전트 아키텍처 실험을 시작할 때입니다.

소규모로 시작하세요. 간단한 작업을 위해 협업하는 두 개의 에이전트를 구축하세요. 단일 에이전트 접근 방식에 비해 품질 향상이 확인되면 모든 것을 에이전트 팀으로 분해하고 싶을 것입니다.

즐거운 코딩하세요!

MarkupString을 사용하여 Blazor에서 원시 HTML 렌더링

Sat, 22 Nov 2025 00:00:00 +0000

얼마 전 저는 CMS에서 가져온 일부 HTML을 렌더링하는 데 필요한 구성 요소를 구축하고 있었습니다. 변수에 HTML 문자열이 있고 @myHtml와 같은 템플릿에 놓았습니다. 물론 Blazor는 모든 것을 이스케이프 처리하고 실제 태그를 페이지의 텍스트로 렌더링했습니다. 내가 원하는 것이 아닙니다.

문제

기본적으로 Blazor는 템플릿에서 렌더링하는 모든 문자열을 인코딩합니다. 따라서 다음과 같은 경우:

@code {
 private string content = "<strong>Hello</strong> <em>world</em>";
}

그리고 당신은 이렇게 합니다:

<div>@content</div>

페이지에 Hello world 대신 리터럴 텍스트 <strong>Hello</strong> <em>world</em>가 표시됩니다. Blazor는 XSS 공격을 방지하기 위해 의도적으로 이 작업을 수행하며, 이는 올바른 기본 동작입니다.

해결책: MarkupString

실제로 원시 HTML을 렌더링해야 하는 경우 문자열을 MarkupString로 래핑합니다.

<div>@((MarkupString)content)</div>

그리고 그게 다야! 이제 Blazor는 HTML을 실제 마크업으로 렌더링합니다. 변수에 할당할 수도 있습니다.

@code {
 private string rawHtml = "<strong>Hello</strong> <em>world</em>";
 private MarkupString HtmlContent => (MarkupString)rawHtml;
}

<div>@HtmlContent</div>

실제 사례

API에서 블로그 콘텐츠를 가져오고 미리 보기 구성 요소에서 렌더링해야 했습니다. 콘텐츠에는 제목, 코드 블록, 링크, 이미지 등 모든 종류의 HTML이 포함되어 있습니다. 대략적인 모습은 다음과 같습니다.

@inject HttpClient Http

@if (article is not null)
{
 <article>
 <h1>@article.Title</h1>
 <div class="content">
 @((MarkupString)article.HtmlBody)
 </div>
 </article>
}

@code {
 [Parameter]
 public int ArticleId { get; set; }

 private ArticleDto? article;

 protected override async Task OnInitializedAsync()
 {
 article = await Http.GetFromJsonAsync<ArticleDto>($"api/articles/{ArticleId}");
 }
}

완벽하게 작동합니다. API의 HTML은 실제 마크업으로 렌더링됩니다.

#신뢰할 수 없는 내용에 주의하세요

이는 중요합니다. MarkupString는 HTML을 삭제하지 않습니다. <script> 태그를 포함하여 사용자가 제공한 모든 것을 렌더링합니다. 따라서 콘텐츠가 사용자 입력이나 신뢰할 수 없는 소스에서 나온 경우 먼저 해당 콘텐츠를 삭제해야 합니다.

Blazor에는 내장된 HTML 새니타이저가 없지만 HtmlSanitizer와 같은 라이브러리를 사용할 수 있습니다.

using Ganss.Xss;

@code {
 private HtmlSanitizer sanitizer = new();

 private MarkupString SafeHtml(string html)
 {
 var clean = sanitizer.Sanitize(html);
 return (MarkupString)clean;
 }
}

<div>@SafeHtml(untrustedContent)</div>

이는 <script>, onclick 핸들러와 같은 위험한 요소와 사용자 제공 콘텐츠에서 렌더링하고 싶지 않은 기타 항목을 제거합니다.

언제 사용하는가

나는 다음 용도로 MarkupString를 사용합니다.

HTML 서버측으로 변환된 CMS 콘텐츠 또는 마크다운
리치 텍스트 편집기 출력
이메일 템플릿 미리보기
신뢰할 수 있는 소스에서 사전 구축된 HTML

사용자 입력에서 나오는 모든 항목은 항상 먼저 삭제하세요. 후회하는 것보다 안전합니다.

게시물이 마음에 드셨기를 바랍니다! @emimontesdeoca로 소셜 미디어를 통해 언제든지 저에게 연락해주세요.

리소스

EF Core 9의 새로운 기능: 알아야 할 기능

Tue, 18 Nov 2025 00:00:00 +0000

Entity Framework Core 9는 2024년 11월에 .NET 9와 함께 출시되었으며, 여러 프로젝트에서 이를 사용하여 상당한 시간을 투자한 결과, 한동안 가장 의미 있는 릴리스 중 하나라고 말할 수 있습니다. 바퀴를 재발명해서가 아니라 EF Core가 역사적으로 가장 많은 마찰을 일으켰던 영역(쿼리 변환, 성능, 최신 데이터 패턴 작업)을 개선하기 때문입니다.

이 게시물에서는 일상 업무에 가장 큰 영향을 미친 기능을 살펴보겠습니다. 아직 EF Core 8(또는 7)을 사용하고 있다면 업그레이드의 다른 측면에서 무엇이 기다리고 있는지 명확하게 알 수 있습니다.

.NET 9 생태계의 EF Core 9

EF Core 9는 .NET 8 및 .NET 9를 대상으로 합니다. 즉, 이러한 기능을 대부분 활용하기 위해 전체 애플리케이션을 반드시 .NET 9로 업그레이드할 필요는 없습니다. 즉, AOT 및 성능 개선 사항 중 일부는 .NET 9 런타임 변경 사항과 긴밀하게 결합되어 있으므로 끝까지 진행하면 최대한 활용할 수 있습니다.

릴리스는 Microsoft가 설정한 홀수/짝수 흐름을 따릅니다. 홀수 릴리스(예: .NET 9)는 18개월 지원이 포함된 STS(표준 기간 지원)이고, 짝수 릴리스(예: .NET 8)는 장기 지원(LTS)입니다. 업그레이드 일정을 계획할 때 이 점을 염두에 두십시오.

LINQ 번역 개선

대부분의 개발자는 바로 이 부분에서 차이를 느낄 것입니다. EF Core 9는 LINQ 식을 실제로 의미 있는 SQL로 변환하는 데 상당한 진전을 이루었습니다.

더 나은 GroupBy 번역

EF Core에서 GroupBy 쿼리를 작성했는데 클라이언트 측 평가 경고 또는 기괴한 SQL이 발생했다면 그 어려움을 아실 것입니다. EF Core 9는 훨씬 더 광범위한 GroupBy 시나리오 세트를 SQL에서 직접 처리합니다.

var salesByCategory = await context.Products
 .GroupBy(p => p.Category.Name)
 .Select(g => new
 {
 Category = g.Key,
 TotalRevenue = g.Sum(p => p.Price * p.UnitsSold),
 AveragePrice = g.Average(p => p.Price),
 ProductCount = g.Count()
 })
 .OrderByDescending(x => x.TotalRevenue)
 .ToListAsync();

이전 버전에서는 GroupBy 내부 탐색 속성에 대한 집계와 관련된 쿼리가 클라이언트 평가로 대체되는 경우가 있었습니다. EF Core 9는 이를 GROUP BY, SUM, AVG 및 COUNT를 사용하여 단일 SQL 쿼리로 명확하게 변환합니다.

복잡한 프로젝션 및 하위 쿼리

중첩된 하위 쿼리와 복잡한 프로젝션도 대폭 업그레이드되었습니다. 다음과 같은 것을 고려해보세요:

var orderSummaries = await context.Customers
 .Select(c => new CustomerSummaryDto
 {
 Name = c.FullName,
 TotalOrders = c.Orders.Count(),
 MostRecentOrder = c.Orders
 .OrderByDescending(o => o.OrderDate)
 .Select(o => new OrderBriefDto
 {
 Id = o.Id,
 Date = o.OrderDate,
 Total = o.LineItems.Sum(li => li.Quantity * li.UnitPrice)
 })
 .FirstOrDefault(),
 TopCategory = c.Orders
 .SelectMany(o => o.LineItems)
 .GroupBy(li => li.Product.Category.Name)
 .OrderByDescending(g => g.Count())
 .Select(g => g.Key)
 .FirstOrDefault()
 })
 .ToListAsync();

이제 EF Core 9에서는 클라이언트 측 평가를 트리거하지 않고도 이 전체 표현식을 SQL로 변환할 수 있습니다. 생성된 쿼리는 적절한 경우 상관 하위 쿼리와 측면 조인을 사용하며 SQL 계획은 이전 버전에서 생성된 것보다 훨씬 더 효율적입니다.

매개변수화된 기본 컬렉션

LINQ의 뛰어난 개선 사항 중 하나는 기본 값 컬렉션을 쿼리에 직접 전달하는 기능입니다.

var statusFilter = new List<string> { "Active", "Pending", "Review" };

var filteredOrders = await context.Orders
 .Where(o => statusFilter.Contains(o.Status))
 .ToListAsync();

EF Core 8에서는 인라인 값이 있는 IN 절을 사용하여 변환되었습니다. 즉, 목록이 변경되면 쿼리 계획 캐시를 재사용할 수 없습니다. EF Core 9는 이러한 컬렉션을 적절하게 매개 변수화하여 구조화된 매개 변수로 보냅니다. 이는 SQL Server 및 PostgreSQL의 쿼리 계획 캐싱에 있어 큰 문제입니다.## 대량 작업 — ExecuteUpdate 및 ExecuteDelete

ExecuteUpdate 및 ExecuteDelete는 EF Core 7에 도입되었지만 EF Core 9에서는 이를 사용하여 수행할 수 있는 작업을 의미 있는 방식으로 확장합니다.

더 복잡한 업데이트 표현식

이제 탐색 속성을 통한 다른 테이블에 대한 참조를 포함하여 ExecuteUpdate에서 더 복잡한 표현식을 사용할 수 있습니다.

await context.Products
 .Where(p => p.Category.IsDiscontinued)
 .ExecuteUpdateAsync(setters => setters
 .SetProperty(p => p.IsAvailable, false)
 .SetProperty(p => p.DiscontinuedDate, DateTimeOffset.UtcNow)
 .SetProperty(p => p.Price, p => p.Price * 0.5m));

이렇게 하면 카테고리 테이블에 JOIN가 포함된 단일 UPDATE 문이 생성됩니다. 즉, 엔터티를 메모리에 로드할 필요가 없고 변경 내용 추적 오버헤드도 없습니다.

하위 쿼리를 사용한 조건부 대량 삭제

이제 하위 쿼리 필터를 사용한 대량 삭제가 완전히 지원됩니다.

await context.AuditLogs
 .Where(log => log.CreatedAt < DateTime.UtcNow.AddYears(-2))
 .Where(log => !context.ProtectedRecords
 .Any(pr => pr.AuditLogId == log.Id))
 .ExecuteDeleteAsync();

이는 NOT EXISTS 하위 쿼리가 있는 DELETE로 변환되며, 이는 정확히 직접 작성하는 것과 같습니다. 로드된 엔터티가 없고 왕복도 없습니다.

JSON 열 개선 사항

JSON 열은 최근 EF Core 릴리스에서 가장 흥미로운 기능 중 하나였으며 EF Core 9에서는 이를 더욱 발전시켰습니다.

JSON 내부 쿼리

이제 더 나은 번역 지원을 통해 JSON 열 내에서 데이터를 필터링하고 투영할 수 있습니다.

public class Order
{
 public int Id { get; set; }
 public string CustomerName { get; set; }
 public ShippingAddress Address { get; set; } // Stored as JSON
 public List<OrderNote> Notes { get; set; } // Stored as JSON
}

public class ShippingAddress
{
 public string Street { get; set; }
 public string City { get; set; }
 public string State { get; set; }
 public string ZipCode { get; set; }
 public string Country { get; set; }
}

public class OrderNote
{
 public DateTime CreatedAt { get; set; }
 public string Text { get; set; }
 public string Author { get; set; }
}

DbContext의 구성:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Order>(builder =>
 {
 builder.OwnsOne(o => o.Address, ab =>
 {
 ab.ToJson();
 });

 builder.OwnsMany(o => o.Notes, nb =>
 {
 nb.ToJson();
 });
 });
}

이제 JSON에 직접 쿼리할 수 있습니다.

var newYorkOrders = await context.Orders
 .Where(o => o.Address.State == "NY")
 .OrderByDescending(o => o.Notes.Count)
 .Select(o => new
 {
 o.CustomerName,
 o.Address.City,
 LatestNote = o.Notes
 .OrderByDescending(n => n.CreatedAt)
 .Select(n => n.Text)
 .FirstOrDefault()
 })
 .ToListAsync();

EF Core 9는 SQL Server(또는 다른 공급자의 경우 이에 상응하는 항목)에서 적절한 JSON_VALUE 및 JSON_QUERY 호출을 생성하며 변환은 이전보다 JSON 요소에 대한 훨씬 더 광범위한 LINQ 작업을 다룹니다.

JSON 속성 업데이트

EF Core 8의 문제점 중 하나는 JSON 열 내부의 단일 속성을 업데이트하면 전체 JSON 문서가 다시 작성된다는 것입니다. EF Core 9는 JSON 매핑 유형에 대한 보다 세부적인 변경 추적을 통해 이를 개선하여 가능한 경우 더 많은 대상 업데이트를 생성합니다.

var order = await context.Orders.FindAsync(orderId);
order.Address.ZipCode = "10001";
await context.SaveChangesAsync();

지원되는 공급자에서는 전체 Blob을 다시 작성하는 대신 보다 타겟팅된 JSON 수정을 생성할 수 있습니다.

복잡한 유형 - ID가 없는 값 개체

복합 유형은 도메인 중심 디자인 실무자가 기다려온 기능 중 하나입니다. 소유된 유형과 달리 복합 유형에는 ID가 없습니다. 즉, 순수한 값 개체입니다.

[ComplexType]
public record Money(decimal Amount, string Currency);

[ComplexType]
public record DateRange(DateTime Start, DateTime End);

public class Project
{
 public int Id { get; set; }
 public string Name { get; set; }
 public Money Budget { get; set; }
 public DateRange Timeline { get; set; }
}

이는 별도의 테이블이나 어떤 종류의 키도 필요 없이 상위 테이블(Budget_Amount, Budget_Currency, Timeline_Start, Timeline_End)에 평면화된 열로 저장됩니다.

소유 유형과의 주요 차이점: 복합 유형은 참조가 아닌 값으로 비교됩니다. Amount 및 Currency가 동일한 두 개의 Money 인스턴스는 속한 엔터티에 관계없이 동일한 것으로 간주됩니다.

var expensiveProjects = await context.Projects
 .Where(p => p.Budget.Amount > 100_000m && p.Budget.Currency == "USD")
 .OrderByDescending(p => p.Budget.Amount)
 .ToListAsync();

이는 평면화된 열에 대한 필터링으로 직접 변환됩니다. 즉, 깔끔하고 효율적이며 기대했던 것과 정확히 일치합니다.

SQL Server에 대한 HierarchyId 지원

SQL Server의 계층적 데이터(조직 차트, 범주 트리, 파일 시스템)로 작업해 본 적이 있다면 HierarchyId가 이에 대한 기본 제공 유형이라는 것을 알고 있을 것입니다. EF Core 9는 이에 대한 최고 수준의 지원을 제공합니다.

public class Employee
{
 public int Id { get; set; }
 public string Name { get; set; }
 public string Title { get; set; }
 public HierarchyId PathFromCeo { get; set; }
}

이제 계층적 관계를 직접 쿼리할 수 있습니다.

var managerId = HierarchyId.Parse("/1/3/");

// All direct and indirect reports
var allReports = await context.Employees
 .Where(e => e.PathFromCeo.IsDescendantOf(managerId))
 .Where(e => e.PathFromCeo != managerId) // exclude the manager
 .OrderBy(e => e.PathFromCeo)
 .ToListAsync();

// Direct reports only (one level down)
var directReports = await context.Employees
 .Where(e => e.PathFromCeo.GetAncestor(1) == managerId)
 .ToListAsync();

// Get an employee's depth in the hierarchy
var employeesWithDepth = await context.Employees
 .Select(e => new
 {
 e.Name,
 e.Title,
 Level = e.PathFromCeo.GetLevel()
 })
 .OrderBy(e => e.Level)
 .ToListAsync();
```이들 모두는 SQL Server의 기본 `HierarchyId` 메서드로 변환됩니다. 자체 참조 외래 키와 재귀 CTE를 사용하여 트리 구조를 구현했다면 이 방법이 훨씬 더 깔끔한 접근 방식입니다.

## 컴파일된 모델 및 AOT 지원

성능에 민감한 개발자는 컴파일된 모델과 AOT(Ahead-of-Time) 컴파일 지원에 대한 지속적인 투자를 높이 평가할 것입니다.

### 컴파일된 모델

컴파일된 모델은 EF Core가 일반적으로 시작 시 빌드하는 모델 메타데이터를 미리 생성합니다. 대규모 모델(수백 개의 엔터티 생각)의 경우 콜드 스타트 시간을 크게 줄일 수 있습니다.

```bash
dotnet ef dbcontext optimize --output-dir CompiledModels --namespace MyApp.CompiledModels

그런 다음 연결하십시오.

builder.Services.AddDbContext<AppDbContext>(options =>
 options
 .UseSqlServer(connectionString)
 .UseModel(MyApp.CompiledModels.AppDbContextModel.Instance));

EF Core 9에서는 컴파일된 모델이 더욱 완벽해졌습니다. 즉, 더 많은 매핑 기능을 지원하고 더 작은 출력을 생성합니다. 약 400개 엔터티가 있는 모델의 경우 시작 시간은 몇 초에서 거의 순간적으로 단축될 수 있습니다.

AOT 컴파일 진행

EF Core에 대한 완전한 기본 AOT 지원은 아직 진행 중인 작업이지만 EF Core 9는 상당한 발전을 이루었습니다. 반사가 많은 코드 경로 중 상당수가 트리밍에 적합하도록 리팩터링되었으며 컴파일된 모델은 AOT 스토리의 핵심 부분입니다. 콜드 스타트가 중요한 Azure Functions 또는 마이크로서비스와 같은 시나리오를 대상으로 하는 경우 이러한 개선 사항은 직접적인 관련이 있습니다.

Cosmos DB 공급자 업데이트

Azure Cosmos DB 공급자는 EF Core 9를 통해 계속 발전하고 있습니다. 몇 가지 주목할만한 개선 사항은 다음과 같습니다.

파티션 키 처리

이제 공급자는 계층적 파티션 키를 지원하고 파티션 키 필터를 보다 지능적으로 처리합니다.

public class TenantDocument
{
 public string Id { get; set; }
 public string TenantId { get; set; } // Partition key
 public string Region { get; set; } // Sub-partition key
 public string Content { get; set; }
}

// This query now correctly uses the partition key for routing
var docs = await context.TenantDocuments
 .Where(d => d.TenantId == "tenant-42" && d.Region == "us-east")
 .Where(d => d.Content.Contains("important"))
 .ToListAsync();

LINQ에서 NoSQL로의 변환 개선

이제 Contains, Any, 중첩 배열 작업 및 수학 함수에 대한 더 나은 지원을 포함하여 더 많은 LINQ 작업이 Cosmos DB의 SQL 언어로 변환됩니다. 이전에 클라이언트 평가로 대체되었던 쿼리는 이제 서버 측에서 처리됩니다.

벡터 검색 지원

EF Core 9에는 Cosmos DB를 통한 벡터 유사성 검색에 대한 초기 지원이 도입되었습니다. 이는 임베딩 또는 AI 기반 검색과 통합되는 애플리케이션을 구축하는 경우에 유용합니다.

var results = await context.Documents
 .OrderBy(d => EF.Functions.VectorDistance(d.Embedding, queryVector))
 .Take(10)
 .ToListAsync();

마이그레이션 개선

마이그레이션을 통해 팀 환경에서 마이그레이션 작업의 고통을 덜 수 있도록 삶의 질이 향상되었습니다.

마이그레이션의 임시 테이블

이제 마이그레이션은 기간 열 및 기록 테이블 이름 지정에 대한 적절한 지원을 통해 임시 테이블 구성을 보다 원활하게 처리합니다.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Employee>()
 .ToTable("Employees", b => b.IsTemporal(t =>
 {
 t.HasPeriodStart("ValidFrom");
 t.HasPeriodEnd("ValidTo");
 t.UseHistoryTable("EmployeeHistory");
 }));
}

멱등성 스크립트

Script-Migration 명령(및 이에 상응하는 CLI)은 기본적으로 특정 상태에 존재하는 데이터에 의존하는 스키마 변경과 관련된 엣지 케이스 처리가 개선되어 더 나은 멱등성 스크립트를 생성합니다.

마이그레이션 번들

마이그레이션을 배포용 독립 실행형 실행 파일로 패키징하는 마이그레이션 번들은 더 나은 오류 보고 및 일시적 오류에 대한 재시도 논리를 통해 EF Core 9에서 더욱 안정적입니다.

dotnet ef migrations bundle --self-contained -r linux-x64

그러면 배포 대상에 .NET SDK를 설치하지 않고도 CI/CD 파이프라인에서 실행할 수 있는 바이너리가 생성됩니다.

성능 벤치마크다음은 제가 직접 테스트한 대략적인 벤치마크입니다. 이는 BenchmarkDotNet으로 측정된 SQL Server 2022에 대해 실행되는 약 200개의 엔터티가 있는 프로젝트에서 가져온 것입니다. 수치는 다양하지만 상대적인 개선 정도는 비슷할 것입니다.

시나리오	EF 코어 8	EF 코어 9	개선
모델 빌드(콜드 스타트)	1,850ms	320ms	~5.8배 더 빠름(컴파일됨)
단순 쿼리(PK별 단일 엔터티)	0.42ms	0.38ms	~10% 더 빨라짐
복잡한 쿼리(조인 + 집계)	3.1ms	2.4ms	~23% 더 빨라짐
대량 업데이트(10,000개 행)	145ms	118ms	~19% 더 빨라짐
JSON 열 쿼리	2.8ms	1.9ms	~32% 더 빨라짐
SaveChanges(엔티티 100개)	48ms	41ms	~15% 더 빨라짐

컴파일된 모델 개선은 가장 극적이지만 전반적으로 꾸준한 개선이 이루어지고 있습니다. 특히 초당 수천 개의 쿼리를 실행하는 처리량이 높은 시나리오에서는 더욱 그렇습니다.

EF Core 8에서 업그레이드

EF Core 8을 사용하는 경우 업그레이드 경로가 비교적 원활합니다. 체크리스트는 다음과 같습니다.

1. 패키지 업데이트:

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="9.0.0" />

2. 주요 변경 사항을 확인하세요. EF Core 9의 목록은 일부 이전 릴리스에 비해 상대적으로 짧습니다. 가장 주목할만한 것 :

이전에 사용되지 않았던 일부 API가 제거되었습니다.
특정 GroupBy 쿼리가 변환되는 방식 변경(이제 서버측으로 이동하여 클라이언트 평가에 의존하는 경우 동작이 변경됨)
마이그레이션 스캐폴딩 출력의 사소한 변경

3. 컴파일된 모델을 사용하는 경우 다시 생성하세요. 형식이 변경되었으므로 이전에 컴파일된 모델은 EF Core 9에서 작동하지 않습니다.

4. 테스트 스위트를 실행하십시오. 이전에 클라이언트에서 평가된 쿼리에 특별한 주의를 기울이십시오. 이제 서버에서 평가될 수도 있습니다. 이는 일반적으로 더 좋지만 데이터 차이가 드러날 수 있습니다.

5. 해당 공급자를 사용하는 경우 Cosmos DB 쿼리를 확인하세요. 향상된 번역은 일부 쿼리가 다르게(일반적으로 더 빠르게) 실행된다는 것을 의미하지만 결과가 동일한지 확인할 가치가 있습니다.

일반적인 프로젝트의 최소 업그레이드는 다음과 같습니다.

dotnet add package Microsoft.EntityFrameworkCore --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.Design --version 9.0.0
dotnet build
dotnet test

모든 것이 컴파일되고 테스트에 통과되면 아마도 좋은 상태일 것입니다. 문제가 발생하면 EF Core 9 주요 변경 설명서에 각 변경 사항에 대한 자세한 마이그레이션 지침이 있습니다.

마무리

EF Core 9는 혁명적인 릴리스가 아닙니다. 이는 진화적인 릴리스이며, 이것이 바로 필요한 것입니다. LINQ 개선만으로도 대부분의 프로젝트에 대한 업그레이드가 정당화되며 JSON 열 개선, 복합 유형 및 HierarchyId와 같은 기능은 이전에 어색하거나 불가능했던 개방형 패턴을 지원합니다.

내 프로젝트에 가장 큰 영향을 미친 세 가지 기능을 선택해야 한다면:

매개변수화된 기본 컬렉션 — 쿼리 계획 캐시 효율성이 규모에 따라 중요하기 때문
JSON 열 개선 — 하이브리드 관계형 문서 패턴이 매우 유용하기 때문입니다.
컴파일된 모델 — 시작 시간이 개발자 생산성과 배포 속도에 직접적인 영향을 미치기 때문입니다.EF Core 팀은 EF Core 5 이후 탄탄한 궤도를 유지해 왔으며 버전 9에서는 이러한 추세를 이어갑니다. 이미 EF Core 8을 사용하고 있다면 업그레이드는 위험은 낮고 보상은 높습니다. 만약 당신이 오래된 무언가를 하고 있다면, 도약하기에 이보다 더 좋은 때는 없었습니다.

즐거운 코딩과 행복한 쿼리.

시맨틱 커널 시작하기: C#의 AI 오케스트레이션

Sun, 05 Oct 2025 00:00:00 +0000

.NET 애플리케이션을 구축하고 AI 환경이 발전하는 것을 지켜봤다면 아마도 다음과 같이 궁금해했을 것입니다. 내 코드베이스를 스파게티로 바꾸지 않고 대규모 언어 모델을 내 C# 프로젝트에 통합하는 가장 좋은 방법은 무엇입니까? 이것이 바로 Microsoft의 Semantic Kernel이 해결하는 문제이며, 작년에 이를 사용하여 프로덕션 애플리케이션을 구축한 후에는 이것이 내 개발자 툴킷에서 가장 중요한 도구 중 하나가 되었다고 말할 수 있습니다.

이 게시물에서는 핵심 개념 이해부터 실제 AI 도우미 구축에 이르기까지 Semantic Kernel을 시작하는 데 필요한 모든 것을 안내해 드리겠습니다. AI 개발에 발을 담그고 있거나 기존 .NET 애플리케이션에서 LLM 호출을 조정하는 구조화된 방법을 찾고 있다면 이 가이드에서 다룹니다.

시맨틱 커널이란 무엇입니까?

SK(의미론적 커널)는 애플리케이션 코드와 GPT-4o, Azure OpenAI 또는 기타 AI 서비스와 같은 대규모 언어 모델 사이에서 오케스트레이션 레이어 역할을 하는 Microsoft의 오픈 소스 SDK입니다. 기존 C# 코드와 AI 기능을 깔끔하고 구성 가능한 방식으로 결합할 수 있는 경량 미들웨어라고 생각하세요.

하지만 OpenAI API를 직접 호출하면 어떨까요? 물론 가능합니다. 간단한 사용 사례에서는 괜찮습니다. 하지만 다음과 같은 조치가 필요한 순간:

AI가 사용자 입력에 따라 호출할 함수를 결정하도록 함
파이프라인에서 여러 AI 호출을 기존 코드와 결합합니다.
AI가 이전 상호 작용을 기억할 수 있도록 메모리 및 컨텍스트를 추가하세요.
복잡한 작업을 통해 추론하는 다단계 에이전트 구축

…당신은 바퀴를 재발명하는 자신을 발견하게 될 것입니다. Semantic Kernel은 최고 수준의 .NET 지원, 종속성 주입 통합, 모든 C# 개발자에게 자연스럽게 느껴지는 플러그인 아키텍처를 통해 이 모든 기능을 즉시 제공합니다.

이 프로젝트는 GitHub의 microsoft/semantic-kernel 저장소에 있으며 C#, Python 및 Java용 SDK가 있습니다. C# SDK는 가장 성숙한 버전이며 여기서 중점적으로 살펴보겠습니다.

핵심 개념

코드를 작성하기 전에 구성 요소를 이해해 봅시다.

커널

Kernel은 Semantic Kernel의 중심 개체입니다. AI 서비스, 플러그인 및 구성을 하나로 묶는 오케스트레이터입니다. 하나를 만들고 여기에 서비스와 플러그인을 등록한 다음 이를 사용하여 프롬프트를 실행하거나 기능을 호출합니다. ASP.NET Core의 종속성 주입에 익숙하다면 커널은 매우 친숙하게 느껴질 것입니다. 즉, 본질적으로 AI 초능력을 갖춘 서비스 컨테이너입니다.

플러그인 및 기능

플러그인은 커널이 호출할 수 있는 관련 함수의 모음입니다. 함수에는 두 가지 형태가 있습니다.

프롬프트 기능 — LLM으로 전송되는 자연어 템플릿으로 정의됩니다.
네이티브 함수 — 커널이 발견하고 호출할 수 있는 속성으로 장식된 일반 C# 메서드

예를 들어 기본 함수 GetCurrentWeather(string city)와 날씨 데이터를 친숙한 방식으로 요약하는 프롬프트 함수가 있는 WeatherPlugin가 있을 수 있습니다.### AI 커넥터

커넥터는 Semantic Kernel이 AI 서비스와 통신하는 방식입니다. 가장 일반적인 것들은 다음과 같습니다:

AzureOpenAIChatCompletion — Azure OpenAI 서비스용
OpenAIChatCompletion — OpenAI API 직접용
벡터 검색 및 메모리용 커넥터 내장

시작 시 커널에 이를 등록하면 다른 모든 것이 제대로 작동합니다.

프로젝트 설정

손을 더럽히자. 새 콘솔 애플리케이션을 만드는 것부터 시작하세요.

dotnet new console -n SemanticKernelDemo
cd SemanticKernelDemo

이제 Semantic Kernel NuGet 패키지를 추가합니다.

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Connectors.AzureOpenAI

Azure OpenAI 대신 OpenAI를 직접 사용하는 경우:

dotnet add package Microsoft.SemanticKernel.Connectors.OpenAI

메모리 및 임베딩 지원의 경우(나중에 사용함):

dotnet add package Microsoft.SemanticKernel.Plugins.Memory
dotnet add package Microsoft.Extensions.VectorData.Abstractions

.csproj은 .NET 8 이상을 대상으로 해야 합니다. Semantic Kernel의 최신 버전은 최신 .NET 기능을 최대한 활용합니다.

첫 번째 커널

커널을 생성하고 이를 AI 서비스에 연결하고 질문하는 가장 간단한 예부터 시작해 보겠습니다.

using Microsoft.SemanticKernel;

// Build the kernel with Azure OpenAI
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

var kernel = builder.Build();

// Invoke a simple prompt
var result = await kernel.InvokePromptAsync(
 "Explain dependency injection in C# in three sentences."
);

Console.WriteLine(result);

OpenAI를 직접 사용하는 경우 서비스 등록을 교체하세요.

builder.AddOpenAIChatCompletion(
 modelId: "gpt-4o",
 apiKey: "your-openai-api-key"
);

그게 다야. 이를 실행하면 종속성 주입에 대한 간결한 설명을 얻을 수 있습니다. 그러나 이것은 단지 표면적인 것에 불과합니다.

프롬프트 템플릿 사용

프롬프트 템플릿을 사용하면 핸들바 스타일 구문을 사용하여 변수로 프롬프트를 매개변수화할 수 있습니다.

var prompt = """
 You are a technical writer. Write a brief summary of {{$topic}}
 aimed at developers with {{$experienceLevel}} experience.
 Keep it under 200 words.
 """;

var function = kernel.CreateFunctionFromPrompt(prompt);

var arguments = new KernelArguments
{
 ["topic"] = "gRPC in .NET",
 ["experienceLevel"] = "intermediate"
};

var result = await kernel.InvokeAsync(function, arguments);
Console.WriteLine(result);

이것이 Semantic Kernel이 빛을 발하기 시작하는 곳입니다. 재사용 가능한 프롬프트 템플릿을 정의하고 버전을 지정하고 더 큰 워크플로로 구성할 수 있습니다.

플러그인 및 기본 기능

플러그인은 Semantic Kernel이 AI와 기존 C# 코드 사이의 격차를 해소하는 곳입니다. 네이티브 함수는 커널에 노출되는 일반적인 메서드입니다.

using Microsoft.SemanticKernel;
using System.ComponentModel;

public class TimePlugin
{
 [KernelFunction("get_current_time")]
 [Description("Gets the current date and time in UTC")]
 public string GetCurrentTime()
 {
 return DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss UTC");
 }

 [KernelFunction("get_time_in_timezone")]
 [Description("Gets the current time in a specific timezone")]
 public string GetTimeInTimezone(
 [Description("The IANA timezone identifier, e.g. 'America/New_York'")] string timezone)
 {
 var tz = TimeZoneInfo.FindSystemTimeZoneById(timezone);
 var time = TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz);
 return time.ToString("yyyy-MM-dd HH:mm:ss");
 }
}

[KernelFunction] 및 [Description] 속성을 확인하세요. 이는 매우 중요합니다. 설명은 AI가 함수를 호출하는 시기와 방법을 이해하기 위해 읽는 내용입니다. 좋은 설명은 도구를 효과적으로 사용하는 AI와 혼란스러운 AI를 구분합니다.

커널에 플러그인을 등록합니다:

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromType<TimePlugin>();

var kernel = builder.Build();

서비스를 주입하는 더 복잡한 플러그인을 구축할 수도 있습니다. Semantic Kernel은 Microsoft.Extensions.DependencyInjection와 통합되므로 플러그인은 다른 서비스와 마찬가지로 생성자 종속성을 받을 수 있습니다.

public class OrderPlugin
{
 private readonly IOrderRepository _repository;

 public OrderPlugin(IOrderRepository repository)
 {
 _repository = repository;
 }

 [KernelFunction("get_order_status")]
 [Description("Retrieves the status of an order by its ID")]
 public async Task<string> GetOrderStatus(
 [Description("The order ID to look up")] string orderId)
 {
 var order = await _repository.GetByIdAsync(orderId);
 return order is null
 ? $"No order found with ID {orderId}"
 : $"Order {orderId}: {order.Status}, placed on {order.CreatedAt:d}";
 }
}

함수 호출 및 자동 호출

이것은 상황이 정말 흥미로워지는 곳입니다. 함수 호출(도구 호출이라고도 함)을 사용하면 AI 모델이 대화 컨텍스트에 따라 호출할 등록된 함수를 결정하도록 할 수 있습니다. 모델은 코드를 실행하지 않습니다. “이 인수를 사용하여 함수 X를 호출하고 싶습니다"라는 구조화된 요청을 반환하고 커널이 실제 호출을 처리합니다.

자동 함수 호출을 활성화하는 방법은 다음과 같습니다.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromType<TimePlugin>();
builder.Plugins.AddFromType<WeatherPlugin>();

var kernel = builder.Build();

// Enable automatic function calling
var settings = new OpenAIPromptExecutionSettings
{
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

var result = await kernel.InvokePromptAsync(
 "What time is it in Tokyo and what's the weather like there?",
 new KernelArguments(settings)
);

Console.WriteLine(result);

FunctionChoiceBehavior.Auto()를 사용하면 커널은 다음을 수행합니다.

사용 가능한 모든 기능에 대한 설명과 함께 프롬프트를 AI에 보냅니다.
AI는 get_time_in_timezone 및 get_weather를 호출해야 한다고 결정합니다.
커널은 해당 기능을 자동으로 실행합니다.
결과는 AI로 다시 전송됩니다.
AI는 함수 결과를 사용하여 자연어 응답을 구성합니다.이 루프는 단일 호출에서 여러 번 발생할 수 있습니다. AI는 필요한 모든 정보를 수집하기 위해 여러 함수를 순서대로 호출할 수 있습니다. 또한 FunctionChoiceBehavior.Required()를 사용하여 AI가 적어도 하나의 기능을 호출하도록 강제하거나 사용이 허용된 특정 기능 목록을 제공할 수도 있습니다.

기록으로 채팅 완료

대화형 애플리케이션의 경우 ChatCompletionService를 ChatHistory 객체와 함께 직접 사용하는 것이 좋습니다.

using Microsoft.SemanticKernel.ChatCompletion;

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory();

history.AddSystemMessage("""
 You are a helpful developer assistant. You have access to tools
 for checking the time and weather. Be concise and friendly.
 """);

while (true)
{
 Console.Write("You: ");
 var input = Console.ReadLine();
 if (string.IsNullOrWhiteSpace(input)) break;

 history.AddUserMessage(input);

 var response = await chatService.GetChatMessageContentAsync(
 history,
 executionSettings: settings,
 kernel: kernel
 );

 history.AddAssistantMessage(response.Content ?? "");
 Console.WriteLine($"Assistant: {response.Content}");
}

이는 대화 기록을 유지하고 필요에 따라 플러그인을 호출할 수 있는 완전한 대화형 챗봇을 제공합니다.

메모리 및 임베딩

AI 애플리케이션의 가장 강력한 패턴 중 하나는 **RAG(Retrieval-Augmented Generation)**입니다. 즉, AI가 사용자 데이터를 벡터 공간에 삽입하고 쿼리 시 관련 청크를 검색하여 해당 데이터에 액세스할 수 있도록 합니다.

시맨틱 커널은 벡터 저장소 및 임베딩 작업을 위한 추상화를 제공합니다. 개발을 위해 메모리 내 벡터 저장소를 설정하는 방법은 다음과 같습니다.

using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Microsoft.SemanticKernel.Embeddings;

#pragma warning disable SKEXP0010

// Create an embedding generation service
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAITextEmbeddingGeneration(
 deploymentName: "text-embedding-ada-002",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

var kernel = builder.Build();
var embeddingService = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

// Generate embeddings for your documents
var documents = new[]
{
 "Semantic Kernel is an open-source SDK for AI orchestration.",
 "Azure OpenAI provides enterprise-grade AI models.",
 "Plugins in SK allow you to expose C# methods to AI models."
};

var embeddings = await embeddingService.GenerateEmbeddingsAsync(documents);

프로덕션 시나리오의 경우 이러한 임베딩을 Azure AI Search, Qdrant 또는 Pinecone과 같은 전용 벡터 데이터베이스에 저장합니다. 시맨틱 커널에는 Microsoft.Extensions.VectorData 추상화를 통해 이들 모두에 대한 커넥터가 있습니다.

일반적인 RAG 흐름은 다음과 같습니다.

수집: 문서를 청크하고, 임베딩을 생성하고, 벡터 데이터베이스에 저장합니다.
검색: 사용자가 질문하면 쿼리를 삽입하여 가장 유사한 문서를 찾습니다.
생성: 검색된 문서를 사용자의 질문과 함께 LLM에 컨텍스트로 전달합니다.

[KernelFunction("search_knowledge_base")]
[Description("Searches the internal knowledge base for relevant information")]
public async Task<string> SearchKnowledgeBase(
 [Description("The search query")] string query)
{
 var queryEmbedding = await _embeddingService.GenerateEmbeddingAsync(query);

 var results = await _vectorStore.SearchAsync(queryEmbedding, limit: 3);

 return string.Join("\n\n", results.Select(r => r.Text));
}

RAG 파이프라인을 커널 기능으로 노출함으로써 AI는 지식 기반을 검색해야 할 시기를 자동으로 결정하여 오케스트레이션을 깔끔하게 유지하고 모델이 가장 잘 수행할 수 있도록 합니다.

기획자 및 에이전트

AI 애플리케이션이 더욱 복잡해짐에 따라 다단계 작업을 계획하고 실행하려면 AI가 필요합니다. 이것이 Semantic Kernel의 에이전트 프레임워크가 들어오는 곳입니다.

기본 사항: 채팅 완료 에이전트

가장 간단한 에이전트 유형은 지침과 플러그인을 사용하여 채팅 완료 모델을 래핑합니다.

using Microsoft.SemanticKernel.Agents;

#pragma warning disable SKEXP0110

var agent = new ChatCompletionAgent
{
 Name = "DevAssistant",
 Instructions = """
 You are a senior .NET developer assistant. Help users with code
 reviews, architecture decisions, and debugging. Always provide
 code examples when relevant. Use your available tools to look up
 current information when needed.
 """,
 Kernel = kernel,
 Arguments = new KernelArguments(settings)
};

var history = new ChatHistory();

history.AddUserMessage("How should I structure a clean architecture project in .NET 8?");

await foreach (var message in agent.InvokeAsync(history))
{
 Console.WriteLine(message.Content);
 history.Add(message);
}

다중 에이전트 협업

여러 상담원이 함께 작업할 때 정말 강력해집니다. Semantic Kernel은 다양한 전문 분야를 가진 에이전트가 협업하는 그룹 채팅 패턴을 지원합니다.

#pragma warning disable SKEXP0110

var codeReviewer = new ChatCompletionAgent
{
 Name = "CodeReviewer",
 Instructions = """
 You review C# code for bugs, performance issues, and best practices.
 Be specific about what you find and suggest concrete fixes.
 """,
 Kernel = kernel
};

var securityAuditor = new ChatCompletionAgent
{
 Name = "SecurityAuditor",
 Instructions = """
 You focus exclusively on security vulnerabilities in code.
 Look for injection attacks, authentication issues, data exposure,
 and OWASP Top 10 violations.
 """,
 Kernel = kernel
};

var groupChat = new AgentGroupChat(codeReviewer, securityAuditor)
{
 ExecutionSettings = new AgentGroupChatSettings
 {
 TerminationStrategy = new MaximumIterationTerminationStrategy(4)
 }
};

groupChat.AddChatMessage(
 new ChatMessageContent(AuthorRole.User, "Review this code: ...")
);

await foreach (var message in groupChat.InvokeAsync())
{
 Console.WriteLine($"[{message.AuthorName}]: {message.Content}");
}

이 패턴은 다양한 관점이나 전문 분야를 고려해야 하는 복잡한 작업에 매우 유용합니다. 각 에이전트는 자체 시스템 프롬프트로 작동하며 자체 플러그인 세트를 가질 수 있습니다.

실제 사례: 프로젝트 문서화 도우미 구축

파일을 읽고 질문에 답변하여 개발자가 코드베이스를 이해하도록 돕는 AI 도우미인 실제 사례를 통해 모든 것을 하나로 묶어 보겠습니다.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using System.ComponentModel;

// Define our plugins
public class FileSystemPlugin
{
 private readonly string _rootPath;

 public FileSystemPlugin(string rootPath)
 {
 _rootPath = rootPath;
 }

 [KernelFunction("read_file")]
 [Description("Reads the contents of a file from the project directory")]
 public async Task<string> ReadFile(
 [Description("Relative path to the file")] string path)
 {
 var fullPath = Path.Combine(_rootPath, path);

 if (!File.Exists(fullPath))
 return $"File not found: {path}";

 var content = await File.ReadAllTextAsync(fullPath);

 // Truncate very large files
 if (content.Length > 8000)
 content = content[..8000] + "\n... [truncated]";

 return content;
 }

 [KernelFunction("list_files")]
 [Description("Lists files in a directory, optionally filtered by extension")]
 public string ListFiles(
 [Description("Relative directory path")] string directory,
 [Description("File extension filter like '.cs' or '.json'")] string? extension = null)
 {
 var fullPath = Path.Combine(_rootPath, directory);

 if (!Directory.Exists(fullPath))
 return $"Directory not found: {directory}";

 var files = Directory.GetFiles(fullPath, "*.*", SearchOption.AllDirectories)
 .Select(f => Path.GetRelativePath(_rootPath, f))
 .Where(f => extension is null || f.EndsWith(extension))
 .Take(50);

 return string.Join("\n", files);
 }
}

public class DocumentationPlugin
{
 [KernelFunction("generate_summary")]
 [Description("Generates a structured markdown summary for documentation")]
 public string GenerateSummaryTemplate(
 [Description("Name of the component")] string componentName,
 [Description("Brief description")] string description,
 [Description("Key responsibilities as comma-separated values")] string responsibilities)
 {
 var items = responsibilities.Split(',', StringSplitOptions.TrimEntries);
 var bullets = string.Join("\n", items.Select(r => $"- {r}"));

 return $"""
 ## {componentName}

 {description}

 ### Responsibilities
 {bullets}

 ---
 *Generated documentation — review and expand as needed.*
 """;
 }
}

// Wire it all up
var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: "https://your-resource.openai.azure.com/",
 apiKey: "your-api-key"
);

builder.Plugins.AddFromObject(new FileSystemPlugin("./src"));
builder.Plugins.AddFromType<DocumentationPlugin>();

var kernel = builder.Build();

var chatService = kernel.GetRequiredService<IChatCompletionService>();
var history = new ChatHistory();

history.AddSystemMessage("""
 You are a codebase documentation assistant. You help developers understand
 projects by reading source files and explaining architecture, patterns,
 and design decisions.

 When asked about code, use your tools to read the actual files rather
 than guessing. Be specific and reference actual code when possible.
 Generate documentation artifacts when asked.
 """);

var settings = new OpenAIPromptExecutionSettings
{
 FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
};

Console.WriteLine("Documentation Assistant ready. Ask me about your codebase!");
Console.WriteLine("Type 'exit' to quit.\n");

while (true)
{
 Console.Write("You: ");
 var input = Console.ReadLine();

 if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
 break;

 history.AddUserMessage(input);

 var response = await chatService.GetChatMessageContentAsync(
 history,
 executionSettings: settings,
 kernel: kernel
 );

 Console.WriteLine($"\nAssistant: {response.Content}\n");
 history.AddAssistantMessage(response.Content ?? "");
}

이 도우미는 다음을 수행할 수 있습니다.- 프로젝트 디렉터리의 파일 나열 및 읽기

실제 소스 파일을 읽어 코드베이스에 관한 질문에 답하세요.
마크다운 형식으로 문서 생성
대화 맥락을 유지하여 후속 질문이 자연스럽게 작동하도록 합니다.

AI는 사용자가 요청한 내용에 따라 read_file, list_files 또는 generate_summary를 언제 호출할지 자동으로 결정합니다. “OrderService는 무엇을 하나요?“라고 물어보세요. 파일을 읽고, 분석하고, 설명합니다. “인증 모듈에 대한 문서 생성"을 요청하면 파일을 탐색하고 구조를 이해하고 형식화된 요약을 생성합니다.

제작 팁

Semantic Kernel 애플리케이션을 출시하기 전에 제가 힘들게 배운 몇 가지 사항은 다음과 같습니다.

종속성 주입을 적절하게 사용하세요. ASP.NET Core 앱에서 커널과 서비스를 인라인으로 만드는 대신 DI 컨테이너에 등록하세요.

builder.Services.AddKernel()
 .AddAzureOpenAIChatCompletion(
 deploymentName: "gpt-4o",
 endpoint: configuration["AzureOpenAI:Endpoint"]!,
 apiKey: configuration["AzureOpenAI:ApiKey"]!
 )
 .Plugins.AddFromType<TimePlugin>()
 .AddFromType<OrderPlugin>();

오류를 적절하게 처리합니다. LLM 호출은 실패하거나 시간 초과되거나 예상치 못한 결과를 반환할 수 있습니다. try-catch 블록으로 호출을 래핑하고 Polly 또는 내장된 복원력 기능을 사용하여 재시도 정책을 구현하세요.

토큰 사용량을 모니터링합니다. 모든 프롬프트, 모든 기능 설명, 모든 채팅 기록은 토큰을 소비합니다. 필터를 사용하여 사용량을 기록하고 추적하세요.

kernel.FunctionInvocationFilters.Add(new LoggingFilter());

함수 설명을 정확하게 유지하세요. 모호한 설명으로 인해 AI가 함수를 잘못 호출하게 됩니다. “설명만 읽어도 이 기능을 언제, 어떻게 사용하는지 정확히 알 수 있나요?“라고 질문하여 설명을 테스트해 보세요.

결론

Semantic Kernel은 애플리케이션 구축에 대한 생각을 근본적으로 바꾸는 라이브러리 중 하나입니다. 이는 단순한 API 래퍼가 아닙니다. 유지 관리 및 테스트가 가능하고 프로덕션에 즉시 사용할 수 있는 방식으로 기존 코드로 AI 기능을 구성할 수 있는 오케스트레이션 프레임워크입니다.

제가 가장 좋아하는 점은 .NET 생태계를 존중한다는 것입니다. 종속성 주입, 속성, 비동기/대기, 인터페이스 등 이미 알고 있는 패턴을 사용하여 AI 세계로 확장합니다. 완전히 새로운 패러다임을 배울 필요는 없습니다. 툴킷에 AI를 또 다른 기능으로 추가하기만 하면 됩니다.

.NET 애플리케이션을 구축 중이고 아직 Semantic Kernel을 탐색하지 않았다면 지금이 바로 적기입니다. SDK는 안정적이고 커뮤니티가 활발하며 간단한 프롬프트 오케스트레이션부터 다중 에이전트 협업에 이르기까지 SDK가 지원하는 패턴은 현대 개발자에게 필수적인 기술이 되고 있습니다.

작게 시작하십시오. 커널을 생성하고, 플러그인을 등록하고, AI가 코드를 호출하는 것을 지켜보세요. 일단 클릭하면 애플리케이션의 모든 곳에 인텔리전스를 추가할 수 있는 기회가 나타나기 시작합니다.

공식 문서 및 GitHub 저장소는 여정을 계속하는 데 훌륭한 리소스입니다. 행복한 건물!

Blazor에서 구성 요소 상속

Thu, 04 Sep 2025 00:00:00 +0000

저는 여러 개의 양식 페이지가 있는 프로젝트를 구축하고 있었는데, 모든 페이지마다 동일한 로드 상태 논리, 동일한 오류 처리 및 동일한 토스트 알림이 있었습니다. 모든 것을 복사하여 붙여넣는 것이 잘못된 것 같아서 Blazor에서 구성 요소 상속을 살펴보았습니다. Blazor 구성 요소는 C# 클래스이므로 매우 간단합니다.

기본

모든 Blazor 구성 요소는 기본적으로 ComponentBase에서 상속됩니다. ComponentBase을 확장하는 고유한 기본 클래스를 생성한 다음 구성 요소가 그로부터 상속받도록 할 수 있습니다.

대부분의 페이지에 로딩 상태와 오류 처리가 필요하다고 가정해 보겠습니다. 기본 클래스를 만들 수 있습니다:

using Microsoft.AspNetCore.Components;

public abstract class PageBase : ComponentBase
{
 protected bool IsLoading { get; set; } = true;
 protected string? ErrorMessage { get; set; }

 protected async Task LoadDataAsync(Func<Task> action)
 {
 try
 {
 IsLoading = true;
 ErrorMessage = null;
 await action();
 }
 catch (Exception ex)
 {
 ErrorMessage = ex.Message;
 }
 finally
 {
 IsLoading = false;
 StateHasChanged();
 }
 }
}

기본 클래스 사용

이제 모든 페이지 구성 요소에서 ComponentBase에서 상속하는 대신 PageBase에서 상속합니다.

@page "/users"
@inherits PageBase

@if (IsLoading)
{
 <div class="spinner"></div>
}
else if (ErrorMessage is not null)
{
 <div class="alert alert-danger">@ErrorMessage</div>
}
else
{
 <ul>
 @foreach (var user in users)
 {
 <li>@user.Name</li>
 }
 </ul>
}

@code {
 private List<User> users = new();

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 users = await Http.GetFromJsonAsync<List<User>>("api/users");
 });
 }
}

@inherits PageBase 지시문이 핵심입니다. 이는 Blazor에게 기본 ComponentBase 대신 기본 클래스를 사용하도록 지시합니다. 이제 상속받은 모든 페이지에서 IsLoading, ErrorMessage 및 LoadDataAsync()를 무료로 얻을 수 있습니다.

기본 클래스에 서비스 주입

또한 기본 클래스에 서비스를 삽입하여 모든 하위 구성 요소에서 사용할 수 있도록 할 수도 있습니다.

public abstract class PageBase : ComponentBase
{
 [Inject]
 protected NavigationManager Navigation { get; set; } = default!;

 [Inject]
 protected IToastService Toast { get; set; } = default!;

 protected bool IsLoading { get; set; } = true;
 protected string? ErrorMessage { get; set; }

 protected void NavigateBack() => Navigation.NavigateTo("javascript:history.back()");

 protected void ShowSuccess(string message) => Toast.ShowSuccess(message);
}

PageBase에서 상속된 모든 구성 요소는 이제 아무것도 주입하지 않고도 Navigation, Toast, NavigateBack() 및 ShowSuccess()에 액세스할 수 있습니다.

일반 기본 클래스에 대해 더 자세히 알아보기

일반적인 CRUD 패턴에 대한 일반 기본 클래스를 만들 수도 있습니다.

public abstract class CrudPageBase<T> : PageBase
{
 protected List<T> Items { get; set; } = new();
 protected T? SelectedItem { get; set; }

 protected abstract Task<List<T>> FetchItems();
 protected abstract Task DeleteItem(T item);

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 Items = await FetchItems();
 });
 }

 protected async Task OnDelete(T item)
 {
 await LoadDataAsync(async () =>
 {
 await DeleteItem(item);
 Items = await FetchItems();
 ShowSuccess("Item deleted.");
 });
 }
}

그러면 실제 페이지가 매우 깨끗해집니다.

@page "/products"
@inherits CrudPageBase<Product>

@* just the markup, all logic lives in the base class *@

@code {
 protected override Task<List<Product>> FetchItems()
 => Http.GetFromJsonAsync<List<Product>>("api/products");

 protected override Task DeleteItem(Product item)
 => Http.DeleteAsync($"api/products/{item.Id}");
}

사용해야 할 때와 사용하지 않을 때

구성 요소 상속은 로드 상태, 오류 처리, 인증 확인 또는 CRUD 패턴과 같은 공유 동작에 적합합니다. 그러나 깊은 상속 계층 구조를 지나치게 사용하지 마십시오. 두 수준 이상의 깊이로 진행되는 경우 구성을 사용하는 것이 더 나을 것입니다(예: 이전 게시물의 LoadingComponent 접근 방식).

나는 보통 페이지의 “유형"별로 하나의 기본 클래스를 유지합니다: 일반 페이지의 경우 PageBase, 양식의 경우 FormPageBase, 그게 전부입니다.

게시물이 마음에 드셨기를 바랍니다! @emimontesdeoca로 소셜 미디어를 통해 언제든지 저에게 연락해주세요.

리소스

ASP.NET Core Razor 구성 요소 상속

.NET Aspire: 올바른 방법으로 클라우드 네이티브 애플리케이션 구축

Wed, 20 Aug 2025 00:00:00 +0000

.NET에서 분산 애플리케이션을 구축해 본 적이 있다면 훈련 방법을 알고 계실 것입니다. 웹 API를 가동하고, 백그라운드 작업자를 추가하고, 캐싱을 위해 Redis를, 지속성을 위해 PostgreSQL을, 메시징을 위해 RabbitMQ를 추가하면 갑자기 비즈니스 로직을 작성하는 것보다 인프라 연결에 더 많은 시간을 소비하게 됩니다. appsettings.json 파일에 흩어져 있는 연결 문자열, 구성하는 것을 잊은 상태 확인, 항상 “다음 스프린트의 문제"인 관찰 가능성.

나는 거기에 있었다. 내가 인정하고 싶은 것보다 더 많이.

이것이 바로 .NET Aspire가 해결하도록 설계된 문제입니다. 몇 달 동안 프로덕션 환경에서 실행한 후 제가 배운 좋은 점, 좋은 점, 문제점 등을 공유하고 싶습니다.

.NET Aspire란 무엇입니까?

.NET Aspire는 .NET을 사용하여 관찰 가능하고 생산 준비가 완료된 분산 애플리케이션을 구축하기 위한 독보적인 스택입니다. 이는 전통적인 의미의 프레임워크가 아닙니다. ASP.NET Core를 대체하거나 새로운 프로그래밍 모델을 강제로 적용하지 않습니다. 대신, 이미 알고 있는 내용을 바탕으로 클라우드 네이티브 앱을 구축할 때 항상 존재했던 격차를 메웁니다.

Aspire는 기본적으로 네 가지 기능을 제공합니다.

AppHost — 전체 분산 애플리케이션 토폴로지를 정의하는 프로젝트입니다. 어떤 서비스가 존재하는지, 무엇에 의존하는지, 어떻게 연결되는지 알아보세요.
서비스 기본값 — 모든 서비스에 대해 상태 확인, 탄력성 정책, OpenTelemetry와 같은 교차 관심사를 한 번에 구성하는 공유 프로젝트입니다.
구성 요소 — Redis, PostgreSQL, RabbitMQ, Azure Storage 등과 같은 지원 서비스와의 표준화된 통합을 제공하는 NuGet 패키지입니다.
개발자 대시보드 — 로컬 개발 중에 전체 배포 앱에 대한 로그, 추적 및 측정항목을 표시하는 실시간 UI입니다.

철학은 간단합니다. 모든 .NET 클라우드 앱에 이러한 기능이 필요하다면 왜 매번 처음부터 구현해야 할까요?

첫 번째 Aspire 프로젝트 설정

시작하는 방법은 간단합니다. .NET 8 이상이 필요하고 Aspire 워크로드가 설치되어 있어야 합니다.

dotnet workload update
dotnet workload install aspire

이제 새로운 Aspire 시작 프로젝트를 만듭니다.

dotnet new aspire-starter -n MyCloudApp

그러면 다음 네 가지 프로젝트가 포함된 솔루션이 생성됩니다.

MyCloudApp.AppHost — 오케스트레이터
MyCloudApp.ServiceDefaults — 공유 구성
MyCloudApp.ApiService — 샘플 웹 API
MyCloudApp.Web — Blazor 프런트엔드

AppHost를 실행하면 브라우저에 Aspire 대시보드가 열려 모든 서비스, 로그 및 상태를 즉시 볼 수 있습니다. Docker Compose 파일이 없습니다. 수동 포트 관리가 없습니다. 그냥 작동합니다.

dotnet run --project MyCloudApp.AppHost

그 첫 경험이 나를 매료시켰습니다. 1분 안에 관찰 기능이 내장된 완벽하게 조정된 분산 앱이 완성됩니다.

AppHost 패턴

AppHost는 마법이 살아있는 곳입니다. 이는 빌더 패턴을 사용하여 분산 애플리케이션의 토폴로지, 즉 존재하는 리소스와 서비스가 리소스에 연결되는 방식을 정의하는 작은 콘솔 애플리케이션입니다.

현실적인 AppHost의 모습은 다음과 같습니다.

var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure resources
var postgres = builder.AddPostgres("postgres")
 .WithPgAdmin()
 .AddDatabase("catalogdb");

var redis = builder.AddRedis("cache");

var rabbitmq = builder.AddRabbitMQ("messaging")
 .WithManagementPlugin();

// Application services
var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
 .WithReference(postgres)
 .WithReference(redis)
 .WithReference(rabbitmq);

var orderApi = builder.AddProject<Projects.OrderApi>("order-api")
 .WithReference(postgres)
 .WithReference(rabbitmq);

var frontend = builder.AddProject<Projects.WebFrontend>("frontend")
 .WithExternalHttpEndpoints()
 .WithReference(catalogApi)
 .WithReference(orderApi);

builder.Build().Run();
```해당 코드를 소리내어 읽어보세요. 실제로는 그 자체를 문서화합니다. "카탈로그 API는 PostgreSQL, Redis 및 RabbitMQ를 참조합니다. 프런트엔드는 카탈로그 API 및 주문 API를 참조합니다." 이것이 코드로 표현된 아키텍처입니다.

주목할 만한 몇 가지 사항:

- **`WithReference`** 무거운 작업을 수행합니다. 환경 변수 및 구성을 통해 연결 문자열과 서비스 URL을 소비 프로젝트에 자동으로 삽입합니다. 귀하의 서비스는 Redis가 *어디* 실행되고 있는지 알 필요가 없습니다. Aspire가 이를 처리합니다.
- **`WithPgAdmin()`** 및 **`WithManagementPlugin()`** 실제 서비스와 함께 PostgreSQL 및 RabbitMQ용 관리 UI를 실행합니다. 개발하는 동안 이는 매우 중요합니다.
- **`WithExternalHttpEndpoints()`** 서비스를 외부에서 액세스할 수 있는 것으로 표시하며 이는 배포 시 중요합니다.

### 리소스 구성

세분화된 제어를 통해 리소스를 구성할 수 있습니다.

```csharp
var postgres = builder.AddPostgres("postgres")
 .WithEnvironment("POSTGRES_MAX_CONNECTIONS", "200")
 .WithDataVolume("postgres-data")
 .AddDatabase("catalogdb");

var redis = builder.AddRedis("cache")
 .WithDataVolume("redis-data");

데이터 볼륨은 로컬 개발 데이터가 컨테이너를 다시 시작해도 유지되도록 보장합니다. 작은 디테일로 삶의 질이 크게 향상됩니다.

서비스 기본값: 알려지지 않은 영웅

ServiceDefaults 프로젝트는 Aspire에서 가장 과소평가된 부분입니다. 이는 솔루션의 모든 서비스가 참조하는 공유 라이브러리이며, 잊어버리거나 일관되지 않게 구현할 수 있는 모든 교차 문제를 구성합니다.

ServiceDefaults의 일반적인 Extensions.cs는 다음과 같습니다.

public static class Extensions
{
 public static IHostApplicationBuilder AddServiceDefaults(
 this IHostApplicationBuilder builder)
 {
 builder.ConfigureOpenTelemetry();
 builder.AddDefaultHealthChecks();
 builder.Services.AddServiceDiscovery();

 builder.Services.ConfigureHttpClientDefaults(http =>
 {
 http.AddStandardResilienceHandler();
 http.AddServiceDiscovery();
 });

 return builder;
 }

 public static IHostApplicationBuilder ConfigureOpenTelemetry(
 this IHostApplicationBuilder builder)
 {
 builder.Logging.AddOpenTelemetry(logging =>
 {
 logging.IncludeFormattedMessage = true;
 logging.IncludeScopes = true;
 });

 builder.Services.AddOpenTelemetry()
 .WithMetrics(metrics =>
 {
 metrics.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddRuntimeInstrumentation();
 })
 .WithTracing(tracing =>
 {
 tracing.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddGrpcClientInstrumentation();
 });

 builder.AddOpenTelemetryExporters();
 return builder;
 }

 public static IHostApplicationBuilder AddDefaultHealthChecks(
 this IHostApplicationBuilder builder)
 {
 builder.Services.AddHealthChecks()
 .AddCheck("self", () => HealthCheckResult.Healthy(),
 ["live"]);

 return builder;
 }
}

그런 다음 각 서비스의 Program.cs에서 한 줄로 모든 작업을 수행합니다.

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

// Your service-specific configuration...

var app = builder.Build();
app.MapDefaultEndpoints();
app.Run();

단일 AddServiceDefaults() 호출은 다음을 제공합니다.

구조화된 로깅, 측정항목 및 분산 추적 기능을 갖춘 OpenTelemetry
활성 및 준비 엔드포인트를 통한 상태 확인
서비스 검색 - 서비스가 이름으로 서로를 찾을 수 있음
나가는 모든 HTTP 호출에 대한 복원력 정책(재시도, 회로 차단기, 시간 초과)

이것은 “내 컴퓨터에서 작동하는” 데모와 프로덕션 준비 시스템을 구분하는 요소입니다. 그리고 Aspire는 이를 나중에 고려하지 않고 기본값으로 설정합니다.

Aspire 구성요소

Aspire 구성 요소는 서비스가 지원 인프라에 연결되는 방식을 표준화하는 NuGet 패키지입니다. 이는 단순한 클라이언트 라이브러리 그 이상입니다. 상태 확인, 로깅, 추적 및 즉시 구성 가능한 복원력을 포함합니다.

레디스

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();
builder.AddRedisDistributedCache("cache");

그게 다야. 연결 문자열은 WithReference를 통해 AppHost에서 가져옵니다. 구성 요소는 상태 확인 및 OpenTelemetry 계측이 이미 연결되어 있는 Redis에서 지원하는 IDistributedCache를 등록합니다.

출력 캐싱에 Redis를 사용할 수도 있습니다.

builder.AddRedisOutputCache("cache");

Entity Framework Core가 포함된 PostgreSQL

builder.AddNpgsqlDbContext<CatalogDbContext>("catalogdb", settings =>
{
 settings.DisableRetry = false;
});

그러면 AppHost에 정의된 catalogdb 데이터베이스에 연결하여 DbContext가 등록됩니다. 여기에는 연결 풀링, 상태 확인 및 재시도 정책이 포함됩니다.

토끼MQ

builder.AddRabbitMQClient("messaging");

완전히 구성되고 상태가 확인된 RabbitMQ 클라이언트 라이브러리에서 IConnection를 등록합니다.

Azure 통합

Aspire에는 Azure 서비스를 위한 최고 수준의 구성 요소도 있습니다.

// Azure Blob Storage
builder.AddAzureBlobClient("blobs");

// Azure Service Bus
builder.AddAzureServiceBusClient("servicebus");

// Azure Key Vault
builder.AddAzureKeyVaultClient("secrets");
```패턴은 항상 동일합니다. AppHost의 한 줄은 리소스를 정의하고 소비 서비스의 한 줄은 리소스를 사용합니다. 연결 세부정보가 자동으로 전달됩니다.

## 개발자 대시보드

Aspire 대시보드는 실제로 사용하기 전까지는 가지고 있으면 좋을 것 같은 기능 중 하나입니다. Aspire 대시보드 없이 작업하는 것은 상상할 수 없습니다.

AppHost를 로컬로 실행하면 대시보드가 시작되고 다음을 제공합니다.

- **리소스 개요** — 상태 표시기를 통해 모든 서비스와 인프라를 한 눈에 볼 수 있습니다.
- **구조화된 로그** — 모든 서비스의 실시간 로그 스트리밍, 필터링 및 검색 가능
- **분산 추적** — 플레임 차트로 시각화된 여러 서비스에 걸친 엔드투엔드 요청 추적
- **지표** — 실시간 HTTP 요청 비율, 오류율, 지연 시간 및 사용자 지정 지표
- **콘솔 로그** — 각 컨테이너 및 프로젝트의 원시 stdout/stderr

분산 추적은 특히 중요합니다. 요청이 프런트엔드에 도달하고 카탈로그 API를 통해 흐르고 Redis 및 PostgreSQL에 도달하면 각 홉에 대한 타이밍과 함께 전체 체인을 볼 수 있습니다. 더 이상 병목 현상이 발생하는 위치를 추측할 필요가 없습니다.

디버깅하는 동안 대시보드가 가장 유용하다는 것을 알았습니다. 여러 터미널 창을 추적하거나 로그 파일 사이를 이동하는 대신 서비스 전반에 걸쳐 관련 이벤트를 연결하는 상관 관계 ID를 통해 모든 것이 한 곳에 있습니다.

대시보드는 독립형 컨테이너로도 제공됩니다. 즉, 스테이징 환경이나 CI 파이프라인에서 사용할 수 있습니다.

```bash
docker run --rm -p 18888:18888 \
 mcr.microsoft.com/dotnet/aspire-dashboard:latest

배포

Aspire는 개발 중에 도움이 되지만 생산은 어떻습니까? 이것이 실제적인 일이 되는 곳입니다.

Azure 컨테이너 앱

가장 간단한 배포 경로는 최고 수준의 Aspire를 지원하는 ACA(Azure Container Apps)입니다. Azure 개발자 CLI를 사용하여 직접 배포할 수 있습니다.

azd init
azd up

azd init 명령은 Aspire AppHost를 감지하고 필요한 코드형 인프라를 생성합니다. azd up는 AppHost 토폴로지를 기반으로 컨테이너 레지스트리, 컨테이너 앱, 데이터베이스, Redis 인스턴스 등 모든 것을 프로비저닝합니다.

AppHost는 기본적으로 배포 매니페스트가 됩니다. “catalog-api는 PostgreSQL 및 Redis에 따라 달라집니다"를 정의하는 동일한 코드가 인프라 프로비저닝을 구동합니다.

쿠버네티스

Kubernetes 배포의 경우 Aspire는 매니페스트를 직접 생성하지 않지만 AppHost 토폴로지는 Kubernetes 리소스에 깔끔하게 매핑됩니다. 커뮤니티 도구 aspirate(Aspir8)는 AppHost에서 Helm 차트 또는 Kubernetes 매니페스트를 생성할 수 있습니다.

dotnet tool install -g aspirate
aspirate generate
aspirate apply

배포 고려 사항

명심해야 할 몇 가지 사항:- 연결 문자열은 환경에 따라 변경됩니다. 로컬에서 Aspire는 컨테이너를 회전하고 연결 문자열을 자동으로 주입합니다. 프로덕션에서는 관리형 서비스를 가리킵니다. Aspire는 표준 .NET 구성을 사용하므로 환경 변수와 Azure Key Vault가 예상대로 작동합니다.

AppHost는 프로덕션 환경에서 실행되지 않습니다. 개발 및 배포 조정 도구입니다. 프로덕션에서 서비스는 환경 변수 및 오케스트레이터를 통해 구성되어 독립적으로 실행됩니다.
인프라 리소스는 관리형 서비스가 됩니다. 로컬 PostgreSQL 컨테이너는 Azure Database for PostgreSQL이 됩니다. 로컬 Redis 컨테이너는 Azure Cache for Redis가 됩니다. 소비 코드는 변경되지 않습니다.

실제 팁

한동안 프로덕션 환경에서 Aspire를 실행한 후 시간을 절약할 수 있었던 교훈은 다음과 같습니다.

1. 맞춤형 리소스 수명 주기 확인을 사용하세요

리소스가 준비되었는지 확인하기 위해 컨테이너 시작에만 의존하지 마세요. PostgreSQL은 실제로 쿼리를 제공할 준비가 되기 전에 TCP 연결을 수락할 수 있습니다.

var postgres = builder.AddPostgres("postgres")
 .AddDatabase("catalogdb")
 .WithHealthCheck();

Aspire는 리소스에 대해 상태 확인을 실행하고 실제로 준비될 때까지 종속 서비스를 보유할 수 있습니다.

2. 공통 패턴을 확장으로 추출

여러 서비스가 비슷한 구성을 공유하는 경우 확장 메서드를 만듭니다.

public static class AppHostExtensions
{
 public static IResourceBuilder<ProjectResource> AddWorkerService(
 this IDistributedApplicationBuilder builder,
 string name,
 IResourceBuilder<IResourceWithConnectionString> db,
 IResourceBuilder<IResourceWithConnectionString> messaging)
 {
 return builder.AddProject<Projects.WorkerService>(name)
 .WithReference(db)
 .WithReference(messaging)
 .WithReplicas(3);
 }
}

3. 부하 테스트에 WithReplicas 활용

var catalogApi = builder.AddProject<Projects.CatalogApi>("catalog-api")
 .WithReference(postgres)
 .WithReference(redis)
 .WithReplicas(5);

WithReplicas는 서비스의 여러 인스턴스를 로컬에서 실행합니다. 이는 클러스터에 배포하지 않고도 로드 밸런싱, 동시성 버그 및 분산 캐싱 동작을 테스트하는 데 유용합니다.

4. 민감한 값에 대한 매개변수 사용

로컬 개발의 경우에도 자격 증명을 하드코딩하지 마세요.

var dbPassword = builder.AddParameter("db-password", secret: true);

var postgres = builder.AddPostgres("postgres", password: dbPassword)
 .AddDatabase("catalogdb");

로컬로 실행할 때 Aspire는 값을 묻는 메시지를 표시하거나 사용자 비밀에서 값을 읽습니다. CI/CD에서는 환경 변수에서 가져옵니다.

5. 통합 테스트가 쉬워졌습니다.

Aspire에는 분산 앱 통합 테스트를 매우 쉽게 만드는 테스트 패키지가 포함되어 있습니다.

[Fact]
public async Task CatalogApiReturnsProducts()
{
 var appHost = await DistributedApplicationTestingBuilder
 .CreateAsync<Projects.MyCloudApp_AppHost>();

 await using var app = await appHost.BuildAsync();
 await app.StartAsync();

 var httpClient = app.CreateHttpClient("catalog-api");
 var response = await httpClient.GetAsync("/api/products");

 response.EnsureSuccessStatusCode();

 var products = await response.Content
 .ReadFromJsonAsync<List<Product>>();
 Assert.NotEmpty(products);
}

이는 데이터베이스 및 메시지 브로커를 포함한 전체 분산 애플리케이션을 가동하여 이에 대해 테스트를 실행하고 해체합니다. CI 파이프라인에서 실제 인프라에 대한 실제 통합 테스트를 수행합니다. 조롱하지 마세요.

6. 로컬에서 리소스 사용량 모니터링

여러 컨테이너를 로컬에서 실행하는 경우 리소스 소비를 주의 깊게 살펴보세요. 관리 UI가 포함된 PostgreSQL, Redis 및 RabbitMQ 인스턴스는 2~3GB의 RAM을 쉽게 사용할 수 있습니다. 제한된 시스템을 사용하는 경우 더 가벼운 리소스 구성을 사용하는 것이 좋습니다.

var redis = builder.AddRedis("cache")
 .WithContainerRuntimeArgs("--memory=256m");

결론

.NET Aspire는 분산 애플리케이션을 구축하는 방식을 근본적으로 변경했습니다. 혁신적인 개념을 도입했기 때문이 아닙니다. 상태 확인, OpenTelemetry 및 컨테이너 오케스트레이션은 새로운 것이 아닙니다. 하지만 기본값으로 만들기 때문입니다. 일반적으로 내려야 하는 수백 가지의 작은 결정을 내리고 이를 합리적인 기본값으로 구현하며 필요할 때 재정의할 수 있습니다.제 생각에는 AppHost 패턴이 가장 큰 승리라고 생각합니다. Docker Compose 파일, Kubernetes 매니페스트 및 README 문서에 분산되지 않고 코드로 표현된 분산 애플리케이션 토폴로지를 가짐으로써 시스템을 이해하기 쉽게 만듭니다. 새로운 팀 구성원은 AppHost에서 Program.cs를 열고 몇 분 안에 전체 아키텍처를 이해할 수 있습니다.

.NET으로 분산 애플리케이션을 구축하고 있다면 Aspire를 진지하게 살펴보세요. aspire-starter 템플릿으로 시작하여 대시보드를 탐색하고 필요에 따라 구성 요소를 점진적으로 채택하세요. 첫날부터 올인할 필요는 없습니다. Aspire는 설계상 추가 기능을 제공합니다.

인프라 상용구를 배선하는 데 첫 번째 스프린트를 소비하는 시대는 끝났습니다. Aspire가 배관 작업을 처리하도록 하여 실제로 중요한 것, 즉 애플리케이션에 집중할 수 있도록 하세요.

Blazor의 인증 및 권한 부여: 실용 가이드

Sat, 12 Jul 2025 00:00:00 +0000

ASP.NET MVC 또는 Razor Pages를 사용하여 작업한 경우 인증 작동 방식에 대한 정신적 모델이 있을 것입니다. 미들웨어가 요청을 가로채고, 쿠키 또는 토큰을 확인하고, HttpContext.User를 채우면 경쟁이 시작됩니다. Blazor는 미묘하지만 중요한 방식으로 정신 모델을 변경합니다. 이러한 차이점을 조기에 이해하지 못하면 불가능하다고 느껴지는 인증 문제를 디버깅하게 됩니다.

이 게시물에서는 서버 및 WebAssembly 호스팅 모델을 모두 다루면서 Blazor에서 인증 및 권한 부여가 실제로 어떻게 작동하는지 살펴보고 싶습니다. 우리는 사용자 지정 공급자, 외부 OAuth 및 숙련된 .NET 개발자라도 겪었던 함정을 통해 기본부터 끝까지 진행할 것입니다.

Blazor의 인증이 다른 이유

기존 ASP.NET에서는 모든 사용자 상호 작용이 HTTP 요청입니다. 서버는 자격 증명을 확인하고 쿠키를 설정하며 모든 후속 요청에는 해당 쿠키가 전달됩니다. 인증 파이프라인은 선형적이고 예측 가능합니다.

Blazor Server는 지속적인 SignalR 연결을 통해 작동합니다. 초기 HTTP 요청이 페이지를 로드한 후 모든 후속 상호 작용은 WebSocket을 통해 발생합니다. 각 버튼 클릭에 대한 새로운 HTTP 요청이 없으므로 미들웨어는 모든 상호 작용에서 다시 실행되지 않습니다. HttpContext은 초기 연결 중에 사용할 수 있지만 회로 수명 내내 이에 의존하면 버그가 발생할 수 있습니다.

Blazor WebAssembly는 전적으로 브라우저에서 실행됩니다. 서버 측 HttpContext가 전혀 없습니다. 인증 상태는 API에서 가져와서 클라이언트측에 저장하고 토큰(일반적으로 JWT)을 통해 관리해야 합니다. 서버는 토큰 유효성 검사가 진행되는 동안에만 클라이언트를 신뢰합니다.

이는 Blazor가 호스팅 모델에 관계없이 작동하는 인증 상태에 대한 자체 추상화가 필요함을 의미합니다. 그 추상화는 AuthenticationStateProvider입니다.

인증 상태: 재단

Blazor 인증 시스템의 핵심은 AuthenticationStateProvider입니다. 이는 단일 중요한 메서드를 노출하는 추상 클래스입니다.

public abstract Task<AuthenticationState> GetAuthenticationStateAsync();

AuthenticationState 개체는 .NET 전체에서 사용되는 것과 동일한 ID 모델인 ClaimsPrincipal를 래핑합니다. 구성 요소는 쿠키나 토큰과 직접 대화하지 않습니다. 그들은 현재 상태에 대해 AuthenticationStateProvider에게 묻습니다.

전체 구성 요소 트리에서 이 상태를 사용할 수 있도록 Blazor는 CascadingAuthenticationState를 제공합니다. 일반적으로 라우터를 App.razor 또는 레이아웃으로 래핑합니다.

<CascadingAuthenticationState>
 <Router AppAssembly="@typeof(App).Assembly">
 <Found Context="routeData">
 <AuthorizeRouteView RouteData="@routeData"
 DefaultLayout="@typeof(MainLayout)">
 <NotAuthorized>
 <p>You're not authorized to view this page.</p>
 </NotAuthorized>
 </AuthorizeRouteView>
 </Found>
 <NotFound>
 <LayoutView Layout="@typeof(MainLayout)">
 <p>Page not found.</p>
 </LayoutView>
 </NotFound>
 </Router>
</CascadingAuthenticationState>

AuthorizeRouteView는 여기서 이중 임무를 수행합니다. 즉, 일치하는 페이지 구성 요소를 렌더링하기 전에 사용자가 인증 및 승인되었는지 확인하고 그렇지 않은 경우 대체 UI를 제공합니다.

통합 Blazor 모델이 포함된 .NET 8 이상에서는 App.razor에서 이를 구성하고 서비스 등록에서 AddCascadingAuthenticationState()를 사용할 때 프레임워크가 계단식 매개 변수를 자동으로 처리합니다.

ASP.NET ID 통합

대부분의 프로젝트에서는 처음부터 인증을 구축할 필요가 없습니다. ASP.NET ID는 사용자 관리, 암호 해싱, 2단계 인증 및 계정 확인 기능을 즉시 제공합니다.Blazor를 사용한 설정은 Program.cs에서 시작됩니다.

builder.Services.AddDbContext<ApplicationDbContext>(options =>
 options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddDefaultIdentity<IdentityUser>(options =>
 {
 options.SignIn.RequireConfirmedAccount = true;
 options.Password.RequireDigit = true;
 options.Password.RequiredLength = 8;
 })
 .AddRoles<IdentityRole>()
 .AddEntityFrameworkStores<ApplicationDbContext>();

builder.Services.AddAuthentication(options =>
 {
 options.DefaultScheme = IdentityConstants.ApplicationScheme;
 options.DefaultSignInScheme = IdentityConstants.ExternalScheme;
 });

.NET 8+의 Blazor 웹앱 템플릿을 사용하면 스캐폴드된 ID UI가 Razor 구성 요소를 직접 사용합니다. 나머지 Blazor 애플리케이션과 자연스럽게 통합되는 로그인, 등록 및 계정 관리 페이지가 제공됩니다. 더 이상 Razor Pages와 Blazor 구성 요소를 어색하게 혼합할 필요가 없습니다.

ApplicationDbContext는 IdentityDbContext에서 상속되며 ID 테이블을 생성하려면 마이그레이션을 실행해야 합니다.

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
 public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
 : base(options) { }
}

dotnet ef migrations add InitialIdentity
dotnet ef database update

AuthorizeView 구성 요소

인증 상태가 구성 요소 트리를 통해 흐르면 AuthorizeView를 사용하면 조건부로 UI를 렌더링할 수 있습니다.

<AuthorizeView>
 <Authorized>
 <p>Welcome, @context.User.Identity?.Name!</p>
 <a href="/account/manage">Manage Account</a>
 <form method="post" action="/account/logout">
 <button type="submit">Log Out</button>
 </form>
 </Authorized>
 <NotAuthorized>
 <a href="/account/login">Log In</a>
 <a href="/account/register">Register</a>
 </NotAuthorized>
</AuthorizeView>

<Authorized> 내부의 context 매개변수는 AuthenticationState에 대한 액세스를 제공하므로 마크업에서 직접 클레임, 역할 및 사용자 ID를 검사할 수 있습니다.

역할 및 정책과 함께 AuthorizeView를 사용할 수도 있습니다.

<AuthorizeView Roles="Admin,Moderator">
 <Authorized>
 <button @onclick="DeletePost">Delete Post</button>
 </Authorized>
</AuthorizeView>

<AuthorizeView Policy="CanEditArticles">
 <Authorized>
 <button @onclick="EditArticle">Edit</button>
 </Authorized>
</AuthorizeView>

명심해야 할 한 가지: AuthorizeView는 UI 문제입니다. 요소를 숨기거나 표시하지만 기본 논리를 보호하지는 않습니다. 누군가가 API 엔드포인트를 호출하거나 메소드를 직접 호출할 수 있으면 AuthorizeView를 완전히 우회합니다. 항상 서버 측에서도 인증을 시행하십시오.

[Authorize] 속성

전체 페이지를 보호하려면 [Authorize] 속성을 적용하세요.

@page "/admin/dashboard"
@attribute [Authorize(Roles = "Admin")]

<h1>Admin Dashboard</h1>
<p>Only administrators can see this page.</p>

인증되지 않은 사용자가 이 페이지를 탐색하면 AuthorizeRouteView가 시작되어 이전에 정의한 <NotAuthorized> 템플릿을 렌더링합니다. 대신 탐색을 통해 NotAuthorized 사례를 처리하여 로그인 페이지로 리디렉션할 수 있습니다.

<NotAuthorized>
 @if (!context.User.Identity?.IsAuthenticated ?? true)
 {
 <RedirectToLogin />
 }
 else
 {
 <p>You don't have permission to access this page.</p>
 }
</NotAuthorized>

간단한 RedirectToLogin 구성 요소는 다음과 같습니다.

@inject NavigationManager Navigation

@code {
 protected override void OnInitialized()
 {
 var returnUrl = Uri.EscapeDataString(Navigation.Uri);
 Navigation.NavigateTo($"/account/login?returnUrl={returnUrl}", forceLoad: true);
 }
}

여기서는 forceLoad: true가 중요합니다. 서버 측 인증 미들웨어가 로그인 흐름을 적절하게 처리할 수 있도록 실제 HTTP 탐색이 필요합니다.

역할 기반 및 정책 기반 인증

역할은 가장 간단한 모델입니다. 사용자를 “관리자” 또는 “편집자"와 같은 그룹에 할당한 다음 멤버십을 확인하세요. 그러나 정책은 훨씬 더 많은 유연성을 제공합니다.

Program.cs에 정책을 등록합니다.

builder.Services.AddAuthorizationCore(options =>
{
 options.AddPolicy("CanPublish", policy =>
 policy.RequireClaim("Permission", "Publish"));

 options.AddPolicy("MinimumAge", policy =>
 policy.Requirements.Add(new MinimumAgeRequirement(18)));

 options.AddPolicy("PremiumUser", policy =>
 policy.RequireRole("Premium")
 .RequireClaim("Subscription", "Active"));
});

사용자 정의 요구 사항에는 처리기가 필요합니다.

public class MinimumAgeRequirement : IAuthorizationRequirement
{
 public int MinimumAge { get; }
 public MinimumAgeRequirement(int minimumAge) => MinimumAge = minimumAge;
}

public class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
 protected override Task HandleRequirementAsync(
 AuthorizationHandlerContext context,
 MinimumAgeRequirement requirement)
 {
 var dateOfBirthClaim = context.User.FindFirst("DateOfBirth");

 if (dateOfBirthClaim is null)
 return Task.CompletedTask;

 var dateOfBirth = DateOnly.Parse(dateOfBirthClaim.Value);
 var age = DateOnly.FromDateTime(DateTime.Today).Year - dateOfBirth.Year;

 if (age >= requirement.MinimumAge)
 context.Succeed(requirement);

 return Task.CompletedTask;
 }
}

핸들러를 등록합니다.

builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();

구성 요소에서 동적 논리가 필요할 때 프로그래밍 방식으로 인증을 확인할 수도 있습니다.

@inject IAuthorizationService AuthorizationService
@inject AuthenticationStateProvider AuthStateProvider

@code {
 private bool canPublish;

 protected override async Task OnInitializedAsync()
 {
 var authState = await AuthStateProvider.GetAuthenticationStateAsync();
 var result = await AuthorizationService.AuthorizeAsync(
 authState.User, "CanPublish");
 canPublish = result.Succeeded;
 }
}

외부 OAuth 제공자

ASP.NET 인증 미들웨어를 사용하면 “Google로 로그인” 또는 “GitHub으로 로그인” 지원이 간단해집니다. OAuth 흐름에는 HTTP 리디렉션이 필요하므로 서버 측에서 구성됩니다.

builder.Services.AddAuthentication()
 .AddGoogle(options =>
 {
 options.ClientId = builder.Configuration["Auth:Google:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:Google:ClientSecret"]!;
 options.Scope.Add("profile");
 })
 .AddMicrosoftAccount(options =>
 {
 options.ClientId = builder.Configuration["Auth:Microsoft:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:Microsoft:ClientSecret"]!;
 })
 .AddGitHub(options =>
 {
 options.ClientId = builder.Configuration["Auth:GitHub:ClientId"]!;
 options.ClientSecret = builder.Configuration["Auth:GitHub:ClientSecret"]!;
 });

GitHub의 경우 기본 ASP.NET 라이브러리에 포함되어 있지 않으므로 AspNet.Security.OAuth.GitHub NuGet 패키지가 필요합니다.

그런 다음 로그인 UI는 외부 인증 확인을 트리거하는 링크를 제공합니다.

@page "/account/external-login"

<h2>Sign in with an external provider</h2>

<form method="post" action="/api/auth/external-login">
 <button type="submit" name="provider" value="Google">
 Sign in with Google
 </button>
 <button type="submit" name="provider" value="Microsoft">
 Sign in with Microsoft
 </button>
 <button type="submit" name="provider" value="GitHub">
 Sign in with GitHub
 </button>
</form>

API 엔드포인트는 챌린지를 트리거하고 콜백을 처리합니다.

app.MapPost("/api/auth/external-login", (string provider, HttpContext context) =>
{
 var properties = new AuthenticationProperties
 {
 RedirectUri = "/api/auth/external-callback"
 };
 return Results.Challenge(properties, [provider]);
});

Blazor의 외부 인증에는 항상 전체 페이지 탐색이 필요합니다. 서버를 통하지 않고는 SignalR 회로 또는 WebAssembly 앱 내에서 OAuth 리디렉션을 완료할 수 없습니다.

Blazor WebAssembly의 토큰 기반 인증Blazor WebAssembly는 클라이언트에서 실행되므로 쿠키 기반 인증은 동일한 방식으로 적용되지 않습니다. 대신 일반적으로 메모리에 저장되어 나가는 HTTP 요청에 연결된 JWT를 사용합니다.

프레임워크는 토큰을 자동으로 연결하기 위해 AuthorizationMessageHandler를 제공합니다.

builder.Services.AddHttpClient("API",
 client => client.BaseAddress = new Uri("https://api.example.com"))
 .AddHttpMessageHandler<AuthorizationMessageHandler>();

builder.Services.AddScoped(sp =>
 sp.GetRequiredService<IHttpClientFactory>().CreateClient("API"));

자체 API에 대해 인증하는 독립 실행형 Blazor WASM 앱의 경우 JWT를 구문 분석하는 사용자 지정 AuthenticationStateProvider을 구현합니다.

public class JwtAuthenticationStateProvider : AuthenticationStateProvider
{
 private readonly ILocalStorageService _localStorage;
 private readonly HttpClient _httpClient;

 public JwtAuthenticationStateProvider(
 ILocalStorageService localStorage,
 HttpClient httpClient)
 {
 _localStorage = localStorage;
 _httpClient = httpClient;
 }

 public override async Task<AuthenticationState> GetAuthenticationStateAsync()
 {
 var token = await _localStorage.GetItemAsync<string>("authToken");

 if (string.IsNullOrWhiteSpace(token))
 return new AuthenticationState(new ClaimsPrincipal(new ClaimsIdentity()));

 _httpClient.DefaultRequestHeaders.Authorization =
 new AuthenticationHeaderValue("Bearer", token);

 var claims = ParseClaimsFromJwt(token);
 var identity = new ClaimsIdentity(claims, "jwt");

 return new AuthenticationState(new ClaimsPrincipal(identity));
 }

 public void NotifyAuthStateChanged()
 {
 NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
 }

 private IEnumerable<Claim> ParseClaimsFromJwt(string jwt)
 {
 var payload = jwt.Split('.')[1];

 var padded = payload.Length % 4 switch
 {
 2 => payload + "==",
 3 => payload + "=",
 _ => payload
 };

 var bytes = Convert.FromBase64String(padded);
 var json = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(bytes);

 return json?.Select(kvp => new Claim(kvp.Key, kvp.Value.ToString()))
 ?? Enumerable.Empty<Claim>();
 }
}

로그인에 성공하면 토큰을 저장하고 인증 상태를 알립니다.

public class AuthService
{
 private readonly HttpClient _httpClient;
 private readonly ILocalStorageService _localStorage;
 private readonly JwtAuthenticationStateProvider _authStateProvider;

 public AuthService(
 HttpClient httpClient,
 ILocalStorageService localStorage,
 AuthenticationStateProvider authStateProvider)
 {
 _httpClient = httpClient;
 _localStorage = localStorage;
 _authStateProvider = (JwtAuthenticationStateProvider)authStateProvider;
 }

 public async Task<bool> LoginAsync(string email, string password)
 {
 var response = await _httpClient.PostAsJsonAsync("/api/auth/login",
 new { Email = email, Password = password });

 if (!response.IsSuccessStatusCode)
 return false;

 var result = await response.Content
 .ReadFromJsonAsync<LoginResponse>();

 await _localStorage.SetItemAsync("authToken", result!.Token);
 _authStateProvider.NotifyAuthStateChanged();

 return true;
 }

 public async Task LogoutAsync()
 {
 await _localStorage.RemoveItemAsync("authToken");
 _authStateProvider.NotifyAuthStateChanged();
 }
}

주의 사항: JWT를 localStorage에 저장하면 XSS 공격에 노출됩니다. 보안 수준이 높은 애플리케이션의 경우 토큰을 메모리에만 유지하고 새로 고침 토큰을 사용하거나 서버가 토큰을 관리하고 클라이언트가 HTTP 전용 쿠키를 사용하는 BFF(Backend-for-Frontend) 패턴을 채택하는 것이 좋습니다.

Blazor 서버와 WebAssembly: 보안 고려 사항

호스팅 모델은 보안 상태를 근본적으로 변화시킵니다.

Blazor Server는 모든 구성 요소 논리를 서버에 유지합니다. 클라이언트는 SignalR을 통해 렌더링된 HTML diff만 볼 수 있습니다. 이는 다음을 의미합니다.

민감한 로직은 절대 서버를 떠나지 않습니다.
구성 요소에서 직접 데이터베이스 및 내부 서비스에 액세스할 수 있습니다.
인증 상태는 초기 연결 시 서버의 HttpContext에서 가져옵니다.
회로는 인증 쿠키보다 오래 지속될 수 있습니다. 사용자의 쿠키가 만료되면 회로는 연결이 끊어질 때까지 활성 상태로 유지됩니다.
회로 연결 해제를 적절하게 처리하고 다시 연결 시 인증 상태를 다시 검증해야 합니다.

Blazor WebAssembly는 전적으로 브라우저에서 실행됩니다. 이는 다음을 의미합니다.

모든 구성 요소 코드를 다운로드하고 검사할 수 있습니다.
WASM 구성 요소에 비밀, 연결 문자열 또는 민감한 비즈니스 논리를 넣지 마십시오.
인증은 UX용 클라이언트에만 적용됩니다. 실제 시행은 API 계층에서 이루어져야 합니다.
토큰 관리는 귀하의 책임입니다
서버 프로젝트가 인증을 처리하고 WASM 앱을 제공하는 호스팅 모델 사용을 고려하세요.

WebAssembly 앱에 대해 제가 권장하는 패턴은 모든 구성 요소를 “신뢰할 수 없는 UI"인 것처럼 처리하고 모든 API 엔드포인트를 알 수 없는 클라이언트에 의해 호출되는 것처럼 처리하는 것입니다. 클라이언트가 확인하는 내용에 관계없이 서버 측의 모든 것을 검증합니다.

사용자 정의 AuthenticationStateProvider 구축

때로는 기본 제공 공급자가 아키텍처에 맞지 않는 경우가 있습니다. 레거시 인증 시스템과 통합하거나 인증 상태 변경을 폴링해야 할 수도 있습니다. Blazor Server에 대한 보다 완전한 사용자 지정 공급자는 다음과 같습니다.

public class CustomAuthStateProvider : AuthenticationStateProvider
{
 private readonly IHttpContextAccessor _httpContextAccessor;
 private readonly IUserService _userService;

 public CustomAuthStateProvider(
 IHttpContextAccessor httpContextAccessor,
 IUserService userService)
 {
 _httpContextAccessor = httpContextAccessor;
 _userService = userService;
 }

 public override async Task<AuthenticationState> GetAuthenticationStateAsync()
 {
 var httpContext = _httpContextAccessor.HttpContext;

 if (httpContext?.User?.Identity?.IsAuthenticated != true)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var userId = httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier);

 if (userId is null)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var user = await _userService.GetUserWithClaimsAsync(userId);

 if (user is null)
 return new AuthenticationState(
 new ClaimsPrincipal(new ClaimsIdentity()));

 var claims = new List<Claim>
 {
 new(ClaimTypes.NameIdentifier, user.Id),
 new(ClaimTypes.Name, user.DisplayName),
 new(ClaimTypes.Email, user.Email)
 };

 claims.AddRange(user.Roles.Select(r => new Claim(ClaimTypes.Role, r)));
 claims.AddRange(user.Permissions.Select(p => new Claim("Permission", p)));

 var identity = new ClaimsIdentity(claims, "Custom");
 return new AuthenticationState(new ClaimsPrincipal(identity));
 }

 public void MarkUserAsAuthenticated(string userId)
 {
 NotifyAuthenticationStateChanged(GetAuthenticationStateAsync());
 }

 public void MarkUserAsLoggedOut()
 {
 var anonymous = new ClaimsPrincipal(new ClaimsIdentity());
 var authState = Task.FromResult(new AuthenticationState(anonymous));
 NotifyAuthenticationStateChanged(authState);
 }
}

Program.cs에 등록하세요.

builder.Services.AddScoped<AuthenticationStateProvider, CustomAuthStateProvider>();
builder.Services.AddScoped<CustomAuthStateProvider>();

여기서 핵심 통찰력은 NotifyAuthenticationStateChanged입니다. 이를 호출하면 계단식 매개변수가 업데이트되어 구성 요소 트리의 모든 AuthorizeView 및 AuthorizeRouteView가 다시 평가됩니다. 이는 전체 페이지 새로 고침 없이 UI가 로그인/로그아웃 이벤트에 반응하도록 만드는 방법입니다.

일반적인 함정 및 솔루션

여러 프로젝트에서 Blazor 인증을 사용한 후 가장 자주 보게 되는 문제는 다음과 같습니다.

1. Blazor 서버 구성 요소에서 HttpContext 사용`HttpContext`는 초기 HTTP 요청 중에 사용할 수 있지만 SignalR 상호 작용 중에는 `null`이거나 오래되었습니다. 초기 렌더링 후에 실행되는 구성 요소에 `IHttpContextAccessor`를 삽입하지 마세요.

해결책: 초기화 중에 HttpContext에서 필요한 것을 캡처하고 범위가 지정된 서비스에 저장합니다.

public class UserContext
{
 public string? UserId { get; set; }
 public string? AccessToken { get; set; }
}

// In a component that renders during the initial HTTP request:
@inject IHttpContextAccessor HttpContextAccessor
@inject UserContext UserContext

@code {
 protected override void OnInitialized()
 {
 var context = HttpContextAccessor.HttpContext;
 UserContext.UserId = context?.User.FindFirstValue(ClaimTypes.NameIdentifier);
 UserContext.AccessToken = context?.Request.Headers.Authorization
 .ToString().Replace("Bearer ", "");
 }
}

2. 로그인 후 인증 상태가 업데이트되지 않습니다.

로그인 API를 호출하면 성공하지만 UI에는 여전히 “로그인"이 표시됩니다.

해결책: 인증 상태가 변경된 후 AuthenticationStateProvider에서 NotifyAuthenticationStateChanged를 호출해야 합니다. 프레임워크는 토큰이 저장되었거나 쿠키가 설정되었음을 마법처럼 감지하지 않습니다.

3. 구성 요소에서 작동하지 않는 속성 승인

구성 요소에 [Authorize]를 추가했지만 인증되지 않은 사용자를 차단하지는 않습니다.

해결책: App.razor에서 일반 RouteView 대신 AuthorizeRouteView를 사용하고 있는지 확인하세요. 표준 RouteView는 인증 속성을 완전히 무시합니다.

4. 사전 렌더링으로 인해 인증 상태가 중단됩니다.

Blazor WebAssembly에서 서버 측 사전 렌더링 중에는 사용 가능한 인증 토큰이 없습니다. 구성 요소는 인증되지 않은 것으로 렌더링된 다음 WASM이 로드된 후 인증된 상태로 깜박입니다.

해결책: @rendermode InteractiveWebAssembly를 사용하여 인증에 민감한 페이지에 대한 사전 렌더링을 비활성화하거나(사전 렌더링 없이) 로드 상태를 적절하게 처리합니다.

<AuthorizeView>
 <Authorized>
 <p>Welcome back, @context.User.Identity?.Name</p>
 </Authorized>
 <Authorizing>
 <p>Loading...</p>
 </Authorizing>
 <NotAuthorized>
 <a href="/login">Sign in</a>
 </NotAuthorized>
</AuthorizeView>

5. 장기 실행 회로에서의 토큰 만료

Blazor Server 회로는 몇 시간 동안 활성 상태를 유지할 수 있습니다. 토큰 또는 세션이 만료되면 사용자는 UI에서 “인증된” 상태를 유지하지만 API 호출은 실패하기 시작합니다.

해결책: 정기적인 점검을 구현하거나 RevalidatingServerAuthenticationStateProvider를 사용하십시오.

public class RevalidatingAuthStateProvider
 : RevalidatingServerAuthenticationStateProvider
{
 private readonly IServiceScopeFactory _scopeFactory;

 public RevalidatingAuthStateProvider(
 ILoggerFactory loggerFactory,
 IServiceScopeFactory scopeFactory)
 : base(loggerFactory)
 {
 _scopeFactory = scopeFactory;
 }

 protected override TimeSpan RevalidationInterval => TimeSpan.FromMinutes(30);

 protected override async Task<bool> ValidateAuthenticationStateAsync(
 AuthenticationState authenticationState, CancellationToken cancellationToken)
 {
 await using var scope = _scopeFactory.CreateAsyncScope();
 var userManager = scope.ServiceProvider
 .GetRequiredService<UserManager<IdentityUser>>();

 var user = await userManager.GetUserAsync(authenticationState.User);
 return user is not null;
 }
}

이는 30분마다 사용자가 여전히 존재하는지(그리고 보안 스탬프가 변경되지 않았는지) 확인합니다.

결론

Blazor의 인증 및 권한 부여에는 기존 요청-응답 ASP.NET에서 생각의 전환이 필요합니다. AuthenticationStateProvider 추상화는 모든 것이 어떻게 조화를 이루는지 이해하는 열쇠입니다. 일단 이를 내면화하면 나머지는 자연스럽게 따라옵니다.

대부분의 애플리케이션에서는 ASP.NET Identity 및 기본 제공 템플릿으로 시작합니다. 이들은 사용자 관리, 비밀번호 해싱 및 토큰 생성의 무거운 작업을 처리합니다. 요구 사항이 증가함에 따라 정책 및 클레임 기반 인증을 계층화합니다. 사용자가 원할 때 외부 OAuth 공급자를 추가하세요.

호스팅 모델이 중요합니다. Blazor Server는 코드가 서버에 유지되는 보다 전통적인 보안 상태를 제공하는 반면, WebAssembly는 설계상 클라이언트를 신뢰할 수 없는 API 우선 사고를 지향하도록 유도합니다. 둘 다 본질적으로 더 안전하지는 않습니다. 단지 위협 모델이 다를 뿐입니다.

어떤 접근 방식을 선택하든 황금률을 기억하세요. UI에서의 인증은 사용자 경험을 위한 것이고, 서버의 인증은 보안을 위한 것입니다. 항상 두 가지 모두를 적용하세요.

함께 배치된 JS 파일을 사용하여 Blazor에서 격리된 JavaScript

Wed, 18 Jun 2025 00:00:00 +0000

이전에 Blazor 및 JS Interop을 사용해 본 적이 있다면 아마도 다양한 구성 요소에 대한 임의의 기능으로 가득 찬 대규모 app.js 파일을 갖게 되었을 것입니다. 작동하지만 빨리 지저분해집니다. 운 좋게도 훨씬 더 깔끔한 접근 방식이 있습니다. 바로 JavaScript 파일을 함께 배치하는 것입니다.

아이디어

CSS 격리와 마찬가지로 Blazor를 사용하면 구성 요소 옆에 .razor.js 파일을 배치할 수 있습니다. JavaScript 모듈은 구성 요소에 실제로 필요한 경우에만 요청 시 로드됩니다. 전역 스크립트도 없고 오염도 없습니다.

설정하기

텍스트를 클립보드에 복사하는 Clipboard.razor 구성 요소가 있다고 가정해 보겠습니다. 바로 옆에 Clipboard.razor.js라는 파일을 만듭니다.

export function copyToClipboard(text) {
 navigator.clipboard.writeText(text).then(() => {
 console.log("Copied to clipboard!");
 });
}

export 키워드에 주목하세요. 이는 중요합니다. Blazor는 이를 표준 ES 모듈로 로드합니다.

Blazor에 모듈 로드

구성 요소에서 IJSRuntime를 사용하여 모듈을 가져옵니다. 경로는 라이브러리의 경우 ./_content/{ASSEMBLY_NAME}/{COMPONENT_PATH}.razor.js 또는 현재 프로젝트의 상대 경로라는 규칙을 따릅니다.

@inject IJSRuntime JS
@implements IAsyncDisposable

<button @onclick="Copy">Copy to clipboard</button>

@code {
 [Parameter]
 public string Text { get; set; }

 private IJSObjectReference? module;

 protected override async Task OnAfterRenderAsync(bool firstRender)
 {
 if (firstRender)
 {
 module = await JS.InvokeAsync<IJSObjectReference>(
 "import", "./Components/Clipboard.razor.js");
 }
 }

 private async Task Copy()
 {
 if (module is not null)
 {
 await module.InvokeVoidAsync("copyToClipboard", Text);
 }
 }

 public async ValueTask DisposeAsync()
 {
 if (module is not null)
 {
 await module.DisposeAsync();
 }
 }
}

여기서 주목해야 할 몇 가지 사항은 다음과 같습니다.

서버 측 사전 렌더링 중에는 JS Interop을 사용할 수 없기 때문에 OnAfterRenderAsync에 모듈을 로드합니다.
IJSObjectReference을 사용하여 모듈에 대한 참조를 유지합니다.
구성요소가 파괴될 때 모듈을 정리하기 위해 IAsyncDisposable를 구현합니다.

이게 더 나은 이유

이전에는 모든 것을 단일 wwwroot/js/app.js에 덤프했습니다. 작동했지만 기능을 찾는 것이 어려웠고 모든 페이지에 필요하지 않은 JavaScript가 로드되었습니다. 함께 배치된 JS 파일 사용:

각 구성 요소는 자체 JavaScript를 소유합니다.
모듈은 필요할 때만 느리게 로드됩니다.
전역 함수 이름이 충돌하지 않습니다.
유지 관리 및 삭제가 더 쉽습니다. 구성 요소를 삭제하면 해당 구성 요소와 함께 JS도 삭제됩니다.

경로 문제

import에 전달하는 경로는 독립 실행형 Blazor 앱에 있는지 아니면 Razor 클래스 라이브러리에 있는지에 따라 달라집니다. 일반 Blazor 앱의 경우 경로는 wwwroot에 상대적입니다. .razor.js 파일은 빌드 시 복사되므로 프로젝트의 구성 요소 위치에서 참조할 수 있습니다.

모듈을 로드할 때 404가 표시되면 경로를 다시 확인하고 파일이 .js가 아닌 .razor.js로 끝나는지 확인하세요.

게시물이 마음에 드셨기를 바랍니다! @emimontesdeoca로 소셜 미디어를 통해 언제든지 저에게 연락해주세요.

리소스

병치된 JS가 포함된 ASP.NET Core Blazor JavaScript

.NET 9 및 .NET 10의 Blazor 상호 작용: 전체 가이드

Sun, 15 Jun 2025 00:00:00 +0000

지난 몇 년 동안 Blazor를 사용하여 웹 애플리케이션을 구축해 왔다면 프레임워크가 먼 발전했다는 것을 알 것입니다. Blazor Server와 Blazor WebAssembly 사이의 선택으로 시작된 것은 애플리케이션의 각 구성 요소에 대해 올바른 상호 작용 전략을 선택할 수 있는 유연한 통합 렌더링 모델로 발전했습니다.

.NET 8에서는 기본적으로 렌더링 모드와 정적 서버 측 렌더링(SSR)이 도입되었습니다. 이제 .NET 9 및 .NET 10은 개발자 환경을 보다 원활하게 만들고 최종 사용자 환경을 더욱 빠르게 만드는 개선 사항을 통해 이러한 기반 위에 구축되었습니다.

이 게시물에서는 렌더링 모드 작동 방식, 스트리밍 SSR이 테이블에 제공하는 것, 향상된 탐색 및 양식 처리가 게임을 어떻게 변화시키는지, 최신 릴리스의 새로운 기능 등 현재의 Blazor 상호 작용에 대한 전체 그림을 안내하고 싶습니다. 새로운 Blazor 프로젝트를 계획하고 있거나 업그레이드를 고려하고 있다면 이 가이드가 제가 이 모든 것을 파헤치기 시작할 때 갖고 싶었던 가이드입니다.

간략한 되돌아보기: 우리가 여기까지 온 과정

.NET 8 이전에는 프로젝트 수준에서 호스팅 모델을 커밋해야 했습니다. Blazor Server는 SignalR 연결을 통해 서버에서 모든 것이 실행됨을 의미합니다. Blazor WebAssembly는 모든 것이 브라우저에서 실행된다는 것을 의미했습니다. 각각에는 장단점이 있었고 이를 혼합하는 것은 고통스러웠습니다.

.NET 8은 두 모델을 통합하는 단일 프로젝트 템플릿인 Blazor Web App을 도입하여 판도를 바꾸었습니다. 핵심 개념은 렌더링 모드입니다. 구성 요소별로 렌더링 방법과 상호 작용이 발생하는 위치를 결정합니다. 기본값은 정적 SSR이 되었습니다. 즉, 구성 요소가 서버에서 렌더링되고 일반 HTML을 브라우저에 보냅니다. SignalR도 없고 WebAssembly도 없고 빠른 HTML만 있습니다.

.NET 9는 이러한 개념을 다듬고 개발자 환경을 개선하며 성능을 최적화했습니다. .NET 10은 더 나은 재연결 처리, 렌더링 모드 전반의 지속적인 구성 요소 상태, Blazor 스크립트 자체 전달 방식 개선을 통해 이를 더욱 발전시켰습니다.

모든 것을 분석해 봅시다.

.NET 9의 렌더링 모드

최신 Blazor의 핵심은 렌더링 모드의 개념입니다. 알아야 할 네 가지 모드는 다음과 같습니다.

1. 정적 SSR(기본값)

새 Blazor 웹앱을 만들면 구성 요소는 기본적으로 서버에서 정적으로 렌더링됩니다. 서버는 Razor 구성 요소를 처리하고 HTML을 생성하여 브라우저로 보냅니다. 지속적인 연결도 없고 WebAssembly 런타임도 없습니다. 단지 전통적인 요청/응답만 있을 뿐입니다.

이는 콘텐츠가 많은 페이지, 주로 데이터를 표시하는 대시보드 또는 실시간 상호 작용이 필요하지 않은 페이지에 적합합니다.

@page "/products"

<h1>Our Products</h1>

@foreach (var product in products)
{
 <div class="product-card">
 <h3>@product.Name</h3>
 <p>@product.Description</p>
 <span class="price">@product.Price.ToString("C")</span>
 </div>
}

@code {
 private List<Product> products = new();

 protected override async Task OnInitializedAsync()
 {
 products = await ProductService.GetAllAsync();
 }
}

이 구성 요소는 서버에서 렌더링하고 HTML을 생성하며 그게 전부입니다. 진행 중인 연결이 없습니다. 빠른 초기 로드, SEO에 적합, 서버 리소스 사용량 최소화.

2. 대화형 서버버튼 클릭 처리, 사용자 입력 처리, 동적인 UI 업데이트 등 실시간 상호 작용이 필요한 경우 대화형 서버 모드를 선택할 수 있습니다. 그러면 브라우저와 서버 간에 SignalR 연결이 설정되고 해당 연결을 통해 UI 업데이트가 발생합니다.

@page "/counter"
@rendermode InteractiveServer

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
 private int currentCount = 0;

 private void IncrementCount()
 {
 currentCount++;
 }
}

@rendermode InteractiveServer 지시어만 있으면 됩니다. 구성 요소는 처음에 서버에서 렌더링된 다음 후속 상호 작용을 처리하기 위해 SignalR 연결이 설정됩니다. C# 이벤트 핸들러는 서버에서 실행되고 UI 차이점은 브라우저로 전송됩니다.

사용 시기: 상호 작용이 필요할 때 구성 요소는 서버 측 리소스(데이터베이스, API, 파일 시스템)에 액세스해야 하며 WebAssembly가 다운로드될 때까지 기다리지 않고 빠른 초기 로드를 원합니다.

3. 대화형 웹어셈블리

서버 연결을 유지하지 않고 상호 작용을 원하는 경우 Interactive WebAssembly는 .NET WebAssembly 런타임을 사용하여 브라우저에서 직접 구성 요소 논리를 실행합니다.

@page "/search"
@rendermode InteractiveWebAssembly

<h1>Product Search</h1>

<input @bind="searchTerm" @bind:event="oninput" placeholder="Search products..." />

@if (filteredProducts.Any())
{
 <ul>
 @foreach (var product in filteredProducts)
 {
 <li>@product.Name — @product.Price.ToString("C")</li>
 }
 </ul>
}

@code {
 private string searchTerm = string.Empty;
 private List<Product> allProducts = new();
 private IEnumerable<Product> filteredProducts => allProducts
 .Where(p => p.Name.Contains(searchTerm, StringComparison.OrdinalIgnoreCase));

 protected override async Task OnInitializedAsync()
 {
 allProducts = await Http.GetFromJsonAsync<List<Product>>("api/products") ?? new();
 }
}

단점: .NET 런타임 및 어셈블리에 대한 초기 다운로드 비용이 있습니다. 그러나 일단 로드되면 구성 요소는 UI 상호 작용을 위한 서버 왕복 없이 브라우저에서 완전히 실행됩니다.

사용 시기: 대기 시간이 중요한 대화형 구성 요소(예: 서식 있는 텍스트 편집기, 그리기 도구, 실시간 필터링)의 경우, 서버 로드를 줄이려는 경우 또는 프로그레시브 웹 앱(PWA)을 구축할 때.

4. 대화형 자동

이것이 실용적인 중간 지점이자 제가 가장 좋아하는 기능 중 하나입니다. Interactive Auto는 첫 번째 로드를 위해 SignalR을 통한 서버 측 렌더링으로 시작한 다음 백그라운드에서 WebAssembly 런타임을 자동으로 다운로드합니다. 후속 방문에서는 구성 요소가 WebAssembly에서 실행됩니다.

@page "/dashboard"
@rendermode InteractiveAuto

<h1>Dashboard</h1>

<DashboardWidget Title="Sales" Value="@salesTotal" />
<DashboardWidget Title="Users" Value="@activeUsers" />

<button @onclick="RefreshData">Refresh</button>

@code {
 private decimal salesTotal;
 private int activeUsers;

 protected override async Task OnInitializedAsync()
 {
 await RefreshData();
 }

 private async Task RefreshData()
 {
 var data = await DashboardService.GetSummaryAsync();
 salesTotal = data.SalesTotal;
 activeUsers = data.ActiveUsers;
 }
}

이는 빠른 첫 번째 렌더링(WASM 다운로드를 기다리지 않음)과 결국 구성 요소가 클라이언트 측에서 실행된다는 두 가지 장점을 모두 제공합니다. 사용자는 전환을 알아차리지 못합니다.

사용 시기: 빠른 초기 로드와 최종 클라이언트 측 실행을 모두 원하는 경우. 이는 많은 대화형 구성 요소에 대한 훌륭한 기본 선택입니다.

스트리밍 SSR: 양쪽 세계의 최고

스트리밍 SSR은 단순해 보이지만 인지된 성능에 엄청난 차이를 만드는 기능 중 하나입니다. 아이디어는 다음과 같습니다. HTML을 보내기 전에 모든 데이터가 로드될 때까지 기다리는 대신 서버는 페이지 셸을 즉시 보낸 다음 데이터가 사용 가능해지면 콘텐츠 업데이트를 스트림합니다.

@page "/reports"
@attribute [StreamRendering]

<h1>Monthly Reports</h1>

@if (reports is null)
{
 <div class="loading-spinner">
 <p>Loading reports...</p>
 </div>
}
else
{
 <table class="table">
 <thead>
 <tr>
 <th>Month</th>
 <th>Revenue</th>
 <th>Growth</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var report in reports)
 {
 <tr>
 <td>@report.Month</td>
 <td>@report.Revenue.ToString("C")</td>
 <td class="@(report.Growth >= 0 ? "text-success" : "text-danger")">
 @report.Growth.ToString("P1")
 </td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private List<MonthlyReport>? reports;

 protected override async Task OnInitializedAsync()
 {
 // This might take a couple of seconds
 reports = await ReportService.GetMonthlyReportsAsync();
 }
}

[StreamRendering] 속성을 사용하면 다음과 같은 일이 발생합니다.

서버는 로딩 스피너와 함께 HTML을 즉시 보냅니다.
OnInitializedAsync가 실행되어 데이터를 가져옵니다.
데이터가 도착하면 서버는 업데이트된 HTML(테이블)을 브라우저로 스트리밍합니다.
브라우저는 전체 페이지를 다시 로드하지 않고도 DOM을 패치합니다.

사용자는 로딩 표시기와 함께 페이지를 즉시 본 다음 콘텐츠가 채워집니다. JavaScript 프레임워크가 필요하지 않습니다. WebSocket 연결이 없습니다. HTTP 스트리밍을 영리하게 사용하는 것뿐입니다.사용 시기: 렌더링 중에 데이터를 가져오는 정적 SSR 페이지. 제품 목록 페이지, 대시보드, 보고서 등 어디에서나 초기 데이터 로드에 수백 밀리초 이상이 걸릴 수 있습니다.

사용하지 말아야 할 경우: 데이터가 매우 빠르게(100ms 미만) 로드되는 경우 스트리밍 오버헤드는 그만한 가치가 없습니다. 또한 스트리밍 SSR은 지속적인 상호작용을 제공하지 않습니다. 이를 위해서는 여전히 대화형 렌더링 모드가 필요합니다.

향상된 탐색 및 양식 처리

최신 Blazor의 미묘하지만 강력한 개선 사항 중 하나는 향상된 탐색 기능입니다. 기본적으로 Blazor는 내부 링크 클릭 및 양식 제출을 가로채서 fetch를 통해 새 페이지 콘텐츠를 가져오고 전체 브라우저 탐색을 수행하는 대신 DOM을 패치합니다.

이는 정적 SSR 페이지 사이를 탐색하는 것이 SPA처럼 느껴진다는 것을 의미합니다. 전체 페이지 플래시가 없고 스크롤 위치가 유지될 수 있으며 경험이 매우 매끄러워집니다.

작동 방식

Blazor 스크립트(blazor.web.js)가 로드되면 내부 링크에 대한 클릭을 자동으로 차단합니다. 기존 브라우저 탐색 대신 다음을 수행합니다.

대상 URL에 fetch 요청을 보냅니다.
HTML 응답을 받습니다.
새 콘텐츠를 기존 DOM에 병합합니다.
브라우저의 URL과 기록을 업데이트합니다.

이 기능을 활성화하기 위해 아무것도 할 필요가 없습니다. 기본적으로 켜져 있습니다. 하지만 다음과 같이 제어할 수 있습니다.

<!-- Disable enhanced navigation for a specific link -->
<a href="/legacy-page" data-enhance-nav="false">Legacy Page</a>

<!-- Force a full page reload for external-like behavior -->
<a href="/downloads/report.pdf" data-enhance-nav="false">Download Report</a>

향상된 양식 처리

양식도 동일한 처리를 받습니다. Blazor의 양식 처리와 함께 EditForm 또는 표준 <form> 요소를 사용하면 제출이 가로채서 fetch를 통해 처리됩니다.

@page "/contact"

<EditForm Model="contactModel" OnValidSubmit="HandleSubmit" FormName="contact" Enhance>
 <DataAnnotationsValidator />

 <div class="mb-3">
 <label for="name">Name</label>
 <InputText id="name" @bind-Value="contactModel.Name" class="form-control" />
 <ValidationMessage For="() => contactModel.Name" />
 </div>

 <div class="mb-3">
 <label for="email">Email</label>
 <InputText id="email" @bind-Value="contactModel.Email" class="form-control" />
 <ValidationMessage For="() => contactModel.Email" />
 </div>

 <div class="mb-3">
 <label for="message">Message</label>
 <InputTextArea id="message" @bind-Value="contactModel.Message" class="form-control" />
 <ValidationMessage For="() => contactModel.Message" />
 </div>

 <button type="submit" class="btn btn-primary">Send</button>
</EditForm>

@code {
 [SupplyParameterFromForm]
 private ContactModel contactModel { get; set; } = new();

 private async Task HandleSubmit()
 {
 await ContactService.SubmitAsync(contactModel);
 contactModel = new ContactModel();
 }
}

EditForm의 Enhance 속성은 Blazor에게 양식 제출을 가로채도록 지시합니다. 양식이 서버에 게시되고, 서버가 이를 처리하고 페이지를 다시 렌더링하며, 업데이트된 HTML이 다시 스트리밍됩니다. 이 모든 작업은 전체 페이지 탐색 없이 수행됩니다. 대화식으로 느껴지지만 완전히 서버에서 렌더링됩니다.

[SupplyParameterFromForm] 속성에 주목하세요. 이는 Blazor가 정적 SSR 시나리오에서 게시된 양식 데이터를 모델에 바인딩하는 방법입니다. 이는 전통적인 양식 게시물과 Blazor의 구성 요소 모델 사이를 연결하는 다리입니다.

페이지별 및 구성 요소별 상호 작용

새 모델의 가장 강력한 측면 중 하나는 단일 애플리케이션 내에서 렌더링 모드를 혼합할 수 있다는 것입니다. 제품 목록 페이지는 정적 SSR일 수 있고, 장바구니는 Interactive Server일 수 있으며, 제품 구성기는 Interactive WebAssembly일 수 있습니다. 이 모든 것이 동일한 앱에 있습니다.

구성 요소 수준에서 렌더링 모드 설정

@rendermode 지시문을 사용하여 구성 요소에서 직접 렌더링 모드를 설정할 수 있습니다.

@* This component is interactive via Server *@
@rendermode InteractiveServer

<h3>Live Chat</h3>
<!-- chat UI here -->

또는 상위 구성 요소를 사용할 때 설정할 수 있습니다.

@page "/product/{Id:int}"

<h1>@product?.Name</h1>
<p>@product?.Description</p>

<!-- This child component gets its own interactive render mode -->
<ProductConfigurator Product="product" @rendermode="InteractiveWebAssembly" />

<!-- This stays static -->
<ProductReviews ProductId="Id" />

@code {
 [Parameter] public int Id { get; set; }
 private Product? product;

 protected override async Task OnInitializedAsync()
 {
 product = await ProductService.GetByIdAsync(Id);
 }
}

이 예에서 페이지 자체는 정적 SSR입니다. ProductConfigurator 구성 요소는 풍부한 클라이언트 측 상호 작용을 위해 WebAssembly에서 실행됩니다. ProductReviews 구성 요소는 단지 데이터만 표시하기 때문에 정적으로 유지됩니다.

렌더링 모드를 전역적으로 설정하기

기본적으로 모든 페이지를 대화형으로 만들려면 App.razor의 루트 수준에서 렌더링 모드를 설정할 수 있습니다.

<Routes @rendermode="InteractiveServer" />
```이는 서버 렌더링을 통해 모든 페이지를 대화형으로 만듭니다. 필요한 경우 개별 구성 요소가 이를 재정의할 수 있습니다.

### 기억해야 할 중요한 규칙

렌더링 모드를 혼합할 때 염두에 두어야 할 몇 가지 제약 조건이 있습니다.

- **하위 구성 요소는 상위 구성 요소보다 "더 대화형"인 렌더링 모드를 가질 수 없습니다.** 상위 구성 요소가 정적이면 하위 구성 요소는 정적이거나 대화형일 수 있습니다. 그러나 부모가 Interactive Server인 경우 자식은 Interactive WebAssembly가 될 수 없습니다(Server 또는 Auto여야 함).
- **대화형 구성 요소는 정적 부모의 범위 서비스를 직접 사용할 수 없습니다.** 구성 요소가 WebAssembly에서 실행되는 경우 서버 측 `DbContext` 인스턴스에 직접 액세스할 수 없습니다. API 계층이 필요합니다.
- **상태는 렌더링 모드 간에 자동으로 전송되지 않습니다.** 구성 요소가 서버에서 사전 렌더링된 다음 WebAssembly로 전환하는 경우 상태 지속성을 명시적으로 처리해야 합니다. 이에 대한 자세한 내용은 .NET 10 섹션에서 확인하세요.

## .NET 10의 새로운 기능

.NET 10은 안정성과 개발자 경험에 초점을 맞춰 점진적인 개선 접근 방식을 이어갑니다. Blazor 상호 작용의 주요 내용은 다음과 같습니다.

### 향상된 재연결 경험

프로덕션에서 대화형 서버 모드를 사용한 경우 아마도 재연결 오버레이를 접했을 것입니다. 즉, SignalR 연결이 끊어지고 사용자에게 "재연결 중..." 메시지가 표시되는 순간입니다. .NET 10에서는 이 환경이 훨씬 더 좋아졌습니다.

이제 재연결 논리가 재시도에 대해 더 똑똑해졌습니다. 고정된 재시도 간격 대신 상황에 맞는 백오프 전략을 사용합니다. 다시 연결하는 동안의 UI도 더욱 세련되었으며 경험을 사용자 정의할 수 있는 더 나은 후크가 있습니다.

```razor
<!-- In your App.razor or layout -->
<div id="components-reconnect-modal">
 <div class="reconnect-visible">
 <p>Connection lost. Attempting to reconnect...</p>
 <div class="spinner"></div>
 </div>
 <div class="reconnect-failed">
 <p>Could not reconnect to the server.</p>
 <button onclick="location.reload()">Reload</button>
 </div>
 <div class="reconnect-rejected">
 <p>Your session has expired.</p>
 <a href="/">Return to Home</a>
 </div>
</div>

이제 프레임워크는 일시적인 오류가 발생할 경우 더욱 적극적으로 재연결을 시도하며 회로 상태를 보다 안정적으로 복원할 수 있습니다. 이는 사용자의 “페이지를 다시 로드하세요"라는 순간이 줄어든다는 것을 의미합니다.

렌더링 모드 전반에 걸쳐 지속적인 구성 요소 상태

이것은 큰 것입니다. .NET 9에서는 구성 요소가 서버에서 사전 렌더링된 다음 WebAssembly로 전환되거나 렌더링 모드 간에 전환되면 구성 요소 상태가 손실됩니다. 구성요소가 효과적으로 다시 초기화되므로 데이터 가져오기가 중복되고 UI가 깜박일 수 있습니다.

.NET 10은 렌더링 모드 전환 전반에 걸쳐 보다 원활하게 작동하도록 PersistentComponentState 서비스를 개선합니다.

@page "/weather"
@rendermode InteractiveWebAssembly
@inject PersistentComponentState ApplicationState

<h1>Weather Forecast</h1>

@if (forecasts is null)
{
 <p>Loading...</p>
}
else
{
 @foreach (var forecast in forecasts)
 {
 <div class="forecast-card">
 <h4>@forecast.Date.ToShortDateString()</h4>
 <p>@forecast.Summary — @forecast.TemperatureC°C</p>
 </div>
 }
}

@code {
 private List<WeatherForecast>? forecasts;
 private PersistingComponentStateSubscription persistingSubscription;

 protected override async Task OnInitializedAsync()
 {
 persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);

 if (!ApplicationState.TryTakeFromJson<List<WeatherForecast>>(
 "weather-forecasts", out var restored))
 {
 // Data wasn't persisted from prerendering — fetch it
 forecasts = await Http.GetFromJsonAsync<List<WeatherForecast>>("api/weather");
 }
 else
 {
 forecasts = restored;
 }
 }

 private Task PersistData()
 {
 ApplicationState.PersistAsJson("weather-forecasts", forecasts);
 return Task.CompletedTask;
 }

 public void Dispose()
 {
 persistingSubscription.Dispose();
 }
}

.NET 10의 개선 사항을 통해 이 패턴은 더욱 안정적으로 작동합니다. 사전 렌더링 중에 직렬화된 상태는 구성 요소가 대화형 모드에서 초기화될 때 적절하게 사용할 수 있으므로 이중 데이터 가져오기 및 사용자에게 표시될 수 있는 짧은 깜박임이 방지됩니다.

정적 웹 자산으로서의 Blazor 스크립트

이전 버전에서는 Blazor JavaScript 파일(blazor.web.js)이 프레임워크의 내부 엔드포인트에서 제공되었습니다. .NET 10에서는 정적 웹 자산으로 제공됩니다. 이는 작은 변화처럼 들릴 수도 있지만 실질적인 이점이 있습니다.- 더 나은 캐싱: 정적 웹 자산은 적절한 캐시 헤더와 지문 URL을 가져오므로 브라우저는 이를 더욱 효과적으로 캐시합니다.

CDN 친화적: 일반 정적 파일이므로 CDN은 이를 엣지 위치에서 캐시하고 제공할 수 있습니다.
압축: 정적 웹 자산 압축이 자동으로 적용되어 전송 중인 스크립트 크기가 줄어듭니다.

참조 방법을 변경할 필요가 없습니다. 프레임워크가 업데이트된 경로를 자동으로 처리합니다.

모범 사례: 올바른 렌더링 모드 선택

여러 프로젝트에 걸쳐 이러한 모든 모드를 사용한 후의 결정 프레임워크는 다음과 같습니다.

정적 SSR로 시작

정적 SSR을 기본값으로 설정하세요. 대부분의 애플리케이션에서 대부분의 페이지는 주로 데이터 표시에 관한 것입니다. 제품 페이지, 블로그 게시물, 사용자 프로필, 설정 페이지 등에는 실시간 상호 작용이 필요하지 않습니다. 정적 SSR은 최고의 성능, 가장 낮은 리소스 사용량 및 가장 단순한 정신 모델을 제공합니다.

필요한 경우에만 상호작용 기능 추가

사용자 상호 작용에 실시간으로 응답해야 하는 특정 구성 요소를 식별합니다. ‘좋아요’ 버튼, 채팅 위젯, 드래그 앤 드롭 인터페이스 등에는 상호작용이 필요합니다. 그러나 그들을 둘러싼 페이지는 아마도 그렇지 않을 것입니다.

대화형 자동 모드를 대화형 모드로 사용하세요

대화형 기능이 필요한 경우 Interactive Auto가 기본적으로 최선의 선택인 경우가 많습니다. 최종 클라이언트 측 실행(WebAssembly)을 통해 빠른 초기 로드(서버 렌더링)를 제공합니다. 사용자는 두 가지 장점을 최대한 활용하고 코드를 한 번만 작성하면 됩니다.

특정 사례를 위한 대화형 서버 예약

다음과 같은 경우 대화형 서버를 사용하세요.

구성 요소는 서버 리소스(데이터베이스, 파일 시스템, 내부 API)에 직접 액세스해야 합니다.
WebAssembly 다운로드 크기가 문제로 Auto를 사용할 수 없습니다.
보안상의 이유로(예: 민감한 데이터 처리) 구성 요소가 항상 서버에서 실행되어야 합니다.

스트리밍 SSR을 아낌없이 사용하세요

정적 SSR 페이지가 데이터를 가져오는 경우 [StreamRendering]를 추가하세요. 비용은 최소화되며 인지된 성능 향상은 상당합니다. 사용자는 빈 페이지를 쳐다보는 것이 아니라 점진적으로 나타나는 콘텐츠를 봅니다.

상태 전환을 신중하게 처리

Interactive Auto를 사용하거나 WebAssembly와 사전 렌더링을 혼합하는 경우 중복된 데이터 가져오기를 방지하려면 항상 PersistentComponentState를 사용하세요. 사용자는 깜박이는 콘텐츠가 없다는 점에 감사할 것입니다.

구성요소 트리를 염두에 두세요

렌더링 모드 계층 구조 규칙을 기억하세요. 대화형 경계가 이해되도록 구성 요소 트리를 계획합니다. 일반적인 패턴은 필요한 곳에 대화형 “섬"이 포함된 정적 레이아웃을 갖는 것입니다.

@* Layout: Static SSR *@
<header>
 <NavMenu />
 <UserMenu @rendermode="InteractiveServer" /> @* Needs real-time auth state *@
</header>

<main>
 @Body
</main>

<footer>
 <ChatWidget @rendermode="InteractiveAuto" /> @* Rich interactivity *@
</footer>

결론

.NET 9 및 .NET 10의 Blazor 상호 작용 모델은 웹 애플리케이션 구축에 대한 성숙하고 신중한 접근 방식을 나타냅니다. 구성 요소별로 렌더링 모드를 선택할 수 있는 기능, 원활하게 향상된 탐색, 스트리밍 SSR, 재연결 및 상태 관리의 지속적인 개선으로 인해 광범위한 애플리케이션에 대한 강력한 선택이 됩니다.핵심 통찰력은 상호작용은 이분법적인 선택이 아니라 스펙트럼입니다라는 것입니다. 대부분의 애플리케이션은 정적일 수 있습니다. 일부 부품에는 서버 기반 상호 작용이 필요합니다. 일부는 브라우저에서 실행하면 이점을 얻을 수 있습니다. 이제 Blazor를 사용하면 프레임워크와 싸우지 않고도 가장 세밀한 수준(개별 구성 요소)에서 선택할 수 있습니다.

새 프로젝트를 시작하는 경우 제 조언은 간단합니다. Blazor 웹 앱을 만들고, 정적 SSR로 시작하고, 데이터가 많은 페이지에 [StreamRendering]를 추가하고, 필요할 때만 개별 구성 요소를 대화형 모드로 승격하세요. 빠르고 효율적이며 확장성이 뛰어난 애플리케이션을 얻게 될 것입니다.

즐거운 코딩 되시기 바랍니다. 언제나 그렇듯이 궁금한 점이 있으면 언제든지 문의해 주세요!

.NET의 최소 API: 경량 HTTP API 구축

Thu, 10 Apr 2025 00:00:00 +0000

한동안 ASP.NET Core를 사용하여 API를 구축했다면 아마도 컨트롤러 기반 접근 방식에 매우 익숙할 것입니다. 즉, 컨트롤러 클래스를 만들고 특성으로 장식하고 생성자를 통해 서비스를 삽입하고 경로를 연결합니다. 그것은 작동하고 잘 작동합니다. 그러나 때때로 “이 요청을 받고, 무언가를 하고, 응답을 반환"하는 것에 대한 많은 의식을 작성하고 있는 것처럼 느껴질 때가 있습니다.

이것이 바로 Minimal API가 해결하려고 하는 문제입니다. .NET 6에 도입된 Minimal API를 사용하면 매우 적은 상용구를 사용하여 HTTP 엔드포인트를 정의할 수 있습니다. 컨트롤러도 없고, 속성도 없고, 시작 클래스 저글링도 없습니다. 깔끔하고 기능적인 스타일로 경로에서 핸들러까지 직접 매핑만 하면 됩니다.

이 게시물에서는 첫 번째 엔드포인트부터 대규모 애플리케이션 구성, 인증 처리, 유효성 검사, OpenAPI 문서 및 성능 고려 사항에 이르기까지 최소 API에 대해 알아야 할 모든 것을 안내하고 싶습니다. 시작해 봅시다.

왜 최소 API인가?

시작하기 전에 기존 컨트롤러 기반 접근 방식 대신 최소 API를 선택하는 이유에 대해 이야기해 보겠습니다.

컨트롤러는 구조화되고 독선적인 프레임워크가 필요할 때 유용합니다. 이는 모델 바인딩, 필터, 콘텐츠 협상 및 기본적으로 우려 사항을 명확하게 분리하는 기능을 제공합니다. 수십 명의 개발자가 있는 대규모 엔터프라이즈 애플리케이션의 경우 컨트롤러가 적용하는 일관성은 실질적인 이점이 될 수 있습니다.

반면에 최소 API는 원할 때 빛을 발합니다.

상용구 감소 — 컨트롤러 클래스 없음, [ApiController] 속성 없음, 별도의 시작 구성 없음.
빠른 시작 — 부팅 시 반사 기반 작업이 줄어듭니다.
더 단순한 정신 모델 — 경로가 핸들러에 직접 매핑됩니다. 그게 다야.
마이크로서비스 친화적 — API에 5~10개의 엔드포인트가 있는 경우 전체 컨트롤러 설정이 과잉처럼 느껴질 수 있습니다.

좋은 소식은 이것이 둘 중 하나의 결정이 아니라는 것입니다. 동일한 프로젝트에서 컨트롤러와 최소 API를 혼합할 수 있습니다. 그러나 일단 최소한의 접근 방식에 익숙해지면 예상보다 더 자주 접근하게 될 수도 있습니다.

시작하기

Minimal API를 처음부터 만들어 보겠습니다. .NET SDK가 설치되어 있는 경우 다음과 같이 간단합니다.

dotnet new web -n MyMinimalApi
cd MyMinimalApi

그러면 다음과 같은 Program.cs가 제공됩니다.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

그게 다야. 그것은 작동하는 API입니다. Startup.cs 없음, 컨트롤러 클래스 없음, 라우팅 구성 없음. dotnet run를 실행하고 http://localhost:5000를 누르면 “Hello World!“가 표시됩니다. 뒤쪽에. 단순함이 핵심입니다.

클래식 todo API를 사용하여 좀 더 유용하게 만들어 보겠습니다.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var todos = new List<Todo>();

app.MapGet("/todos", () => todos);

app.MapGet("/todos/{id:int}", (int id) =>
 todos.FirstOrDefault(t => t.Id == id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound());

app.MapPost("/todos", (Todo todo) =>
{
 todos.Add(todo);
 return Results.Created($"/todos/{todo.Id}", todo);
});

app.MapDelete("/todos/{id:int}", (int id) =>
{
 var todo = todos.FirstOrDefault(t => t.Id == id);
 if (todo is null) return Results.NotFound();
 todos.Remove(todo);
 return Results.NoContent();
});

app.Run();

record Todo(int Id, string Title, bool IsComplete);

우리는 30줄 미만의 전체 CRUD를 가지고 있습니다. 이것이 바로 최소한의 접근 방식의 힘입니다.

경로 처리기

경로 핸들러는 요청이 경로와 일치할 때 실행되는 기능입니다. 이를 정의하는 데는 여러 가지 옵션이 있습니다.

람다 표현식

가장 일반적인 접근 방식과 대부분의 예에서 볼 수 있는 내용은 다음과 같습니다.

app.MapGet("/hello", () => "Hello!");
app.MapGet("/hello/{name}", (string name) => $"Hello, {name}!");

메소드 그룹

더 복잡한 논리의 경우 명명된 메서드를 지정할 수 있습니다.

app.MapGet("/products", GetProducts);
app.MapPost("/products", CreateProduct);

static IResult GetProducts(AppDbContext db)
 => Results.Ok(db.Products.ToList());

static IResult CreateProduct(Product product, AppDbContext db)
{
 db.Products.Add(product);
 db.SaveChanges();
 return Results.Created($"/products/{product.Id}", product);
}
```이것은 한 줄 이상의 내용에 대해 내가 선호하는 접근 방식입니다. 경로 매핑 섹션을 깔끔하고 읽기 쉽게 유지합니다. 구현 세부 사항을 살펴보지 않고도 어떤 엔드포인트가 있는지 한눈에 확인할 수 있습니다.

### 로컬 함수

로컬 함수를 사용할 수도 있는데, 이는 핸들러를 경로 정의에 가깝게 유지하려는 경우에 유용합니다.

```csharp
app.MapGet("/health", CheckHealth);

IResult CheckHealth()
{
 // Some health check logic
 return Results.Ok(new { Status = "Healthy", Timestamp = DateTime.UtcNow });
}

매개변수 바인딩

Minimal API에 대해 제가 정말 높이 평가하는 점 중 하나는 매개변수 바인딩이 얼마나 직관적인지입니다. 프레임워크는 컨텍스트와 유형을 기반으로 어디에서 값을 가져올지 파악합니다.

경로 매개변수

app.MapGet("/users/{id:int}", (int id) => $"User {id}");
app.MapGet("/files/{*path}", (string path) => $"File: {path}"); // catch-all

쿼리 문자열 매개변수

app.MapGet("/search", (string? query, int page = 1, int pageSize = 20) =>
 Results.Ok(new { query, page, pageSize }));

Null 허용 유형은 선택적 매개변수가 됩니다. 기본값은 예상한 대로 정확하게 작동합니다.

요청 본문

app.MapPost("/orders", (Order order) =>
{
 // 'order' is automatically deserialized from the JSON body
 return Results.Created($"/orders/{order.Id}", order);
});

헤더 및 서비스 바인딩

app.MapGet("/protected", (
 [FromHeader(Name = "X-Api-Key")] string apiKey,
 [FromServices] ILogger<Program> logger) =>
{
 logger.LogInformation("Request with API key: {Key}", apiKey[..4] + "****");
 return Results.Ok("Authorized");
});

HttpContext 및 HttpRequest

낮은 수준의 액세스가 필요한 경우:

app.MapGet("/info", (HttpContext context) =>
{
 var userAgent = context.Request.Headers.UserAgent.ToString();
 var ip = context.Connection.RemoteIpAddress?.ToString();
 return Results.Ok(new { userAgent, ip });
});

BindAsync를 사용한 사용자 정의 바인딩

복합 유형의 경우 정적 BindAsync 메소드를 구현할 수 있습니다.

public record PaginationParams(int Page, int PageSize)
{
 public static ValueTask<PaginationParams?> BindAsync(HttpContext context)
 {
 int.TryParse(context.Request.Query["page"], out var page);
 int.TryParse(context.Request.Query["pageSize"], out var pageSize);

 var result = new PaginationParams(
 Page: page > 0 ? page : 1,
 PageSize: pageSize > 0 ? Math.Min(pageSize, 100) : 20
 );

 return ValueTask.FromResult<PaginationParams?>(result);
 }
}

app.MapGet("/items", (PaginationParams pagination, AppDbContext db) =>
{
 var items = db.Items
 .Skip((pagination.Page - 1) * pagination.PageSize)
 .Take(pagination.PageSize)
 .ToList();

 return Results.Ok(items);
});

이것은 엄청나게 강력합니다. 바인딩 논리를 한 번 정의하면 모든 엔드포인트에서 재사용됩니다.

검증

Minimal API가 컨트롤러에 비해 기본적으로 많은 것을 제공하지 못하는 영역 중 하나는 모델 검증입니다. 자동 [Required] 또는 [StringLength] 시행은 없습니다. 하지만 이를 처리하기 위한 깔끔한 패턴이 있습니다.

수동 검증

가장 간단한 접근 방식은 처리기에서 유효성을 검사하는 것입니다.

app.MapPost("/users", (CreateUserRequest request) =>
{
 if (string.IsNullOrWhiteSpace(request.Email))
 return Results.BadRequest(new { Error = "Email is required" });

 if (request.Name?.Length > 100)
 return Results.BadRequest(new { Error = "Name must be 100 characters or less" });

 // Create user...
 return Results.Created($"/users/{request.Email}", request);
});

유효성 검사 라이브러리 사용

중요하지 않은 경우에는 FluentValidation 또는 유사한 라이브러리에 접근하는 것이 좋습니다.

public class CreateUserValidator : AbstractValidator<CreateUserRequest>
{
 public CreateUserValidator()
 {
 RuleFor(x => x.Email).NotEmpty().EmailAddress();
 RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
 RuleFor(x => x.Age).InclusiveBetween(0, 150);
 }
}

엔드포인트 필터를 통해 이를 엔드포인트에 연결할 수 있으며 다음 섹션으로 넘어갑니다.

엔드포인트 필터

엔드포인트 필터는 Minimal API의 가장 뛰어난 기능 중 하나입니다. 이를 미들웨어로 생각하지만 전체 파이프라인 대신 특정 엔드포인트로 범위가 지정됩니다. 이는 .NET 7에서 도입되었으며 교차 편집 문제에 환상적입니다.

기본 필터

app.MapPost("/todos", (Todo todo) =>
{
 // Handle the request
 return Results.Created($"/todos/{todo.Id}", todo);
})
.AddEndpointFilter(async (context, next) =>
{
 var todo = context.GetArgument<Todo>(0);

 if (string.IsNullOrEmpty(todo.Title))
 {
 return Results.BadRequest(new { Error = "Title is required" });
 }

 return await next(context);
});

FluentValidation을 사용한 유효성 검사 필터

재사용 가능한 검증 필터가 정말 강력해지는 부분은 다음과 같습니다.

public class ValidationFilter<T> : IEndpointFilter where T : class
{
 private readonly IValidator<T> _validator;

 public ValidationFilter(IValidator<T> validator)
 {
 _validator = validator;
 }

 public async ValueTask<object?> InvokeAsync(
 EndpointFilterInvocationContext context,
 EndpointFilterDelegate next)
 {
 var model = context.Arguments
 .OfType<T>()
 .FirstOrDefault();

 if (model is null)
 return Results.BadRequest(new { Error = "Request body is required" });

 var result = await _validator.ValidateAsync(model);

 if (!result.IsValid)
 {
 var errors = result.Errors
 .GroupBy(e => e.PropertyName)
 .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray());

 return Results.ValidationProblem(errors);
 }

 return await next(context);
 }
}

// Usage
app.MapPost("/users", (CreateUserRequest request) =>
{
 // Only reached if validation passes
 return Results.Created($"/users/{request.Email}", request);
})
.AddEndpointFilter<ValidationFilter<CreateUserRequest>>();

로깅 필터

app.MapGet("/products", (AppDbContext db) => db.Products.ToList())
 .AddEndpointFilter(async (context, next) =>
 {
 var logger = context.HttpContext
 .RequestServices.GetRequiredService<ILogger<Program>>();

 var sw = Stopwatch.StartNew();
 var result = await next(context);
 sw.Stop();

 logger.LogInformation("Endpoint executed in {Elapsed}ms", sw.ElapsedMilliseconds);

 return result;
 });

여러 필터를 연결할 수 있으며 미들웨어처럼 추가된 순서대로 실행됩니다.

OpenAPI / Swagger 통합

좋은 API 문서화는 더 이상 선택 사항이 아닙니다. 다행히도 Minimal API는 Microsoft.AspNetCore.OpenApi 패키지를 통해 OpenAPI를 최고 수준으로 지원합니다.

기본 설정

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/todos", () => new List<Todo>())
 .WithName("GetTodos")
 .WithDescription("Retrieves all todo items")
 .WithTags("Todos");

app.Run();

풍부한 엔드포인트 메타데이터

엔드포인트에 대한 자세한 정보를 제공할 수 있습니다.

app.MapPost("/todos", (Todo todo) =>
{
 return Results.Created($"/todos/{todo.Id}", todo);
})
.WithName("CreateTodo")
.WithDescription("Creates a new todo item")
.WithTags("Todos")
.Accepts<Todo>("application/json")
.Produces<Todo>(StatusCodes.Status201Created)
.Produces(StatusCodes.Status400BadRequest)
.ProducesValidationProblem();

사용자 정의를 위해 WithOpenApi 사용

생성된 OpenAPI 문서를 세부적으로 제어하려면 다음을 수행하세요.

app.MapGet("/todos/{id:int}", (int id) => Results.Ok(new Todo(id, "Sample", false)))
 .WithOpenApi(operation =>
 {
 operation.Summary = "Get a specific todo";
 operation.Description = "Retrieves a single todo item by its unique identifier.";
 operation.Parameters[0].Description = "The unique identifier of the todo item";
 return operation;
 });

이를 통해 컨트롤러에서 Swashbuckle XML 주석을 사용하여 얻을 수 있는 것과 동일한 수준의 문서 제어 기능을 제공하지만 보다 명시적인 코드 우선 방식을 사용합니다.

인증 및 승인

최소 API 엔드포인트 보안은 나머지 ASP.NET Core와 동일한 패턴을 따르므로 다르게 적용하면 됩니다.

기본 설정```csharp

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.Authority = “https://your-identity-provider.com”; options.Audience = “your-api”; });

builder.Services.AddAuthorizationBuilder() .AddPolicy(“AdminOnly”, policy => policy.RequireRole(“Admin”)) .AddPolicy(“PremiumUser”, policy => policy.RequireClaim(“subscription”, “premium”));

var app = builder.Build();

app.UseAuthentication(); app.UseAuthorization();


### 엔드포인트에 권한 부여 적용

```csharp
// Require any authenticated user
app.MapGet("/profile", (ClaimsPrincipal user) =>
{
 return Results.Ok(new
 {
 Name = user.FindFirstValue(ClaimTypes.Name),
 Email = user.FindFirstValue(ClaimTypes.Email)
 });
}).RequireAuthorization();

// Require a specific policy
app.MapDelete("/admin/users/{id}", (int id) =>
{
 // Delete user logic
 return Results.NoContent();
}).RequireAuthorization("AdminOnly");

// Allow anonymous access
app.MapGet("/public/health", () => Results.Ok(new { Status = "Healthy" }))
 .AllowAnonymous();

핸들러 매개변수에 ClaimsPrincipal를 직접 주입하는 방법에 주목하세요. 나머지는 프레임워크가 처리합니다. 이는 Minimal API를 정말 우아하게 느끼게 만드는 작은 요소 중 하나입니다.

대규모 API 정리

최소 API를 사용하는 방의 코끼리는 조직입니다. Program.cs에 엔드포인트가 50개 있으면 엉망이 됩니다. 다음은 작업을 관리하기 쉽게 유지하기 위해 사용하는 패턴입니다.

경로 그룹

경로 그룹(.NET 7에 도입됨)을 사용하면 관련 엔드포인트 간에 구성을 공유할 수 있습니다.

var todos = app.MapGroup("/todos")
 .WithTags("Todos")
 .RequireAuthorization();

todos.MapGet("/", (AppDbContext db) => db.Todos.ToListAsync());
todos.MapGet("/{id:int}", (int id, AppDbContext db) => db.Todos.FindAsync(id));
todos.MapPost("/", (Todo todo, AppDbContext db) =>
{
 db.Todos.Add(todo);
 db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
});

그룹의 모든 엔드포인트는 /todos 접두사, Todos 태그 및 권한 부여 요구 사항을 공유합니다. 깨끗한.

확장 방법

이것은 실제로 확장되는 패턴입니다. 각 엔드포인트 그룹을 자체 정적 클래스로 이동합니다.

// Endpoints/TodoEndpoints.cs
public static class TodoEndpoints
{
 public static RouteGroupBuilder MapTodoEndpoints(this WebApplication app)
 {
 var group = app.MapGroup("/todos").WithTags("Todos");

 group.MapGet("/", GetAll);
 group.MapGet("/{id:int}", GetById);
 group.MapPost("/", Create);
 group.MapPut("/{id:int}", Update);
 group.MapDelete("/{id:int}", Delete);

 return group;
 }

 private static async Task<IResult> GetAll(AppDbContext db)
 => Results.Ok(await db.Todos.ToListAsync());

 private static async Task<IResult> GetById(int id, AppDbContext db)
 => await db.Todos.FindAsync(id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound();

 private static async Task<IResult> Create(Todo todo, AppDbContext db)
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 }

 private static async Task<IResult> Update(int id, Todo updated, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 todo.Title = updated.Title;
 todo.IsComplete = updated.IsComplete;
 await db.SaveChangesAsync();

 return Results.Ok(todo);
 }

 private static async Task<IResult> Delete(int id, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 db.Todos.Remove(todo);
 await db.SaveChangesAsync();

 return Results.NoContent();
 }
}

// Program.cs — stays clean
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapTodoEndpoints();
app.MapUserEndpoints();
app.MapOrderEndpoints();

app.Run();

Program.cs는 API의 목차가 됩니다. 각 끝점 그룹은 자체 파일에 있습니다. 이것이 제가 프로덕션 애플리케이션에 권장하는 접근 방식입니다.

카터 도서관

더 많은 구조를 원할 경우 Carter 라이브러리는 모듈 기반 접근 방식을 제공합니다.

public class TodoModule : ICarterModule
{
 public void AddRoutes(IEndpointRouteBuilder app)
 {
 app.MapGet("/todos", async (AppDbContext db) =>
 await db.Todos.ToListAsync());

 app.MapPost("/todos", async (Todo todo, AppDbContext db) =>
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 });
 }
}

Carter는 모든 모듈을 자동으로 검색하고 등록합니다. 원시 최소 API 접근 방식과 전체 컨트롤러 사이의 좋은 중간 지점입니다.

TypedResults 및 응답 유형

.NET 7부터 형식이 안전한 응답을 위해 Results 대신 TypedResults를 사용할 수 있습니다. 이는 작은 변화처럼 보일 수 있지만 OpenAPI 문서화 및 테스트 가능성에 실질적인 이점이 있습니다.

app.MapGet("/todos/{id:int}", async Task<Results<Ok<Todo>, NotFound>> (int id, AppDbContext db) =>
{
 var todo = await db.Todos.FindAsync(id);
 return todo is not null
 ? TypedResults.Ok(todo)
 : TypedResults.NotFound();
});

반환 유형 Results<Ok<Todo>, NotFound>는 이 끝점이 생성할 수 있는 응답 유형을 정확히 프레임워크(및 OpenAPI 문서)에 명시적으로 알려줍니다. 더 이상 추측이나 기본 사례에 대한 수동 Produces<>() 호출이 없습니다.

여러 가능한 결과의 경우:

app.MapPost("/todos",
 async Task<Results<Created<Todo>, ValidationProblem, Conflict>>
 (Todo todo, AppDbContext db) =>
{
 if (string.IsNullOrEmpty(todo.Title))
 return TypedResults.ValidationProblem(
 new Dictionary<string, string[]>
 {
 { "Title", new[] { "Title is required" } }
 });

 if (await db.Todos.AnyAsync(t => t.Title == todo.Title))
 return TypedResults.Conflict();

 db.Todos.Add(todo);
 await db.SaveChangesAsync();

 return TypedResults.Created($"/todos/{todo.Id}", todo);
});

나는 모든 새 프로젝트에서 TypedResults를 사용하기 시작했습니다. 컴파일러는 선언된 반환 유형과 실제로 반환하는 것 사이의 불일치를 포착하여 전체 런타임 놀라움을 제거합니다.

성능 고려 사항

Minimal API의 판매 포인트 중 하나는 성능이며, 왜 더 빠른지 이해할 가치가 있습니다.

시작 오버헤드 감소. 컨트롤러는 엔드포인트를 검색하고, 모델을 바인딩하고, 필터를 적용하기 위해 리플렉션에 크게 의존합니다. 최소 API는 소스 생성기(.NET 7부터 시작)를 사용하여 컴파일 타임에 바인딩 코드를 생성합니다. 이는 시작 시 작업량이 적고 요청당 메모리 할당량이 적다는 것을 의미합니다.

MVC 파이프라인 없음. 컨트롤러 기반 API는 전체 MVC 파이프라인(작업 선택, 모델 바인딩, 작업 필터, 결과 실행)을 거칩니다. 최소 API는 이 모든 것을 건너뛰고 라우팅에서 핸들러로 바로 이동합니다.

RequestDelegate 컴파일. 프레임워크는 람다 표현식을 최적화된 RequestDelegate 인스턴스로 컴파일합니다. 결과 코드는 HttpContext로 직접 작업하는 경우 직접 작성하는 코드와 매우 유사합니다.

성능을 극대화하기 위한 몇 가지 실용적인 팁은 다음과 같습니다.

// Use AsNoTracking for read-only queries
app.MapGet("/products", async (AppDbContext db) =>
 await db.Products.AsNoTracking().ToListAsync());

// Return results directly — avoid unnecessary allocations
app.MapGet("/count", async (AppDbContext db) =>
 await db.Products.CountAsync());

// Use cancellation tokens for long-running operations
app.MapGet("/report", async (AppDbContext db, CancellationToken ct) =>
 await db.Orders
 .AsNoTracking()
 .GroupBy(o => o.Status)
 .Select(g => new { Status = g.Key, Count = g.Count() })
 .ToListAsync(ct));
```컨트롤러와 최소 API 간의 성능 격차가 .NET 릴리스마다 계속해서 줄어들고 있다는 점도 언급할 가치가 있습니다. 대부분의 애플리케이션의 경우 병목 현상이 아니라 데이터베이스 쿼리와 외부 서비스 호출의 차이가 있을 것입니다. 벤치마크가 아닌 개발자 경험과 프로젝트 요구 사항을 기준으로 선택하세요.

## 결론

최소 API는 .NET 6에 도입된 이후 많은 발전을 이루었습니다. "hello world" 데모 기능으로 시작된 것이 프로덕션 API를 위한 합법적인 선택으로 발전했습니다. 엔드포인트 필터, 경로 그룹, 입력된 결과 및 견고한 OpenAPI 지원을 통해 잘 구조화되고 유지 관리 가능한 서비스를 구축하는 데 필요한 모든 것을 갖추고 있습니다.

내 추천? 새로운 API 프로젝트, 특히 마이크로서비스나 집중적인 내부 API를 시작하는 경우 Minimal API를 진지하게 시도해 보세요. 조직에 확장 메서드 패턴을 사용하고, 교차 문제에 대해 끝점 필터를 사용하고, 유형 안전성을 위해 `TypedResults`를 활용합니다.

기존 컨트롤러 기반 프로젝트의 경우 마이그레이션을 서두르지 않습니다. 두 접근 방식 모두 잘 작동하며 나란히 사용할 수도 있습니다. 하지만 다음에 소규모 서비스나 빠른 내부 API를 추가해야 할 경우 컨트롤러를 건너뛰고 최소화하세요. 돌아가지 않을 수도 있습니다.

즐거운 코딩하세요!

Blazor 구성 요소에서 격리된 CSS 사용

Wed, 12 Mar 2025 00:00:00 +0000

Blazor로 작업할 때 항상 나를 괴롭혔던 한 가지는 실수로 구성 요소 전체에서 스타일을 깨뜨리는 것이 얼마나 쉬운지였습니다. 한 구성요소에 클래스를 추가했는데 갑자기 완전히 다른 페이지에 있는 다른 항목이 이상해 보였습니다. 알고 보니 Blazor에는 이를 위한 내장 솔루션인 CSS 격리가 있습니다.

CSS 격리란 무엇인가요?

CSS 격리를 사용하면 스타일 범위를 특정 구성 요소로 지정할 수 있습니다. Blazor는 빌드 시 각 구성 요소에 대해 고유한 특성을 생성하고 이를 CSS 선택기에 추가하여 이를 수행합니다. 따라서 스타일은 해당 스타일이 속한 구성 요소에만 적용됩니다.

BEM 이름 지정도 필요 없고, 말도 안 되는 특정성 해킹도 필요하지 않습니다. 깨끗하고 범위가 지정된 CSS입니다.

사용방법

Card.razor라는 구성요소가 있다고 가정해 보겠습니다.

<div class="card">
 <h3 class="card-title">@Title</h3>
 <p class="card-body">@ChildContent</p>
</div>

@code {
 [Parameter]
 public string Title { get; set; }

 [Parameter]
 public RenderFragment ChildContent { get; set; }
}

분리된 스타일을 추가하려면 이름은 같지만 확장자는 .razor.css인 파일을 생성하면 됩니다. 이 경우: Card.razor.css.

.card {
 border: 1px solid var(--color-border);
 border-radius: 8px;
 padding: 1rem;
 background: var(--color-bg-secondary);
}

.card-title {
 font-size: 1.1rem;
 font-weight: 600;
 margin-bottom: 0.5rem;
}

.card-body {
 color: var(--color-text-secondary);
 font-size: 0.9rem;
}

그리고 그게 다야! Blazor는 자동으로 이를 선택하고 해당 스타일의 범위를 Card 구성 요소로만 지정합니다. 다른 곳에 또 다른 .card 클래스가 있으면 영향을 받지 않습니다.

내부적으로는 어떻게 작동하나요?

프로젝트를 빌드하면 Blazor는 HTML과 CSS를 다시 작성합니다. 구성 요소는 b-3x8qz7k2f1와 같은 고유한 속성을 가지며 CSS 선택기는 해당 속성을 추가합니다.

.card[b-3x8qz7k2f1] {
 border: 1px solid var(--color-border);
 /* ... */
}

생성된 CSS 번들은 {ProjectName}.styles.css로 제공됩니다. index.html 또는 _Host.cshtml에 이것이 있는지 확인하십시오.

<link href="YourApp.styles.css" rel="stylesheet" />

해당 링크가 없으면 격리된 스타일이 표시되지 않으며 무슨 일이 일어나고 있는지 궁금해하는 데 30분을 소비하게 됩니다. 저를 믿으세요. 저는 거기에 가봤습니다.

하위 요소 타겟팅

한 가지 명심해야 할 점은 기본적으로 격리된 CSS는 현재 구성 요소의 요소에만 적용된다는 것입니다. 하위 구성 요소 내부의 요소 스타일을 지정하려면 ::deep 연결자가 필요합니다.

::deep .child-element {
 color: red;
}

이는 Blazor가 하위 구성 요소 내의 일치하는 요소에도 스타일을 적용하도록 지시합니다. 하위 항목의 스타일을 지정해야 하는 래퍼 구성 요소가 있는 경우 매우 편리합니다.

언제 사용하는가

저는 현재 거의 모든 구성 요소에 CSS 격리를 사용합니다. 모든 것을 깨끗하고 예측 가능하게 유지합니다. 내가 사용하지 않는 유일한 때는 재설정, 타이포그래피 또는 테마 변수와 같은 진정한 전역 스타일(공유 CSS 파일에 포함됨)에 사용하는 것입니다.

게시물이 마음에 드셨기를 바랍니다! @emimontesdeoca로 소셜 미디어를 통해 언제든지 저에게 연락해주세요.

리소스

ASP.NET Core Blazor CSS 격리

Semantic Kernel을 사용하여 크리스마스 지출 제어

Sat, 28 Dec 2024 00:00:00 +0000

## 소개

연휴 시즌이 다가옴에 따라, 특히 쇼핑과 선물 구매가 붐비는 상황에서 비용 관리가 어려워질 수 있습니다. 이 블로그 게시물에서는 인공 지능을 활용하여 .NET 기술을 사용하여 크리스마스 지출을 추적하는 방법을 살펴보겠습니다. Semantic Kernel과 AI의 힘으로 영수증을 분석하여 매장명, 날짜, 품목 목록, 총액 등 주요 세부정보를 효율적으로 추출할 수 있습니다. 이 솔루션을 사용하면 크리스마스 지출을 쉽게 모니터링하고 관리할 수 있으므로 영수증을 수동으로 검토하는 번거로움 없이 예산을 최대한 활용할 수 있습니다.

Calendario de Adviento de Inteligencia Artificial 2024 en Español

이 프로젝트는 AI에 관한 온라인 이벤트인 Calendario de Adviento de Inteligencia Artificial 2024 en Español에 참여하면서 영감을 얻었습니다. 이 Dev.to 링크에서 이벤트에 대한 자세한 내용을 확인할 수 있습니다.

프로젝트

이 프로젝트에서는 GPT-4와 같은 강력한 AI 모델을 활용하여 이미지를 처리하고 분석할 수 있는 서비스인 Azure OpenAI를 사용할 예정입니다. 이 프로세스에는 백엔드 API 서비스 설정부터 이미지 업로드를 위한 Blazor 프런트 엔드 통합까지 여러 단계가 포함됩니다. 또한 모든 것을 원활하게 연결하는 데 도움이 되는 구성 요소인 .NET Aspire를 사용할 것입니다.

전제 조건

코드를 살펴보기 전에 다음 전제 조건이 충족되었는지 확인하세요.

.NET 9
Azure OpenAI 액세스(API 키)
비주얼 스튜디오 또는 비주얼 스튜디오 코드
Blazor, HTTP 클라이언트 및 API 개발에 대한 기본 지식

Visual Studio 솔루션

우리는 결국 다음과 같은 결과를 얻게 될 것입니다. 저는 항목을 분리하고 멋진 이름을 사용하는 것을 좋아하므로 다음과 같습니다.

하지만 단계별로 물건을 만들어 봅시다!

0단계: 모델

영수증 스캐너 애플리케이션의 핵심은 프런트 엔드, API 및 AI 서비스 간의 상호 작용을 촉진하는 여러 주요 모델에 의존합니다. 이 프로젝트에 사용된 주요 모델은 다음과 같습니다.

AnalyzeReceiptRequest
이 모델은 영수증 분석을 위한 요청 구조를 나타냅니다. 여기에는 처리될 영수증 이미지의 바이트 배열을 보유하는 ImageBytes 속성이 포함되어 있습니다.
```
public class AnalyzeReceiptRequest
{
 public byte[] ImageBytes { get; set; }
}
```
영수증분석결과
이 모델은 영수증 처리 후 결과를 캡처합니다. 영수증에서 추출한 매장명, 날짜, 품목, 총액 등 구조화된 데이터를 담고 있습니다.
```
public class ReceiptAnalyzeResult
{
 public DateTime CreatedAt { get; set; }
 public ReceiptData Result { get; set; }
}
```
영수증 데이터
구조화된 영수증 데이터를 보유하는 모델입니다. 여기에는 매장 이름, 날짜, 품목 목록(각 품목의 이름과 가격 포함), 영수증의 총액에 대한 속성이 포함됩니다.
```
public class ReceiptData
{
 public string Store { get; set; }
 public DateTime? Date { get; set; }
 public List<ReceiptItem> Items { get; set; }
 public decimal? Total { get; set; }
}
```

영수증 항목
영수증의 각 항목은 이 모델로 표시됩니다. 품목 이름과 가격이 들어 있습니다.

public class ReceiptItem
{
 public string Name { get; set; }
 public decimal? Price { get; set; }
}
```이러한 모델은 클라이언트와 서버 간에 데이터를 전달하기 위한 기반 역할을 하여 원활한 정보 흐름을 보장합니다. API는 영수증 이미지를 수신하고 그 대가로 프런트엔드에서 쉽게 사용할 수 있는 구조화된 JSON 개체를 처리하고 반환합니다.

1단계: 백엔드 API 서비스 설정

이 애플리케이션을 구축하는 첫 번째 단계는 영수증 이미지를 분석하기 위한 API 서비스를 설정하는 것입니다. Azure OpenAI API를 사용하여 영수증 이미지에서 정보를 추출하겠습니다. 모든 것이 어떻게 조화를 이루는지에 대한 분석은 다음과 같습니다.

AI 서비스 - 심층 분석

AI 서비스는 당사 영수증 분석 시스템의 핵심입니다. Azure OpenAI의 API와 통신하여 이미지 데이터를 처리하고 의미 있는 통찰력을 반환하는 역할을 담당합니다. AiApiClient 클래스는 Azure OpenAI API와의 모든 상호 작용을 처리하는 클라이언트입니다.

AI 클라이언트 구현

AiApiClient는 영수증 이미지(바이트 배열 형식)를 Azure OpenAI API로 보내는 주요 구성 요소입니다. 통신, 오류 로깅 및 데이터 구문 분석을 처리합니다.

public class AiApiClient
{
 private readonly HttpClient _httpClient;
 private readonly ILogger<AiApiClient> _logger;

 public AiApiClient(HttpClient httpClient, ILogger<AiApiClient> logger)
 {
 _httpClient = httpClient;
 _logger = logger;
 }

 public async Task<ReceiptAnalyzeResult?> AnalyzeAsync(byte[] imageBytes, CancellationToken cancellationToken = default)
 {
 if (imageBytes == null || imageBytes.Length == 0)
 {
 _logger.LogWarning("ImageBytes is null or empty.");
 return null;
 }

 _logger.LogInformation("Sending analyze request with image bytes of length: {Length}", imageBytes.Length);

 var request = new AnalyzeReceiptRequest
 {
 ImageBytes = imageBytes
 };

 try
 {
 var response = await _httpClient.PostAsJsonAsync("/analyze-receipt", request, cancellationToken);

 if (!response.IsSuccessStatusCode)
 {
 _logger.LogWarning("Failed to analyze receipt. StatusCode: {StatusCode}", response.StatusCode);
 return null;
 }

 var analyzeResult = await response.Content.ReadFromJsonAsync<ReceiptAnalyzeResult>(cancellationToken: cancellationToken);

 if (analyzeResult == null)
 {
 _logger.LogWarning("No content received from AI API service.");
 return null;
 }

 _logger.LogInformation("Analysis result received: {AnalyzeResult}", analyzeResult);

 return analyzeResult;
 }
 catch (Exception ex)
 {
 _logger.LogError(ex, "An error occurred while analyzing the receipt.");
 return null;
 }
 }
}

코드의 이 부분에서는 다음을 담당하는 AnalyzeAsync 메서드를 정의합니다.

이미지 바이트 배열을 Azure OpenAI API로 보냅니다.
API의 오류나 실패한 응답을 처리합니다.
반환된 JSON 데이터를 구조화된 결과(ReceiptAnalyzeResult)로 구문 분석합니다.

이 기능을 전용 서비스(AiApiClient)로 분리하면 다음과 같은 이점이 있습니다.

오류 처리: 네트워크 문제 또는 잘못된 응답과 같은 오류를 중앙 집중식으로 처리합니다.
로깅: 시스템 동작을 모니터링하기 위해 요청 및 응답을 적절하게 로깅합니다.

API 서비스 - 요청 및 응답 처리

API 서비스는 프런트엔드 Blazor 애플리케이션과 AI 서비스 간의 중개자 역할을 합니다. 이 서비스는 이미지 데이터를 받아 AI 서비스에 전달하고 분석 결과를 클라이언트에 반환하는 역할을 담당합니다.

API 엔드포인트

이 단계에서는 영수증 이미지를 수락하고, 처리를 위해 AI 서비스에 전달하고, 결과를 클라이언트에 반환하는 간단한 API 엔드포인트를 정의합니다.

using ReceiptScanner.Shared.Clients;
using ReceiptScanner.Shared.Models;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();

// Add services to the container.
builder.Services.AddProblemDetails();

// Register AiApiClient with HttpClient
builder.Services.AddHttpClient<AiApiClient>(client =>
{
 client.BaseAddress = new Uri("https+http://aiservice");
});

// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

if (app.Environment.IsDevelopment())
{
 app.MapOpenApi();
}

// POST endpoint to analyze receipt
app.MapPost("/api/analyze-receipt", async (AnalyzeReceiptRequest request, AiApiClient aiApiClient, ILogger<Program> logger) =>
{
 if (request.ImageBytes == null || request.ImageBytes.Length == 0)
 {
 logger.LogWarning("ImageBytes is null or empty.");
 return Results.BadRequest("ImageBytes is required.");
 }

 logger.LogInformation("Received analyze receipt request with image bytes of length: {Length}", request.ImageBytes.Length);

 try
 {
 var result = await aiApiClient.AnalyzeAsync(request.ImageBytes);

 if (result == null)
 {
 logger.LogWarning("Failed to analyze the receipt.");
 return Results.Problem("Unable to process the receipt at this time. Please try again later.");
 }

 logger.LogInformation("Analysis completed successfully. Result: {Result}", result);

 return Results.Ok(result);
 }
 catch (Exception ex)
 {
 logger.LogError(ex, "An error occurred while processing the receipt.");
 return Results.Problem("An error occurred while processing the receipt. Please try again later.");
 }
});

app.MapDefaultEndpoints();

app.Run();

이 끝점은 다음과 같습니다.

요청 본문의 일부로 영수증 이미지를 수락합니다.
AiService endopint 메서드를 호출하여 처리를 위해 이미지를 Azure OpenAI로 보냅니다.
분석 결과를 클라이언트에게 다시 반환합니다.

2단계: Blazor 프런트엔드 설정

이제 백엔드가 설정되었으므로 Blazor 프런트엔드에 주목해 보겠습니다. 여기에서 사용자는 분석을 위해 영수증 이미지를 업로드하고 결과를 확인할 수 있습니다.

Blazor 페이지 구현

Blazor 페이지는 사용자가 여러 영수증 이미지를 업로드한 다음 테이블에 표시되는 분석 결과를 볼 수 있는 간단한 인터페이스를 제공합니다. 페이지 코드는 다음과 같습니다.

@page "/analyzer"
@using ReceiptScanner.Shared.Clients
@using ReceiptScanner.Shared.Models
@using System.Globalization
@inject ApiServiceClient ApiClient
@inject ILogger<Program> Logger

@attribute [StreamRendering]
@rendermode InteractiveServer

<PageTitle>Receipt Analyzer</PageTitle>

<h1 class="text-center my-4">Receipt Analyzer</h1>

<div class="container">
 <p class="lead text-center mb-4">Upload receipt images below to extract their data.</p>

 <!-- File Upload Section -->
 <div class="card mb-4">
 <div class="card-body">
 <InputFile OnChange="HandleFileSelected" multiple class="form-control mb-3" />
 <button class="btn btn-primary w-100" @onclick="ProcessReceipts" disabled="@(!hasFiles)" type="button">
 <span class="@(!processing ? "d-none" : "") spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>
 @if (processing)
 {
 <span>Processing...</span>
 }
 else
 {
 <span>Process Receipts</span>
 }
 </button>
 </div>
 </div>

 <!-- Uploaded Images Preview -->
 @if (fileBytesList.Any())
 {
 <div class="card mb-4">
 <div class="card-header">
 <h5 class="mb-0">Uploaded Receipt Images</h5>
 </div>
 <div class="card-body">
 <div class="row">
 @foreach (var fileBytes in fileBytesList)
 {
 <div class="col-12 col-md-4 mb-3">
 <img src="@($"data:image/jpeg;base64,{Convert.ToBase64String(fileBytes)}")" class="img-fluid rounded" alt="Uploaded receipt" />
 </div>
 }
 </div>
 </div>
 </div>
 }

 <!-- Processing Indicator -->
 @if (processing)
 {
 <div class="alert alert-info text-center" role="alert">
 <strong>Processing receipts...</strong> Please wait while we analyze the uploaded files.
 </div>
 }

 <!-- Analysis Results Section -->
 @if (analyzedReceipts != null && analyzedReceipts.Any())
 {
 <div class="card">
 <div class="card-header">
 <h5 class="mb-0">Analysis Results</h5>
 </div>
 <div class="card-body">
 <table class="table table-striped table-bordered">
 <thead>
 <tr>
 <th>Store</th>
 <th>Date</th>
 <th>Total</th>
 <th>Items</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var receipt in analyzedReceipts)
 {
 <tr>
 <td>@(receipt.Result?.Store ?? "Unknown")</td>
 <td>@(receipt.Result?.Date?.ToString() ?? "Unknown")</td>
 <td>@(receipt.Result?.Total?.ToString("C", ci) ?? "Unknown")</td>
 <td>
 <ul class="list-unstyled">
 @if (receipt.Result?.Items is not null)
 {
 @foreach (var item in receipt.Result?.Items!)
 {
 <li><strong>@item.Name</strong> - @item.Price?.ToString("C", ci)</li>
 }
 }
 </ul>
 </td>
 </tr>
 }
 </tbody>
 </table>
 </div>
 </div>
 }
 else if (processed && (analyzedReceipts == null || !analyzedReceipts.Any()))
 {
 <div class="alert alert-warning text-center" role="alert">
 <strong>No results found.</strong> Please try again with different images or ensure they are clear and legible.
 </div>
 }
</div>

@code {
 private bool hasFiles;
 private bool processing;
 private bool processed;
 private List<byte[]> fileBytesList = new();
 private List<ReceiptAnalyzeResult> analyzedReceipts = new();
 CultureInfo ci = new CultureInfo("es-es");

 private async Task HandleFileSelected(InputFileChangeEventArgs e)
 {
 try
 {
 fileBytesList.Clear();

 foreach (var file in e.GetMultipleFiles())
 {
 var memoryStream = new MemoryStream();
 await file.OpenReadStream().CopyToAsync(memoryStream);
 fileBytesList.Add(memoryStream.ToArray());
 }

 hasFiles = fileBytesList.Any();
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while handling file upload.");
 }
 }

 private async Task ProcessReceipts()
 {
 if (!hasFiles)
 return;

 processing = true;
 analyzedReceipts.Clear();

 try
 {
 foreach (var fileBytes in fileBytesList)
 {
 var result = await ApiClient.AnalyzeReceiptAsync(fileBytes);
 if (result != null)
 {
 analyzedReceipts.Add(result);
 }
 }
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while processing receipts.");
 }
 finally
 {
 processing = false;
 processed = true;
 }
 }
}

```이 페이지에서는 영수증을 업로드할 수 있으며 분석 결과를 매장명, 날짜, 총액, 품목 목록이 포함된 테이블로 표시합니다.

<p 정렬="중앙">
<img src="https://imgur.com/BLswKhm.png">
</p>

## 3단계: .NET Aspire

<p 정렬="중앙">
<img src="https://imgur.com/ja56RWN.png">
</p>

### .NET Aspire란 무엇입니까?

.NET Aspire는 관찰 가능한 프로덕션 지원 앱을 구축하기 위한 강력한 도구, 템플릿 및 패키지 세트입니다. .NET Aspire는 특정 클라우드 기반 문제를 처리하는 NuGet 패키지 컬렉션을 통해 제공됩니다. 클라우드 네이티브 앱은 단일한 모놀리식 코드 기반이 아닌 상호 연결된 작은 조각이나 마이크로서비스로 구성되는 경우가 많습니다. 클라우드 네이티브 앱은 일반적으로 데이터베이스, 메시징, 캐싱과 같은 많은 서비스를 사용합니다. 지원에 대한 자세한 내용은 .NET Aspire 지원 정책을 참조하세요.

분산 애플리케이션은 서로 다른 호스트에서 실행되는 컨테이너와 같이 여러 노드에서 컴퓨팅 리소스를 사용하는 애플리케이션입니다. 이러한 노드는 사용자에게 응답을 전달하기 위해 네트워크 경계를 통해 통신해야 합니다. 클라우드 네이티브 앱은 클라우드 인프라의 확장성, 탄력성 및 관리 용이성을 최대한 활용하는 특정 유형의 분산 앱입니다.

이 프로젝트에 **.NET Aspire**를 사용하면 다음과 같이 전체 시스템 품질을 향상시키는 여러 가지 이점을 얻을 수 있습니다.

### 1. **중앙 집중식 로깅**

.NET Aspire는 전체 애플리케이션에 걸쳐 로깅을 자동으로 통합합니다. 즉, 각 서비스에 대한 로깅을 수동으로 구성할 필요가 없습니다. 이렇게 하면 로그가 일관되고 중앙 위치에 저장되므로 디버깅 및 모니터링이 훨씬 쉬워집니다.

예를 들어 `AiApiClient` 클래스는 로깅을 사용하여 AI 서비스로 전송된 이미지 바이트, API 응답 및 분석 프로세스 중에 발생하는 모든 오류를 기록합니다.

```csharp
_logger.LogInformation("Sending analyze request with image bytes of length: {Length}",

 imageBytes.Length);

2. 자동 측정항목 수집

.NET Aspire는 또한 응답 시간, 요청 수, 오류율과 같은 중요한 애플리케이션 지표를 자동으로 추적하고 보고합니다. 이를 통해 애플리케이션의 성능을 이해하고 병목 현상이나 문제를 신속하게 감지할 수 있습니다.

3. 향상된 성능

.NET Aspire는 HTTP 호출을 최적화하여 응답 시간을 낮게 유지하고 불필요한 리소스 소비를 줄이는 데 도움이 됩니다. 연결 풀링, 요청 재시도 및 지능형 라우팅과 같은 기능을 제공합니다.

4. 완벽한 통합

.NET Aspire는 다양한 서비스(예: 이 프로젝트의 AI 및 API 서비스)의 통합을 단순화하고 배포 프로세스를 간소화합니다. Aspire가 인프라 관련 작업을 자동으로 처리하므로 낮은 수준 구성에 대해 걱정할 필요가 없습니다.

결론AI는 더 이상 공상과학 영화에서나 볼 수 있는 유행어가 아닙니다. 영수증에서 구조화된 데이터를 추출하여 이 프로젝트에서 다룬 문제와 같이 오늘날 실제 문제를 적극적으로 해결하고 있습니다. Azure OpenAI, .NET Aspire 및 Blazor의 도움으로 시간이 많이 걸리고 오류가 발생하기 쉬운 수동 작업을 자동화할 수 있습니다. AI는 단순히 ChatGPT와 같은 메시지에 채팅하거나 응답하는 것이 아닙니다. 이미지를 해석하고, 귀중한 정보를 추출하고, 몇 초 만에 실행 가능한 통찰력을 제공합니다.

영수증 분석에 Azure OpenAI를 사용하고 로깅 및 메트릭과의 원활한 통합을 위해 .NET Aspire를 사용하여 강력하고 확장 가능한 솔루션을 만들었습니다. 비즈니스 프로세스를 간소화하고, 지루한 작업을 자동화하고, 정확성을 향상시키는 AI의 잠재력은 엄청나며, 이는 AI가 어떻게 적용될 수 있는지 보여주는 한 가지 예일 뿐입니다.

이 게시물은 실제 AI 애플리케이션을 선보이고 스페인어를 사용하는 기술 커뮤니티에 최신 트렌드를 교육하는 이벤트인 Calendario de Adviento de Inteligencia Artificial 2024 en Español의 일부입니다. AI와 그 가능성에 대해 더 깊이 알아보고 싶다면 이 이벤트를 시작하는 것이 좋습니다.

AI는 우리가 일하는 방식을 변화시키고 있으며, 이 프로젝트는 무엇이 가능한지 보여줍니다. AI의 진정한 힘은 영수증 처리, 이미지 분석, 추세 예측 등 실제 문제를 해결하는 능력에 있습니다. 우리는 단지 표면만 긁고 있을 뿐입니다.

소스 코드

이 프로젝트의 전체 소스 코드는 GitHub에서 확인할 수 있습니다. 자유롭게 다운로드하여 AI와 API 서비스가 어떻게 함께 작동하는지 살펴보고 자신의 사용 사례에 맞게 조정하세요. 문제가 발생하거나 개선을 위한 아이디어가 있는 경우 주저하지 말고 문제를 생성하거나 끌어오기 요청을 제출하세요. 기여는 언제나 환영하며 귀하의 피드백은 이 프로젝트를 더욱 개선하는 데 도움이 됩니다!

즐거운 코딩하세요!

컨테이너를 사용하여... 크리스마스 선물 가격을 추적하시나요?

Thu, 12 Dec 2024 00:00:00 +0000

크리스마스가 코앞으로 다가왔습니다. 사랑하는 사람을 위한 완벽한 선물을 찾는 즐거운 일이 다가오고 있습니다. 저와 같은 사람이라면 좋은 상품을 구매하는 것을 좋아할 것입니다. 하지만 연휴 동안 치솟는 인기 품목 가격을 탐색하는 것은 실제 썰매를 타는 것처럼 느껴질 수 있습니다. 흥미롭지만 약간 부담스럽습니다! 올해는 매일 가격을 확인하느라 정신없게 지내는 대신 기술 능력을 잘 활용하고 프로세스를 자동화하기로 결정했습니다.

소프트웨어 개발자이자 기술을 활용하여 일상적인 문제를 해결하는 데 열정을 갖고 있는 사람으로서 저는 가격 확인 프로세스를 자동화하는 방법을 찾았습니다. 매일 수동으로 여러 온라인 매장을 방문하여 가격을 비교하는 대신, 이를 대신해 줄 수 있는 시스템을 만들기로 결정했습니다. 이를 통해 시간을 절약할 수 있을 뿐만 아니라 매일 확인하는 스트레스 없이 최고의 거래를 얻을 수 있습니다.

가격 모니터링을 자동화하는 이유는 무엇입니까?

가격 모니터링을 자동화하는 것은 손가락 하나 까딱하지 않고도 최고의 거래를 얻을 수 있도록 24시간 내내 일하는 산타의 요정 팀을 갖는 것과 같습니다. 당신이 그것을 좋아할 이유는 다음과 같습니다:

비싼 품목: 우리 모두는 크리스마스 선물이 상당히 비쌀 수 있다는 것을 알고 있습니다. 특히 장치와 장난감이 목록에 있을 때 더욱 그렇습니다. 이것에 대한 비용을 절약하는 것은 재고에서 마지막 나무 꼭대기를 찾는 것만큼 만족스러울 수 있습니다.
일일 확인: 매일 가격을 확인할 시간(또는 인내심)이 있는 사람은 누구입니까? 나 말고!
자동화: 나눔이라는 명절 정신을 받아들이고 자신에게 효율성을 선물하세요.
정확성: 자동화는 루돌프의 코처럼 정확한 가격 확인을 보장합니다.

핵심 기술

나만의 산타 도우미를 만들기 위해 저는 몇 가지 핵심 기술을 사용하기로 결정했습니다.

컨테이너

컨테이너는 소프트웨어의 크리스마스 포장과 같습니다. 애플리케이션을 모든 기능(종속성)과 함께 묶어 신선한 눈 속에서 썰매를 타는 것처럼 모든 것이 원활하게 실행되도록 합니다. Docker는 이러한 컨테이너를 만드는 데 사용되는 도구입니다.

블레이저

Blazor는 .NET을 사용하여 대화형 웹 애플리케이션을 구축하기 위한 멋진 프레임워크입니다. 일반적인 크리스마스 캐롤을 맞춤화되고 효율적이며 재미있는 나만의 휴일 재생목록으로 바꾸는 것과 같습니다.

Docker-작성

Docker-Compose는 North Pole 운영의 관리자입니다. 이는 API 및 Blazor 프런트 엔드와 같은 모든 서비스가 완벽한 조화를 이루며 함께 실행되는 데 도움이 됩니다. 그를 우리 명절 교향곡의 지휘자로 생각해보세요.

단계별 가이드

이제 산타의 작업장에 들어가 이 프로젝트에 생기를 불어넣어 보세요!

1단계: API 생성

1.1 프로젝트 설정

코딩 산타 모자를 쓰고 새로운 ASP.NET Core Web API 프로젝트를 설정하세요. 터미널을 열고(강림절 달력을 여는 것과 약간 비슷함) 다음을 실행합니다.

dotnet new webapi -o PriceMonitorApi
cd PriceMonitorApi

이 명령은 PriceMonitorApi라는 새 디렉터리를 생성하고 기본 웹 API 프로젝트를 설정합니다. 진저브레드 하우스를 위한 견고한 기반을 만드는 것과 같다고 상상해 보세요.

1.2 HttpClient 추가 및 라이브러리 스크랩다음으로 `HttpClient` 및 라이브러리를 추가하여 HTML을 구문 분석합니다. 이는 가격 데이터를 가져오고 읽는 데 있어 신뢰할 수 있는 썰매가 될 것입니다.

dotnet add package HtmlAgilityPack

HtmlAgilityPack은 HTML 문서를 구문 분석하는 데 도움이 되는 엘프입니다.

1.3 모델 생성

모델은 장난감의 청사진과 같습니다. 제품 정보를 나타내는 모델을 만들어 보겠습니다.

namespace PriceMonitorApi.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

우리는 데이터에 딱 맞는 템플릿을 만들었습니다.

1.4 스크레이퍼 서비스 구현

우리의 스크레이퍼 서비스는 산타의 작은 도우미와 같습니다. 우리를 위해 정보를 가져오고 처리합니다.

using HtmlAgilityPack;
using PriceMonitorApi.Models;
using System.Globalization;

namespace PriceMonitorApi.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> ScrapeProductInfoAsync(string url)
 {
 var response = await _httpClient.GetStringAsync(url);

 var htmlDoc = new HtmlDocument();
 htmlDoc.LoadHtml(response);

 var title = htmlDoc.DocumentNode.SelectSingleNode("//h1[@class='product-title']").InnerText.Trim();
 var priceString = htmlDoc.DocumentNode.SelectSingleNode("//span[@class='product-price']").InnerText.Trim();

 if (decimal.TryParse(priceString, NumberStyles.Currency, CultureInfo.InvariantCulture, out var price))
 {
 return new ProductInfo
 {
 Title = title,
 Price = price,
 Date = DateTime.UtcNow
 };
 }

 throw new Exception("Unable to parse price");
 }
 }
}

이 스니펫은 HtmlAgilityPack를 휴일 마술 지팡이로 바꿔줍니다.

1.5 API 컨트롤러 생성

데이터의 게이트키퍼 역할을 하는 컨트롤러를 만들어 보겠습니다.

using Microsoft.AspNetCore.Mvc;
using PriceMonitorApi.Models;
using PriceMonitorApi.Services;

namespace PriceMonitorApi.Controllers
{
 [ApiController]
 [Route("api/[controller]")]
 public class ScraperController : ControllerBase
 {
 private readonly ScraperService _scraperService;

 public ScraperController(ScraperService scraperService)
 {
 _scraperService = scraperService;
 }

 [HttpGet("productinfo")]
 public async Task<ActionResult<ProductInfo>> GetProductInfo(string url)
 {
 try
 {
 var productInfo = await _scraperService.ScrapeProductInfoAsync(url);
 return Ok(productInfo);
 }
 catch (Exception ex)
 {
 return BadRequest(new { Message = ex.Message });
 }
 }
 }
}

우리 컨트롤러는 굴뚝 아래로 산타보다 데이터가 더 빨리 전달되도록 보장합니다.

1.6 DI 컨테이너에 서비스 등록

마지막으로 ScraperService를 등록하여 필요할 때 사용할 수 있는지 확인하세요.

services.AddHttpClient<ScraperService>();

이제 크리스마스 이브의 산타 썰매처럼 API가 준비되었습니다!

2단계: Blazor 애플리케이션 만들기

Blazor를 사용하면 프로젝트를 크리스마스 트리처럼 장식하여 시각적으로 매력적이고 대화형으로 만들 수 있습니다.

2.1 Blazor 프로젝트 설정

다음으로 가격 모니터링 썰매 타기를 위한 인터페이스 역할을 하는 Blazor 프로젝트를 만듭니다.

dotnet new blazor -o PriceMonitorBlazor
cd PriceMonitorBlazor

이 명령은 기본 Blazor WebAssembly 프로젝트를 설정하기 위해 몇 가지 휴일 마법을 뿌립니다.

2.2 모델 추가

장식품 설정과 마찬가지로 Blazor 프로젝트에 ProductInfo 모델을 추가합니다.

namespace PriceMonitorBlazor.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

2.3 API 호출을 위한 서비스 생성

API에서 데이터를 가져오는 서비스를 만듭니다. 온라인 쇼핑 친구라고 생각하세요.

using PriceMonitorBlazor.Models;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"https://localhost:5001/api/scraper/productinfo?url={url}");
 return response;
 }
 }
}

2.4 DI 컨테이너에 서비스 등록

구성요소에 주입할 수 있도록 ScraperService가 등록되어 있는지 확인하세요.

builder.Services.AddScoped<ScraperService>();

2.5 Blazor 구성 요소 만들기

재미있고 대화형 인터페이스를 포함하도록 Pages/Index.razor를 업데이트하세요.

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="FetchProductInfo">Fetch Price</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();

 private async Task FetchProductInfo()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 var productInfo = await ScraperService.GetProductInfoAsync(productUrl);
 productInfos.Add(productInfo);
 }
 }
}

이는 축제의 휴일 디스플레이를 설정하여 앱을 대화형이고 즐겁게 만드는 것과 같습니다.

3단계: Docker-Compose를 사용하여 모든 항목 연결

이제 Docker-Compose를 사용하여 모든 것을 연결하여 프로젝트를 기름진 썰매 타기로 바꿔 보겠습니다.

3.1 Dockerfile 만들기

API 및 Blazor 프로젝트 모두에 대한 Dockerfile을 만듭니다.

PriceMonitorApi/Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorApi/PriceMonitorApi.csproj", "PriceMonitorApi/"]
RUN dotnet restore "PriceMonitorApi/PriceMonitorApi.csproj"
COPY . .
WORKDIR "/src/PriceMonitorApi"
RUN dotnet build "PriceMonitorApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorApi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorApi.dll"]

PriceMonitorBlazor/Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorBlazor/PriceMonitorBlazor.csproj", "PriceMonitorBlazor/"]
RUN dotnet restore "PriceMonitorBlazor/PriceMonitorBlazor.csproj"
COPY . .
WORKDIR "/src/PriceMonitorBlazor"
RUN dotnet build "PriceMonitorBlazor.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorBlazor.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorBlazor.dll"]

3.2 docker-compose.yml 만들기

단일 docker-compose.yml 파일로 모든 점(크리스마스 조명)을 연결합니다.

version: '3.4'

services:
 api:
 image: pricemonitorapi
 build:
 context: ./PriceMonitorApi
 dockerfile: Dockerfile
 ports:
 - "5000:80"
 networks:
 - price-monitor-network

 blazor:
 image: pricemonitorblazor
 build:
 context: ./PriceMonitorBlazor
 dockerfile: Dockerfile
 ports:
 - "5001:80"
 depends_on:
 - api
 networks:
 - price-monitor-network

networks:
 price-monitor-network:
 driver: bridge

다이어그램

다음은 다양한 구성 요소와 데이터 흐름을 시각화하는 데 도움이 되는 다이어그램입니다. 이는 산타 세계에서 실제로 무슨 일이 일어나고 있는지 이해하는 데 도움이 됩니다.

시스템 아키텍처 다이어그램

데이터 흐름 다이어그램

시퀀스 다이어그램

Docker 설정을 위한 구성 요소 다이어그램

4단계: URL 관리, 새로 고침 및 자동 주기적 새로 고침이 데모에서는 이를 메모리에 저장하지만 실제 애플리케이션에서는 데이터베이스를 사용합니다. 이 재미있는 프로젝트에서는 메모리 내 저장소를 고수하겠습니다.

4.1 URL 관리를 위한 서비스 수정

먼저, 우리 서비스가 URL 추가 및 검색은 물론 제품 정보 가져오기도 처리할 수 있는지 확인하겠습니다.

Services/ScraperService.cs 업데이트:

using PriceMonitorBlazor.Models;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;
 private List<string> urls = new List<string>();

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"http://localhost:5000/api/scraper/productinfo?url={url}");
 return response;
 }

 public void AddUrl(string url)
 {
 if (!urls.Contains(url))
 {
 urls.Add(url);
 }
 }

 public List<string> GetUrls()
 {
 return urls;
 }

 public void ClearUrls()
 {
 urls.Clear();
 }
 }
}

4.2 URL 관리 및 새로 고침을 위한 Blazor 구성 요소 업데이트

다음으로 Pages/Index.razor를 업데이트하여 URL 관리, 새로 고침 및 자동 주기적 새로 고침을 추가합니다.

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="AddUrl">Add URL</button>
</p>

<p>
 <button @onclick="RefreshPrices">Refresh All Prices</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();
 private Timer _timer;

 protected override void OnInitialized()
 {
 StartTimer();
 }

 private void StartTimer()
 {
 // Set up the timer to call RefreshPrices every minute (60000 ms)
 _timer = new Timer(async _ => await InvokeAsync(RefreshPrices), null, TimeSpan.Zero, TimeSpan.FromMinutes(1));
 }

 private void AddUrl()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 ScraperService.AddUrl(productUrl);
 productUrl = string.Empty;
 }
 }

 private async Task RefreshPrices()
 {
 productInfos.Clear();
 var urls = ScraperService.GetUrls();

 foreach (var url in urls)
 {
 var productInfo = await ScraperService.GetProductInfoAsync(url);
 productInfos.Add(productInfo);
 }
 StateHasChanged();
 }
}

이 업데이트된 구성 요소에서는 다음을 수행합니다.

Timer를 사용하여 1분마다 RefreshPrices 메서드를 주기적으로 호출합니다.
StartTimer 메소드는 타이머를 초기화하여 즉시 시작하고 60초마다 트리거합니다.
OnInitialized 수명 주기 메서드는 구성 요소가 초기화되어 주기적 새로 고침을 시작할 때 StartTimer를 호출합니다.

4.3 솔루션 실행

새로운 기능으로 업데이트된 Blazor 애플리케이션을 실행하려면 Docker 컨테이너를 다시 빌드하고 다시 시작하세요.

docker-compose build
docker-compose up

브라우저에 http://localhost:5001를 로드한 후 Blazor 앱은 수동 새로 고침 및 URL 관리를 허용하는 것 외에도 매분 자동으로 제품 가격을 새로 고쳐야 합니다.

결론

이 가격 모니터링 시스템을 구축하는 것은 정말 즐거운 일이었습니다! 매일 가격을 확인하는 스트레스에서 벗어날 수 있었을 뿐만 아니라 현대 웹 기술의 마법도 보여주었습니다.

축제 기술 달력 2024

저는 기술 애호가, 혁신가, 디지털 몽상가들이 함께 모여 지식을 공유하고 축제 정신과 기술의 경이로움의 융합을 축하하는 Festive Tech Calendar 2024 이벤트의 일환으로 이 게시물을 작성했습니다. 이 이니셔티브는 학습과 연결뿐만 아니라 환원에 관한 것입니다.

Festive Tech Calendar 2024는 올해 Beatson Cancer Charity를 지원합니다. Beatson Cancer Charity는 암으로 고통받는 사람들과 그 가족, 그들을 돌보는 의료 전문가를 지원하는 데 최선을 다하고 있습니다. 그들의 놀라운 작업에 대한 자세한 내용은 https://www.beatsoncancercharity.org/에서 확인할 수 있습니다.

자주 묻는 질문과 이벤트에 대한 자세한 내용은 Festive Tech Calendar 웹사이트 https://festivetechcalendar.com에서 확인하세요.

호호호!

이 프로젝트를 만드는 것은 축제 기술 커뮤니티에 기여하고 동시에 훌륭한 목적을 지원할 수 있는 훌륭한 방법이었습니다.

이 가이드가 도움이 되기를 바라며 기술을 사용하여 일상적인 작업을 단순화하는 더 많은 방법을 탐색하는 데 영감을 주기를 바랍니다.

궁금한 점이 있거나 추가 지원이 필요한 경우 언제든지 문의해 주세요.

즐거운 코딩하세요!

사용자 지정 ValidationAttribute 및 Blazor 유효성 검사

Fri, 29 Mar 2024 00:00:00 +0000

# 모든 것을 맞춤설정하세요

아마도 내 모든 게시물에서 보셨겠지만 저는 이미 사용자 정의 속성, 사용자 정의 예외 처리, 서비스 컬렉션 주입 등에 관한 게시물을 작성했기 때문에 모든 것을 가능한 한 깔끔하게 유지하려고 노력합니다.

나는 이런 종류의 코딩 방식이 나와 내 팀에게 초과 근무 시간을 개선하고, 문제를 더 쉽게 찾고, 코드를 최대한 분리할 수 있는 방법을 제공한다는 것을 시간이 지나면서 깨달았습니다.

네, 이 멋진 이야기를 마치고 지금 여러분을 모시고 있습니다. 저는 최근 평소처럼 Blazor를 작업해 왔으며 수년 간의 개발 끝에 사용자 지정 유효성 검사 속성을 만들 수 있다는 것을 발견했습니다.

응, 웃기네, 몇년이 지나서야…

사용자 정의 유효성 검사 속성

아이디어는 실제로 작업에서 나왔습니다. 우리는 항상 모든 곳에서 유효성 검사를 수행하지만 동일한 유효성 검사 프로세스가 필요한 일부 필드가 있었기 때문에 거기에 뭔가가 있을 수 있다고 생각했습니다…. 사용자 정의 유효성 검사 속성과 같은 것입니다!

그래서 이에 대한 Microsoft 문서를 실행한 후 다음과 같이 사용자 지정 유효성 검사 특성을 만들고 속성에 할당할 수 있다는 것을 알게 되었습니다.

public class StringLengthRangeAttribute : ValidationAttribute
{
 public int Minimum { get; set; }
 public int Maximum { get; set; }

 public StringLengthRangeAttribute()
 {
 this.Minimum = 0;
 this.Maximum = int.MaxValue;
 }

 public override bool IsValid(object value)
 {
 string strValue = value as string;
 if (!string.IsNullOrEmpty(strValue))
 {
 int len = strValue.Length;
 return len >= this.Minimum && len <= this.Maximum;
 }
 return true;
 }
}

다음과 같은 간단한 클래스에서 사용하세요.

[Required]
[StringLengthRange(Minimum = 10, ErrorMessage = "Must be >10 characters.")]

[StringLengthRange(Maximum = 20)]

[Required]
[StringLengthRange(Minimum = 10, Maximum = 20)]

사용자 정의 유효성 검사기

그래서 저는 9개의 숫자와 하이픈으로 끝나는 20개의 첫 번째 문자를 계산하고 일반적으로 국가 코드가 되는 2개의 문자로 끝나는 특정 비즈니스 사례에 필요한 유효성 검사기를 가지고 있습니다. 123456789-123456789-ES

나는 결국 다음과 같은 결과를 얻었습니다. 정말 간단하지만 작동합니다.

using System;
using System.ComponentModel.DataAnnotations;
using System.Text.RegularExpressions;

public class SpecialStringValidatorAttribute : ValidationAttribute
{
 private const int TotalLength = 22;
 private const string Pattern = @"^(\d{10})-(\d{10})-([A-Za-z]{2})$";

 protected override ValidationResult IsValid(object value, ValidationContext validationContext)
 {
 string strValue = value as string;

 if (!string.IsNullOrEmpty(strValue))
 {
 if (strValue.Length != TotalLength)
 {
 return new ValidationResult($"The string must be {TotalLength} characters long.");
 }

 if (!Regex.IsMatch(strValue, Pattern))
 {
 return new ValidationResult("The string must follow the pattern: 1234567890-1234567890-AB");
 }

 return ValidationResult.Success;
 }

 return new ValidationResult("The string cannot be null or empty.");
 }
}

테스트

만일의 경우를 대비해 나는 그들을 위해 몇 가지 테스트도 작성했습니다.

public class SpecialStringValidatorTests
{
 [Theory]
 [InlineData("1234567890-1234567890-AB", true)]
 [InlineData("1234567890-1234567890-XY", true)]
 [InlineData("1234567890-1234567890-A1", false)]
 [InlineData("1234567890-1234567890-A", false)]
 [InlineData("1234567890-123456789-AB", false)]
 [InlineData("1234567890-1234567890", false)]
 [InlineData("1234567890-1234567890-ABCDE", false)]
 public void SpecialStringValidatorTest(string input, bool expectedResult)
 {
 // Arrange
 var validator = new SpecialStringValidatorAttribute();

 // Act
 var result = validator.IsValid(input);

 // Assert
 Assert.Equal(expectedResult, result);
 }
}

그리고 실행해보니 다음과 같은 결과가 나왔습니다.

Microsoft (R) Test Execution Command Line Tool Version 16.9.1
Copyright (c) Microsoft Corporation. All rights reserved.

Starting test execution, please wait...

A total of 1 test files matched the specified pattern.

Test run in progress...

Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-AB", expectedResult: True)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-XY", expectedResult: True)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-A1", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-A", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-123456789-AB", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890", expectedResult: False)
Passed! - SpecialStringValidatorTests.SpecialStringValidatorTest(input: "1234567890-1234567890-ABCDE", expectedResult: False)

Test Run Successful.
Total tests: 7
 Passed: 7
 Total time: 1.7296 Seconds

사용자 정의 유효성 검사 및 Blazor

이제 그의 것을 사용할 수 있다는 것을 알았으니 Blazor에 구현하는 것이 확실히 좋은 생각이겠죠?

이전에 보여드린 Person 모델을 사용하는 다음 양식이 있다고 가정해 보겠습니다.

@using Models
@page "/"

<PageTitle>Home</PageTitle>

<h1>Hello, world!</h1>

<EditForm Model=@Person FormName="PersonForm">
 <DataAnnotationsValidator/>
 <ValidationSummary/>
 <div class="form-group">
 <label for="Name">Name</label>
 <InputText @bind-Value=Person.Name class="form-control" id="Name" />
 <ValidationMessage For="() => Person.Name"/>
 </div>
 <div class="form-group">
 <label for="MySpecialString">My special string</label>
 <InputText @bind-Value=Person.MySpecialString class="form-control" id="Name" />
 <ValidationMessage For="() => Person.MySpecialString"/>
 </div>
 <div class="form-group">
 <label for="Age">Age</label>
 <InputNumber @bind-Value=Person.Age class="form-control" id="Age" />
 <ValidationMessage For=@(() => Person.Age) />
 </div>
 <input type="submit" class="btn btn-primary" value="Save"/>
</EditForm>

@code {
 Person Person = new Person();
}

이것을 실행하자마자 다음과 같은 오류가 발생합니다.

그리고 우리가 원하는 것을 넣으면 다음과 같은 결과가 나옵니다.

솔직히 말해서 최소한 해당 양식의 유효성을 검사하는 논리를 사용자 정의 유효성 검사 속성으로 옮겨야 한다는 점은 매우 분명합니다. 그러면 해당 로그인에 대한 코드를 한 곳에 자유롭게 저장할 수 있으며 나중에 API나 다른 애플리케이션에 사용할 수 있습니다.

재미있게 보셨기를 바라며, 궁금하신 점이나 연락하고 싶으신 점이 있으시면 주저하지 마시고 연락주세요!

.NET API의 사용자 정의 예외 처리

Sun, 01 Oct 2023 00:00:00 +0000

예외는 좋지 않습니다. 우리도 알고 있죠? 하지만 우리가 그것들을 처리해야 한다면 어떨까요?

예를 들어 API에서 예외가 발생하면 사용자가 받는 응답에서 제거하고 싶은 많은 정보가 포함된 스택 메시지가 표시됩니다.

데모를 위해 dotnet API를 만들고 예외를 발생시키는 메서드를 추가했습니다.

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new Exception("This is a custom exception!");
}

예외를 던지면 다음과 같습니다.

System.Exception: This is a custom exception!
 at CustomExceptionHandleDemo.Controllers.WeatherForecastController.GetWithoutExceptionHandler()
 at lambda_method16(Closure , Object , Object[] )
 at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.AwaitableResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeActionMethodAsync>g__Logged|12_1(ControllerActionInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeNextActionFilterAsync>g__Awaited|10_0(ControllerActionInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Rethrow(ActionExecutedContextSealed context)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.InvokeInnerFilterAsync()
--- End of stack trace from previous location ---
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeFilterPipelineAsync>g__Awaited|20_0(ResourceInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Routing.EndpointMiddleware.<Invoke>g__AwaitRequestTask|6_0(Endpoint endpoint, Task requestTask, ILogger logger)
 at Microsoft.AspNetCore.Authorization.AuthorizationMiddleware.Invoke(HttpContext context)
 at Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIMiddleware.Invoke(HttpContext httpContext)
 at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
 at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)

이것은 정상으로 보입니다. 예외에서 얻은 정보이지만 저에게는 많은 정보가 표시됩니다. 라이브러리 등이 있는 경우 클라이언트, 프로젝트 또는 기타 항목에 관한 합리적인 정보를 보려고 하는 사람에게 표시될 수 있습니다.

Swagger에서는 다음과 같이 표시됩니다.

사용자 정의 예외 만들기

어떤 예외(이 경우에는 [[TOK_3]]])가 발생할지 알고 있으므로 이 단계를 피할 수 있지만, 나에게는 사용자 정의 예외를 갖는 것이 더 좋습니다. 왜냐하면 여러분이 던지는 것을 더 잘 제어할 수 있기 때문입니다.

이 경우에는 Exception에서 상속받은 CustomException 객체를 생성했습니다.

namespace CustomExceptionHandleDemo.Exceptions
{
 public class CustomException : Exception
 {
 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 public CustomException() { }

 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 /// <param cref="string" name="message">Parameter for message</param>
 public CustomException(string message) : base(message) { }

 /// <summary>
 /// Constructor for <see cref="CustomException"/>
 /// </summary>
 /// <param cref="string" name="message">Parameter for message</param>
 /// <param cref="Exception" name="inner">Parameter for inner</param>
 public CustomException(string message, Exception inner) : base(message, inner) { }
 }
}

사용자 정의 예외를 생성한 후 Exception 대신 CustomException을 던지도록 메서드를 업데이트해 보겠습니다.

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new CustomException("This is a custom exception!");
}

이것은 지금은 아무것도 변경하지 않지만 스택 추적은 던져진 객체가 Exception 대신 CustomException임을 보여줍니다. 스택 추적의 시작 부분을 살펴보십시오.

CustomExceptionHandleDemo.Exceptions.CustomException: This is a custom exception!
 at CustomExceptionHandleDemo.Controllers.WeatherForecastController.GetWithoutExceptionHandler()
 at lambda_method24(Closure , Object , Object[] )
 at Microsoft.AspNetCore.Mvc.Infrastructure.ActionMethodExecutor.AwaitableResultExecutor.Execute(IActionResultTypeMapper mapper, ObjectMethodExecutor executor, Object controller, Object[] arguments)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeActionMethodAsync>g__Logged|12_1(ControllerActionInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.<InvokeNextActionFilterAsync>g__Awaited|10_0(ControllerActionInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Rethrow(ActionExecutedContextSealed context)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.Next(State& next, Scope& scope, Object& state, Boolean& isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker.InvokeInnerFilterAsync()
--- End of stack trace from previous location ---
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeFilterPipelineAsync>g__Awaited|20_0(ResourceInvoker invoker, Task lastTask, State next, Scope scope, Object state, Boolean isCompleted)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Mvc.Infrastructure.ResourceInvoker.<InvokeAsync>g__Logged|17_1(ResourceInvoker invoker)
 at Microsoft.AspNetCore.Routing.EndpointMiddleware.<Invoke>g__AwaitRequestTask|6_0(Endpoint endpoint, Task requestTask, ILogger logger)
 at Microsoft.AspNetCore.Authorization.AuthorizationMiddleware.Invoke(HttpContext context)
 at Swashbuckle.AspNetCore.SwaggerUI.SwaggerUIMiddleware.Invoke(HttpContext httpContext)
 at Swashbuckle.AspNetCore.Swagger.SwaggerMiddleware.Invoke(HttpContext httpContext, ISwaggerProvider swaggerProvider)
 at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddleware.Invoke(HttpContext context)

ExceptionFilterAttribute 만들기

Microsoft는 예외가 발생한 후 예외를 처리하는 방법을 제공했습니다. 자세한 내용은 여기에서 확인할 수 있습니다.

그러나 지금까지 그들이 우리에게 제공한 문서는 다음과 같습니다:

작업에서 예외가 발생한 후 비동기적으로 실행되는 추상 필터입니다. 서브클래스는 OnException(ExceptionContext) 또는 OnExceptionAsync(ExceptionContext)를 재정의해야 하지만 둘 다 재정의할 수는 없습니다.

그럼 하나를 만들어 보겠습니다. OnException를 재정의할 CustomExceptionFilterAttribute를 생성하겠습니다.

using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.AspNetCore.Mvc;
using CustomExceptionHandleDemo.Exceptions;

namespace CustomExceptionHandleDemo.ExceptionFilterAttributes
{
 public class CustomExceptionFilterAttribute : ExceptionFilterAttribute
 {
 /// <summary>
 /// OnException
 /// </summary>
 /// <param cref="ExceptionContext" name="context">Parameter for context</param>
 public override void OnException(ExceptionContext context)
 {
 if (context.Exception is CustomException)
 {
 context.HttpContext.Response.StatusCode = 500;
 context.Result = new ObjectResult(context.Exception.Message);
 }
 }
 }
}

보시다시피, 우리는 ExceptionContext를 살펴보고 있는데, 예외가 CustomException 유형일 때 뭔가를 합니다.

이것은 우리가 반환할 응답과 상태 코드를 업데이트하는 것입니다.

상태 코드를 업데이트하려면 context.HttpContext.Response.StatusCode를 업데이트해야 하며, 결과를 반환하려면 ActionResult에서 상속된 객체를 제공하여 context.Result을 업데이트해야 합니다.

이것은 필터이므로 [CustomExceptionFilter]를 추가하여 무언가를 추가해야 함을 의미합니다.

필터 사용하기

이제 우리가 가지고 있는 메소드를 복제하고 이 필터를 추가하여 조치를 취하도록 하겠습니다. API 엔드포인트는 다음과 같습니다.

using CustomExceptionHandleDemo.ExceptionFilterAttributes;
using CustomExceptionHandleDemo.Exceptions;
using Microsoft.AspNetCore.Mvc;

namespace CustomExceptionHandleDemo.Controllers
{
 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
 public WeatherForecastController()
 {
 }

 [HttpGet]
 [Route("GetWithoutExceptionHandler")]
 public Task GetWithoutExceptionHandler()
 {
 throw new CustomException("This is a custom exception!");
 }

 [HttpGet]
 [Route("GetWithExceptionHandler")]
 [CustomExceptionFilter]
 public Task GetWithExceptionHandler()
 {
 throw new CustomException("This is a custom exception!");
 }
 }
}

보시다시피 GetWithExceptionHandler라는 새로운 메서드가 있습니다. 이는 GetWithoutExceptionHandler와 동일한 논리를 가지고 있지만 이 경우에는 메서드에 [CustomExceptionFilter] 필터를 추가했습니다.

메서드를 실행한 후 결과는 다음과 같습니다. 더 이상 스택 추적이 표시되지 않으므로 이미지를 표시하겠습니다.

따라서 이를 통해 우리는 사용자 정의 예외, 즉 예외를 던지고 메서드에서 사용할 때 발생하는 일을 재정의하는 필터를 만들었습니다.

이는 로깅 및 오류가 언제, 어디서 발생하는지 파악하는 등 많은 작업에 사용될 수 있습니다.

물건을 주입하는 더 좋은 방법

Mon, 04 Sep 2023 00:00:00 +0000

서비스, 리포지토리, 속성 또는 애플리케이션에 삽입할 모든 항목을 구축할 때마다 실제로 애플리케이션에 서비스를 추가하는 이 단계를 수행해야 합니다.

이것은 항상 동일합니다. Program.cs로 이동한 다음 서비스를 주입하기 위해 파일 추가 builder.Services.AddScoped<MyService>();의 일부로 진행합니다.

다음과 같은 것 :

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddScoped<ARepository>(); // 👀
builder.Services.AddScoped<BRepository>(); // 👀

// Services
builder.Services.AddScoped<AService>(); // 👀
builder.Services.AddScoped<BService>(); // 👀
builder.Services.AddScoped<CService>(); // 👀
builder.Services.AddScoped<DService>(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

제 말은, 효과는 있지만 제가 까다롭고 별로 좋아하지 않는다는 거죠.

우리가 수행하려는 종속성 주입이 여러 개 있고 실제로는 동일한 것이 아니라고 가정해 보겠습니다. 제 경우에는 모든 저장소를 포함하는 라이브러리, 모든 서비스를 포함하는 또 다른 라이브러리, 마지막으로 속성을 포함하는 또 다른 라이브러리를 갖는 것과 같을 수 있습니다.

그렇다면 Program.cs에 추가해야 할 줄의 양을 상상할 수 있습니까?

일부 서비스가 포함된 라이브러리가 있다고 가정해 보겠습니다. 모든 서비스를 포함하려면 IServiceCollection를 사용하여 작업해야 합니다.

따라서 IServiceCollection를 반환하는 AddServices라는 static 메서드를 갖는 static class를 생성하겠습니다.

이 경우 이름은 IServiceCollectionServicesExtensions로 지정됩니다.

/// <summary>
/// IServiceCollectionServicesExtensions class
/// </summary>
public static class IServiceCollectionServicesExtensions
{
 /// <summary>
 /// AddCoreServices
 /// </summary>
 /// <param cref="IServiceCollection" name="services">Parameter for <see cref="IServiceCollection"/></param>
 /// <returns>An object of type <see cref="IServiceCollection"/></returns>
 public static IServiceCollection AddServices(this IServiceCollection services)
 {
 services
 .AddScoped<AService>()
 .AddScoped<BService>()
 .AddScoped<CService>()
 .AddScoped<DService>();

 return services;
 }
}

뿐만 아니라 이 서비스에서 사용되는 일부 저장소를 포함하는 또 다른 라이브러리도 있으므로 동일한 작업을 수행해 보겠습니다.

/// <summary>
/// IServiceCollectionServicesExtensions class
/// </summary>
public static class IServiceCollectionServicesExtensions
{
 /// <summary>
 /// AddCoreServices
 /// </summary>
 /// <param cref="IServiceCollection" name="services">Parameter for <see cref="IServiceCollection"/></param>
 /// <returns>An object of type <see cref="IServiceCollection"/></returns>
 public static IServiceCollection AddRepositories(this IServiceCollection services)
 {
 services
 .AddScoped<ARepository>()
 .AddScoped<BRepository>();

 return services;
 }
}

이제 주입할 리포지토리와 서비스 메서드가 생겼습니다. 그런데 이를 어떻게 사용합니까?

Program.cs로 돌아가서 다음을 추가해 보겠습니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddRepositories(); // 👀

// Services
builder.Services.AddServices(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

이게 훨씬 더 깔끔해 보이지 않나요? 글쎄요, 우리는 일부 서비스와 리포지토리를 성공적으로 주입했지만 이제 더 보기 좋아 보이고 실제로 외부 라이브러리에 주입한 내용을 갖게 되었습니다.

.NET API의 특성을 사용한 종속성 주입

Tue, 22 Aug 2023 00:00:00 +0000

종속성 주입은 아마도 현재 .NET에서 제공하는 최고의 기능 중 하나일 것입니다. 당신이 그것을 사용하지 않을 가능성은 전혀 없습니다. 따라서 당신이 나와 같다면 당신이 만드는 모든 구현에 그것을 추가하고 싶을 것입니다.

공식 Microsoft의 문서에 따른 필터:

ASP.NET Core의 필터를 사용하면 요청 처리 파이프라인의 특정 단계 전후에 코드를 실행할 수 있습니다.

내장 필터는 다음과 같은 작업을 처리합니다.

승인, 사용자가 승인되지 않은 리소스에 대한 액세스를 방지합니다.

응답 캐싱, 캐시된 응답을 반환하기 위해 요청 파이프라인을 단락시킵니다.

교차 편집 문제를 처리하기 위해 사용자 정의 필터를 만들 수 있습니다. 교차 편집 문제의 예로는 오류 처리, 캐싱, 구성, 권한 부여 및 로깅이 있습니다. 필터는 코드 중복을 방지합니다.

저는 API로 많은 작업을 하고 있으며 모든 단일 요청 또는 거의 모든 요청을 실행해야 하는 몇 가지 작업이 있습니다. 따라서 이상적으로 우리가 원하는 것은 API를 사용하여 작업하는 것입니다…. 종속성 주입!

하지만 때로는 약간의 트릭일 수도 있습니다. ActionAttribute에서 상속하려는 경우 원하는 대로 작동하지 않으므로 OnActionExecutionAsync를 재정의할 때 작업을 수행할 수 있는 TypeFilterAttribute로 작업해야 합니다.

저는 보통 로깅을 수행하기 위해 이 필터를 생성하므로 이를 예로 사용하겠습니다.

/// <summary>
/// LoggedQueryAttribute class
/// </summary>
public class LoggedQueryTypeFilterAttribute : TypeFilterAttribute
{
 /// <summary>
 /// Constructor for <see cref="LoggedQueryTypeFilterAttribute"/>
 /// </summary>
 public LoggedQueryTypeFilterAttribute() : base(typeof(LoggedQueryFilter))
 {
 }

 /// <summary>
 /// LoggedQueryFilter class
 /// </summary>
 private class LoggedQueryFilter : IAsyncActionFilter
 {
 /// <summary>
 /// <see cref="_loggingService"/> object
 /// </summary>
 private readonly LoggingService _loggingService;

 /// <summary>
 /// Constructor for <see cref="LoggedQueryFilter"/>
 /// </summary>
 /// <param cref="LoggingService" name="loggingService">Parameter for loggingService</param>
 public LoggedQueryFilter(LoggingService loggingService)
 {
 _loggingService = loggingService;
 }

 /// <summary>
 /// OnActionExecutionAsync
 /// </summary>
 /// <param cref="ActionExecutingContext" name="context">Parameter for context</param>
 /// <param cref="ActionExecutionDelegate" name="next">Parameter for next</param>
 public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
 {
 // Get properties
 var properties = (Request)context.ActionArguments.First().Value!;

 // Get call from context
 var call = context.HttpContext.Request.Path.Value!;

 // Logging
 _loggingService.LogCustomEvent(call);

 // Continue call
 await next();
 }
 }
}

논리는 매우 간단합니다. context.ActionArguments.First().Value를 사용하여 context 객체에 액세스하여 본문을 얻고, 또한 context.HttpContext.Request.Path.Value를 사용하여 메서드 호출을 수행합니다.

그런 다음 서비스에서 메서드를 호출합니다. 이 경우에는 _loggingService.LogCustomEvent(call)입니다.

그런 다음 파이프라인이 계속되어야 하므로 await next();를 호출해야 합니다.

이는 속성에 대한 것이므로 실제로 이 속성을 메소드에 포함해야 합니다.

[LoggedQueryTypeFilterAttribute]
public ActionResult<string> TestFilter()
{
 return Ok("Hello world!");
}

재미있게 보셨기를 바라며, 궁금하신 점이나 연락하고 싶으신 점이 있으시면 주저하지 마시고 연락주세요!

외부 라이브러리가 포함된 Swagger 문서

Fri, 17 Feb 2023 00:00:00 +0000

여러 라이브러리를 사용하여 향후 사례를 위해 코드를 분할하는 것은 좋은 일입니다. 개인적으로 나는 로직을 분할하여 다른 프로젝트나 프로젝트의 일부에서 재사용할 수 있다면 이 작업을 좋아합니다.

적어도 나에게는 Entity Framework을 포함하는 데이터 모델을 분할하여 Console application, Blazor application 또는 API에서 참조하고 사용할 수 있도록 해야 합니다.

제가 작업을 수행하는 방법에 대한 예를 살펴보겠습니다. 이것은 몇 가지 애플리케이션이 있는 프로젝트의 스크린샷과 모든 모델이 있는 공유 라이브러리입니다.

이것은 각 속성과 클래스에 대한 summary 문서가 포함된 API 프로젝트에서 이동한 클래스의 예입니다.

namespace CustomLibrariesDocumentation.Models
{
 /// <summary>
 /// WeatherForecast class
 /// </summary>
 public class WeatherForecast
 {
 /// <summary>
 /// Gets or sets the Date
 /// </summary>
 public DateOnly Date { get; set; }

 /// <summary>
 /// Gets or sets the TemperatureC
 /// </summary>
 public int TemperatureC { get; set; }

 /// <summary>
 /// Gets or sets the TemperatureF
 /// </summary>
 public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

 /// <summary>
 /// Gets or sets the Summary
 /// </summary>
 public string? Summary { get; set; }
 }
}

Console application를 참조하고 모델을 사용하기 시작하면 문서를 볼 수 있습니다. 이는 Visual Studio의 표준 기능이므로 여기에서 볼 수 있듯이 잘 작동합니다.

그러나 API를 참조하고 Swagger로 이동하면 요약 문서가 없습니다.

이 문제를 어떻게 해결하나요?

먼저, 라이브러리에서 XML 주석을 활성화해야 합니다. 이를 위해서는 프로젝트 설정을 업데이트하고 ``:

그러면 여기에서 볼 수 있듯이 빌드 폴더에 파일 확장자 xml로 끝나는 일부 파일이 생성됩니다.

이제 이 작업이 완료되었으므로 Program.cs에 몇 가지 항목을 추가해야 해당 파일을 읽을 수 있습니다. 이는 기본적으로 해당 프로젝트의 XML 정의만 로드하기 때문입니다.

이는 AddSwaggerGen 내부에 있는 IncludeXmlComments라는 메서드를 사용합니다.

아이디어는 xml 파일이 모두 있으면 해당 파일을 Swagger에 강제로 로드한다는 것입니다.

builder.Services.AddSwaggerGen(s =>
{
 // Comments
 var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

 foreach (string xmlFiles in allXmlFiles)
 {
 s.IncludeXmlComments(xmlFiles);
 }
});

간단히 말해, 빌드 디렉터리에서 xml 파일을 가져와 IncludeXmlComments 메서드를 사용하여 추가합니다.

이제 API를 다시 로드하고 문서를 볼 수 있는지 확인합니다.

그리고 우리가 문서를 볼 수 있다는 것을 알 수 있습니다!

도움이 되셨길 바라며, 궁금한 점이 있으시면 언제든지 연락주세요!

Git의 로컬 지점 정리

Mon, 30 Jan 2023 00:00:00 +0000

현지 지점이 너무 많아진 적이 있나요? 우리는 각 기능, 버그 또는 잡일에 대해 브랜치를 사용하기 때문에 이런 일이 많이 발생합니다.

결국 이런 일이 생기고 시간이 지나면 너무 더러워지죠

정말 짜증나서 이 정리 작업을 수행하기 위해 콘솔에서 실행할 수 있는 빠른 명령을 공유하겠습니다!

Powerhsell에서 실행되는 버전인 Robert Corvus의 다음 답변에서 스택 오버플로에서 이 명령을 찾았습니다.

변경 사항이 손실될 수 있으므로 이 명령을 실행할 때 주의하세요

실행하기 전에 MY_MASTER_BRANCH_NAME를 기본 브랜치로 업데이트해야 합니다. 이는 제가 사용하는 것처럼 master이거나 기본적으로 제공되는 main라는 새로운 브랜치일 수 있습니다.

git branch | %{ $_.Trim() } | ?{ $_ -ne 'MY_MASTER_BRANCH_NAME' } | %{ git branch -D $_ }

이 명령을 실행하면 다음과 같은 출력이 표시됩니다.

그것이 당신에게 도움이 되기를 바랍니다!

ASP.NET Core 7에서 ID의 경로 업데이트

Mon, 23 Jan 2023 00:00:00 +0000

Microsoft라는 이름이 왜 그렇게 희귀한지 궁금하십니까? 나는 항상 그들이 그렇게 훌륭하게 해내지는 않는다고 생각했지만, 글쎄요, 그게 바로 그거예요!

이것의 좋은 점은 개발하는 동안 거의 모든 것을 변경할 수 있다는 것입니다!

페이지에 들어가서 등록이나 로그인 프로세스를 수행하는 것만으로 이것이 ASP.NET 웹 프로젝트라는 것을 즉시 깨달은 적이 있습니까?

여러분이 생성한 프로젝트에는 기본적으로 로그인 및 등록 프로세스를 수행하는 데 필요한 URL이 있기 때문에 이런 일이 많이 발생했습니다(또한 다른 페이지도 많이 있습니다).

따라서 이 튜토리얼에서는 해당 URL을 업데이트하여 프로젝트가 더 멋지게 보이도록 하는 방법을 보여줍니다!!

기본 동작

Blazor 프로젝트를 생성하고 이를 ID와 함께 사용하기로 결정하면 다음과 같이 표시됩니다.

그리고 로그인이나 등록 프로세스를 수행하려고 하면 /Identity/Account/Login 또는 /Identity/Account/Register로 이동합니다.

하지만 해당 URL을 다르게 업데이트할 수 있다고 말하면 어떻게 될까요?

`Login` 및 `Register` 페이지 스캐폴딩

Microsoft는 이러한 페이지를 업데이트하기 위해 해당 페이지를 숨기지만 사용자는 신속하게 페이지를 스캐폴드하고 원하는 변경을 수행할 수 있습니다!

그렇게 하려면 다음과 같이 프로젝트의 컨텍스트 메뉴에서 Add Scaffolded Item로 이동해야 합니다.

그런 다음 모달이 팝업되고 Identity를 두 번 선택하고 Add를 클릭해야 합니다.

이 후에는 또 다른 모달이 팝업되어 전체 ID에서 업데이트할 페이지를 선택할 수 있습니다. 업데이트할 수 있는 페이지가 많지만 여기서는 Account/Login 및 Account/Register에 중점을 둘 것입니다.

이제 잠시 작동시킨 후 솔루션 탐색기를 확인하면 몇 가지 새로운 파일을 찾을 수 있습니다.

이러한 새 파일은 ID를 추가하기 위해 ASP.NET을 선택하면 프로젝트에 추가되는 로그인 및 등록 페이지입니다!

URL 업데이트 중

아마도 눈치채셨겠지만 이 파일은 확장자가 cshtml이므로 면도기 파일이므로 지시문을 사용하여 페이지의 URL을 업데이트하겠습니다.

@page "/login"
@model LoginModel

@{
 ViewData["Title"] = "Log in";
}

<h1>@ViewData["Title"]</h1>
<div class="row">
 <div class="col-md-4">
 <section>
 <form id="account" method="post">
 <h2>Use a local account to log in.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email" class="form-label">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="current-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password" class="form-label">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="checkbox mb-3">
 <label asp-for="Input.RememberMe" class="form-label">
 <input class="form-check-input" asp-for="Input.RememberMe" />
 @Html.DisplayNameFor(m => m.Input.RememberMe)
 </label>
 </div>
 <div>
 <button id="login-submit" type="submit" class="w-100 btn btn-lg btn-primary">Log in</button>
 </div>
 <div>
 <p>
 <a id="forgot-password" asp-page="./ForgotPassword">Forgot your password?</a>
 </p>
 <p>
 <a asp-page="./Register" asp-route-returnUrl="@Model.ReturnUrl">Register as a new user</a>
 </p>
 <p>
 <a id="resend-confirmation" asp-page="./ResendEmailConfirmation">Resend email confirmation</a>
 </p>
 </div>
 </form>
 </section>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to log in.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

보시다시피 대부분의 내용은 동일하지만 수업의 첫 번째 줄을 살펴보면 이전에 있었던 내용을 다음과 같이 업데이트했습니다.

@page

에

@page "/login"

글쎄, 그건 쉬웠지, 그렇지? 이제 간단한 테스트를 통해 제대로 작동하는지 확인해 보겠습니다.

우선, 처음에 있는 기본 페이지로 이동하여 아직 작동하는지 확인하겠습니다.

그렇지 않습니다! 이제 /login인 새 URL을 테스트해 보겠습니다.

그리고 그것은 작동합니다 !!

이제 레지스터에 대해서도 동일한 작업을 수행해 보겠습니다. 페이지를 업데이트하고 @page 지시문에 원하는 경로를 추가한 후 테스트해 보겠습니다.

@page "/register"
@model RegisterModel
@{
 ViewData["Title"] = "Register";
}

<h1>@ViewData["Title"]</h1>

<div class="row">
 <div class="col-md-4">
 <form id="registerForm" asp-route-returnUrl="@Model.ReturnUrl" method="post">
 <h2>Create a new account.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="new-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.ConfirmPassword" class="form-control" autocomplete="new-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.ConfirmPassword">Confirm Password</label>
 <span asp-validation-for="Input.ConfirmPassword" class="text-danger"></span>
 </div>
 <button id="registerSubmit" type="submit" class="w-100 btn btn-lg btn-primary">Register</button>
 </form>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to register.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

@page "/login"로 상단 부분을 업데이트했으며 이제 작동하는지 테스트합니다.

또한 작동합니다 !!

그게 다야이 URL을 업데이트하는 방법을 배웠기를 바랍니다. 주로 일부 프로젝트에서 URL을 특정 방식으로 수행하면 ID가 달라 보이기 때문입니다. 하하!

필요한 것이 있으면 저에게 트윗을 보내거나 이메일을 보내주세요. 제가 도와드리겠습니다!

.NET 6 Core API의 사용자 정의 특성

Fri, 09 Dec 2022 00:00:00 +0000

사용자 정의 특성은 정말 사용하기 좋은 것입니다. 최근에 사용하기 시작했습니다. 그 중 하나를 만들고 컨트롤러, 클래스 또는 메서드 자체에서 재사용할 수 있기 때문입니다.

헤더 확인과 같은 일부 보안 작업을 수행하거나 반드시 필요한 매개변수 값을 확인하려는 경우 정말 도움이 됩니다.

제 경우에는 .NET Core API 프로젝트에서 이를 사용하여 모든 요청에 특정 헤더가 포함되어 있는지 확인하겠습니다.

HeaderCheck속성

멋진 .NET Core API를 만든 후에는 폴더 사용을 좋아하므로 항목을 저장할 폴더를 만들어 보겠습니다.

그런 다음 HeaderCheckAttribute 클래스에 논리를 추가하겠습니다.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

namespace DotNet6CustomAttribute.Attributes
{
 public class HeaderCheckAttribute : ActionFilterAttribute
 {
 public override void OnActionExecuting(ActionExecutingContext context)
 {
 // Get all headers
 var headers = context.HttpContext.Request.Headers;

 // Check if headers has x-dotnet-6-custom-attribute
 if (!headers.ContainsKey("x-dotnet-6-custom-attribute"))
 {
 context.Result = new BadRequestObjectResult("The header x-dotnet-6-custom-attribute is missing");
 }
 else if (string.IsNullOrEmpty(headers["x-dotnet-6-custom-attribute"]))
 {
 context.Result = new BadRequestObjectResult("The header x-dotnet-6-custom-attribute can't be null or empty");
 }

 base.OnActionExecuting(context);
 }
 }
}

기본적으로 논리는 먼저 x-dotnet-6-custom-attribute 키가 있는 헤더를 확인하고 헤더가 있으면 값이 있는지 확인하는 것입니다.

두 표현식이 모두 true이면 특정 메시지와 함께 BadRequestObjectResult를 다시 반환합니다.

컨트롤러에 추가하기

이 로직을 여러 위치에 추가할 수 있고, 전체 컨트롤러에 직접 추가할 수도 있고, 일부 메서드에 추가할 수도 있습니다. 먼저 메서드에 추가한 다음 전체 컨트롤러에 추가하겠습니다.

그럼 WeatherForecastController 클래스를 그것들로 장식해 봅시다.

using DotNet6CustomAttribute.Attributes;
using Microsoft.AspNetCore.Mvc;

namespace DotNet6CustomAttribute.Controllers
{
 [ApiController]
 [Route("[controller]")]
 public class WeatherForecastController : ControllerBase
 {
 private static readonly string[] Summaries = new[]
 {
 "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
 };

 private readonly ILogger<WeatherForecastController> _logger;

 public WeatherForecastController(ILogger<WeatherForecastController> logger)
 {
 _logger = logger;
 }

 [HttpGet]
 [Route("GetWeatherForecastWithCheck")]
 [HeaderCheckAttribute]
 public IEnumerable<WeatherForecast> GetWithCheck()
 {
 return Enumerable.Range(1, 5).Select(index => new WeatherForecast
 {
 Date = DateTime.Now.AddDays(index),
 TemperatureC = Random.Shared.Next(-20, 55),
 Summary = Summaries[Random.Shared.Next(Summaries.Length)]
 })
 .ToArray();
 }

 [HttpGet]
 [Route("GetWeatherForecastWithoutCheck")]
 public IEnumerable<WeatherForecast> GetWithoutCheck()
 {
 return Enumerable.Range(1, 5).Select(index => new WeatherForecast
 {
 Date = DateTime.Now.AddDays(index),
 TemperatureC = Random.Shared.Next(-20, 55),
 Summary = Summaries[Random.Shared.Next(Summaries.Length)]
 })
 .ToArray();
 }
 }
}

프로젝트를 실행해보자!

여기에는 GetWeatherForecastWithCheck 및 GetWeatherForecastWithoutCheck라는 두 가지 기능이 있습니다. 그 중 하나는 실패하고 다른 하나는 실패하지만 Swagger에서 확인해 보겠습니다!

그 중 하나는 메시지와 함께 400 오류를 반환하고 다른 하나는 값을 반환하는 것을 볼 수 있듯이 이제 이를 완전히 테스트하기 위해 Postman을 실행하고 헤더를 추가하여 GetWeatherForecastWithCheck를 사용하여 데이터도 볼 수 있도록 하겠습니다.

우편배달부

이제 Postman에서 실행하면서 헤더를 추가하고 오류 메시지가 변경된 것을 확인합니다. 이제 헤더를 제공하지만 값이 없기 때문입니다.

여기에 값을 추가하면 마침내 값을 얻게 됩니다!

그게 다야

그게 다야! 아주 간단하죠? 이제 속성을 생성하고 이를 메서드와 컨트롤러에 할당하는 방법을 알았습니다!

그들과 함께 즐거운 시간을 보내세요!

코드

이 전체 프로젝트는 Github에 있으며 여기에서 찾을 수 있습니다!

문제나 질문이 있는 경우 소셜 미디어 @emimontesdeoca로 언제든지 저에게 연락해 주세요(트위터에서는 실제로 @emimontesdeocaa이고 끝에 두 개의 aa가 있습니다). 블로그 헤더에서 내 소셜 미디어의 대부분을 찾을 수도 있습니다.

게시물이 마음에 드셨기를 바랍니다! 시아!

Blazor에서 구성 요소 로드 처리

Tue, 19 Jul 2022 00:00:00 +0000

Blazor는 정말 훌륭합니다. 특히 상자 로드와 같은 비동기 작업을 수행할 때 보기에도 좋습니다.

저는 페이지, 상태, 구성 요소 등의 로딩을 처리하는 방법에 대해 여러 가지 방법을 시도해 왔습니다. 그리고 마침내 제가 원하는 방식으로 수행할 수 있는 완벽한 방법을 찾은 것 같습니다.

아이디어

각 페이지나 구성 요소에 로드하기 위한 논리를 다시 작성하는 대신 ChildComponent를 사용하여 상위 구성 요소를 빌드하면 여러 번 재사용할 수 있는 변경 사항이 제공됩니다.

LoadingComponent 코드

코드는 매우 간단합니다. 할 일이 그리 많지 않습니다. 로딩 속성이 있는 기본 if, 내부에 토글 기능이 있으면 완료됩니다!

@if (_loaded)
{
 <div class="text-center">
 <div class="spinner-border" role="status">
 <span class="sr-only"></span>
 </div>
 </div>
}
else
{
 @ChildContent
}

@code {
 private bool _loaded = true;

 [Parameter]
 public RenderFragment? ChildContent { get; set; }

 public void ToggleLoad(bool state)
 {
 _loaded = state;
 }
}

사용법

사용법은 매우 간단합니다. 테스트를 위해 새 페이지를 사용하고 방금 생성한 LoadingComponent 구성 요소에 콘텐츠를 넣을 것입니다.

@page "/loading"
@using LoadingBoxes.Components

<LoadingBoxes.Components.LoadingComponent @ref=loadingComponent>
 This is some content
</LoadingBoxes.Components.LoadingComponent>

@code {
 private LoadingComponent loadingComponent;


 protected override async Task OnInitializedAsync()
 {
 // We are going to simulate some load
 await Task.Delay(5000);

 loadingComponent.ToggleLoad(false);
 }

}

이렇게 생겼어요

더 재미있는 예

각각의 로딩 시간이 있는 여러 구성요소가 있다고 가정해 보겠습니다. 그에 따라 좋아 보이는 것을 만들 수 있습니다!

재사용할 수 있는 FakeLoadingComponent라는 가짜 로딩 구성 요소를 만들어 보겠습니다.

@using LoadingBoxes.Components

<LoadingBoxes.Components.LoadingComponent @ref=loadingComponent>
 It took @ellapsedTime seconds!
</LoadingBoxes.Components.LoadingComponent>

@code {
 private LoadingComponent loadingComponent = new();
 private int ellapsedTime = 0;
 private Random rnd = new();

 protected override async Task OnInitializedAsync()
 {
 var random = rnd.Next(0, 5000);

 // We are going to simulate some load
 await Task.Delay(random);

 ellapsedTime = random/ 1000;

 loadingComponent.ToggleLoad(false);
 StateHasChanged();
 }
}

그런 다음 Loading 페이지를 여러 FakeLoadingComponent 구성 요소로 업데이트하고 결과를 확인합니다!!

@page "/loading"
@using LoadingBoxes.Components

<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>

이제 이게 훨씬 좋아 보이는데

그리고 그게 다야!

문제나 질문이 있는 경우 소셜 미디어 @emimontesdeoca로 언제든지 저에게 연락해 주세요(Twitter에서는 실제로 @emimontesdeocaa이고 끝에 두 개의 aa가 있습니다). 블로그 헤더에서 내 소셜 미디어의 대부분을 찾을 수도 있습니다.

게시물이 마음에 드셨기를 바랍니다!

인증서에서 만료 날짜 가져오기

Fri, 27 May 2022 00:00:00 +0000

저희가 사용하는 도메인의 인증서 현재 상태를 확인하는 데 도움이 되는 몇 가지 웹 앱이 있으며 그 중 몇 가지가 있습니다.

하루에 한 번 실행되고 살펴봐야 할 도메인 몇 개를 확인하는 Azure 함수를 만들었습니다. 인증서 만료 날짜가 30일 미만이면 이메일을 보내는 매우 간단한 콘솔 애플리케이션입니다.

함수가 어떻게 작동하는지에 대한 논리 자체는 표시되지 않으며, 인증서의 기본 확인을 수행하는 함수와 우리가 얻는 데이터를 보여주고 싶습니다.

함수

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

이 CheckCertificateAsync 메소드는 만료 날짜 확인을 포함하여 다양한 작업을 수행할 수 있는 X509Certificate2 인증서를 반환합니다.

직렬화된 결과

이것은 certificate 객체의 직렬화된 값입니다.

{
 "Archived":false,
 "Extensions":[
 {
 "KeyUsages":160,
 "Critical":true,
 "Oid":{
 "Value":"2.5.29.15",
 "FriendlyName":"Key Usage"
 },
 "RawData":"AwIFoA=="
 },
 {
 "EnhancedKeyUsages":[
 {
 "Value":"1.3.6.1.5.5.7.3.1",
 "FriendlyName":"Server Authentication"
 },
 {
 "Value":"1.3.6.1.5.5.7.3.2",
 "FriendlyName":"Client Authentication"
 }
 ],
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.37",
 "FriendlyName":"Enhanced Key Usage"
 },
 "RawData":"MBQGCCsGAQUFBwMBBggrBgEFBQcDAg=="
 },
 {
 "CertificateAuthority":false,
 "HasPathLengthConstraint":false,
 "PathLengthConstraint":0,
 "Critical":true,
 "Oid":{
 "Value":"2.5.29.19",
 "FriendlyName":"Basic Constraints"
 },
 "RawData":"MAA="
 },
 {
 "SubjectKeyIdentifier":"634E1585565AA49402C21642A4A5979A38025797",
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.14",
 "FriendlyName":"Subject Key Identifier"
 },
 "RawData":"BBRjThWFVlqklALCFkKkpZeaOAJXlw=="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.35",
 "FriendlyName":"Authority Key Identifier"
 },
 "RawData":"MBaAFBQusxe3WFbLrlAJQOYfr52LFMLG"
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"1.3.6.1.5.5.7.1.1",
 "FriendlyName":"Authority Information Access"
 },
 "RawData":"MEcwIQYIKwYBBQUHMAGGFWh0dHA6Ly9yMy5vLmxlbmNyLm9yZzAiBggrBgEFBQcwAoYWaHR0cDovL3IzLmkubGVuY3Iub3JnLw=="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.17",
 "FriendlyName":"Subject Alternative Name"
 },
 "RawData":"MB6CHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20="
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"2.5.29.32",
 "FriendlyName":"Certificate Policies"
 },
 "RawData":"MEMwCAYGZ4EMAQIBMDcGCysGAQQBgt8TAQEBMCgwJgYIKwYBBQUHAgEWGmh0dHA6Ly9jcHMubGV0c2VuY3J5cHQub3Jn"
 },
 {
 "Critical":false,
 "Oid":{
 "Value":"1.3.6.1.4.1.11129.2.4.2",
 "FriendlyName":"SCT List"
 },
 "RawData":"BIH0APIAdwBByMqx3yJGShDGoToJQodeTjGLGwPr60vHaPCQYpYG9gAAAYCeJIwYAAAEAwBIMEYCIQCG8sf4iBitUjNCc1dsxVd5mdRQCKapRqqnTHKxSKHjHgIhAJFGNXEZkCHKygT1T7bE4orpd6p2l1+GmifMEIuRsgHbAHcARqVV63X6kSAwtaKJafTzfREsQXS+/Um4havy/HD+bUcAAAGAniSMNgAABAMASDBGAiEAoxv1LBn/vfyR7s67kRLB/n1tq3eicuA/8/V0S2YzQCYCIQDXaS3FZbdIVNxQvKxPFxM1awBO/sGxBXafz0lspOoWSA=="
 }
 ],
 "FriendlyName":"",
 "HasPrivateKey":false,
 "PrivateKey":null,
 "IssuerName":{
 "Name":"CN=R3, O=Let's Encrypt, C=US",
 "Oid":{
 "Value":null,
 "FriendlyName":null
 },
 "RawData":"MDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJSMw=="
 },
 "NotAfter":"2022-08-05T10:50:35+01:00",
 "NotBefore":"2022-05-07T10:50:36+01:00",
 "PublicKey":{
 "EncodedKeyValue":{
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 },
 "RawData":"MIIBCgKCAQEAq8cbDO3GAfjqqbPPCBdPost8NMRmEubv85gXecll7mZMH5qSfTPuB/ouFWL3tPMf1U8usWeoSUK/48yatzBGwmj1KKlkaW9MS2QkydztRp+kH8LvbzbQvGknuOLWGHBALLT17o/3DYxuA5LnXdY+vLvJWygQoFr2N/XhnhUjcm6OaQEJpIykydfbBQGQSEuQIIw4egpgdHkYJjCOYAsXuSSggN8/FADTCec0RzVjfFTSoJ3hV9HLE9M8MCSXjuo0AJ/MbAxq91S8XmDcRjHCCd7Zw+NjHo8cxZCQ6NqGvn3xwx8ahmmbC+CyDEcIyJJZK2Yv+qE4oS8QZfaX/RaHMwIDAQAB"
 },
 "EncodedParameters":{
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 },
 "RawData":"BQA="
 },
 "Key":{
 "Key":{
 "Algorithm":{
 "Algorithm":"RSA"
 },
 "AlgorithmGroup":{
 "AlgorithmGroup":"RSA"
 },
 "ExportPolicy":0,
 "Handle":{
 "IsInvalid":false,
 "IsClosed":false
 },
 "IsEphemeral":true,
 "IsMachineKey":false,
 "KeyName":null,
 "KeySize":2048,
 "KeyUsage":16777215,
 "ParentWindowHandle":{
 "value":0
 },
 "Provider":{
 "Provider":"Microsoft Software Key Storage Provider"
 },
 "ProviderHandle":{
 "IsInvalid":false,
 "IsClosed":false
 },
 "UIPolicy":{
 "ProtectionLevel":0,
 "FriendlyName":null,
 "Description":null,
 "UseContext":null,
 "CreationTitle":null
 },
 "UniqueName":null
 },
 "LegalKeySizes":[
 {
 "MinSize":512,
 "MaxSize":16384,
 "SkipSize":64
 }
 ],
 "KeyExchangeAlgorithm":"RSA",
 "SignatureAlgorithm":"RSA",
 "KeySize":2048
 },
 "Oid":{
 "Value":"1.2.840.113549.1.1.1",
 "FriendlyName":"RSA"
 }
 },
 "RawData":"MIIFQDCCBCigAwIBAgISBNwTmwP/RTcrEeIgAdMrpaFtMA0GCSqGSIb3DQEBCwUAMDIxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MQswCQYDVQQDEwJSMzAeFw0yMjA1MDcwOTUwMzZaFw0yMjA4MDUwOTUwMzVaMCcxJTAjBgNVBAMTHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCrxxsM7cYB+Oqps88IF0+iy3w0xGYS5u/zmBd5yWXuZkwfmpJ9M+4H+i4VYve08x/VTy6xZ6hJQr/jzJq3MEbCaPUoqWRpb0xLZCTJ3O1Gn6Qfwu9vNtC8aSe44tYYcEAstPXuj/cNjG4Dkudd1j68u8lbKBCgWvY39eGeFSNybo5pAQmkjKTJ19sFAZBIS5AgjDh6CmB0eRgmMI5gCxe5JKCA3z8UANMJ5zRHNWN8VNKgneFX0csT0zwwJJeO6jQAn8xsDGr3VLxeYNxGMcIJ3tnD42MejxzFkJDo2oa+ffHDHxqGaZsL4LIMRwjIklkrZi/6oTihLxBl9pf9FoczAgMBAAGjggJZMIICVTAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFGNOFYVWWqSUAsIWQqSll5o4AleXMB8GA1UdIwQYMBaAFBQusxe3WFbLrlAJQOYfr52LFMLGMFUGCCsGAQUFBwEBBEkwRzAhBggrBgEFBQcwAYYVaHR0cDovL3IzLm8ubGVuY3Iub3JnMCIGCCsGAQUFBzAChhZodHRwOi8vcjMuaS5sZW5jci5vcmcvMCcGA1UdEQQgMB6CHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20wTAYDVR0gBEUwQzAIBgZngQwBAgEwNwYLKwYBBAGC3xMBAQEwKDAmBggrBgEFBQcCARYaaHR0cDovL2Nwcy5sZXRzZW5jcnlwdC5vcmcwggEGBgorBgEEAdZ5AgQCBIH3BIH0APIAdwBByMqx3yJGShDGoToJQodeTjGLGwPr60vHaPCQYpYG9gAAAYCeJIwYAAAEAwBIMEYCIQCG8sf4iBitUjNCc1dsxVd5mdRQCKapRqqnTHKxSKHjHgIhAJFGNXEZkCHKygT1T7bE4orpd6p2l1+GmifMEIuRsgHbAHcARqVV63X6kSAwtaKJafTzfREsQXS+/Um4havy/HD+bUcAAAGAniSMNgAABAMASDBGAiEAoxv1LBn/vfyR7s67kRLB/n1tq3eicuA/8/V0S2YzQCYCIQDXaS3FZbdIVNxQvKxPFxM1awBO/sGxBXafz0lspOoWSDANBgkqhkiG9w0BAQsFAAOCAQEAjSEID5MWonbSiyHbmPYWO8ImCCOjkLGxgY8WJODbrWxFy+xU44UwrWOCkqYZUlv2LRmPqSyZDrIeeHK9VMbGh71oXX+XovikgAr6PpI0Mp897nPWj0XvOBaSYG0s+f+CXMtyt0tWCsQOcl+iT82+Ja71f8gbVL6l7xESewEE78pTKEH8EqD22r8VSD7FNICD8EYQr13v3AuVWObSU/R8Td6SrSVEknw1HgJS4e9nvmrMxBGKOJ+aWrAGiUydehg8M9o2gbGckMhz6D7cwB5l618cYaXKkW1dEOYZHl++qUj1/VPK+FNkiDZOPVNN//PbZuOLwAUIlZvhqGWX5/9PBg==",
 "SerialNumber":"04DC139B03FF45372B11E22001D32BA5A16D",
 "SignatureAlgorithm":{
 "Value":"1.2.840.113549.1.1.11",
 "FriendlyName":"sha256RSA"
 },
 "SubjectName":{
 "Name":"CN=blog.emilianomontesdeoca.com",
 "Oid":{
 "Value":null,
 "FriendlyName":null
 },
 "RawData":"MCcxJTAjBgNVBAMTHGJsb2cuZW1pbGlhbm9tb250ZXNkZW9jYS5jb20="
 },
 "Thumbprint":"28CF960F772ABFF22AA193C291492C27F8E13D4D",
 "Version":3,
 "Handle":{
 "value":2658150705632
 },
 "Issuer":"CN=R3, O=Let's Encrypt, C=US",
 "Subject":"CN=blog.emilianomontesdeoca.com"
}

유효기간

만료 시간을 알기 위해서는 이 객체 내부에 있는 NotAfter 및 NotBefore를 살펴봐야 합니다.

 "NotAfter":"2022-08-05T10:50:35+01:00",
 "NotBefore":"2022-05-07T10:50:36+01:00",

콘솔 애플리케이션

다음 코드 조각은 .NET 6을 기반으로 구축된 간단한 콘솔 애플리케이션으로, 원하는 인증을 확인할 수 있는 다음 결과를 생성합니다.

using Newtonsoft.Json;
using System.Net;
using System.Security.Cryptography.X509Certificates;
using System.Text.Json;

var url = "https://blog.emilianomontesdeoca.com/";

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

var cert = await CheckCertificateAsync(url);

var serializedValue = JsonConvert.SerializeObject(cert);

Console.WriteLine(serializedValue);

Console.ReadLine();

데모 프로젝트

내 Github의 expiration-date-certificate라는 저장소에서 콘솔 애플리케이션을 찾을 수 있습니다.

Blazor에서 요소에 초점 맞추기

Thu, 05 May 2022 00:00:00 +0000

최근에 했던 Wordlzor 게임을 작업한 후, 매우 간단한 기능을 추가해야 했습니다. 즉, 게임에 들어갈 때 전체 게임에 집중해야 했습니다.

사용자가 화면 키보드를 사용할 뿐만 아니라 실제로 게임에 입력할 수 있기 때문에 이 작업이 필요했습니다.

자바스크립트 파일

이를 위해서는 함수를 담을 app.js라는 Javascript 파일을 생성해야 합니다.

window.FocusElement = (element) => {
 element.focus();
};

그런 다음 index.html 파일에 스크립트를 포함해야 합니다.

<script src="js/app.js"></script>

Blazor 구성 요소

스크립트를 초기화한 후에는 집중할 요소를 찾아야 하므로 모든 구성 요소에서 해당 요소를 개체에 참조해야 합니다.

따라서 Blazor 구성 요소에 @ref 속성:

<div @ref=@elementToFocus tabindex="0" >
 This is my focus component
</div>

그런 다음 구성 요소 논리에서 속성을 ElementReference로 가질 수 있습니다.

/// <summary>
/// Reference to element
/// </summary>
private ElementReference elementToFocus;

JSInterop 주입

이제 Javascript 파일에 있는 함수를 호출하려면 JSInterop를 사용해야 합니다.

우선 다음 구문을 사용하여 구성 요소에 주입해야 합니다.

[Inject]
public IJSRuntime JSRuntime { get; set; }

서비스가 주입되면 이제 InvokeVoidAsync와 같은 모든 메서드를 호출할 수 있습니다. 이 메서드는 함수를 호출합니다.

public async Task Focus()
{
 // Focus when initializing
 await JSRuntime.InvokeVoidAsync("window.FocusElement", elementToFocus);
}

그리고 함수 Focus()를 호출하면 우리가 만든 요소에 초점을 맞추게 됩니다. 분명히 요소 자체를 매개변수로 리팩토링하고 전달할 수 있습니다.

제가 어떻게 구현했는지 보고 싶으시면 Wordlzor 소스 코드를 보시면 됩니다. 명령어 모달을 닫을 때 경고와 포커스에 사용했습니다.

GitHub Actions의 VS 데이터베이스 프로젝트에서 *.dacpac 파일 생성

Mon, 18 Apr 2022 00:00:00 +0000

데이터베이스 작업이 필요하고 민첩한 개발을 수행하려면 테이블, SP, 함수를 추가하거나 수정할 때마다 이를 컴파일하고 데이터베이스에 대한 배포 파일을 생성하는 흐름이 있어야 합니다.

저는 오랫동안 이 접근 방식을 사용해 왔습니다. 로컬에서 변경을 수행하고 데이터베이스 프로젝트와 비교한 다음 변경 사항을 커밋하고 푸시하면 데이터베이스로 이동될 bacpac 파일이 생성됩니다.

이는 인간의 실수를 야기할 수 있고 데이터베이스에서는 정말 나쁜 소식이 될 수 있는 손으로 작업을 수행하는 모든 문제를 제거합니다.

데이터베이스 프로젝트

Visual Studio에서 데이터베이스 프로젝트를 만들고 데이터베이스를 가져오면 다음과 같이 됩니다.

이 프로젝트에서 컴파일을 실행하면 모든 구조를 포함하는 dacpac 파일이 생성됩니다.

Github 파이프라인

이제 저장소에 코드가 게시되었으므로 이 프로젝트를 컴파일하고 이 dacpac 파일을 생성하고 다운로드하거나 다른 단계에서 사용할 수 있는 위치에 저장하는 작업을 생성해야 합니다.

name: DacpacGithubActions project build

on:
 push:
 branches: main

jobs:
 build:
 runs-on: windows-latest

 steps:
 - uses: actions/checkout@v2

 - name: Setup MSBuild
 uses: microsoft/setup-msbuild@v1

 - name: Navigate to Workspace
 run: cd $GITHUB_WORKSPACE

 - name: Create Build Directory
 run: mkdir artifacts

 - name: Build Solution
 run: |
 msbuild.exe /t:DacpacGithubActions /p:DebugSymbols=false /p:DebugType=None /p:DeployOnBuild=true /p:WebPublishMethod=FileSystem /p:OutDir="../artifacts"
 
 - name: Upload artifact
 uses: actions/upload-artifact@v1.0.0
 with:
 name: DacpacGithubActionsArtifacts
 path: "../artifacts"

이 작업은 여러 작업을 수행하고 솔루션을 빌드하고 결과를 미리 생성된 artifacts 폴더에 저장한 다음 해당 폴더의 파일을 아티팩트에 업로드합니다.

파이프라인 실행

이제 빌드를 트리거해 보세요. 결과는 다음과 같습니다.

실제로 아티팩트를 다운로드하고 콘텐츠를 살펴보면 향후 지속적인 배포 단계를 구현할 때 필요한 것이 바로 dacpac 파일입니다!

코드

이 전체 프로젝트는 Github에 있으며 여기에서 찾을 수 있습니다!

문제나 질문이 있는 경우 @emimontesdeoca로 소셜 미디어를 통해 저에게 연락해 주세요(Twitter에서는 실제로 @emimontesdeocaa이고 끝에 두 개의 aa가 있습니다). 블로그 헤더에서 내 소셜 미디어의 대부분을 찾을 수도 있습니다.

게시물이 마음에 드셨기를 바랍니다! 시아!

Blazor에서 Javascript Interop을 사용하여 테마 전환

Fri, 01 Apr 2022 00:00:00 +0000

웹 페이지를 열 때마다 플래시백으로 인해 어려움을 겪는 저와 같은 사람들을 위해 Javascript를 사용하여 밝은 모드와 어두운 모드 사이를 전환하고 Javascript Interop을 사용하여 Blazor에서 호출하는 방법에 대한 매우 간단한 솔루션을 제시했습니다.

부모 속성 설정

우선, 식별자로 상위 요소를 식별해야 합니다. 이는 해당 식별자의 값에 따라 색상을 변경하기 때문입니다.

Javascript에서 이를 수행하려면 다음 명령을 실행해야 합니다.

document.documentElement.setAttribute('data-theme', 'YOUR_IDFENTIFIER');

우리의 경우 각 스타일 유형에 대해 light 및 dark라는 두 개의 식별자를 갖고 싶습니다.

로직을 처리하기 위한 자바스크립트 파일 생성

이제 식별자를 업데이트하는 기능이 생겼습니다. 이제 해당 로직을 실행하는 기능을 사용하여 Javscript 파일을 만들어 보겠습니다. 파일 이름은 app.js입니다.

해당 파일에는 앞서 언급한 코드를 호출하는 함수가 있습니다.

var toggleTheme = function (identifier) {
 document.documentElement.setAttribute('data-theme', identifier);
}

Blazor에 Javascript 파일 추가

스크립트가 있는 위치에 추가하여 Blazor 애플리케이션에 스크립트를 추가합니다.

<script src="~/js/app.js"></script>

서비스 생성

이제 Javascript 코드가 있으므로 ThemeToggleService라는 서비스를 생성해야 합니다.

이 서비스는 light 테마와 dark 테마 사이를 전환하는 로직을 처리합니다.

JSInterop 주입

Javascipt를 호출하려면 JSInterop을 호출해야 하므로 주입할 속성을 생성해야 합니다.

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorDarkmodeToggle.Data
{
 private readonly IJSRuntime jSRuntime;

 public ThemeToggleService(IJSRuntime jSRuntime)
 {
 this.jSRuntime = jSRuntime;
 }
}

식별자를 설정하는 함수

이제 서비스가 생성되었으므로 식별자를 설정하는 함수를 생성해 보겠습니다. 이 함수는 페이지의 data-theme만 업데이트합니다.

using Microsoft.AspNetCore.Components;
using Microsoft.JSInterop;

namespace BlazorDarkmodeToggle.Data
{
 public class ThemeToggleService
 {
 private readonly IJSRuntime jSRuntime;

 public ThemeToggleService(IJSRuntime jSRuntime)
 {
 this.jSRuntime = jSRuntime;
 }

 public bool IsLightTheme { get; set; } = true;
 public string GetIdentifier => IsLightTheme ? "light" : "dark";

 public async Task ToggleTheme() {
 IsLightTheme = !IsLightTheme;
 await jSRuntime.InvokeVoidAsync("toggleTheme", GetIdentifier);
 }
 }
}

시작 시 서비스 추가

모든 구성 요소와 페이지에서 서비스를 사용할 수 있도록 하려면 해당 서비스를 Program.cs 파일에 추가해야 합니다.

builder.Services.AddSingleton<ThemeToggleService>();

그러면 파일은 다음과 같이 끝납니다.

using BlazorDarkmodeToggle.Data;
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddServerSideBlazor();
builder.Services.AddSingleton<WeatherForecastService>();
builder.Services.AddSingleton<ThemeToggleService>();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();

app.UseStaticFiles();

app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

app.Run();

Blazor Server 또는 Blazor WebAssembly를 사용하는지에 따라 변경될 수 있다는 점에 유의하세요.

CSS 굽기

이제 코드의 일부가 준비되었으므로 CSS 작업을 시작해야 합니다. 우리가 해야 할 일은 CSS 색상, 배경 등을 처리하는 모든 CSS 속성을 변수로 설정하는 것입니다.

:root {
 --background-color:#ffffff;
 --text-color:#000000;
}

이 작업을 완료하면 식별자를 사용하여 식별자 간에 쉽게 변경할 수 있으며 다른 값 중 하나를 사용하게 됩니다.

[data-theme="dark"] {
 --background-color: #000000;
 --text-color: #ffffff;
}

멋진 애니메이션 페이딩을 위해 transition 속성을 모두 추가하면 보기에도 좋습니다.

* {
 transition: all 250ms;
}

이제 이 변수를 일부 CSS 클래스에 할당하여 Blazor 페이지에서 볼 수 있도록 하겠습니다.

.app-background {
 background-color: var(--background-color);
 width: 200px;
 height: 200px;
}

.app-text {
 color: var(--text-color);
}

head에 파일을 추가하여 Blazor 애플리케이션에 파일을 추가하는 것을 잊지 마세요.

<link href="css/app.css" rel="stylesheet" />

Blazor에서 호출

그럼 이것을 어떻게 테스트해볼까요? 간단하게 유지하기 위해 app-background 클래스가 있는 div를 추가하고 그 안에 app-text 클래스가 있는 p가 있습니다.이제 Pages 폴더 아래에 Theme.razor라는 페이지를 만들고 이에 대한 코드를 추가해 보겠습니다.

@page "/theme"
@using BlazorDarkmodeToggle.Data
@inject ThemeToggleService ThemeToggleService

<button class="btn btn-primary" @onclick=Toggle>Toggle theme</button>

<br />

<div class="app-background">
 <p class="app-text">Hello world!</p>
</div>

@code{
 public async Task Toggle()
 {
 await this.ThemeToggleService.ToggleTheme();
 }
}

/theme로 이동하여 이를 테스트할 수 있지만 탐색 모음에도 추가해 보겠습니다.

<div class="nav-item px-3">
 <NavLink class="nav-link" href="theme">
 <span class="oi oi-list-rich" aria-hidden="true"></span> Theme togle
 </NavLink>
</div>

테스트

보시다시피, 테마, 배경 및 글꼴 색상 변경을 전환하자마자 이것이 얼마나 강력한지 알 수 있습니다. 실제로 CSS에서 이 변수를 사용하여 전체 페이지를 개발하면 다양한 테마를 갖고 전환할 수 있습니다!

정말 대단해요!!

코드

이 전체 프로젝트는 Github에 있으며 여기에서 찾을 수 있습니다!

게시물이 마음에 드셨기를 바랍니다!

리소스

ASP.NET Core Blazor의 .NET 메서드에서 JavaScript 함수 호출

Blazor의 Azure Blob Storage에 파일 업로드

Wed, 23 Mar 2022 00:00:00 +0000

Azure Blob 저장소 서비스는 Azure 생태계에서 가장 많이 사용되는 서비스 중 하나이며, 매우 저렴하면서 많은 파일을 클라우드에 업로드할 수 있습니다. 또한 직접 링크를 통해 액세스하거나 다운로드할 수 있는 직관적인 웹이 있습니다.

전반적으로 꽤 좋은 서비스입니다. 저는 이 서비스를 업무와 개인 프로젝트 모두에 사용해 왔으며 솔직히 가장 좋은 점은 작동 방법이 단순하다는 것입니다.

제가 Azure Blob Storage를 사용한 대부분의 경우는 백엔드에서 작업 등의 결과를 직접 업로드하는 것입니다. 그래서 저는 실제로 웹사이트 등에서 어떤 종류의 파일 업로드도 해본 적이 없습니다. 불길한!

저는 Blazor의 팬이기 때문에 HTML5의 기본 파일 입력을 사용하여 Azure Blob Storage에 파일을 업로드하는 방법을 소개하겠습니다.

전제 조건

Azure 계정(없으면 여기에서 $$$를 사용하여 계정을 만드세요.
IDE(VS, Code 등 모두 작동)
.NET Core 3.0 이상

Azure Blob 저장소 생성

Azure Portal로 이동하여 스토리지 계정을 만들어 보겠습니다.

먼저 Storage accounts를 검색하고 결과를 클릭하세요.

로드된 후 Create를 클릭합니다.

여러 단계가 포함된 양식이 표시되므로 계속해서 작성하세요.

원하는 설정으로 모든 항목을 채운 후 유효성 검사를 통과하고 리소스를 생성합니다.

생성된 후 Go to resource를 클릭합니다. 우리는 API를 가지고 놀 수 있는 연결 문자열을 얻을 것입니다.

리소스 키를 가져옵니다

새로 생성된 리소스에 도달한 후 Security + networking 아래의 Acccess keys로 이동합니다. 로드한 후에는 Connection string 및 Key가 표시됩니다. 나중에 필요하므로 복사하세요!

멋진 Blazor 서버 프로젝트 만들기

이 튜토리얼에서는 Visual Studio 2022를 사용할 예정이지만 앞서 말했듯이 다른 IDE를 사용하고 dotnet CLI를 사용하여 프로젝트를 생성하면 됩니다.

그런 다음 Visual Studio를 사용하여 여러 단계를 거쳐 Blazor 프로젝트를 매우 빠르게 만들어 보겠습니다.

방금 만든 것을 실행하면 다음과 같이 보일 것입니다. 평범한 일반 Blazor 애플리케이션입니다.

이제 프로젝트가 생성되었으므로 몇 가지 UI 작업을 수행하여 리소스의 키, 파일에 대한 InputFile, 작업을 수행하기 위한 버튼 및 작업으로 인해 발생하는 메시지를 채울 수 있는 여러 입력이 포함된 새 페이지를 만들어 보겠습니다.

모델 생성

이를 제대로 수행하려면 몇 가지 모델이 필요합니다. 먼저 연결 문자열, 컨테이너 이름 및 파일을 처리할 BlobRequest 클래스가 있습니다.

또한 모든 것을 깔끔하게 유지하기 위해 Name 및 Data를 저장할 BlobFile라는 클래스를 생성합니다.

Models라는 폴더를 만들어서 모든 것을 분리했습니다.

수업은 매우 간단합니다.```csharp using System.ComponentModel.DataAnnotations;

namespace UploadingFilesAzBlobBlazor.Models { public class BlobRequest { [Required(ErrorMessage = “Connection string is required”)] public string? ConnectionString { get; set; } [Required(ErrorMessage = “Container name is required”)] public string? Container { get; set; } public List? Files { get; set; } } }


```csharp
namespace UploadingFilesAzBlobBlazor.Models
{
 public class BlobFile
 {
 public string? Name { get; set; }
 public byte[]? Data { get; set; }
 }
}

UI 수정

이제 모델이 생성되었으므로 이를 사용하여 UI에 마법을 걸어보겠습니다!

먼저 Pages 폴더 아래에 Upload.razor라는 페이지를 만듭니다.

이 페이지에서는 BlobRequest 클래스를 채울 작은 양식을 추가할 것이므로 ConnectionString, Container 및 Files에 대한 입력을 추가해야 합니다.

@page "/upload"
@using UploadingFilesAzBlobBlazor.Models
@inject IJSRuntime JsRuntime
<PageTitle> Upload</PageTitle>

<h1> Azure blob storage uploader!</h1>

<EditForm Model="@modal" OnValidSubmit="@HandleValidSubmit">
<DataAnnotationsValidator />
<ValidationSummary />

<div class="mb-3">
<label for="connectionString" class="form-label"> Connection string</label>
<InputText class="form-control" id="connectionString" @bind-Value="modal.ConnectionString" />
</div>

<div class="mb-3">
<label for="container" class="form-label"> Container name</label>
<InputText class="form-control" id="container" @bind-Value="modal.Container" />
</div>

<div class="mb-3">
<label for="formFileMultiple" class="form-label"> Files</label>
<InputFile OnChange="OnInputFileChange" class="form-control" id="formFileMultiple" multiple />
</div>

<div class="mb-3">
<button type="submit" class="btn btn-primary"> Submit</button>
</div>
</EditForm>

@code {
 private BlobRequest modal = new();
 private EditContext editContext;
 IReadOnlyList <IBrowserFile> selectedFiles;
 private void OnInputFileChange(InputFileChangeEventArgs e)
 {
 selectedFiles = e.GetMultipleFiles();
 this .StateHasChanged();
 }

 private async Task HandleValidSubmit() {
 // This is where we are going to upload stuff ! 
 await JsRuntime.InvokeVoidAsync("alert", "Files uploaded!");
 }
}

약간의 코드이지만 기본적으로 양식을 렌더링하고 유효성 검사를 처리합니다.

업로드 버튼을 누르고 모든 것이 정상이면 경고가 표시됩니다.

Azure Blob Storage에 업로드

이제 대부분의 UI가 완료되었으므로 Azure Blob Storage API를 처리하고 파일을 업로드할 수 있는 패키지를 설치해 보겠습니다. 꽤 간단합니다.

NuGet 패키지 추가

프로젝트에서 NuGet 패키지를 관리하고 Azure.Storage.Blob를 추가해 보겠습니다.

Azure Blob Storee에 업로드

이제 실제로 파일을 업로드하기 위한 논리를 수행해 보겠습니다. 일반적으로 연결 문자열과 app.config의 키를 사용하지만 이 자습서에서는 입력을 사용하고 거기에 데이터를 제공합니다.

먼저 Azure Blob Storage 클래스에 using를 추가해 보겠습니다.

@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models

그런 다음 Blob Storage에 연결하고 컨테이너가 없으면 컨테이너를 만든 다음 파일을 업로드하는 HandleValidSubmit 메서드에 대해 작업하겠습니다.

private async Task HandleValidSubmit()
{
 try
 {
 // Instantiate container
 var container = new BlobContainerClient(modal.ConnectionString, modal.Container);
 // Create container if not exists
 var createResponse = await container.CreateIfNotExistsAsync();
 // Set access policy
 if (createResponse != null && createResponse.GetRawResponse().Status == 201)
 {
 await container.SetAccessPolicyAsync(Azure.Storage.Blobs.Models.PublicAccessType.Blob);
 }

 // For each file that we have uploaded
 foreach (var file in selectedFiles)
 {
 // New blob
 var blob = container.GetBlobClient(file.Name);
 // Delete any blob with the same name
 await blob.DeleteIfExistsAsync(Azure.Storage.Blobs.Models.DeleteSnapshotsOption.IncludeSnapshots);
 // Create a file stream and use the UploadSync method to upload the Blob.
 using (var fileStream = file.OpenReadStream())
 {
 await blob.UploadAsync(fileStream, new BlobHttpHeaders { ContentType = file.ContentType });
 }
 }

 // Display success message
 await JsRuntime.InvokeVoidAsync("alert", "Files uploaded!");
 }
 catch (Exception e)
 {
 // Display error message
 await JsRuntime.InvokeVoidAsync("alert", "An error ocurred!");
 }
}

코드 테스트하기

이제 코드를 테스트할 시간입니다. 테스트하려면 양식을 작성하고 제출을 클릭하세요.

경고가 표시되고 파일이 Azure Blob Storage에 업로드되어야 합니다. Azure Portal로 이동하여 살펴보세요.

보시다시피 컨테이너도 생성되었고, 이제 컨테이너 안으로 들어가면 우리가 업로드한 파일이 보입니다.

잘했어요!

리팩터링

이제 모든 것이 작동했으므로 코드를 .razor 페이지에서 .razor.cs 클래스로 이동하여 더 보기 좋게 만들어 보겠습니다.

Visual Studio 2022를 사용하는 경우 @code에 마우스를 가져가면 전구가 있고 Extract block to code behind 옵션이 표시되며 표시된 대로 작동합니다!

이제 모든 것이 분리되어 완료됩니다!

코드

이 전체 프로젝트는 Github에 있으며 여기에서 찾을 수 있습니다!

문제나 질문이 있는 경우 @emimontesdeoca로 소셜 미디어를 통해 저에게 연락해 주세요. (트위터에서는 실제로 @emimontesdeocaa 끝에 두 개의 aa가 있습니다.) 블로그 헤더에서 내 소셜 미디어의 대부분을 찾을 수도 있습니다.

게시물이 마음에 드셨기를 바랍니다! 시아!

리소스

Pimcore의 핵심 컨트롤러 재정의

Thu, 10 Dec 2020 00:00:00 +0000

저는 한동안 Pimcore 프로젝트를 진행해 왔지만 평생 PHP와 Symfony를 접해본 적이 없었기 때문에 정말 큰 도전이었습니다.

문서는 훌륭합니다. 정말 훌륭하지만 언어/프레임워크 초보자를 위해 만들어진 것이 아닌 것 같아서 제가 수행한 모든 작업을 기록해야 했습니다.

번들을 사용하여 Pimcore를 확장할 수 있다는 사실을 배운 후 컨트롤러, 자바스크립트 메서드 등을 재정의하는 데 많은 시간을 보냈습니다.

그래서 이번 포스팅에서는 컨트롤러를 어떻게 재정의했는지 설명하겠습니다. 자바스크립트 파일을 재정의하는 방법은 나중에 나올 예정입니다 8.

번들 생성

우선 번들을 생성해야 합니다. Pimcore 문서에 설명된 대로 매우 간단합니다. 프로젝트 폴더에서 bin/console pimcore:generate:bundle --namespace=EmiDemo/EmiDemoBundle을 실행하기만 하면 됩니다.

몇 가지 질문이 표시되지만 걱정할 것은 없습니다.

이전에 선언한 네임스페이스를 사용하여 src 폴더 아래에 새 폴더가 생성되며, 그 안에는 번들에 필요한 모든 파일이 포함됩니다.

또한 플러그인은 Pimcore 관리 사이트에서 감지되지만 비활성화되므로 사용을 시작하려면 활성화해야 합니다.

컨트롤러에서 메서드 재정의

컨트롤러에서 메서드를 재정의하려면 먼저 업데이트하려는 작업을 찾아야 합니다. 이것은 쉬운 것 같지만 제가 일반적으로 수행하는 방법을 알려 드리겠습니다(팀 동료인 Cesar에게서 배웠습니다).

먼저 컨트롤러가 작업을 수행한다고 생각되는 페이지로 이동합니다. 제 경우에는 자산을 열 때 로드되는 페이지를 확인하고 싶습니다.

그런 다음 콘솔을 열고 네트워크 탭으로 이동하여 동일한 단계를 다시 수행하고 작업을 찾으십시오.

이 정보를 통해 자산을 로드하는 작업이 http://localhost/admin/asset/get-data-by-id?_dc=1607601778450&id=2&type=image임을 알 수 있습니다. 이를 통해 컨트롤러 작업이 get-data-by-id임을 알 수 있습니다.

코어 컨트롤러에서 액션 찾기

나에게 가장 간단한 방법은 Visual Studio Code의 모든 파일을 찾는 것입니다.

아마도 둘 이상을 찾을 것이므로 살펴보고 어느 것이 하나인지 결정해야 합니다. 우리의 경우 자산으로 작업 중이므로 AssetController.php를 사용하려는 것이 분명합니다.

코어 컨트롤러 수정

개발자에 따라 다르며 컨트롤러를 재정의하고 거기에서 개발하는 것이 더 빠르기 때문에 일반적으로 수행하지 않습니다. 하지만 먼저 코어 번들의 컨트롤러를 업데이트하여 변경 사항이 작동하는지 확인하는 것이 좋습니다.

우리의 경우에는 메서드 시작 부분에 메시지를 반환하여 제대로 작동하는지 확인하겠습니다.

return $this->adminJson(['success' => false, 'message' => "Overriding the getDataByIdAction in the core!!"]);

그런 다음 자산을 다시 로드하고 네트워크 탭을 확인해 보겠습니다.

거기에 있는 것을 유지하여 나중에 핵심 메시지 대신 번들 메시지를 사용하고 있음을 알 수 있도록 합시다.

이제 우리가 한 일을 추적하기 위해 임시 파일에 복사해 보겠습니다.

해당 변경 사항을 번들로 이동

이제 이러한 변경 사항을 번들로 이동하려면 먼저 핵심 컨트롤러에서 몇 가지 항목이 필요합니다.

네임스페이스
수입품
컨트롤러 이름

그리고 분명히 우리가 재정의하려는 메서드인 getDataByIdAction가 있습니다.

컨트롤러 노출

컨트롤러를 노출해야 합니다. 이를 위해서는 /src/EmiDemo/EmiDemoBundle/Resources/config/pimcore/routing.yml 파일로 이동하여 다음을 추가해야 합니다.

options:
 expose: true

또한 prefix를 재정의할 항목(이 경우에는 admin 컨트롤러)으로 변경해야 합니다.

그래서 결국에는 이런 모습이 될 것입니다

emi_demo_emi_demo:
 resource: "@EmiDemoEmiDemoBundle/Controller/"
 type: annotation
 prefix: /admin
 options:
 expose: true

DefaultController.php

파일에서 가져오기를 추가하고 재정의할 컨트롤러로 컨트롤러를 확장합니다.

그런 다음 코어 컨트롤러에서 메서드를 복사하고, 이 경우 반환되는 메시지를 업데이트합니다.

기억하신다면 코어 컨트롤러에 이미 Overriding the getDataByIdAction in the core!! 메시지가 있으며 이제 Overriding the getDataByIdAction in the bundle!!가 표시되어야 합니다.

아무것도 반환하지 않고 이제 이전과 같이 페이지를 볼 수 있는지 살펴보겠습니다.

return 문을 주석 처리하고 다시 로드하세요.

그게 다야

이 작은 데모를 통해 기존 Pimcore 코어 컨트롤러를 얼마나 쉽게 재정의할 수 있는지 확인할 수 있습니다. 따라야 할 몇 가지 단계가 있지만 어렵지 않습니다. 변경하는 동안 때때로 컨트롤러를 노출하고 캐시를 지우는지 확인하십시오. 때로는 캐시되어 작동하지 않고 단지 캐시만 되어 있다고 생각하게 됩니다.

자바스크립트 파일을 재정의하는 방법이 궁금하다면 다른 튜토리얼을 통해 확인하세요 😁.

Windows 10에서 Apple Magic Keyboard 2 구성

Wed, 11 Nov 2020 00:00:00 +0000

바로 어제 저는 기계식 키보드가 5개 정도 있더라도 Apple Magic Keyboard 2를 구입했습니다. 사용해 보고 싶었고 무선이었기 때문입니다.

내 주요 OS는 Windows 10입니다. 나는 그것을 좋아하고 그것을 바꾸고 싶지 않습니다. 그래서 이를 염두에 두고 키보드가 완벽하게 작동하려면 몇 가지 작업을 수행해야 한다는 것을 알았습니다. 저는 Apple이 어떻게 작동하는지, 그리고 Apple이 장치를 생태계에 유지하는 방법을 알고 있습니다.

문제

키보드를 페어링하면 다음과 같은 몇 가지 사항을 인식할 수 있습니다.

기능키가 작동하지 않습니다
일부 키가 잘못 매핑되었습니다(스페인어 버전에서 이런 일이 발생했습니다).

문서

이 기능을 작동시키려면 웹에서 많은 내용을 읽어야 했지만 작동하는 데 도움이 된 링크는 다음 두 가지입니다.

Apple 키보드 드라이버 설치

이 단계 중 일부는 이전에 언급한 문서에서 가져온 것입니다.

7zip이 없으면 컴퓨터에 설치합니다.
Python(버전 2.x)이 없으면 컴퓨터에 설치합니다.
- 중요: 최신 버전의 Python은 3.x입니다. 하지만 Brigadier 스크립트는 버전 3.x와 호환되지 않으므로 버전 2.x가 필요합니다.
- (옵션) 기본적으로 설치 프로그램은 python.exe를 PATH에 추가하지 않습니다. 원한다면 이 옵션을 활성화해야 합니다. (오른쪽 스크린샷 참조)
- 이미 다른 버전의 Python이 있는 경우 이 옵션을 활성화하고 싶지 않을 것입니다.
Brigadier(최신 Boot Camp 버전을 다운로드하는 데 도움이 되는 Python 스크립트)를 다운로드합니다.
다음 링크를 마우스 오른쪽 버튼으로 클릭한 후 “다른 이름으로 링크 저장…“을 사용하여 파일을 저장하세요. https://raw.githubusercontent.com/timsutton/brigadier/master/brigadier
명령 프롬프트 창(DOS 상자라고도 함)을 열고 디렉터리를 Brigadier 스크립트를 다운로드한 위치로 변경합니다.
Brigadier 스크립트가 “brigadier.txt"로 저장되었다고 가정하고 다음 명령을 실행하십시오.
- 경로에 Python 버전 2.x가 있는 경우: python brigadier.txt –model=MacBook13,2
- 그렇지 않은 경우: [Python 버전 2.x 경로]\python.exe brigadier.txt –model=MacBook13,2
부트캠프의 모든 드라이버가 포함된 큰 번들을 다운로드합니다.
BootCamp라는 폴더를 생성하고 BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\BootCamp.msi 및 BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\AppleKeyboardMagic2를 여기에 복사합니다.
관리자 Powershell을 실행하고 BootCamp.msi를 실행하면 일부 항목이 설치되지만 AppleKeyboardMagic2 폴더의 내용을 사용하여 드라이버를 업데이트해야 합니다.
장치 관리자 시작(devmgmt.msc)
Human Interface Devices 노드를 확장합니다.
Bluetooth HID Device를 찾습니다.
AppleKeyboardMagic2 폴더의 내용을 사용하여 드라이버를 업데이트합니다.
컴퓨터 재부팅

이제 Bluetooth 키보드가 Apple 키보드로 감지된 것을 볼 수 있습니다.

FN 키 동작 업데이트모든 것을 올바르게 설치했다면 FN 키가 기본적으로 활성화되어 있음을 알 수 있습니다. 이는 실제로 `F5` 버튼을 누르려면 `fn` + `F5`를 눌러야 함을 의미합니다.

이 문제를 해결하기 위해 설명서 섹션에 언급된 대로 regedit의 일부 항목을 변경하여 작동하는 솔루션을 찾았습니다.

regedit 열기
HKEY_CURRENT_USER\SOFTWARE\Apple Inc.\Apple Keyboard Support로 이동
OSXFnBehavior를 생성하거나 업데이트하고 0로 설정합니다.
컴퓨터 재부팅

키 매핑 업데이트

매핑에 문제가 있는 경우 SharpKeys를 사용하여 업데이트할 수 있습니다.

사용하기는 정말 간단하지만 레지스트리를 업데이트하므로 업데이트를 활성화하려면 로그아웃하거나 컴퓨터를 다시 시작해야 합니다.

내 경우에는 Windows, alt, º 및 <> 키를 업데이트해야 했습니다.

NuGet 패키지에 컴파일된 라이브러리 추가

Thu, 01 Oct 2020 00:00:00 +0000

얼마 전 우리가 업로드한 너겟 패키지에서 나온 것이므로 누락된 라이브러리에서 NullReferenceException에 대한 버그를 발견했습니다.

기본적으로 몇 가지 프로젝트를 참조하는 라이브러리 클래스를 컴파일했습니다. 빌드 단계에서는 dll 파일을 bin 폴더에 추가하지만 packaging를 너겟 패키지로 설치하고 다른 솔루션에 설치하면 내가 참조하고 bin 폴더에 복사해야 하는 dll 파일이 없습니다.

해결 방법

이 문제를 해결하는 것은 매우 간단합니다. nuspec 파일을 업데이트하고 복사하려는 각 라이브러리에 대해 files 부분에 file를 추가해야 합니다.

<?xml version="1.0" encoding="utf-8"?>
<package >
 <metadata>
 <id>$id$</id>
 <version>$version$</version>
 <title>$title$</title>
 <authors>$author$</authors>
 <owners>$author$</owners>
 <requireLicenseAcceptance>false</requireLicenseAcceptance>
 <license type="expression">MIT</license>
 <projectUrl>$projectUrl$</projectUrl>
 <iconUrl>$projectIconUrl$</iconUrl>
 <description>$description$</description>
 <releaseNotes></releaseNotes>
 <copyright>$copyright$</copyright>
 <tags></tags>
 </metadata>
 <files>
 <file src="bin\Release\MyFile1.dll" target="lib\net47" />
 <file src="bin\Release\MyFile2.dll" target="lib\net47" />
 <file src="bin\Release\MyFile3.dll" target="lib\net47" />
 <file src="bin\Release\MyFile4.dll" target="lib\net47" />
 </files>
</package>

WSL 홈 디렉터리에서 터미널 로드 bash 만들기

Tue, 22 Sep 2020 00:00:00 +0000

출시된 날부터 개발 및 테스트를 위해 WSL을 사랑해 왔지만 터미널 앱이 중단되었고 더할 나위 없이 기뻤고, 보기에도 좋고, 완벽하게 작동하고, 훌륭한 성능을 발휘했습니다.

제공되는 콘솔을 사용하는 대신 WSL 배포판과 함께 사용하지 않는 것은 어리석은 일입니다.

이 콘솔은 확실히 훌륭하지만 터미널을 사용한 후에는 돌아갈 수 없습니다. 컬러도 훨씬 더 좋습니다.

이제 터미널을 실행하고 새 탭을 열어 WSL 배포판을 로드하면 탑재된 사용자 폴더가 로드됩니다.

cd ~만 수행하면 distro 사용자 폴더만 로드되기 때문에 이것은 실제로 문제가 되지 않습니다.

문제는 이 작업을 계속해서 수행하고 싶지 않으므로 파일을 업데이트하여 자동으로 수행하도록 하겠습니다.

.bashrc

터미널이나 콘솔을 실행하고 프로필 폴더로 이동한 다음 즐겨 사용하는 텍스트 편집기를 사용하여 .bashrc 파일을 편집하세요.

마지막 명령 앞의 파일 끝에 cd ~를 추가합니다.

저장하고 터미널을 사용하여 WSL 콘솔을 다시 열면 프로필 폴더에 있어야 합니다.

단일 WSL에 대해 bashrc 파일을 업데이트하므로 모든 WSL 설치에 대해 이 작업을 수행해야 한다는 점을 명심하세요.

ExpandoObject를 사용한 동적 개체 생성

Fri, 06 Mar 2020 00:00:00 +0000

자체적으로 정의된 열이 있는 Excel 파일을 동적 열이 있는 새 파일로 변환해야 했는데 심각한 성능 문제 없이 이를 올바르게 수행하는 방법이 다소 혼란스러웠습니다.

저는 .NET ExpandoObject를 사용하는 여기를 찾을 수 있는 튜토리얼을 찾았습니다. 이를 통해 객체를 생성하고 동적 구성원을 추가할 수 있습니다.

ExpandoObject

Microsoft 정의는 다음과 같습니다.

런타임 시 동적으로 멤버를 추가하고 제거할 수 있는 개체를 나타냅니다.

그리고 여기에는 몇 가지 설명이 있습니다.

ExpandoObject 클래스를 사용하면 런타임에 해당 인스턴스의 멤버를 추가 및 삭제할 수 있으며 이러한 멤버의 값을 설정하고 가져올 수도 있습니다. 이 클래스는 동적 바인딩을 지원하므로 SampleObject.GetAttribute(“sampleMember”)와 같은 더 복잡한 구문 대신 SampleObject.sampleMember와 같은 표준 구문을 사용할 수 있습니다.

현재 동작

List<T>를 전달하여 이 경우에는 ExcelItem를 전달하여 Reflection를 사용하여 xlsx 파일을 생성하는 ExcelExportService가 있습니다.

지금까지 우리의 코드는 다음과 같습니다:

class ExcelItem
 {
 public int Id { get; set; }
 public string Name { get; set; }
 public string Surname { get; set; }
 public string Age { get; set; }
 public string CreatedAt { get; set; }
 public string UpdatedAt { get; set; }
 }

ExcelItem은 Excel 파일을 생성하는 데 사용되는 모든 속성을 포함하는 개체입니다.

public static byte[] GetExcelBytes() {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var items in itemsToExcel)
 {
 excelItems.Add(new ExcelItem()
 {
 Id = item.Id,
 Name = item.Name,
 Surname = item.Surname,
 Age = item.Age,
 CreatedAt = item.CreatedAt
 UpdatedAt = item.UpdatedAt
 });
 }

 return exportService.ExportToExcel(excelItems);
}

이 접근 방식은 완벽하게 작동합니다. xlsx 파일은 각 열이 각 속성인 문제 없이 생성됩니다. 예를 들어 다음과 같이 GetExcelBytes 메서드를 사용하여 파일에 저장합니다.

File.WriteAllBytes("path-to-somewhere/my-file.xlsx", GetExcelBytes());

문제

우리가 하고 있는 일은 ExcelItem 객체의 모든 속성을 사용하는 것이기 때문에 실제로 모든 속성을 사용하지 않고 2~3개만 사용하는 것이 좋습니다.

또한 요구 사항은 코드를 변경하고 싶지 않다는 것입니다. 모든 작업은 표시할 열을 결정하는 administrator에 의해 수행되어야 하며 코드의 속성을 알 수도 모를 수도 있습니다.

TLDR: 모든 것이 동적이어야 합니다. 속성이 있는 객체가 있고 생성된 파일에 해당 객체의 N 속성이 있는지 확인해야 하지만 하드코딩되지는 않았습니다.

동적 열

변경 사항은 dynamic 객체를 사용하는 것입니다. 왜냐하면 열 목록을 생성하는 데 사용할 객체의 속성을 설정하려고 하기 때문입니다.

1톤과 같은 많은 속성을 가진 객체가 있고 변경할 때마다 ExcelItem 객체를 변경하고 싶지 않고 ColumnExcelItem 테이블을 생성하고 해당 ExcelItem를 생성하는 데 사용된다고 가정해 보겠습니다.

데이터베이스 구조

우리는 이 정의를 다음과 같이 데이터베이스에 저장합니다.

Id PropertyName
---------------------
1 Name
2 Surname
3 Age

ExcelItem 객체의 기존 속성보다 더 적은 값을 가지며, 6 속성을 가지며 데이터베이스에는 3만 나열됩니다.

또한 PropertyName는 동적 할당에 사용할 객체의 속성 이름과 일치해야 합니다.

객체 만들기

이제 데이터베이스 테이블이 있으므로 이를 가져오고 코드에서 사용할 수 있도록 저장소를 구축해야 합니다.이 부분에 대한 튜토리얼은 만들지 않을 것이며, 새로운 GetExcelBytes() 함수 시작 부분에서는 바로 건너뛰겠습니다.

public static byte[] GetExcelBytes(List<string> columns) {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 List<dynamic> objectsToExcel = new List<dynamic>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var item in itemsToExcel)
 {
 dynamic newObject = new ExpandoObject();
 foreach (var col in columns)
 {
 this.AddProperty(newObject, col, product.GetType().GetProperty(col).GetValue(item, null));
 }

 objectsToExcel.Add(newObject);
 }

 return exportService.ExportToExcel(objectsToExcel);
}

이제 우리는 ExcelItem의 일부 속성을 사용하지만 완전히 동적인 객체를 생성하게 됩니다. 6개의 속성을 모두 사용하는 대신 우리는 그 중 우리가 보내고 싶은 속성 3개만 사용하고 있습니다.

이제 이 ExcelItem 객체에 200개의 속성이 있다고 가정해 보겠습니다. 미친 일이지만 그런 일이 일어날 수도 있습니다.

내가 해야 할 유일한 일은 Excel 파일에 렌더링하려는 속성을 ColumnExcelItem 테이블에 삽입하는 것뿐입니다.

사례

이 경우에는 단일 사례를 사용했지만 일부 사용자에 대해 다른 보고서를 갖고 싶다고 가정해 보겠습니다. admin 역할이 모든 속성을 가져와야 한다고 가정하면 데이터베이스에 다음과 같은 구조를 생성할 것입니다.

ReportingTemplates

Id PropertyName
---------------------
1 Admin
2 Users

ReportingTemplateItems

Id TemplateId PropertyName
---------------------
1 1 Id
2 1 Name
3 1 Surname
4 1 Age
5 1 CreatedAt
6 1 UpdatedAt
7 2 Name
8 2 Surname
9 2 Age

그런 다음 템플릿을 가져오면 서로 다른 열을 가질 수 있으며 모두 동적으로 코드와 관련이 없습니다.

Admins 역할을 가진 사용자가 있는 경우 파일에는 Id, Name, Surname, Age, CreatedAt, UpdatedAt 열이 포함됩니다.

Users 역할을 사용하여 생성하는 경우 Name, Age를 갖게 됩니다. Surname.

결론

이는 .NET에서 dynamic가 어떻게 작동하는지 배울 수 있는 멋진 방법이며, 다양한 사용자를 위해 다양한 역할이나 템플릿이 필요하고 하드코딩에 시간을 투자하는 데 별로 관심이 없을 때 정말 좋은 솔루션입니다.

TravisCI를 사용하여 NuGet 패키지를 지속적으로 제공

Tue, 21 Jan 2020 00:00:00 +0000

최근에 Travis CI를 방금 푸시했거나 master 브랜치에 푸시하려고 하는 코드를 자동으로 테스트하는 도구로 사용하는 방법에 대한 튜토리얼을 작성했습니다. 컴파일하고 테스트하여 최종적으로 변경 상태를 보고합니다.

하지만 계속 더 좋게 만들 수 있습니다. 예를 들어 지난 튜토리얼에서 만든 핵심 라이브러리를 NuGet 피드를 사용하여 공개하여 모든 사람이 라이브러리에서 쉽게 작업할 수 있도록 하고 싶습니다!

하지만 어떻게요? 모든 사람이 자신의 프로젝트에서 다운로드할 수 있도록 해당 패키지를 어떻게 컴파일하고 테스트한 다음 피드에 게시할까요?

자, 이것이 😁에 대한 튜토리얼입니다!

새로운 소식은 무엇인가요?

코드와 관련된 변경 사항은 거의 없습니다. 변경해야 할 사항은 패킹, 게시 및 자동화 방법입니다.

.NET 코어 CLI

.NET Core CLI를 사용할 예정이며, 이전 자습서에서 dotnet restore, dotnet build 및 dotnet test와 같은 명령과 함께 사용했습니다.

이제 우리는 새로운 명령 세트를 사용할 것입니다!

`dotnet nuget`

이 도구 세트에 대한 문서는 바로 여기에서 확인할 수 있지만 간략한 설명은 다음과 같습니다.

dotnet nuget는 패키지 설치, 복원, 제거 및 게시를 포함하는 필수 도구 세트입니다.

NuGet 피드

NuGet은 .NET용 패키지 관리자입니다. NuGet 클라이언트 도구는 패키지를 생성하고 사용하는 기능을 제공합니다. NuGet 갤러리는 모든 패키지 작성자와 소비자가 사용하는 중앙 패키지 저장소입니다.

NuGet은 무료이므로 가입하고 API 키를 받아 패키지 업로드를 시작할 수 있습니다. 모든 사람에게 업로드되고 확인된 후 나열됩니다.

API 키를 가져옵니다

패키지를 업로드하려면 가입 후 API 키를 받아야 하므로 API 키 페이지로 이동하여 새 API 키를 만드세요.

API 키의 만료 기간은 365일입니다.

그런 다음 페이지에 설명된 대로 키를 복사하여 어딘가에 저장하면 다시 볼 수 없으며, 저장하지 않으면 다시 생성해야 합니다.

NuGet 패키지 생성

이제 API 키가 있으므로 다음 단계는 솔루션에서 해당 NuGet 패키지를 생성하는 것입니다. 따라서 클래스 라이브러리가 있는 솔루션을 엽니다.

저는 CalculatorCLI.Core라는 .NET Core 라이브러리 클래스가 있는 마지막 자습서의 솔루션을 사용할 것입니다.

이제 프로젝트 속성으로 이동한 다음 패키지로 이동하면 패키지 버전, 작성자, 설명 등과 같은 패키지에 관한 많은 정보를 볼 수 있습니다.

다음은 이것을 채우는 것입니다. 실제로 모든 것을 채울 필요는 없지만 중요하고 필수 사항은 Package id, Package version, Authors 및 Description입니다. 또한 직접 파일을 업로드하려고 하면 License를 요청하게 되므로 해당 파일도 추가해야 합니다.

그런 다음 저장하고 프로젝트를 마우스 오른쪽 버튼으로 클릭한 다음 Pack를 선택합니다.

1>------ Build started: Project: CalculatorCLI.Core, Configuration: Debug Any CPU ------
1>CalculatorCLI.Core -> D:\Development\Personal\CalculatorCLI-demo\CalculatorCLI\CalculatorCLI.Core\bin\Debug\netstandard2.1\CalculatorCLI.Core.dll
1>Successfully created package 'D:\Development\Personal\CalculatorCLI-demo\CalculatorCLI\CalculatorCLI.Core\bin\Debug\CalculatorCLI.Core.1.0.0.1.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

출력에는 모든 것이 정상이면 Successfully created package가 인쇄되는 것으로 표시됩니다.

`dotnet` 사용

이전 튜토리얼과 마찬가지로 솔루션을 빌드하고 테스트하기 위해 다양한 명령을 사용했습니다. 이제 패키지를 압축하고 게시하는 명령을 더 추가하겠습니다.

해당 명령은 다음과 같습니다.

dotnet pack -c <configuration>
dotnet nuget push <package> <k <apikey> -s <source>

배포 스크립트

빌드 방식을 변경할 예정이므로 환경에 따라 각 파일에 빌드 정의가 포함된 다양한 파일을 갖는 것이 가장 좋은 아이디어라고 생각합니다.

이제 저장소 루트에 3개의 bash 스크립트가 포함된 scripts라는 폴더를 생성해 보겠습니다.

scripts\compile.sh

#!/bin/sh

echo "Restoring..."
dotnet restore ".\CalculatorCLI\CalculatorCLI.sln"

echo "Building..."
dotnet build ".\CalculatorCLI\CalculatorCLI.sln" -c Release

scripts\test.sh

#!/bin/sh

echo "Testing..."
dotnet test ".\CalculatorCLI\CalculatorCLI.sln" -c Release -v n

scripts\push.sh

#!/bin/sh

echo "Packing..."
dotnet pack ./CalculatorCLI/CalculatorCLI.Core/CalculatorCLI.Core.csproj -c Release

echo "Pushing..."
dotnet nuget push ./CalculatorCLI/CalculatorCLI.Core/bin/Release/*.nupkg -s "https://nuget.org" -k $NUGET_API_KEY

`.travis.yml` 파일 개선

이제 소스 코드가 업데이트되었으므로 사용해야 하는 명령을 알았으므로 지속적인 통합과 지속적인 제공을 통합해야 합니다. 이를 통해 우리는 코딩, 테스트, 검토 및 푸시 외에는 아무것도 할 필요가 없습니다.

이제 .travis.yml 파일에 대해 수행할 작업은 다음과 같습니다.

다른 stages 추가
각 stage는 지점에 따라 다릅니다.
빌드가 마스터에 있는 경우 패키지를 업데이트해야 함을 의미하므로 패키지를 NuGet 피드에 푸시합니다.
빌드가 풀 요청인 경우에도 빌드가 컴파일되고 테스트되는지 확인하지만 게시하지는 않을 것입니다.

스테이지

해당 문서에서:

빌드 구성(.travis.yml 파일)에서 조건을 지정하여 빌드, 단계 및 작업을 필터링하고 거부할 수 있습니다.

문서 페이지에서 TravisCI stages에 관한 자세한 정보를 찾을 수 있습니다.

따라서 파일을 변경하고 스테이지를 추가하면 다음과 같이 됩니다.

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

jobs:
 include:
 - stage: compile
 script: bash scripts/compile.sh

 - stage: test
 script: bash scripts/test.sh

 - stage: deploy-prod
 if: branch = master AND type = push
 name: "Deploy to NuGet"
 script: bash scripts/push.sh

보시다시피 compile, test 및 push 세 가지 단계가 있습니다. 마지막 단계는 branch가 master이고 pull request가 아닌 push일 때만 실행됩니다.

이것에 대해 이해하지 못한다면 문서로 가서 아주 쉽게 설명되어 있습니다.

이를 염두에 두고 모든 pull request는 NuGet 피드에 아무 것도 푸시하지 않습니다.

API 키를 환경 변수로 설정

리포지토리 빌드 설정으로 이동하여 NUGET_API_KEY라는 새 환경 변수를 추가합니다. 값은 NuGet 페이지에서 복사한 API 키입니다.

`pull request` 생성

이제 모든 설정이 완료되었으므로 pull request를 만들고 해당 풀 요청에 대한 컴파일이 마지막 stage를 무시하는지 확인해야 합니다.

빌드 확인

끌어오기 요청을 하는 즉시 TravisCI 대시보드에 빌드가 대기열에 추가되며 보시다시피 거기에는 3개가 아닌 2개의 서로 다른 빌드가 있습니다.

이제 pull request를 수락하고 빌드를 다시 확인하여 이제 두 개가 아닌 세 개의 작업이 있는지 확인하겠습니다.

그리고 대기열에 있는 빌드를 보자마자 마지막에 Deploy-prod를 포함한 세 가지 작업을 볼 수 있습니다.

전체 빌드가 완료되자마자 로그에서 패키지가 소스에 푸시되었음을 확인할 수 있습니다.

그리고 분명히 NuGet 페이지에서 볼 수 있습니다.

그게 다야

이 튜토리얼에서는 NuGet 패키지 전달을 자동화하는 방법을 알아냈습니다. 우리는 TravisCI, stages 및 dotnet nuget와 같은 도구를 사용했습니다.

제 생각에는 제대로 설정하는 데 시간이 걸리고 어떤 경우에는 너무 복잡할 수도 있습니다. 모든 것을 완벽하고 자동화된 상태로 유지하기 위해 이러한 종류의 기술에 시간을 투자합니다.

.travis.yml 파일과 함께 소스 코드를 여기에서 찾을 수 있습니다. 궁금한 점이 있으면 언제든지 내 twitter로 문의하세요!

TravisCI를 사용하여 .NET Core 3.0 프로젝트에 대한 지속적인 통합

Tue, 14 Jan 2020 00:00:00 +0000

지난 주말에 저는 다른 저장소에서 해왔던 스크레이퍼-체커-다운로더 프로젝트를 제대로 시작하기로 결정했습니다.

또 다른 프로젝트를 시작한 후에는 CI/CD, 끌어오기 요청, 문서, Readme의 배지 등 제가 본 모든 것이 멋지고 실제로 모범 사례인 것을 사용하여 정말 멋지듯이 멋져야 했습니다.

그리고 좋은 주말을 보낸 후 저는 결국 다양한 소스에서 프로그램을 스크랩하고 다운로드하는 도구 세트인 Dramarr를 만들었습니다.

조직에는 다양한 리포지토리가 있으며 대부분은 풀 요청 및 마스터 브랜치에 병합될 때 자체적으로 컴파일, 테스트 및 배포되는 라이브러리입니다.

이것이 바로 CI/CD 또는 지속적 통합/지속적 전달입니다.

하지만 이 튜토리얼에서는 CI에 대해서만 이야기하겠습니다.

지속적인 통합

그게 뭐죠?

Martin Fowler의 블로그에서 발췌한 내용입니다. 제가 읽은 설명 중 가장 좋은 설명은 다음과 같습니다.

지속적 통합은 팀 구성원이 자신의 작업을 자주 통합하는 소프트웨어 개발 방식으로, 일반적으로 각 사람은 적어도 매일 통합하여 하루에 여러 번 통합하게 됩니다. 각 통합은 자동화된 빌드(테스트 포함)를 통해 검증되어 통합 오류를 가능한 한 빨리 감지합니다.

도구

작업 흐름을 CI/CD와 통합하는 도구는 많지만 이 튜토리얼에서는 Github를 사용하여 코드를 저장하고 TravisCI 도구를 사용하여 CI를 설정합니다. 언어와 프레임워크는 C#과 new.NET Core 3.0을 사용하겠습니다.

요구사항

이 작업을 수행하려면 세 가지 간단한 사항이 필요합니다.

Visual Studio 2019 최신 버전
Github 계정
Github 계정에 연결된 Travis-CI 계정

프로젝트

이 튜토리얼에서는 간단한 계산기를 사용하겠습니다. 우리는 모든 것을 테스트하기 위해 라이브러리, 명령줄 도구 및 테스트 프로젝트를 만들 것입니다.

이 테스트 프로젝트는 CI를 설정할 때도 실행됩니다. 즉, 나중에 코드를 변경하고 처음 만든 테스트가 통과하지 못하는 경우 알림을 받거나 끌어오기 요청을 거부할 수 있습니다.

Github 저장소 생성

먼저 Github 저장소를 생성할 예정이므로 Github에 접속하여 저장소를 생성하고 이를 로컬 환경에 복제하세요. 나는 이 새로운 저장소를 CalculatorCLI-demo라고 부르기로 결정했습니다.

솔루션 만들기

이제 복제된 저장소의 루트 폴더에 CalculatorCLI라는 빈 솔루션을 만들어 보겠습니다.

핵심 라이브러리

실제 프로젝트에서와 마찬가지로 라이브러리를 생성하는 별도의 프로젝트에 로직을 저장할 것이므로 라이브러리를 생성해 보겠습니다.

가서 Class Library (.NET Standard)를 만들고 이름을 CalculatorCLI.Core로 지정하세요.

NET Core 버전프로젝트를 생성하자마자 프로젝트 속성으로 이동하여 `Target framework`를 `.NET Standard 2.1`로 변경하여 `.NET Core 3.0`에 빌드된 프로젝트와 호환되게 만듭니다.

코드

튜토리얼을 위해 작업을 처리하는 간단한 클래스를 만들어 보겠습니다.

using System;

namespace ConsoleCalculator.Core
{
 public enum OperatorsEnum
 {
 ADD,
 SUBSTRACT,
 MULTIPLY,
 DIVIDE
 }

 public class Operation
 {
 public OperatorsEnum OperatorEnum { get; set; }
 public int LeftValue { get; set; }
 public int RightValue { get; set; }

 public Operation(string operatorString, int leftValue, int rightValue)
 {
 switch (operatorString)
 {
 case "+":
 OperatorEnum = OperatorsEnum.ADD;
 break;
 case "-":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "*":
 OperatorEnum = OperatorsEnum.MULTIPLY;
 break;
 case "/":
 OperatorEnum = OperatorsEnum.DIVIDE;
 break;
 default:
 throw new Exception("Operator invalid");
 }

 LeftValue = leftValue;
 RightValue = rightValue;
 }

 public int DoOperation()
 {
 switch (OperatorEnum)
 {
 case OperatorsEnum.ADD:
 return LeftValue + RightValue;
 case OperatorsEnum.SUBSTRACT:
 return LeftValue - RightValue;
 case OperatorsEnum.MULTIPLY:
 return LeftValue * RightValue;
 case OperatorsEnum.DIVIDE:
 return LeftValue / RightValue;
 default:
 throw new Exception("Operator is not valid");
 }
 }
 }
}

CLI

이제 핵심 프로젝트가 있으므로 애플리케이션을 만들어 보겠습니다. 이 경우 인수를 받아들이고 결과를 출력하는 간단한 콘솔 애플리케이션이 됩니다.

그럼 계속해서 새로운 Console App (.NET Core)를 만들어 보겠습니다. 저는 이름을 CalculatorCLI.CLI로 지정했습니다.

NET Core 버전

이전과 마찬가지로 프로젝트를 생성하자마자 프로젝트 속성으로 이동하여 Target framework를 .NET Core 3.0로 변경합니다.

그런 다음 새로 생성된 프로젝트에 ConsoleCLI.Core에 대한 참조를 추가합니다.

코드

이제 코드의 경우 이전보다 더 간단해졌습니다.

using ConsoleCalculator.Core;
using System;
using System.Text.RegularExpressions;

namespace ConsoleCalculator.CLI
{
 public class Program
 {
 public static void Main(string[] args)
 {
 if (args.Length == 0)
 {
 PrintUsage();
 }
 else
 {
 var joinedArgs = string.Join(" ", args);
 var regex = @"-op [\+\-\*\/] -l [-0-9]+ -r [-0-9]+";

 if (Regex.IsMatch(joinedArgs, regex))
 {
 int _left = Int32.Parse(args[3]);
 int _right = Int32.Parse(args[5]);
 string _operator = args[1];

 var _operation = new Operation(_operator, _left, _right);
 var _result = _operation.DoOperation();

 Console.WriteLine($"Result is: {_result}");
 }
 else
 {
 PrintUsage();
 }
 }
 }

 public static void PrintUsage()
 {
 Console.WriteLine($"Welcome to ConsoleCalculator!");
 Console.WriteLine($"");
 Console.WriteLine($"-op Operator, it must be +,-,*,/");
 Console.WriteLine($"-l Left number");
 Console.WriteLine($"-r Left number");
 Console.WriteLine($"");
 Console.WriteLine($"Example usage: -op + -l 5 -r 6");
 }
 }
}

우리는 다음과 같은 명령으로 이 애플리케이션을 사용할 것이므로 작동하게 하려면 일부 매개변수를 전달하여 이를 호출해야 합니다. 예를 들면:

ConsoleCalculator.CLI.exe -op + -l 10 -r 20

이는 다음과 같이 번역됩니다.

ConsoleCalculator.CLI.exe -operator + -leftValue 10 -rightValue 20

이에 대한 코드는 매우 간단합니다. 특정 정규식 패턴과 일치하지 않으면 잘못된 호출이고 PrintUsage()를 호출합니다. 이는 숫자가 아닌 다른 것을 입력하면 정규식에 설정되어 있기 때문에 계산을 시도하지도 않는다는 것을 의미합니다.

즉, 다음과 같이 호출하면 다음과 같습니다.

ConsoleCalculator.CLI.exe -operator + -leftValue asdfg -rightValue ghjk

이는 작업 논리 내부에 입력되지 않으며 값 TryParseing과 같은 향후 검사를 저장합니다.

테스트

핵심 라이브러리와 명령줄이 있지만 지금 테스트가 필요합니다. 왜냐하면 그것이 우리가 CI에서 하고 싶은 일이기 때문입니다.

이제 새 MSTest Test Project (.NET Core)를 만들고 이름을 CalculatorCLI.Tests로 지정하겠습니다.

NET Core 버전

이전과 마찬가지로 프로젝트를 생성하자마자 프로젝트 속성으로 이동하여 Target framework를 .NET Core 3.0로 변경합니다.

그런 다음 새로 생성된 테스트 프로젝트에 ConsoleCLI.Core 및 ConsoleCLI.Core에 대한 참조를 추가합니다.

코드

테스트를 CoreTests.cs 및 CLITests.cs 두 개의 서로 다른 파일로 분할할 예정입니다.

using CalculatorCLI.Core;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System;
using System.Collections.Generic;
using System.Text;

namespace CalculatorCLI.Tests
{
 [TestClass]
 public class CoreTests
 {
 public int _left = 2;
 public int _right = 2;

 [TestMethod]
 public void ShouldAdd()
 {
 var expectedResult = 4;
 var operation = new Operation("+", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldSubstract()
 {
 var expectedResult = 0;
 var operation = new Operation("-", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldMultiply()
 {
 var expectedResult = 4;
 var operation = new Operation("*", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 public void ShouldDivide()
 {
 var expectedResult = 1;
 var operation = new Operation("/", _left, _right);
 var functionResult = operation.DoOperation();

 Assert.AreEqual(functionResult, expectedResult);
 }

 [TestMethod]
 [ExpectedException(typeof(System.DivideByZeroException))]
 public void ShouldThrowExceptionForDivideByZero()
 {
 var operation = new Operation("/", _left, 0);
 operation.DoOperation();
 }

 [TestMethod]
 [ExpectedException(typeof(System.Exception), "Operator invalid")]
 public void ShouldThrowExceptionForWrongOperator()
 {
 var operation = new Operation("text", _left, 0);
 operation.DoOperation();
 }
 }
}

using Microsoft.VisualStudio.TestTools.UnitTesting;
using System;
using System.Collections.Generic;
using System.Text;

namespace CalculatorCLI.Tests
{
 [TestClass]
 public class CLITests
 {
 public string _left = "2";
 public string _right = "2";

 [TestMethod]
 public void ShouldAdd()
 {
 var args = new string[] { "-op", "+", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldSubstract()
 {
 var args = new string[] { "-op", "-", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldMultiply()
 {
 var args = new string[] { "-op", "*", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }

 [TestMethod]
 public void ShouldDivide()
 {
 var args = new string[] { "-op", "/", "-l", "45", "-r", "96" };
 CalculatorCLI.CLI.Program.Main(args);
 }
 }
}

모든 것이 생성되면 다음과 같은 솔루션이 생성됩니다.

이제 테스트를 실행할 수 있으므로 Visual Studio의 Test Explorer로 이동하여 실행하세요!

트래비스 CI

아직 그렇지 않다면 TravisCI는 호스팅된 지속적인 통합 및 배포 시스템입니다.

여기서 수행해야 할 몇 가지 단계가 있지만 먼저 프로젝트를 빌드하고 테스트하기 위해 TravisCI 에이전트가 들을 수 있도록 Github 저장소를 연결하겠습니다.

저장소 활성화

이렇게 하려면 Travis CI 페이지에 로그인하고 리포지토리로 이동한 다음, 리포지토리 이름 옆에 있는 슬라이더를 클릭하여 생성한 프로젝트를 필터링하고 활성화하세요.

.travis.yml 생성프로젝트 루트에 `.travis.yml`라는 파일을 생성해야 합니다. 그 이유는 문서에 명시된 바와 같이:

Travis는 .travis.yml 파일을 추가한 후 푸시한 커밋에서만 빌드를 실행합니다.

따라서 다음 줄을 사용하여 저장소 루트에 .travis.yml 파일을 만듭니다.

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

before_script:
 - dotnet restore ".\CalculatorCLI\CalculatorCLI.sln"

script:
 - dotnet build ".\CalculatorCLI\CalculatorCLI.sln" -c Release
 - dotnet test ".\CalculatorCLI\CalculatorCLI.sln" -c Release -v n

.travis.yml 파일이 어떻게 작동하는지에 대한 구문을 다루지는 않겠지만 이것이 무엇을 하는지 검토해 보겠습니다.

언어를 csharp로 설정했습니다.
.NET Core 3.0는 Linux에서 기본적으로 실행되므로 mono를 사용하지 않습니다.
dotnet 버전을 3.0로 설정했습니다.
os를 설정했습니다. 기본적으로 linux이지만 어쨌든 추가했습니다.
이제 여기에서 주요 논리보다 먼저 실행될 before_script가 있으므로 솔루션에 dotnet restore를 실행하여 나중에 모든 것이 완벽하게 로드되도록 했습니다.
이제 script에서 솔루션에 대해 dotnet builld 및 dotnet test를 수행할 것입니다. 이는 컴파일되었는지 확인한 다음 테스트를 실행합니다.

그리고 이제 끝났습니다!

마스터에 업로드

이제 모든 것을 마스터하기만 하면 됩니다.

git add --all
git commit -m "Initial files"
git push

지속적인 통합 확인

저장소 페이지나 TravisCI 대시보드에서 master에 대한 푸시의 CI 상태를 확인할 수 있습니다.

진행 중

완료

#부숴보자

이제 이것이 얼마나 강력한지 확인하기 위해 코드를 깨고 핵심 라이브러리를 변경하여 실패하게 만들어 보겠습니다.

코드 변경

따라서 Operation.cs로 이동하여 일부 테스트를 깨뜨릴 수 있는 항목을 변경하세요.

using System;

namespace CalculatorCLI.Core
{
 public enum OperatorsEnum
 {
 ADD,
 SUBSTRACT,
 MULTIPLY,
 DIVIDE
 }

 public class Operation
 {
 public OperatorsEnum OperatorEnum { get; set; }
 public int LeftValue { get; set; }
 public int RightValue { get; set; }

 public Operation(string operatorString, int leftValue, int rightValue)
 {
 switch (operatorString)
 {
 case "+":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "-":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;
 case "*":
 OperatorEnum = OperatorsEnum.MULTIPLY;
 break;
 case "/":
 OperatorEnum = OperatorsEnum.DIVIDE;
 break;
 default:
 throw new Exception("Operator invalid");
 }

 LeftValue = leftValue;
 RightValue = rightValue;
 }

 public int DoOperation()
 {
 switch (OperatorEnum)
 {
 case OperatorsEnum.ADD:
 return LeftValue + RightValue;
 case OperatorsEnum.SUBSTRACT:
 return LeftValue - RightValue;
 case OperatorsEnum.MULTIPLY:
 return LeftValue * RightValue;
 case OperatorsEnum.DIVIDE:
 return LeftValue / RightValue;
 default:
 throw new Exception("Operator is not valid");
 }
 }
 }
}

그리고 테스트를 다시 실행하면 사례를 추가로 변경했기 때문에 실패할 것입니다.

case "+":
 OperatorEnum = OperatorsEnum.SUBSTRACT;
 break;

예상대로 ShouldAdd 사례에서는 실패했습니다.

이제 이 변경 사항을 커밋하고 마스터에 푸시한 후 TravisCI 에이전트의 결과를 기다립니다.

git add --all
git commit -m "Breaking changes"
git push

빌드

이제 TravisCI 로그로 이동하면 통합 테스트가 실패하고 빌드 상태가 오류이기 때문에 프로젝트가 성공적으로 중단되었음을 알 수 있습니다.

로그 끝에서 오류 자체를 볼 수 있습니다.

다시 고쳐보자!

이제 우리가 했던 작업을 되돌리고 코드를 마스터에 푸시하고 새 빌드의 상태를 확인하세요.

테스트가 성공적으로 통과되었습니다.

그리고 빌드도 성공했습니다.

결론

정말 강력합니다, CI와 CD는 오래 전부터 존재했지만 이제는 모든 단일 프로젝트에서 실행하는 것이 매우 간단하며 그것이 얼마나 작거나 단순한지는 중요하지 않습니다.내 관점에서는 모든 사람이 적어도 각 프로젝트에 대해 CI를 설정해야 합니다. 이는 좋은 습관이고 결국 적절한 tests 및 CI를 설정한 경우 발생해서는 안 되는 오류를 디버깅하고 찾는 시간을 절약할 수 있기 때문입니다.

그게 다야

TravisCI를 사용하고 코드를 Github에 저장하는 모든 빌드에서 지속적으로 통합되는 .NET Core 3.0 솔루션을 만드는 방법에 대한 내용입니다.

이 프로젝트의 소스 코드는 여기에서 찾을 수 있습니다.

인메모리 캐시에 대한 나의 견해

Tue, 03 Sep 2019 00:00:00 +0000

저는 엄청난 양의 데이터를 처리하는 작업을 해왔습니다. 그렇게 하는 동안 나는 그것의 큰 덩어리가 결코 변하지 않거나 적어도 어느 정도 고정된 시간 동안은 변하지 않는다는 것을 깨달았습니다.

그래서 개인 캐시 저장소를 만드는 것이 유용할 것이라고 생각했습니다. 물론 이것은 새로운 것은 아닙니다. 몇 주 전에 Nick Craver가 작성한 StackOverflow의 포스트에서 애플리케이션 캐시를 관리하는 방법에 대해 읽었습니다.

또한 저는 항상 캐시를 사용하여 작업하고 싶었습니다. 캐시가 어떻게 작동하는지, 논리를 어떻게 작동하게 만들 수 있는지, 그래서… 안 될 이유가 없군요!

흐름

다음은 사용자가 값을 요청할 때 캐시를 제어하는 클래스가 어떻게 작동하는지에 대한 간단한 흐름입니다.

구현

시작하기 전에

알아요, 알아요. 메모리 캐시를 처리하는 System.Runtime.Caching가 있습니다. 하지만 제가 직접 만들기로 결정했습니다. 해당 클래스를 사용하려면 여기에서 방법을 확인하세요.

캐시항목

첫 번째 단계는 객체의 값과 만료 날짜를 저장하는 클래스를 만드는 것입니다. 아마도 더 좋은 방법이 있을 것입니다. 하지만 제 생각에는 다음과 같습니다.

public class CacheItem
{
 public string Identifier { get; set; }
 public object Value { get; set; }
 public DateTime ValidUntil { get; set; }

 public CacheItem(string identifier, object value, TimeSpan valid)
 {
 Identifier = identifier;
 Value = value;
 ValidUntil = DateTime.UtcNow.Add(valid);
 }
}

캐시 저장소

그런 다음 객체를 처리하고 어딘가에 저장하는 클래스가 필요합니다(CacheItem). 나는 접미사 Repository가 있는 클래스의 모든 데이터/모델을 처리하고 싶지만 꼭 그럴 필요는 없으므로 캐싱을 위해 하나 만들어 보겠습니다.

public class CacheRepository
{
 private static Dictionary<string, string> Cache = new Dictionary<string, string>();
 private static T Set<T>(string key, Func<T> lookup, TimeSpan durationMinutes)
 {
 var item = new Models.Item(key, lookup(), durationMinutes);
 return Save<T>(key, item);
 }
 private static T Save<T>(string key, Item item)
 {
 Cache[key] = JsonConvert.SerializeObject(item);
 return (T)item.Value;
 }
 private static T Get<T>(string key)
 {
 var cached = Cache.FirstOrDefault(x => x.Key == key).Value;
 var item = string.IsNullOrEmpty(cached) ? null : JsonConvert.DeserializeObject<Item>(cached);
 return (item == null)
 ? default : (item.ValidUntil > DateTime.UtcNow)
 ? JsonConvert.DeserializeObject<T>(JsonConvert.SerializeObject(item.Value)) : default;
 }
 public static T GetOrSet<T>(string key, Func<T> lookup, TimeSpan durationMinutes)
 {
 var cache = Get<T>(key);
 return cache == null ? Set(key, lookup, durationMinutes) : cache;
 }
}

지금까지 모든 항목이 저장될 Cache라는 정적 사전이 있습니다. 이는 애플리케이션이 실행되는 동안에만 지속되므로 이 자습서 제목에 메모리 내 캐싱이 있는 이유를 기억하세요.

Cache 항목은 CacheRepository 클래스가 로드되면 초기화된다는 점에 유의하세요.

CacheRepository 클래스를 호출할 때 사용할 수 있는 유일한 메서드는 세 가지 매개 변수가 필요한 GetOrSet(string key, Func<T> lookup, TimeSpan durationMinutes)입니다.

key: 저장할 객체의 식별자입니다.
lookup: 캐시가 만료되었거나 null인 경우의 콜백 함수입니다.
durationMinutes: 현재 시간(UTC)에 추가될 기간(분)입니다.

캐시할 시간

이제 캐싱 저장소를 사용하여 어딘가에서 일부 데이터를 가져옵니다.

이 모든 것이 이해되도록 하기 위해 몇 가지 속성이 포함된 예제 개체를 만든 다음 해당 개체의 목록을 가져와 채우는 저장소를 만들어 보겠습니다.

public class User
{
 public Guid Id { get; set; }
 public string Name { get; set; }
 public string Email { get; set; }
}
public class UserRepository
{
 public List<User> Get()
 {
 // Code to get users
 }
}

User 목록을 채울 수 있는 방법이 있으므로 CacheRepository 클래스를 활용해 보겠습니다.

private UserRepository _userRepository = new UserRepository();
private List<User> _user;
public List<User> User
{
 get
 {
 _user = CacheRepository.GetOrSet($"users", usersRepo.Get, TimeSpan.FromMinutes(10));
 return _user;
 }
}

마찬가지로 User 변수에 액세스할 때마다 users 키가 있는 객체의 값을 CacheRepository에 요청합니다.

해당 키가 있으면 만료 날짜를 확인합니다. 이러한 조건 중 하나라도 거짓이면 콜백을 사용하여 객체의 값(usersRepo.Get 사용)을 설정하고 만료 날짜가 DateTime.UtcNow + TimeSpan.FromMinutes(10)로 설정된 캐시에 저장한 후 반환합니다.

Devtools를 사용하여 페이지 스크린샷 찍기

Thu, 09 May 2019 00:00:00 +0000

클라이언트나 팀원에게 웹사이트의 현재 상태 또는 그 일부에 대한 전체 스크린샷을 보여줘야 할 때가 있었습니다. 그래서 저는 전체 페이지 화면 캡처를 사용했고, 다른 종류의 스크린샷에는 Windows의 조각 도구 또는 Snaggit를 사용했습니다. 이 게시물 Gyazo처럼 온라인으로 호스팅하려면 GIF 메이커도 있습니다.

최근에 저는 Devtools에 확장 프로그램이 필요 없이 전체 페이지 스크린샷을 찍는 도구가 있다는 것을 발견했습니다!

이것은 새로운 생각이 아니며 2017년 4월 Devtools 업데이트에 포함되었습니다. 하지만 제가 바위 밑에 살고 있어서 지금까지 알지 못한 것 같습니다…

개발자 도구

공식 Devtools 페이지에 명시된 대로:

Chrome DevTools는 Google Chrome 브라우저에 직접 내장된 웹 개발자 도구 세트입니다. DevTools는 페이지를 즉석에서 편집하고 문제를 신속하게 진단하는 데 도움이 되며 궁극적으로 더 나은 웹사이트를 더 빠르게 구축하는 데 도움이 됩니다.

Devtools에서 명령 실행하기

Devtools를 여는 방법을 이미 알고 계시지만 이 게시물을 위해 잊어버린 경우에는 F12 키 또는 Ctrl + Shift + I 단축키를 사용하여 여십시오. 그런 다음 Devtools 내부 메뉴에서 Run command를 열거나 Ctrl + Shift + P를 사용해야 합니다.

스크린샷 도구

screenshot를 입력하면 명령이 필터링되며, 사용할 수 있는 스크린샷 방법에는 4가지가 있습니다.

지역 스크린샷
전체 크기 스크린샷
노드 스크린샷
스크린샷 캡처

모든 스크린샷 방법을 확인하기 전에 devtools가 이미지 처리를 마친 후 웹페이지 이름과 함께 자동으로 다운로드됩니다.

지역 스크린샷

area screenshot를 사용하면 웹사이트의 일부를 선택하고 스크린샷을 만들 수 있습니다.

결과:

전체 크기 스크린샷

full size screenshot는 처음부터 끝까지 전체 웹페이지의 스크린샷을 찍습니다.

결과:

노드 스크린샷

node screenshot를 사용하면 검사 요소에서 선택한 노드의 스크린샷을 만들 수 있습니다.

결과:

스크린샷 캡처

capture screenshot는 스크롤 없이 현재 페이지와 브라우저 크기의 스크린샷을 찍습니다.

결과:

.NET Framework에 포함된 리소스와 외부 리소스를 사용하는 사용자 지정 언어

Mon, 06 May 2019 00:00:00 +0000

소개

직장에서 우리는 많은 개발자가 처리해야 할 일반적인 문제에 직면했습니다. 이는 클라이언트에게 서비스를 제공하는 클라이언트의 언어 및 사용자 정의 언어입니다.

예를 들어, 기본 언어가 비공식 언어를 사용하고 클라이언트가 나이가 많은 사람들이기 때문에 클라이언트가 공식적인 언어를 원한다고 가정해 보겠습니다.

또한 이 솔루션은 여러 언어에 적용되며 영어와 스페인어를 사용합니다.

제 모국어는 영어가 아닙니다. 튜토리얼의 실수에 대해 사과드립니다. 실수를 발견하고 수정하고 싶다면 이 저장소에서 끌어오기 요청을 열면 기꺼이 승인해 드리겠습니다!

리소스

리소스는 키/값 구조를 갖는 확장자가 .resx인 XML 파일이며 다음과 같습니다.

<?xml version="1.0" encoding="utf-8"?>
<root>
 <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
 <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
 <xsd:element name="root" msdata:IsDataSet="true">
 <xsd:complexType>
 <xsd:choice maxOccurs="unbounded">
 <xsd:element name="metadata">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" />
 </xsd:sequence>
 <xsd:attribute name="name" use="required" type="xsd:string" />
 <xsd:attribute name="type" type="xsd:string" />
 <xsd:attribute name="mimetype" type="xsd:string" />
 <xsd:attribute ref="xml:space" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="assembly">
 <xsd:complexType>
 <xsd:attribute name="alias" type="xsd:string" />
 <xsd:attribute name="name" type="xsd:string" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="data">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
 <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
 </xsd:sequence>
 <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
 <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
 <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
 <xsd:attribute ref="xml:space" />
 </xsd:complexType>
 </xsd:element>
 <xsd:element name="resheader">
 <xsd:complexType>
 <xsd:sequence>
 <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
 </xsd:sequence>
 <xsd:attribute name="name" type="xsd:string" use="required" />
 </xsd:complexType>
 </xsd:element>
 </xsd:choice>
 </xsd:complexType>
 </xsd:element>
 </xsd:schema>
 <resheader name="resmimetype">
 <value>text/microsoft-resx</value>
 </resheader>
 <resheader name="version">
 <value>2.0</value>
 </resheader>
 <resheader name="reader">
 <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
 </resheader>
 <resheader name="writer">
 <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
 </resheader>
 <data name="Action_cancel" xml:space="preserve">
 <value>Finish</value>
 </data>
 <data name="Action_greeting" xml:space="preserve">
 <value>Hello</value>
 </data>
</root>

영어 및 스페인어라는 두 가지 다른 언어에 대한 리소스를 생성할 예정이므로 파일 명명법은 resources.ISOLANGUAGECODE.resx입니다. 예를 들어 스페인어의 경우 resource.es.resx, 영어의 경우 resource.resx입니다. 나중에 독일어를 추가하려는 경우 파일 이름은 resource.de.resx가 됩니다.

임베디드 리소스

포함된 리소스는 프로젝트가 컴파일될 때 dll 내부에 추가됩니다.

보시다시피 리소스가 포함된 이미지는 다음과 같습니다. Resource.resx 파일은 편집에서 볼 수 없습니다.

외부 리소스

반면에 외부 리소스 또는 포함되지 않은 리소스는 컴파일 후 폴더에 추가되는 리소스입니다.

리소스 파일(.resx)은 Properties 폴더 안에 있습니다.

프로젝트 빌드

.NET Framework의 콘솔 프로젝트부터 시작해 보겠습니다.

내장 리소스 파일 생성

몇 개의 키가 있는 리소스 파일을 추가하고 나중에 외부 리소스로 업데이트하는 데 사용할 내장 리소스인지 확인하세요.

외부 리소스 파일 생성

외부 리소스와 내장 리소스를 분리하기 위해 나중에 쉽게 액세스할 수 있도록 이름이 있는 폴더 내에 외부 리소스를 추가할 것입니다.

팁: 속성 폴더 안에 폴더를 추가하고, 외부에 만들고 내부로 이동하려면 Visual Studio에서는 폴더를 만들 수 없습니다.

포함된 리소스에 대해 동일한 작업을 수행한 다음 파일의 properties로 이동하여 Advanced, Build action 내부로 이동하여 Content로 변경하고 Copy to Output Dictionary를 Copy if newer로 변경합니다.

다음과 같이 표시됩니다.

app.config에 키 추가

우리는 멋진 개발자이고 모든 것을 잘 수행하고 각 클라이언트의 코드를 변경하지 않기를 원하기 때문에 appconfig에 리소스 파일을 찾을 폴더 이름을 갖는 키를 추가해 보겠습니다.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <startup>
 <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
 </startup>
 <appSettings>
 <add key="CustomResources.Folder" value="John" />
 </appSettings>
</configuration>
```따라서 나중에 리소스를 찾을 때 `Properties.Doe` 대신 `Properties.John`를 찾습니다.

또한 app.config를 쉽게 변경할 수 있으므로 애플리케이션이 이미 배포된 경우에도 쉽게 변경할 수 있습니다.

## 포함된 리소스 파일에 액세스

.NET Framework를 사용하는 것은 매우 쉽기 때문에 임베디드 속성에 액세스하려면 `Properties` 개체를 사용해야 합니다. 이 개체는 리소스 파일을 속성으로 가지며 해당 개체 내부에는 `resx` 파일에 있는 모든 키/값이 있습니다.

```csharp
static void Main(string[] args)
{
 var hello = Properties.Resource.Action_greeting;
 var bye = Properties.Resource.Action_cancel;

 Console.WriteLine($"Action_greeting value: {hello}, Action_cancel value: {bye}");

 Console.Read();
}

실행하면 다음과 같은 내용이 표시됩니다.

Action_greeting value: Hello, Action_cancel value: Cancel

외부 리소스 파일에 접근하기

이 부분은 거의 동일합니다. Properties 객체로 리소스 파일에 액세스할 수 있습니다.

var hello = Properties.Resource.Action_greeting;
var bye = Properties.Resource.Action_cancel;

var johnhello = Properties.John.Resource.Action_greeting;
var johnbye = Properties.John.Resource.Action_cancel;

var doehello = Properties.Doe.Resource.Action_greeting;
var doebye = Properties.Doe.Resource.Action_cancel;

문제

이 방법을 사용하는 주요 문제점은 모든 키가 객체 내부의 속성이므로 이전에 본 것처럼 호출해야 한다는 것입니다. John 리소스 파일의 Action_greeting 키를 호출하려면 다음 Properties.John를 사용한 다음 Resource.Action_greeting를 사용해야 합니다.

바로 문제가 있습니다.

왜냐하면 많은 클라이언트를 위한 애플리케이션을 개발하는 경우 각 클라이언트에 대한 리소스 파일을 호출하는 방법을 변경하는 것은 좋지 않은 생각이기 때문입니다.

상상할 수 있습니까? 각 클라이언트에 대한 애플리케이션을 컴파일하고 John를 Doe로 변경한 다음 다른 것으로 변경합니다. 미친 짓이군요!

솔루션

우리 팀 리더는 폴백 시스템과 같은 매우 좋은 방법을 생각했습니다. 리소스의 기본 모델이 있어야 하고, 각 클라이언트에 대해 해당 리소스로 파일을 업데이트할 리소스 파일이 있어야 하며, 결국 단일 리소스 목록이 생성됩니다.

클라이언트가 사용자 정의 리소스를 원하지 않으면 우리는 기본 리소스를 사용하고, 클라이언트가 원한다면 우리는 그들의 리소스를 사용합니다.

이것을 체크리스트에 넣으려면 다음을 수행해야 합니다.

모든 키/값을 포함된 리소스에 대한 사전에 매핑하는 방법을 찾으세요.
모든 키/값을 외부 리소스에 대한 사전에 매핑하는 방법을 찾습니다.
두 파일을 혼합하고 각 언어에 대한 단일 사전을 갖습니다.
사전에 액세스하고 값을 반환하는 메서드를 만듭니다.

다이어그램

코딩해보자

우선, 리소스 파일을 가져오는 것부터 이를 혼합하고 값을 반환하는 것까지 모든 로직을 포함하는 분리된 클래스를 만들어 보겠습니다. 해당 클래스는 CustomResources라고 합니다.

이것은 다음과 같습니다:

 class CustomResources
 {

 private static Dictionary<string, string> _ResourcesEnglish;
 private static Dictionary<string, string> ResourcesEnglish;

 private static Dictionary<string, string> _ResourcesSpanish;
 private static Dictionary<string, string> ResourcesSpanish;


 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromFile(string file)
 {
 ...
 }

 public static string GetText(string key)
 {
 ...
 }

 public static string GetText(string key, string language)
 {
 ...
 }
 }

저희는 속성에 대한 지연 로딩을 구현하고 있습니다. 이는 성능을 높이는 데 도움이 되며 사전을 한 번 로드하게 합니다.

GetDictionaryFromEmbedded: 포함된 리소스에서 사전을 반환합니다.
GetDictionaryFromFile: 외부 리소스에서 사전u를 반환합니다.
OverwriteDictionary: 두 개의 사전을 혼합하여 단일 사전을 반환합니다.
GetText: 키에 주어진 값을 반환합니다.

삽입된 리소스에서 사전으로

xml 파일에서 모든 속성을 가져와서 사전을 반환해야 합니다.

private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
{
 Dictionary<string, string> res = new Dictionary<string, string>();

 try
 {
 ResourceManager rm = new ResourceManager(embedded, Assembly.GetExecutingAssembly());
 var resourceSet = rm.GetResourceSet(new CultureInfo(cultureInfoCode), true, true);

 var resourceDictionary = resourceSet.Cast<DictionaryEntry>()
 .ToDictionary(r => r.Key.ToString(),
 r => r.Value.ToString());
 res = resourceDictionary;
 }
 catch (Exception e)
 {
 string a = e.Message;
 // Error getting resource file
 }

 return res;
}

두 가지:- embedded라는 매개변수가 필요합니다. parementers는 디자이너에서 볼 수 있는 파일의 이름이며, 우리의 경우에는 resources-demo.Properties.Resource입니다.

또한 선택할 언어에 대한 코드인cultreInfoCode라는 매개변수가 있습니다. 운 좋게도 .NET Framework가 작업을 수행하므로 아무 것도 할 필요가 없습니다. 영어나 스페인어 중 하나를 선택하기만 하면 resource.es.resx 또는 resource.resx 중에서 선택됩니다.

외부 리소스에서 사전으로

파일에서 얻는 것이 약간 해킹적이지만 어렵지는 않습니다. 실행 파일의 현재 위치를 가져와서 리소스 파일의 위치를 연결한 다음 이를 사전으로 구문 분석해야 합니다.

하지만 ResXResourceReader에 액세스하려면 먼저 System.Windows.Forms에 대한 참조를 추가해야 합니다.

이제 GetDictionaryFromFile 메서드로 이동합니다.

private static Dictionary<string, string> GetDictionaryFromFile(string file)
{
 Dictionary<string, string> res = new Dictionary<string, string>();
 string currentPath = (System.IO.Path.GetDirectoryName(System.Reflection.Assembly.GetExecutingAssembly().GetName().CodeBase) + file).Replace("file:\\", "");

 try
 {
 using (ResXResourceReader resxReader = new ResXResourceReader(currentPath))
 {
 foreach (DictionaryEntry entry in resxReader)
 {
 res.Add((string)entry.Key, (string)entry.Value);
 }
 }
 }
 catch (Exception e)
 {
 string a = e.Message;
 }

 return res;
}

파일 매개변수는 실행 파일에서 리소스 파일까지의 위치로 채워져야 합니다. 이 경우에는 "\\Properties\\John\\Resource.resx"입니다.

사전 혼합

거의 끝났습니다. 먼저 app.settings에 액세스할 수 있도록 참조에 System.Configuration를 추가하는 것을 기억하세요.

 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
{
 var identifier = ConfigurationManager.AppSettings["CustomResources.Folder"];
 if (String.IsNullOrEmpty(identifier))
 return currentDictionary;

 foreach (var item in newDictionary)
 {
 try
 {
 currentDictionary[item.Key] = item.Value;
 }
 catch (Exception)
 {
 if(addIfDoesntExist)
 currentDictionary.Add(item.Key, item.Value);
 }
 }

 return currentDictionary;
}

사전에서 텍스트 가져오기

언어를 선택하는 비공개 메서드를 호출하는 공개 메서드를 만듭니다.

private static string GetText(string key, string language)
{
 try
 {
 switch (language)
 {
 case "es":
 return ResourceSpanish[key];
 case "en":
 default:
 return ResourceEnglish[key];
 }
 }
 catch (Exception)
 {
 return $"No value with key: {key} and language: {language}";
 }
}

public static string GetText(string key)
{
 try
 {
 return GetText(key, Thread.CurrentThread.CurrentCulture.TwoLetterISOLanguageName);
 }
 catch (Exception)
 {
 return $"No value with key: {key}";
 }
}

언어를 더 추가하려면 스위치를 수정해야 합니다.

속성 getter에 코드 추가

지금은 모든 메서드가 있으므로 공용 속성의 getter를 수정하여 값을 가져올 수 있습니다.

private static Dictionary<string, string> _ResourcesEnglish;
private static Dictionary<string, string> ResourcesEnglish
{
 get
 {
 if (_ResourcesEnglish == null)
 {
 var folderIndentifier = ConfigurationManager.AppSettings["CustomResources.Folder"]; ;
 var baseResources = GetDictionaryFromEmbedded("resources-demo.Properties.Resource");
 var customResources = GetDictionaryFromFile($"\\Properties\\{folderIndentifier}\\Resource.resx", "en");
 _ResourcesEnglish = OverwriteDictionary(baseResources, customResources);
 }

 return _ResourcesEnglish;
 }
}

private static Dictionary<string, string> _ResourcesSpanish;
private static Dictionary<string, string> ResourcesSpanish
{
 get
 {
 if (_ResourcesSpanish == null)
 {
 var folderIndentifier = ConfigurationManager.AppSettings["CustomResources.Folder"]; ;
 var baseResources = GetDictionaryFromEmbedded("resources-demo.Properties.Resources");
 var customResources = GetDictionaryFromFile($"\\Properties\\{folderIndentifier}\\Resources.es.resx", "es");
 _ResourcesSpanish = OverwriteDictionary(baseResources, customResources);
 }

 return _ResourcesSpanish;
 }
}

먼저 app.settings에서 식별자를 가져옵니다.
그런 다음 기본 리소스, 즉 내장된 리소스를 얻습니다.
그런 다음 사용자 정의 리소스를 얻으려면 폴더 이름(식별자)이 필요합니다.
그런 다음 이를 혼합하고 값을 반환합니다.

이 모든 작업은 한 번만 수행되므로 지연 로딩이 발생합니다.

테스트

코드와 관련된 모든 것이 끝났으므로 이제 테스트해 보겠습니다. 사전에서 값을 얻으려면 값을 반환하는 CustomResources.GetText(string key) 메서드를 호출해야 합니다.

전체 리소스 파일 업데이트

이 테스트는 리소스 파일의 전체 키/값을 업데이트하려는 경우입니다. 그림에서 볼 수 있듯이 키는 동일하지만 값이 다릅니다.

John를 테스트하고 이를 설정하기 위해 app.config를 <add key="CustomResources.Folder" value="John" />로 설정합니다.

이제 기본 리소스 파일(Properties/Resource.es.resx)을 확인해 보겠습니다.

그런 다음 외부 리소스 파일(Properties/John/Resource.es.resx):

좋습니다. 모든 것이 설정되었으면 콘솔 애플리케이션을 실행하고 속성의 get 부분으로 이동하여 모든 것을 확인하겠습니다.

folderIdentifier에는 앱 설정 값이 있습니다.

baseResources에는 기본 리소스, 내장된 리소스의 값이 있습니다.

customResources에는 John 폴더 내부에 외부 리소스 값이 있습니다.

그리고 마지막으로 _ResourcesSpanish는 기본 자원과 외부 자원이 혼합된 값을 갖는다.

하나만 업데이트

이제 동일하지만 다른 시나리오를 테스트해 보겠습니다. 키 하나를 업데이트하고 다른 키도 동일하게 두십시오.

보시다시피 파일은 Action_greeting에 대해 동일한 값 의미를 가지지만 Action_cancel에 대해 다른 값을 가지므로 Action_cancel만 업데이트해야 합니다.

리소스 파일이 누락되었습니다.

외부 리소스 파일을 제공하지 않으면 파일이 있을 것으로 예상하므로 실패하면 빈 사전을 반환하고 두 사전을 혼합하면 기본 사전으로 끝나기 때문에 전혀 문제가 되지 않습니다.

포함된 리소스에 쌍이 없습니다.

외부 리소스 파일에 쌍이 있는 경우 기본적으로 최종 사전에 추가되지 않습니다. 두 사전을 혼합할 때 OverwriteDictionary() 메서드를 호출하고 addIfDoesntExist 매개변수를 true로 설정하여 이를 변경할 수 있습니다.

다른 언어

보시다시피 우리는 언어를 지정하지 않았습니다. 모든 작업은 GetText(string key, string language)를 호출하는 GetText(string key) 함수에 의해 수행되고 매개변수 language는 스레드의 현재 언어를 반환하는 TwoLetterISOLanguageName에 의해 채워지기 때문입니다.

내 경우에는 기본 언어가 스페인어이므로 항상 스페인어로 표시되지만 영어도 사용해 볼 수 있습니다.

약간의 코딩을 하고 스페인어와 영어를 모두 확인할 수 있는 것을 만들어 보겠습니다.

static void Main(string[] args)
{

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("en-US");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("en-US");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("es-ES");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("es-ES");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 Console.Read();
}

private static void WriteText(string key) {
 Console.WriteLine($"[Culture: {System.Threading.Thread.CurrentThread.CurrentCulture}] Key: {key} -> value: {CustomResources.GetText(key)}");
}

이를 실행하면 출력은 다음과 같아야 합니다.

[Culture: en-US] Key: Action_greeting -> value: Hello
[Culture: en-US] Key: Action_cancel -> value: Finish
[Culture: es-ES] Key: Action_greeting -> value: Hola
[Culture: es-ES] Key: Action_cancel -> value: Terminar

처음 두 값은 영어인 resources.resx에서 가져오고 마지막 값은 모두 스페인어로 되어 있으며 값은 resources.es.resx에서 검색됩니다.

그게 다야

이 튜토리얼에서 우리는 언어용 내장 리소스와 외부 리소스를 혼합하는 방법을 찾았습니다. 이는 팀에서 겪었던 문제에 대한 솔루션이었으며 그 이후로 아무런 문제 없이 실행되어 왔습니다.

소스코드는 여기에서 확인할 수 있습니다.

질문이 있으시면 언제든지 @emimontesdeocaa로 트윗해 주세요. 시간이 나면 연락드리겠습니다.

흐름 사례에 대해 Bot Framework 및 DirectLine을 사용한 통합 테스트

Wed, 25 Apr 2018 00:00:00 +0000

소개

이전 블로그 게시물에서는 단일 사례에 대한 몇 가지 통합 테스트를 수행했습니다. “단일 사례"는 봇에게 무언가를 요청한 후 한 번만 응답하고 결과를 비교하는 경우입니다.

이 가이드에서는 인증 및 API 호출이 어떻게 수행되는지 설명하지 않습니다. 확인하려면 단일 사례 가이드를 확인하세요.

흐름 대화는 어떻습니까?

현재 방식을 사용하면 대화에 어떤 종류의 흐름도 없습니다. 예를 들어, 도움을 요청하려는 경우 메뉴에 다양한 옵션이 표시되고 그 중 하나를 선택한 후 다른 메뉴가 표시됩니다. 이렇게 하면 2개 이상의 responses이 됩니다. 즉, 이전에 사용했던 통합 테스트 솔루션을 사용하면 작동하지 않는다는 의미입니다.

다음은 단일 사례에 대한 통합 테스트가 작동하는 방식을 보여주는 다이어그램입니다.

다음은 현재 통합 테스트 솔루션을 흐름 사례에 어떻게 적용할 것인지에 대한 다이어그램입니다.

다음 설명에서는 Bot Framework 작동 방식에 대한 모든 기본 정보를 다루지 않습니다. 이해가 되지 않는 경우 공식 문서를 확인하세요.

예시 사례

다음 가이드에서는 도움을 요청하고 다른 옵션을 선택하는 흐름 대화가 포함된 봇을 사용하겠습니다.

새로운 JSON 구조

이제 봇과 대화할 때 하나 이상의 request가 있으므로 json 구조를 수정하여 수행할 모든 request를 추가해야 합니다.

{
 "secret": "direct-line-secret",
 "directlineGenerateTokenEndpoint":
 "https://directline.botframework.com/v3/directline/tokens/generate",
 "directlineConversationEndpoint":
 "https://directline.botframework.com/v3/directline/conversations/",
 "entries": [
 {
 "name": "PedirAyuda",
 "requests": [
 {
 "type": "message",
 "text": "Ayuda",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Telefono",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Oficina",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 {
 "type": "message",
 "text": "Tenerife",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 }
 ],
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "922920252",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }
 ]
}

보시다시피 중요한 변경 사항이 있습니다. request는 이제 requests입니다. 이는 이제 단일 activity 대신 List<Activity>가 있음을 의미합니다.

새로운 객체

이전에는 TestEntry 및 TestEntryCollection라는 단일 사례에 대해 개체를 설정했습니다. 흐름 사례의 경우 TestEntryFlow 및 TestEntryFlowCollection라는 새 객체를 생성합니다.

`TestEntryFlow`

이 객체는 컬렉션에 있는 모든 항목에 대한 것입니다. 앞서 언급한 것처럼 Requests 객체는 이제 단일 Activity 대신 List<Activity>입니다.

봇에게 여러 번 요청할 것이므로 대화에 전송될 activities가 여러 개 필요합니다.

public class TestEntryFlow
{
 /// <summary>
 /// Entry name
 /// </summary>
 [JsonProperty("name")]
 public string Name { get; set; }
 /// <summary>
 /// Activity requested by the entry
 /// </summary>
 [JsonProperty("requests")]
 public List<Activity> Requests { get; set; }
 /// <summary>
 /// Activity response expected by the entry
 /// </summary>
 [JsonProperty("response")]
 public Activity Response { get; set; }
 /// <summary>
 /// Assert value in string
 /// </summary>
 [JsonProperty("assert")]
 public string Assert { get; set; }
}

`TestEntiresCollection`

이 객체에는 secret 및 엔드포인트와 같은 DirectLine에 대한 관련 정보와 테스트할 Entries 목록이 포함됩니다.

Entries는 이제 TestEntry가 아니라 TestEntryFlow의 목록입니다.

public class TestEntryFlowCollection
{
 /// <summary>
 /// DirectLine Secret
 /// </summary>
 [JsonProperty("secret")]
 public string Secret { get; set; }
 /// <summary>
 /// Endpoint to get the token using the secret for DirectLine
 /// </summary>
 [JsonProperty("directlineGenerateTokenEndpoint")]
 public string DirectLineGenerateTokenEndpoint { get; set; }
 /// <summary>
 /// Endpoint for a conversation in DirectLine
 /// </summary>
 [JsonProperty("directlineConversationEndpoint")]
 public string DirectLineConversationEndpoint { get; set; }
 /// <summary>
 /// Entries list
 /// </summary>
 [JsonProperty("entries")]
 public List<TestEntryFlow> Entries { get; set; }
}

흐름 사례를 위한 `TestMethod` 생성

새로운 흐름

우선 다이어그램을 다시 한 번 살펴보세요(위에 게시한 것과 동일합니다).

보시다시피, 테스트를 수행하기 위한 흐름 구조는 거의 동일합니다.

정보 얻기
인증
대화 만들기여기에 변경 사항이 있습니다. 이제 대화에 대한 모든 요청을 여러 번 보내야 합니다. 이를 위해서는 각 요청을 반복하여 봇에 보낸 다음 최신 응답을 예상 응답과 비교해야 합니다.
모든 요청 보내기
모든 메시지 받기
최신 답변 받기
예상 응답과 비교
결과 어설션

코드

우선 파일에서 정보를 가져와야 합니다. 이는 이전에 단일 사례에서 했던 것과 동일합니다.

// Load entries from file
var path = System.IO.File.ReadAllText(@"C:\dataFlow.json");

// Deserialize to object
var data = JsonConvert.DeserializeObject<TestEntryFlowCollection>(path);

이제 data.entries의 각 TestEntryFlow에 대해 반복해야 합니다. 이를 통해 requests에서 반복하는 새 부분까지 단일 사례에서 수행한 것과 동일한 흐름을 따를 수 있습니다.

/// Arrange with current requested values
string token, newToken, conversationId;
Activity latestResponse = new Activity();

/// Act for step

/// 1 - Get token using secret from DirectLine in BotFramework panel
token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

/// 2 - Create a new conversation
var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

// This returns a new token and a conversationId
newToken = createdConversation.token;
conversationId = createdConversation.conversationId;

/// 3 - Send an activity to the conversation with new token and conversationId
string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";

다음 단계는 매우 간단합니다. entry.requests를 반복하고 모든 activity을 대화로 보내야 합니다.

foreach (Activity step in entry.Requests)
{
 if (step.Type == ActivityTypes.Message)
 {
 /// Step
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(step));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];
 }
}

watermark를 사용하여 최신 메시지를 가져오며, watermark는 DirectLine API가 대화 정보를 요청할 때 반환하는 값입니다.

그런 다음 globals를 latestReponse 및 expectedResponse로 채워야 합니다.

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

그리고 사례를 마무리하기 위해 entry에서 assert 문자열을 평가합니다.

/// Assert
Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));

최종 코드

[TestMethod]
public async Task ShouldTestFlowCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\dataFlow.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntryFlowCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert
 foreach (TestEntryFlow entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;
 Activity latestResponse = new Activity();

 /// Act for step

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";

 foreach (Activity step in entry.Requests)
 {
 if (step.Type == ActivityTypes.Message)
 {
 /// Step
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(step));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];
 }
 }

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }

 await Task.CompletedTask;
}

개선 사항

나는 더 나은 흐름이 가능할 수 있다고 믿습니다. 그러나 이러한 개선은 JSON 구조도 변경되어야 함을 의미합니다. 또한 이를 실현하려면 json을 더 많이 채워야 합니다.

이 테스트를 더 좋게 만들기 위해서는 각 request에 대해 response가 있어야 하며 메시지를 보낼 때마다 주장해야 합니다. 지금 우리가 하고 있는 방법은 모든 requests 와 최종 response 을 저장하는 것입니다.

이것이 어떻게 보이는지 보여주기 위해 다이어그램을 만들었습니다.

나는 최종 응답을 테스트하는 대신 흐름의 거의 모든 동작을 테스트하기 때문에 이 방법이 테스트의 무결성을 위해 전반적으로 훨씬 더 낫다고 생각합니다.

이 가이드는 이것이 전부입니다. 이 가이드는 단일 사례 가이드의 연속이라는 점을 기억하세요. 길을 잃은 것 같으면 모든 것에 대해 더 길고 더 많은 설명이 포함된 가이드를 확인하세요.

모든 코드는 내 github의 this 저장소에 저장되어 있습니다.

좋은 하루 보내세요!

Bot Framework와 DirectLine을 이용한 통합 테스트 (1)

Tue, 24 Apr 2018 00:00:00 +0000

저는 회사에 잠시 입사한 이후 Bot Framework 통합 테스트 업무를 맡게 되었습니다.

그룹에서 제가 하는 일은 봇을 최대한 안정적으로 만드는 것인데, 먼저 Bot Framework가 무엇인가요?

지능형 봇을 구축, 연결, 배포 및 관리하여 웹사이트, 앱, Cortana, Microsoft Teams, Skype, Slack, Facebook Messenger 등에서 사용자와 자연스럽게 상호 작용합니다. 사용한 만큼만 비용을 지불하면서 완전한 봇 구축 환경을 빠르게 시작하세요.

Bot Framework에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

다음 설명에서는 Bot Framework 작동 방식에 대한 모든 기본 정보를 다루지 않습니다. 이해가 되지 않는 경우 공식 문서를 확인하세요.

통합 테스트는 왜 필요한가요?

통합 테스트가 필요한 이유는 동료 중 한 명이 수정 사항, 새 기능 또는 새 버그를 푸시할 때마다 이 테스트가 코드를 프로덕션 환경으로 푸시하기 전에 실행되며, 테스트 중 하나라도 실패하면 코드가 프로덕션 환경으로 이동하지 않기 때문입니다. 즉, 최종 사용자에게는 버그가 발생하지 않습니다.

봇에서의 통합 테스트?

저는 봇에서는 통합 테스트가 매우 중요하다고 믿습니다. 일부 메뉴가 작동하지 않거나 일부 기능이 아무것도 반환하지 않는 봇을 가질 수 없습니다.

회사는 사람들이 문제로 바쁘게 지내는 것을 원하지 않기 때문에 고객을 위해 봇을 사용하고 있습니다. 봇이 사용자를 도울 수 있다면 다른 직원은 자신의 시간을 더 중요한 일에 사용할 수 있습니다.

솔루션 개요.

이 작업을 수행하기 위해 Visual Studio에서 API Rest용 WebClient와 케이스를 저장할 Json 파일을 사용하는 테스트 프로젝트를 사용했습니다.

JSON 파일

{
 "secret": "direct-line-secret",
 "directlineGenerateTokenEndpoint": "https://directline.botframework.com/v3/directline/tokens/generate",
 "directlineConversationEndpoint": "https://directline.botframework.com/v3/directline/conversations/",
 "entries": [
 {
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }
 ]
}

보시다시피 우리는 다음을 가지고 있습니다:

다이렉트라인 비밀 -> 게시된 봇의 비밀
Directline 토큰 생성 엔드포인트 -> 시크릿을 사용하여 토큰을 가져오는 엔드포인트
직접 대화 끝점 -> 대화를 플레이하기 위한 끝점
항목 -> 테스트 케이스
- 요청 -> 대화에 보내는 내용
- 응답 -> 우리가 얻기를 기대하는 것
- 주장 -> 무엇을 비교하고 있나요?

역직렬화

완벽하게 형식화된 json 파일이 있으므로 이제 이를 솔루션에 로드해야 하므로 JSON.NET과 일부 클래스를 사용하게 됩니다. 먼저 모든 것을 포함하는 항목 컬렉션이 있고 각 컬렉션에 대한 항목 목록이 있습니다.

 /// <summary>
 /// Object to parse from the file
 /// </summary>
 public class TestEntriesCollection
 {
 /// <summary>
 /// DirectLine Secret
 /// </summary>
 [JsonProperty("secret")]
 public string Secret { get; set; }
 /// <summary>
 /// Endpoint to get the token using the secret for DirectLine
 /// </summary>
 [JsonProperty("directlineGenerateTokenEndpoint")]
 public string DirectLineGenerateTokenEndpoint { get; set; }
 /// <summary>
 /// Endpoint for a conversation in DirectLine
 /// </summary>
 [JsonProperty("directlineConversationEndpoint")]
 public string DirectLineConversationEndpoint { get; set; }
 /// <summary>
 /// Entries list
 /// </summary>
 [JsonProperty("entries")]
 public List<TestEntry> Entries { get; set; }
 }

그리고 이것은 테스트 케이스에 대한 이름, 요청, 응답 및 주장을 포함하는 객체입니다.


 public class TestEntry
 {
 /// <summary>
 /// Entry name
 /// </summary>
 [JsonProperty("name")]
 public string Name { get; set; }
 /// <summary>
 /// Activity requested by the entry
 /// </summary>
 [JsonProperty("request")]
 public Activity Request { get; set; }
 /// <summary>
 /// Activity response expected by the entry
 /// </summary>
 [JsonProperty("response")]
 public Activity Response { get; set; }
 /// <summary>
 /// Assert value in string
 /// </summary>
 [JsonProperty("assert")]
 public string Assert { get; set; }
 }

테스트 케이스의 json에서 객체로 구문 분석

구문 분석 개체에 대한 클래스가 있으면 개체로 읽어야 하므로 매우 쉽습니다.

// Load entries from file
var path = System.IO.File.ReadAllText(@"C:\data.json");

// Deserialize to object
var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

이제 이 컬렉션을 사용하면 컬렉션을 반복하여 foreach 등을 사용하여 정보를 얻을 수 있습니다.

 foreach (TestEntry entry in data.Entries)
 {
 ....
 }

이것이 이 부분의 전부입니다. 다음 부분에는 DirectLine에 대한 인증이 포함됩니다. 모든 코드는 내 github의 this 저장소에 저장되어 있습니다.

Bot Framework와 DirectLine을 이용한 통합 테스트 (2)

Tue, 24 Apr 2018 00:00:00 +0000

이 부분에서는 DirectLine 인증을 수행하고 봇의 응답에서 값을 가져옵니다.

이제 역직렬화를 완료했으므로 인증을 받고 API를 호출하고 결과를 확인하는 데 사용할 컬렉션과 전체에서 정보를 가져올 차례입니다.

다음 설명에서는 Bot Framework 작동 방식에 대한 모든 기본 정보를 다루지 않습니다. 이해가 되지 않는 경우 공식 문서를 확인하세요.

WebClient를 사용하여 API 호출하기

API를 더 쉽게 호출할 수 있도록 utils 클래스를 만들었습니다. 여기에 몇 번 사용할 함수를 저장합니다. 이 클래스에는 POST용 uploadString과 GET용 downloadString가 포함되어 있습니다.

 public class Utils
 {
 /// <summary>
 /// Uploads to an URL and gets result
 /// </summary>
 /// <typeparam name="T">Type of object you are receiving</typeparam>
 /// <param name="bearer">Token</param>
 /// <param name="url">Url</param>
 /// <param name="serializedJson">Serialized JSON to send</param>
 /// <returns></returns>
 public static T uploadString<T>(string bearer, string url, string serializedJson)
 {
 string serializedResult = "";

 /// Webclient
 using (var client = new WebClient())
 {
 /// Add headers
 client.Headers.Add("Content-Type", "application/json");
 client.Headers.Add("Authorization", $"Bearer {bearer}");

 /// Upload string
 serializedResult = client.UploadString(url, serializedJson);
 }

 /// Get result and return it as an object
 return JsonConvert.DeserializeObject<T>(serializedResult);
 }

 /// <summary>
 /// Downloads from URL
 /// </summary>
 /// <typeparam name="T">Type of object you are receiving</typeparam>
 /// <param name="bearer">Token</param>
 /// <param name="url">Url</param>
 /// <returns></returns>
 public static T downloadString<T>(string bearer, string url)
 {
 string serializedResult = "";

 /// Webclient
 using (var client = new WebClient())
 {
 /// Add headers
 client.Headers.Add("Content-Type", "application/json");
 client.Headers.Add("Authorization", $"Bearer {bearer}");

 /// Download string
 serializedResult = client.DownloadString(url);
 }

 /// Get result and return it as an object
 return JsonConvert.DeserializeObject<T>(serializedResult);
 }
 }

DirectLine 인증

공식 문서를 읽으면 이를 수행하는 방법을 찾을 수 있으며 매우 쉽습니다. 우리 기능을 사용하면 훨씬 더 쉽습니다. 우선 우리가 foreach 문 안에 있다는 점을 기억하세요. 시간이 부족할 경우를 대비해 각 사례에 대해 인증을 수행하고 있기 때문에 테스트가 실패한다는 의미입니다.

/// Arrange with current requested values
string token, newToken, conversationId;
/// Act

/// 1 - Get token using secret from DirectLine in BotFramework panel
token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

이제 대화 끝점에 대한 다음 호출을 모두 수행하는 데 사용되는 토큰이 있습니다.

대화를 만드는 중입니다.

봇과 대화하려면 먼저 대화를 만들어야 합니다. 이 대화는 대화 ID가 포함된 새 토큰을 반환합니다.

/// 2 -Create a new conversation
var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

// This returns a new token and a conversationId
newToken = createdConversation.token;
conversationId = createdConversation.conversationId;

또한 newToken 및 conversationId를 저장합니다. 둘 다 사용자가 봇에 메시지를 보내는 데 필요합니다.

활동을 대화로 보내기

이제 conversationId 및 conversationEndpoint를 사용하여 json 파일에서 request인 Activity를 보내는 최종 엔드포인트를 생성할 수 있습니다.

/// 3 - Send an activity to the conversation with new token and conversationId
string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

Bot Framework와 DirectLine을 이용한 통합 테스트 (3)

Tue, 24 Apr 2018 00:00:00 +0000

이것은 가이드의 최신 부분입니다. 이 부분에서는 json에 있는 어설션의 텍스트를 평가할 것입니다.

이제 request를 사용하고 activity를 봇에 보냈으므로 response를 얻었고 json의 assert(json에 저장한 응답, 예상 응답)과 봇에서 얻은 응답을 비교해야 합니다.

다음 설명에서는 Bot Framework 작동 방식에 대한 모든 기본 정보를 다루지 않습니다. 이해가 되지 않는 경우 공식 문서를 확인하세요.

솔루션에 Microsoft.CodeAnalytic 추가

우선 CodeAnalytic을 NuGet 패키지로 포함해야 합니다.

설치 후에는 .cs 파일에 패키지를 추가해야 합니다.

using Microsoft.CodeAnalysis.CSharp.Scripting;

`Globals` 객체 생성

평가하려면 매개변수를 평가자에게 전달해야 합니다. 이 평가자에는 구성 파일이 필요합니다.

 /// <summary>
/// Object to pass parameters to Roslyn compiler
/// </summary>
public class Globals
{
 /// <summary>
 /// ExpectedResponse
 /// </summary>
 public Activity Request;
 /// <summary>
 /// ReceivedResponse
 /// </summary>
 public Activity Response;
}

이 부분은 매우 중요합니다. 해당 구성 파일에는 비교할 객체가 포함되므로 예상 응답과 응답을 전달해야 합니다.

해당 정보를 사용하여 json 파일의 assert을 사용하고 내용을 평가합니다.

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

/// Assert
Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));

EvaluateAsync<T>는 T를 평가하고 반환합니다. 이 경우 평가할 string와 평가할 데이터가 있는 globals를 전달합니다.

나는 항목(이름, 요청, 응답 및 주장이 있음)을 사용하여 예를 들어 이것을 설명하려고 합니다.

{
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }

이 항목에서 중요한 사항을 알아봅시다. 먼저 **"assert": "Request.Text == Response.Text"**를 주장합니다. 이는 Request.Text를 Response.Text와 비교하고 값을 부울로 반환한다는 의미입니다.

그러나 await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals) 함수를 호출할 때 2개의 매개변수를 전달합니다.

string 평가할 문자열 -> "Request.Text == Response.Text"
평가자를 위한 globals 데이터 -> 이 경우 Request 및 Response를 제공해야 합니다. 요청은 예상 응답이고 응답은 수신된 응답입니다.

평가자에 데이터를 채우는 동안 이제 문자열을 사용하여 평가할 수 있으므로 true 또는 false가 반환됩니다.

완료

끝났습니다. 여기서 완성된 TestMethod를 볼 수 있습니다.

[TestMethod]
public async Task ShouldTestSingleCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\data.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert

 foreach (TestEntry entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;

 if (entry.Request.Type == ActivityTypes.Message)
 {
 /// Act

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 var latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }
 }
 await Task.CompletedTask;
}

다이어그램

다음은 이 지점을 얻기 위해 우리가 따른 모든 흐름에 대한 다이어그램입니다. 이해하지 못한 부분이 있으면 이를 통해 문제가 해결되기를 바랍니다.

이것이 전부입니다. 이는 사례가 1:1인 단일 사례에 대해 수행되며 사용자는 activity를 보내고 봇은 또 다른 단일 activity를 반환합니다.

마음에 드셨기를 바랍니다. 다음은 응답이 두 개 이상인 테스트 흐름 사례입니다.

모든 코드는 내 github의 this 저장소에 저장되어 있습니다.

발표

Mon, 01 Jan 0001 00:00:00 +0000

저는 .NET, Azure, AI, 클라우드 네이티브 개발에 초점을 맞춘 국제 기술 컨퍼런스의 자주 발표자입니다. 2023, 2024, 2025년에 Sessionize 가장 활발한 발표자로 선정되었으며, 개발자 기술 분야의 Microsoft MVP 자격을 보유하고 있습니다.

제 이벤트에서 발표하기를 원하신다면, 연락해 주세요!

2026

2026년의 Blazor

2026년 Blazor의 현재 상태와 .NET 10과 함께 어떻게 발전했는지 살펴봅니다. 최신 변경 사항과 개선 사항, 실제 애플리케이션 개발에 미치는 영향, 그리고 각 시나리오에 가장 적합한 Blazor 호스팅 모델을 검토합니다.

AI로 Level 3 지원 강화: Azure Functions + OpenAI 실전

Azure Functions, Azure Monitor 알림, Azure OpenAI가 함께 작동하여 Level 3 지원을 가속화하는 방법. 자동 알림 분류에서 지능형 로그 분석까지 — AI를 실제 지원 워크플로에 추가하는 실용적인 방법.

대시보드에서 에이전트로: 관찰 가능성의 다음 단계

AI 에이전트와 프로덕션 관찰 가능성의 세계를 연결하는 실습 세션. Semantic Kernel에서 OpenTelemetry 데이터를 쿼리하고, MCP를 통해 Grafana와 상호 작용하며, 실제 시스템 운영과 최적화를 돕는 자율 에이전트까지.

예정: Global Azure 2026 — 2026년 4월, 스페인 마드리드

2025

크리스마스를 구하는 Microsoft Agent Framework

완벽한 크리스마스 선물을 찾기 위해 Microsoft Agent Framework를 사용하여 여러 AI 에이전트를 구축하고 조정합니다. 각 에이전트는 전문화되어 — 선물 아이디어 생성에서 가격 비교까지 — 더 스마트한 연말 쇼핑을 위해 함께 작동합니다.

AI로 Level 3 지원 강화: Azure Functions + Semantic Kernel 실전

Azure Functions, Azure Monitor, Semantic Kernel이 함께 작동하여 Level 3 지원을 더 빠르고 효율적으로 만듭니다 — 자동 알림 감지에서 지능형 로그 분석까지.

.NET 10으로 Blazor에 무엇이 새로워졌나?

성능 향상, 양식, 영구 상태, 더 강력한 JavaScript 상호 운용성 등 .NET 10을 위한 Blazor의 주요 새 기능 탐색.

C#, Semantic Kernel, Gemini를 활용한 하이브리드 AI: 스마트한 엔터프라이즈 앱 구축

C#에서 하이브리드 AI 워크플로 오케스트레이션 — 로컬 모델(Phi-3)을 Vertex AI를 통한 Gemini Pro/Ultra와 결합하고, Semantic Kernel 플러그인으로 인지 에이전트를 구축하며, 적응형 아키텍처를 설계합니다.

.NET Aspire: 두통 없이 Cloud-Native 앱 구축

태생적으로 확장 가능하고, 탄력적이며, 관찰 가능한 클라우드 퍼스트 마이크로서비스를 구축하는 실습 세션. .NET Aspire가 클라우드 보일러플레이트의 70%를 어떻게 제거하는지 탐색.

.NET Aspire: 혼돈 없는 Cloud-Native

첫 번째 커밋부터 관찰 가능성과 자동 탄력성이 내장된, 태생적으로 확장 가능한 앱 설계의 실제 사례.

2024

AI와 SQL의 만남: .NET과 Semantic Kernel로 스마트 피자 가게 구축

코드와 데이터를 이해하는 자연어 AI 상호 작용 — .NET과 Semantic Kernel로 구동되는 지능형 피자 가게 구축.

.NET Aspire: 복잡함 없는 Cloud-Native 애플리케이션

두통 없이 클라우드 퍼스트 마이크로서비스 구축 — .NET Aspire가 클라우드 네이티브 개발을 어떻게 단순화하는지 보여주는 실용적인 데모 중심 세션.

Power Platform: Low-code에서 Pro-code 기술로의 여정

같은 플랫폼 내에서 TypeScript를 사용하여 Low-code Power Apps에서 고급 Pro-code 컴포넌트로 전환.

지능형 자동화: AI 통합으로 엔터프라이즈 애플리케이션 혁신

.NET 애플리케이션을 다음 단계로 — Semantic Kernel과 .NET Aspire를 사용하여 전통적인 로직을 AI 기반 추론과 결합.

Low-Code에서 Pro-Code로: 엔터프라이즈 솔루션에서의 AI 개발 접근 방식

엔터프라이즈 솔루션의 다양한 접근 방식 탐색 — AI가 포함된 Power Platform에서 Semantic Kernel을 사용한 전통적인 개발까지.

Azure로 출장 비용 관리

Azure AI Vision, Document Intelligence, Semantic Kernel과 OpenAI를 사용하여 출장 비용 관리를 자동화.

배지 및 인정

🏆 Sessionize Most Active Speaker 2025
🏆 Sessionize Most Active Speaker 2024
🏆 Sessionize Most Active Speaker 2023
🏅 개발자 기술 분야 Microsoft MVP

Sessionize에서 모든 세션 보기 →

소개

Mon, 01 Jan 0001 00:00:00 +0000

저에 대해

저는 **에밀리아노 몬테스데오카(Emiliano Montesdeoca)**입니다. 우루과이-스페인 출신 소프트웨어 개발자이며, 개발자 기술 분야 Microsoft MVP이고, 테네리페, 카나리아 제도에 거주하는 자랑스러운 아빠입니다.

복잡한 기술적 도전을 극복하고 Microsoft 기술로 확장 가능한 클라우드 솔루션을 구축하는 것을 좋아합니다. 일상적인 도구로는 .NET, Azure, Semantic Kernel을 활용한 AI, 그리고 .NET Aspire와 같은 현대적인 아키텍처를 사용합니다.

제가 하는 일

Intelequia Technologies의 클라우드 솔루션 팀 리드로서, 클라우드 네이티브 애플리케이션의 설계와 제공을 이끌고 있습니다 — 전략적 비전과 실질적 실행을 결합하여. 저는 아키텍처와 코드의 교차점에서 번창하며, 팀이 우아하고 프로덕션 준비가 된 솔루션을 제공하도록 보장합니다.

커뮤니티

저는 자주 국제 발표자로 활동하며, 2023, 2024, 2025에 Sessionize 가장 활발한 발표자로 인정받았습니다. 전 세계 컨퍼런스 발표와 블로그를 통해 실용적인 실세계 인사이트를 공유합니다.

또한 .NET 커뮤니티를 위한 리소스인 The .NET Blog의 창시자이며, 배우고 만드는 것들에 대해 이 블로그에 정기적으로 글을 씁니다.

멘토링과 커뮤니티 구축은 제 정체성의 핵심 부분입니다. 제 커리어를 형성한 생태계에 보답하는 것은 진지하게 임하는 일입니다.

연락해요

이벤트 발표, 프로젝트 협업, 또는 클라우드 아키텍처와 AI에 대한 대화에 언제나 열려 있습니다. 편하게 연락해 주세요!

Email: emimontesdeoca@outlook.es
GitHub: @emimontesdeoca
X / Twitter: @emimontesdeocaa
LinkedIn: emimontesdeoca
Instagram: @emimontesdeoca
Sessionize: emimontesdeoca

Emiliano Montesdeoca

Blazor 처음부터: 3장 — 확장 가능한 컴포넌트

Blazor 컴포넌트란 무엇인가

1단계: 목적이 분명한 컴포넌트부터 시작

2단계: 파라미터로 동작을 명시적으로 표현

3단계: RenderFragment로 레이아웃 컴포지션

4단계: 거대한 페이지보다 컴포지션

5단계: 마크업과 로직의 균형

6단계: 실용적인 폴더 구조

초기에 자주 하는 실수

다음 장

Blazor 기초부터: 챕터 2 — 첫 번째 Blazor 앱

1단계: 프로젝트 생성

2단계: 로컬 실행

3단계: 프로젝트 구조 이해

4단계: 첫 변경 만들기

5단계: Program.cs 한 번 읽기

자주 발생하는 문제

다음 챕터

Blazor 처음부터: 1장 — Blazor란 무엇인가?

간략한 역사

Blazor가 실제로 무엇인가

렌더링 모델

정적 SSR

인터랙티브 서버

인터랙티브 WebAssembly

Auto 모드

동일한 앱에서 모드 혼합

Blazor와 JavaScript 프레임워크 비교

따라하기 위해 필요한 것

다음 편

Blazor 처음부터: 새 시리즈

이 시리즈는 누구를 위한 것인가

무엇을 다룰 것인가

왜 시리즈를, 왜 지금

시리즈를 따라가는 방법

C# Union 유형: 차별된 Union이 마침내 등장합니다.

차별적 노동조합이란 무엇입니까?

오늘날 노동조합을 시뮬레이션하는 방법

상속이 포함된 추상 레코드

수동 열거형 + 데이터 패턴

C# 제안: union 키워드

가치 전용 회원

일반 공용체

메소드가 있는 공용체

중첩 패턴 일치

보호 조항

실제 예

결과 패턴: 예상되는 오류에 대한 예외 교체

도메인 모델링: 결제 유형

상태 머신

사용 방법

기존 접근방식과의 비교

이것이 .NET 생태계에 미치는 영향

결론

시맨틱 커널을 사용하여 C#으로 RAG 시스템 구축

소개

RAG 작동 방식

전제 조건

커널 설정

데이터 모델 정의

문서 청킹

문서 수집 중

관련 청크 검색

상황에 맞는 답변 생성

사용하기

프로덕션으로 이동

Microsoft Agent Framework를 사용하여 에이전트 워크플로 구축

소개

상담사 워크플로란 무엇인가요?

전제 조건

순차 워크플로 구축

에이전트 정의

순차적으로 실행 중

병렬 실행

조건부 분기

워크플로 에이전트에 플러그인 추가

워크플로의 오류 처리

모범 사례

결론

3단계: `RenderFragment`로 레이아웃 컴포지션

C# 제안: `union` 키워드