Emiliano Montesdeoca

Blazor をゼロから: 第3章 — スケールするコンポーネント設計

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

Blazor をゼロから 第3章へようこそ。まだ第2章を読んでいない場合は、先にそちらを読むとスムーズです。

第2章ではアプリを動かしました。第3章ではそれを 保守しやすい構造 にします。

Blazor は、各ページが巨大な .razor ファイルになると一気に複雑化します。そこで重要なのがコンポーネントです。再利用性、一貫性、責務の分離を実現できます。

Blazor コンポーネントとは何か

コンポーネントは、次のことができる .razor ファイルです。

マークアップを描画する
ローカル状態を持つ
パラメーターで入力を受け取る
親コンポーネントへイベントを通知する
子コンテンツを描画する

実行時、Blazor は各コンポーネントを小さな状態マシンとして扱います。状態が変わると再描画し、DOM の差分だけを更新します。

つまり、明確な入力と予測可能な動作を設計することが大切です。

ステップ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>

大事なのは契約設計です。

パラメーターは少なく明確に
暗黙的な挙動より明示的な名前
安全なデフォルト値

ステップ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: マークアップとロジックのバランスを取る

小さいコンポーネントなら @code のインラインで十分です。

大きい場合は code-behind に分けます。

UserCard.razor
UserCard.razor.cs

UI と C# ロジックの可読性がどちらも上がります。

ステップ6: 実用的なフォルダー構成

スケールしやすい構成の例:

Components/Pages/ -> ルーティング対象ページ
Components/Layout/ -> アプリ共通レイアウトとナビ
Components/Common/ -> 汎用の共有コンポーネント
Components/Features/<FeatureName>/ -> 機能別コンポーネント

初期の Blazor プロジェクトでよくあるミス

専用モデルを作らず、パラメーターを増やしすぎる
ページコンポーネントに業務ロジックを入れすぎる
数百行の “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 を使っていればすぐ反映されます。

この小さな変更で、編集 -> ビルド -> 表示の流れを確認できます。

ステップ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 — 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ではパラメータ）、ローカル状態（@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とは？ — ホスティングモデル、歴史、従来のWeb開発との比較
はじめての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# ユニオン型: 差別的なユニオンがついに登場

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

かなりの期間 C# を書いてきた場合、「いくつかあるもののうちの 1 つ」となるものをモデル化しようとしたときに壁にぶつかった可能性が高くなります。おそらく、成功値またはエラーのいずれかを返すメソッドが必要でした。おそらく、クレジットカード、銀行振込、デジタルウォレットを処理する支払いシステムを構築していたのでしょう。それぞれにまったく異なるデータが含まれていました。あるいは、F# や Rust を見て、「なぜ C# でそれができないの?」と思ったかもしれません。

待ち時間はもう終わりに近づいています。 差別的な共用体が C# に登場します。

これは長年にわたり最も要望の多かった言語機能の 1 つであり、コミュニティでの議論は 2017 年以前にまで遡ります。 C# 言語設計チームは、網羅的なパターンマッチングを使用して閉じた型の階層を定義するための union キーワードを導入する提案に取り組んでいます。この投稿では、識別共用体とは何か、それがそれほど重要である理由、これまでどのように偽装してきたのか、そして提案された構文が実際にどのようなものであるのかを、それぞれの実際のコード例とともに説明したいと思います。

本題に入る前に簡単な注意事項: この記事の執筆時点では、ユニオン型機能はまだ提案とプレビューの段階にあります。ここで説明する構文と動作は、公開されている最新の設計ドキュメントと C# 言語設計チームからのディスカッションに基づいています。最終リリースまでに状況が変わる可能性があります。何が確認されているのか、何がまだ議論中であるのかを明確にさせていただきます。

差別的な組合とは何ですか?

本質的に、識別共用体 (「タグ付き共用体」または「合計型」と呼ばれることもあります) は、可能な値の固定セットの 1 つを保持できる型であり、各バリアントは異なるデータを保持できます。「識別された」部分は、ランタイムがそれがどのバリアントであるかを常に知っていることを意味します。それを識別するタグがあります。

これは 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 ライブラリ

もう 1 つの一般的なアプローチは、[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 は、ジェネリック型パラメーターを通じてコンパイル時に徹底的なチェックを提供します。これは優れています。しかし、位置一致 (最初のタイプ、2 番目のタイプなど) に依存しており、汎用署名はすぐに扱いにくくなり、言語のパターンマッチングと統合されていません。これは賢いハックですが、それでもハックです。

手動列挙 + データパターン

一部の開発者は、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 がこれら 3 つのうちの 1 つにしかなり得ないことを知っています。

内部では、コンパイラーは密閉型階層を生成します。これは、抽象レコードを使用して手動で記述するものと似ていますが、コンパイラーは型の閉じた性質を完全に認識します。これは、コンパイラがパターンマッチングの網羅性を強制できることを意味し、これが主な利点です。

価値のみのメンバー

組合員はデータを持ち歩く必要がありません。データ保持メンバーと単純な値メンバーを混在させることができます。

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)
};

}


`Area` および `Perimeter` 内の `switch` 式がデフォルトのアームを必要としないことに注目してください。コンパイラーは、共用体が完全であることを認識しています。バリアントは 3 つだけあり、3 つすべてが処理されます。後で 4 番目のバリアントを追加すると、コンパイラはそれを処理しないすべての `switch` にフラグを立てます。

## パターン マッチングの統合

C# ではパターン マッチングがバージョン 7.0 以降進化しており、共用体型はそのシステムの第一級市民となるように設計されています。

### 網羅的なスイッチ式

最も影響力のある機能は、徹底的なスイッチ チェックです。共用体を使用すると、コンパイラは考えられるすべてのケースを **認識**します。

```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"
};

実用的な例

共用体型によってコードが劇的に改善される実際のシナリオをいくつか見てみましょう。

結果のパターン: 予期されるエラーの例外を置き換える

最新のアプリケーション開発で最も一般的なパターンの 1 つは、制御フローの例外を使用せずに、成功または失敗する可能性のある操作を表現することです。例外は、ネットワーク障害やメモリ不足状態など、例外的なものである必要があります。検証エラーまたは「見つからない」という結果は予期された結果であり、例外ではありません。

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 はそれらを明示的かつ安全なものにします。

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 状態では Connecting が存在しないため、誤って [[TOK_39]]] にアクセスすることはできません。型システムはステートマシンの不変条件を強制します。

シリアル化と相互運用に関する考慮事項共用体型についてすぐに浮かぶ実際的な疑問の 1 つは、「どうやってそれらをシリアル化するのか?」というものです。 API を構築している場合、またはデータを保存している場合、正しく機能するには JSON シリアル化が必要です。

設計チームは、共用体型の組み込みの System.Text.Json サポートについて議論してきました。期待されるアプローチには、識別子プロパティを使用したシリアル化が含まれます。

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

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

これは、.NET 7 で JsonDerivedType 属性を使用して導入された既存のポリモーフィックシリアル化サポートと一致しています。デフォルトで型識別子としてバリアント名を使用し、共用体が 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>	列挙型 + データ	ユニオンの種類
徹底チェック	❌ いいえ	✅ はい	❌ いいえ	✅ はい
パターンマッチング	✅ はい	❌限定	❌ マニュアル	✅ ネイティブ
コンパイラによる強制的なクロージャ	❌ いいえ	✅ はい	❌ いいえ	✅ はい
バリアントごとのデータ	✅ はい	✅ はい	⚠️壊れやすい	✅ はい
可読性	⚠️ 詳細	⚠️ 位置	❌ 悪い	✅ 素晴らしい
連載	✅ マニュアル	⚠️コンプレックス	✅ マニュアル	✅ 内蔵
定型文	⚠️中程度	✅ 低い	⚠️高い	✅ ミニマル
外部依存性なし	✅ はい	❌NuGet	✅ はい	✅ はい

これが .NET エコシステムにとって何を意味するか

差別的結合の導入は、.NET エコシステム全体に波及します。私が期待しているものは次のとおりです。

ライブラリの設計が改善されます。 現在、「見つからない」ことを示すために null を返したり、検証の失敗に対して例外をスローしたりする API は、代わりに Result<T, E> タイプを返すことができるようになります。これにより、型シグネチャで障害モードが明確になります。ドキュメントやソースコードを読むのではなく、メソッドシグネチャを見ることで、何が問題になるのかがわかります。

ドメインモデリングがより表現力豊かになります。 問題のドメインとコード表現の間のギャップが劇的に縮小します。ドメインの専門家が「支払いにはクレジットカード、銀行振込、または代金引換が可能です」と言う場合、それを継承階層に変換するのではなく、結合として直接モデル化できます。

C# 開発者が F# のアイデアにアクセスできるようになります。 多くの C# 開発者は、遠くから F# の型システムに憧れてきましたが、組織に F# を採用することができませんでした。ユニオン型は、F# の最も強力な機能の 1 つを C# にもたらします。これは、.NET エコシステム全体にとって有益です。

実行時エラーが減少します。 徹底的なチェックだけでも、カテゴリ全体のバグを防ぐことができます。新しいバリアントを共用体に追加するたびに、コンパイラはコードベース内の更新が必要なすべての場所を案内します。 switch の忘れ去られるケースや、運用環境でのみ表示されるデフォルトのブランチの NotImplementedException はもう必要ありません。

結論

差別的ユニオンは 10 年近くにわたって C# コミュニティの要望リストのトップにありましたが、それには十分な理由があります。これらは、型システムの根本的なギャップ、つまりコンパイラによって強制される安全性を備えた「いくつかのもののうちの 1 つ」となるデータをモデル化する機能を解決します。

提案された union キーワードは、C# のパターンマッチングと深く統合し、ジェネリックスと連携し、メソッドとインターフェイスをサポートし、実行時ではなくコンパイル時にバグを検出する徹底的なチェックを可能にする、クリーンで簡潔な構文をもたらします。

ドメインモデルを構築している場合でも、明示的なエラータイプを使用した API を設計している場合でも、ステートマシンを実装している場合でも、単に厄介な継承階層をより自然なものに置き換えようとしている場合でも、ユニオン型は C# の記述方法を変えることになります。

私たちはこれを長い間待っていました。構文は洗練されており、既存の言語機能との統合は思慮深く行われており、実際的な影響は .NET エコシステム全体にわたって感じられます。

プレビューリリースに注目し、機能を試して、言語設計チームにフィードバックを提供してください。これは、一度使用すると、これなしでどうして生きていたのかと不思議に思うような機能の 1 つです。

セマンティックカーネルを使用した C# での RAG システムの構築

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

はじめに

LLM を使用して自分のデータ (会社のドキュメント、製品仕様、社内ナレッジベース) に関する質問に答えようとしたことがあるなら、おそらく、LLM が幻覚を示すか、単に「それに関する情報がありません」と表示されることに気づいたでしょう。それは、モデルは何に基づいてトレーニングされたかしか知らないからです。

RAG (検索拡張生成) はこれを修正します。データに基づいてモデルを微調整する代わりに、クエリ時にドキュメントの関連するチャンクを取得し、それらをコンテキストとして LLM に渡します。その後、モデルは実際のデータに基づいた回答を生成します。

この投稿では、セマンティックカーネルを使用して 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();

2 つのモデルが必要です。1 つはチャット完了 (質問に答える) 用、もう 1 つは埋め込みを生成する (テキストをベクトルに変換する) 用です。

データモデルの定義

ベクターストア内のドキュメントチャンクを表すクラスが必要です。

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;
 }
}

オーバーラップは重要です。これにより、チャンク間の境界のコンテキストが失われないことが保証されます。関連する文が 2 つのチャンクに分割されている場合、重複することは、その文が少なくとも 1 つのチャンクに完全に表示されることを意味します。

ドキュメントの取り込み

次に、ドキュメントをベクターストアに取り込むためにすべてをまとめてみましょう。

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

本番環境への移行

インメモリベクターストアはプロトタイピングには最適ですが、運用環境では永続的なベクターデータベースが必要になります。セマンティックカーネルには、いくつかのオプション用のコネクタがあります。

# 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 で最も実用的なパターンの 1 つです。これにより、微調整することなく独自のデータに AI を活用した Q&A システムを構築でき、セマンティック カーネルにより 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 のワークフロー機能が提供するものです。エージェントをグループチャットに放り込んで、彼らがそれを理解してくれることを期待するのではなく、明示的なステップ、依存関係、およびエージェント間のデータフローを定義します。

エージェントのワークフローとは何ですか?

エージェントのワークフローはパイプラインのようなものだと考えてください。各ステップは専門のエージェントによって処理され、あるステップの出力は次のステップにフィードされます。ステップは、結果に基づいて、順次、並列、または条件付きで実行できます。

いくつかの例:

コンテンツパイプライン: 調査 → 草案 → レビュー → 公開
データ処理: 抽出 → 変換 → 検証 → ロード
カスタマーサポート: 分類 → ルート → 対応 → フォローアップ

前提条件

最新のエージェントフレームワークパッケージがあることを確認してください。

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

Azure OpenAI または OpenAI エンドポイントが構成されています。

順次ワークフローの構築

研究者、ライター、編集者の 3 人のエージェントによるコンテンツ作成ワークフローを構築してみましょう。

エージェントの定義

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);

その後、すべての研究概要を 1 つのライターエージェントにフィードして、1 つのまとまりのある投稿を作成できます。

条件分岐

実際のワークフローには意思決定が必要です。投稿が十分でない場合にライターに戻す品質チェックのステップが必要な場合があります。

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;
 }
}

ワークフローでのエラー処理

複数のエージェントをチェーンしている場合、エラー処理が重要になります。 1 つのステップが失敗しただけで、ワークフロー全体が静かにクラッシュすることは望ましくありません。

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; }
}

ベストプラクティス

いくつかのエージェントワークフローを構築した後、私が学んだことは次のとおりです。- エージェントの指示に重点を置く — 各エージェントは 1 つのことをうまく実行する必要があります。スイスアーミーナイフのエージェントになろうとしないでください。

コンテキストを制限する — 会話履歴全体をすべてのエージェントに渡さないでください。各ステップに必要なものだけを与えます。
リビジョン制限を設定 — 品質ループは優れていますが、注意しないと永久に実行される可能性があります。常に最大反復回数の上限を設定します。
すべてをログに記録 — エージェントの出力は予測できない場合があります。デバッグのためにすべてのステップの入力と出力をログに記録します。
並列実行を賢く使用してください - 速度は向上しますが、API レート制限とトークンコストに注意してください。
最初に小規模なモデルでテストします — 本番環境で GPT-4o に切り替える前に、GPT-3.5 でワークフローロジックを開発およびテストします。

結論

エージェントワークフローを使用すると、各エージェントが専門家である複雑な複数ステップの AI パイプラインを構築できます。順次ワークフローから開始し、ステップが独立した並列実行を追加し、品質ゲートのために条件付き分岐を使用します。パターンは構成可能です。一度コツを掴めば、かなり洗練された自動化を構築できます。

コーディングを楽しんでください!

リソース

Blazor コンポーネントのライフサイクル: 完全なガイド

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

私はしばらく Blazor を使用してきましたが、正直に言って、最初はライフサイクルの方法に戸惑いました。 OnInitialized 対 OnInitializedAsync? OnParametersSet vs 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

ここで、データのロード、サービスの初期化、デフォルト値の設定などのセットアップ作業を行います。これは、コンポーネントが最初に作成されたときに 1 回実行されます。

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

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

私をつまずかせた点が 1 つあります。Blazor サーバーでは、プリレンダリング中に OnInitializedAsync が 2 回呼び出されます。 1 回目はサーバー側のプリレンダリング中、2 回目は 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 に直接関わるものを設定している場合は、ここで設定します。

ShouldRender

これはあまり知られていませんが、非常に便利です。 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
}

私はこれを使用して、大きなリストを処理するコンポーネントを最適化しました。項目が変更されるたびに再レンダリングするのではなく、更新をバッチ処理し、最後に 1 回レンダリングします。

破棄 / 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 サービス。

状態が変化しましたこれはライフサイクル手法ではありませんが、密接に関連しています。これは 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 のエージェントフレームワークとは何ですか?

Agent Framework は、AI エージェントおよびマルチエージェントシステムを構築、オーケストレーション、展開するための Microsoft のソリューションです。これは、順次、同時、またはハンドオフパターンを通じて動作できるエージェントを作成するための柔軟な基盤を提供します。このフレームワークは OpenAI、Azure OpenAI、Microsoft Foundry モデルをサポートしており、非常に多用途です。

主な機能は次のとおりです。

マルチエージェントオーケストレーション: グループチャット、順次、同時、ハンドオフパターン
プラグインエコシステム: ネイティブ関数、OpenAPI、およびモデルコンテキストプロトコル (MCP) で拡張します。
ワークフローサポート: エグゼキュータとエッジを使用して複雑なエージェントパイプラインを構築

前提条件

コードに入る前に、以下が揃っていることを確認してください。

.NET9
Azure OpenAI アクセス (または OpenAI API キー)
Visual Studio または Visual Studio Code

必要なパッケージをインストールします (プレビュー中は --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

ギフトショッピングエージェント

当社のクリスマスプレゼントファインダーは、連携する 3 人の専門エージェントで構成されます。

ギフトアイデアエージェント - 受取人のプロフィールに基づいてクリエイティブなギフトの提案を生成します
価格比較エージェント - さまざまな店舗間で最高の価格を見つけます
サマリーエージェント - 最終的な推奨事項をまとめます

モデル

まず、エージェントパイプラインを流れるデータモデルを定義します。

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 を使用して実際の Web 検索を追加する

これまでのところ、エージェントは AI モデルの知識に基づいて応答を生成しています。しかし、Web で実際の製品の価格と在庫状況を検索したい場合はどうすればよいでしょうか?ここで、Bing Search によるグラウンディング が登場します。これは、Microsoft Foundry (旧称 Azure AI Foundry) で利用可能なツールで、エージェントが応答を生成するときにリアルタイムの公開 Web データを組み込むことができます。

まず、Azure Portal で Grounding with Bing Search リソースを作成する必要があります。必ず AI プロジェクトと同じリソースグループに作成してください。

Bing Search を使用したグラウンディングの設定

Grounding with Bing Search の利点は、Azure AI エージェントと直接統合できることです。エージェントは、ユーザーのクエリに基づいて検索ツールをいつ使用するかを決定し、Web を検索し、その結果を使用して根拠のある応答を生成します。

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;
 }
}

Real Search を使用した価格比較エージェントの作成

次に、Web で実際の製品情報を検索する完全な価格比較エージェントを作成しましょう。

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 を使用したグラウンディングの重要な側面の 1 つは、応答にソース Web サイトへのリンクを含む引用が含まれていることです。それらを抽出して表示する方法は次のとおりです。

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 によるグラウンディング を使用して、実際の製品リスト、現在の価格、利用可能なセールをライブ Web から検索します。エージェントはクエリに基づいていつ検索するかを自動的に決定し、適切な引用を含む根拠のある応答を返します。

完全なプログラム

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 と Bing Search を統合することにより、当社の価格比較エージェントは実際に Web で現在の価格、取引、在庫状況を検索できるようになり、単純な AI チャットボットが適切な引用を備えた真に役立つショッピングアシスタントに変わります。

フレームワークは逐次パターン、同時パターン、およびハンドオフパターンをサポートしているため、ニーズに正確に一致するエージェントシステムを設計できます。ギフトを探す場合でも、旅行を計画する場合でも、その他の複数ステップのタスクでも、エージェントフレームワークはそれを実現するための構成要素を提供します。このホリデーシーズンは、AI エージェントにリサーチを任せて、あなたはプレゼントのラッピングや家族との時間を楽しむことに集中しましょう。

ソースコード

この投稿で示されている概念は、公式のエージェントフレームワークサンプルに基づいています。 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 DevBlog RSS フィードを監視し、Azure OpenAI とセマンティックカーネルを使用して記事を分析して魅力的な投稿を生成し、分析された記事ごとに詳細なマークダウンドキュメントを作成し、コンテンツを確認して共有できるように Telegram 経由で通知を送信し、投稿の重複を避けるためにすべてを追跡し、GitHub Actions 経由で自動的に実行する、AI を活用した RSS フィードアグリゲーターをどのように構築したかについて説明します。

このソリューションのあらゆる側面を詳しく見てみましょう。

このプロジェクトの裏話

情報過多と共存する

このツールを作成する前の私の典型的な朝の様子を描いてみましょう。私は朝起きてコーヒーを飲み、ラップトップを開いて Microsoft 開発者エコシステムの最新情報をチェックしました。まず、メインの DevBlogs サイトに移動して、重大な発表があるかどうかを確認します。次に、.NET ブログを特にチェックします。それが私の主要なテクノロジスタックだからです。その後、AI の重要性がますます高まっているため、セマンティックカーネルのブログに移動します。 IDE の更新は日常のワークフローに大きな影響を与える可能性があるため、Visual Studio ブログがリストの次に挙げられました。次に、CI/CD および GitHub 関連のニュースに関する DevOps ブログ、クラウドインフラストラクチャの更新に関する All Things Azure ブログ、最後にデータベースのイノベーションに関する Azure SQL ブログが続きました。

チェックすべきフィードは 7 つあります。これらの各ブログは、週に複数の記事を公開します。.NET Conf や Build などの主要な発表期間には、1 日に複数の記事を公開することもあります。追跡し、読み、共有する必要がある記事は数十件になる可能性があります。ここで重要なのは、コミュニティと知識を共有することを重視する人間として、これらの記事をただ読むことだけを望んでいたわけではありません。最も価値のあるものを LinkedIn のネットワークと共有し、他の開発者も最新情報を入手できるようにしたいと考えました。しかし、LinkedIn で優れた投稿を作成するには時間がかかります。記事を徹底的に読み、重要なポイントを理解し、それが読者にとってなぜ重要なのかを考え、魅力的なフックを作成し、すべてを適切にフォーマットする必要があります。これに週に数本の記事を掛けると、作業時間になります。

私が本当に欲しかったもの

何か月もこの問題に対処した後、私は腰を据えて、理想的な解決策とはどのようなものかを考えました。何よりもまず、重要な発表を二度と見逃したくありませんでした。新しい記事が公開されるとすぐに、システムが自動的にそれをキャッチする必要があります。また、AI に魅力的な投稿の作成を支援してもらい、コンテンツ作成の時間を節約したいと考えていました。これは、私の声を完全に置き換えるのではなく、カスタマイズできる確かな出発点を提供するためでした。

一貫性も大きな要素でした。毎日手動で行うことを忘れずに、コンテンツを定期的に共有したいと考えていました。追跡の側面も重要でした。重複投稿やフォロワーの迷惑を避けるために、自分がすでに共有した内容を知る方法が必要でした。最後に、処理したすべての内容を永久に記録して整理整頓し、どのようなトピックを扱ったかを振り返って確認できるようにしたいと思いました。

ソリューションが形になる

私が思い描いていたソリューションは、GitHub Actions を使用して完全にハンズフリーでスケジュールに従って実行されるものです。ブラウザのタブを 1 つも開かなくても、7 つのフィードすべてが自動的に取得されます。 AI コンポーネントは実際にコンテンツを読んで理解し、視聴者にとって役立つ方法で要約します。投稿を一から書く必要がなくなり、すぐに共有できるソーシャルメディアコンテンツが作成され、必要に応じて調整できるようになります。すべてはレビューのために私の Telegram に送信されるので、携帯電話をざっと見て、何を共有するかを決めることができました。そしてもちろん、将来の参照のためにすべてを永久に記録します。

構築を始める前に

マシンに必要なもの

このチュートリアルを進めるには、開発マシンにいくつかのものがインストールされている必要があります。最も重要なものは、.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 分のアクションランタイムが提供され、パブリックリポジトリでは無制限のアクションランタイムが提供されます。

これを可能にするライブラリ

私たちのプロジェクトは 3 つの主要な NuGet パッケージに依存しており、それぞれが特定の目的を果たします。

1 つ目は HtmlAgilityPack で、.NET での HTML 解析のゴールドスタンダードです。ブログから記事を取得すると、ナビゲーションメニュー、フッター、広告、その他私たちが気にしないあらゆる種類の要素を含む、ページの完全な HTML が返されます。 HtmlAgilityPack を使用すると、その HTML を解析して、必要な記事コンテンツだけを抽出できます。

2 番目のパッケージは Microsoft.SemanticKernel で、AI モデルをアプリケーションに統合するための Microsoft の SDK です。これは、.NET コードと GPT-4 などの大規模な言語モデルの間の橋渡しであると考えてください。 API 呼び出し、トークン管理、応答解析の複雑さをすべて処理するため、AI に実際に実行してもらいたいことに集中できます。

3 番目のパッケージは System.ServiceModel.Syndication で、RSS フィードと Atom フィードを解析するための組み込みサポートを提供します。 RSS は古いテクノロジーのように思えるかもしれませんが、ブログやニュースサイトから構造化された更新情報を取得するための最良の方法であることに変わりはありません。このパッケージは、生の XML フィードを、扱いやすい厳密に型指定された C# オブジェクトに変換します。

アーキテクチャを理解する

ピースがどのように組み合わされるか

コードの説明に入る前に、すべてのコンポーネントがどのように連携して動作するかを説明しましょう。全体像を理解すると、実装の詳細がより明確になります。

最上位レベルには、オーケストレーターとして機能するメインの Program.cs ファイルがあります。これはアプリケーションのエントリポイントであり、他のすべてのコンポーネントを調整します。アプリケーションが実行されると、まず環境変数 (API キーや Telegram 認証情報など) から設定が読み込まれます。次に、7 つの Microsoft DevBlog ソースすべてから RSS フィードを取得します。これらのフィードを処理するときに、同じ記事が複数のフィードに表示される場合に対処するために記事の重複が排除されます。各記事を追跡ファイルと照合して、すでに処理されているかどうかを確認します。新しい記事の場合は、処理のために AI アナライザーに渡します。ArticleAnalyzer クラスは、AI の魔法が起こる場所です。このコンポーネントは記事を受け取り、それに対していくつかの処理を実行します。まず、記事の URL から完全な HTML コンテンツを取得します。次に、その HTML からクリーンなテキストを抽出し、不要なナビゲーション要素、スクリプト、スタイルをすべて削除します。クリーンテキストを取得すると、慎重に作成されたプロンプトとともにセマンティックカーネルを介してそれを Azure OpenAI に送信します。 AI は記事を分析し、概要、重要なトピック、関連性の説明、そして最も重要なことに、すぐに使用できる LinkedIn 投稿を含む構造化された応答を返します。アナライザーはこの応答を解析し、このすべての情報を含む ArticleAnalysis オブジェクトを返します。

MarkdownGenerator クラスは、ArticleAnalysis オブジェクトを取得し、その永続的なレコードを作成します。すべての記事のメタデータ、AI の分析、生成された投稿を含む、適切にフォーマットされたマークダウンファイルが生成されます。これらのファイルは generated-posts ディレクトリに保存され、処理したすべてのものを検索可能なアーカイブとして保存できます。

最後に、Telegram 統合により、生成された投稿コンテンツが携帯電話に送信されます。これは、人間として AI の作業をレビューし、それを共有するかどうかを決定するポイントです。ボットは投稿コンテンツを含むメッセージを送信します。それを LinkedIn に直接コピーするか、最初に変更することができます。

データの流れ

新しい記事が .NET ブログに公開されると何が起こるかを説明します。ワークフローは、GitHub Actions がスケジュールに従って (たとえば 6 時間ごとに) アプリケーションをトリガーすると開始されます。アプリケーションが起動し、7 つすべての RSS フィードの取得を開始します。各フィードは、そのブログの最新の記事を含む XML ドキュメントを返します。

各フィードを解析すると、個々の記事が抽出され、リストに保存されます。ただし、ここには注意が必要です。DevBlog のメインフィードには、個々のカテゴリフィードにも表示される記事が含まれることがよくあります。したがって、「.NET 10」に関する記事は、メインフィードと .NET 固有のフィードの両方に表示される可能性があります。これは、HashSet 内の URL を追跡することで処理され、重複が自動的に防止されます。

重複を除去した記事のリストを取得したら、フィルタリングして最近の記事のみに絞ります。通常は、ここ 1 日ほどに公開された記事です。以前の実行ですでに処理した古い記事は処理したくありません。次に、最近の記事を追跡ファイルと照合してチェックします。記事についてすでに処理して投稿している場合は、その記事をスキップします。

新しい記事ごとに、AI 分析パイプラインが開始されます。アナライザーは記事全体の HTML を取得し、クリーンアップして、プロンプトとともに GPT-4 に送信します。 AI は記事を読み取り、LinkedIn の投稿とともに包括的な分析を生成します。この分析を記録のためにマークダウンファイルに保存します。分析が完了したら、メッセージをフォーマットし、テレグラム経由で送信します。メッセージには、URL とハッシュタグが追加された生成された投稿コンテンツが含まれます。携帯電話で通知を受け取り、投稿を確認し、気に入ったものがあれば、数回タップするだけでコピーして LinkedIn で共有できます。

最後に、追跡ファイルを更新してこの記事を処理済みとしてマークします。これにより、今後の実行では再び処理されなくなります。ファイルが作成または変更された場合、GitHub Actions はこれらの変更をリポジトリにコミットして、すべての同期を維持します。

プロジェクトを最初からセットアップする

ソリューション構造の作成

構築を始めましょう。ターミナルを開き、プロジェクトを作成する場所に移動します。私はプロジェクトを Development フォルダーに整理しておくのが好きですが、自分にとって都合の良い場所にどこにでも置くことができます。

まず、新しいソリューションファイルを作成します。 .NET では、ソリューションは複数のプロジェクトを保持できるコンテナです。今のところプロジェクトは 1 つだけですが、ソリューションから始めると、後で必要に応じてプロジェクトを追加するのが簡単になります。コマンド 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 パッケージを追加し、開発のほとんどを行います。

必要なパッケージの追加

プロジェクトを作成したら、前に述べた 3 つの 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 をターゲットとして、暗黙的な using や null 許容参照型などの最新の C# 機能を使用して、実行可能ファイル (OutputType は Exe) を構築していることを .NET に伝えます。 ItemGroup セクションには、3 つのパッケージの依存関係とその正確なバージョンがリストされています。

RSS フィードを詳しく見る

RSS とは何ですか?

フィードを取得するコードを書き始める前に、何を扱うのかを必ず理解してください。 RSS は Really Simple Syndication の略で、コンテンツ更新を配布するための標準化された XML 形式です。アイデアはシンプルです。ユーザーに新しいコンテンツがあるかどうかを確認するために Web サイトにアクセスするよう要求する代わりに、最近のコンテンツをリストした機械可読ファイルを公開します。アプリケーションはこのファイルを定期的にポーリングして、新しい記事を検出できます。

RSS は 1990 年代後半から 2000 年代初頭にかけて存在しました。時代遅れのテクノロジーだと思うかもしれませんが、実際には今でも、特にブログ、ニュースサイト、ポッドキャストなどで広く使用されています。 RSS の利点はそのシンプルさです。これは定義された構造を持つ単なる XML であり、どのアプリケーションでも解析できます。

DevBlogs フィードの構造Microsoft DevBlog から RSS フィードをフェッチすると、特定の構造に従った XML ドキュメントが返されます。最上位には、単一のチャネル要素を含む rss 要素があります。チャネルはブログ自体を表し、ブログのタイトル、URL、説明などのメタデータが含まれます。

チャネル内には複数の item 要素があり、それぞれが個々のブログ投稿を表します。各項目には、タイトル (記事の見出し)、リンク (記事全文を読める URL)、pubDate (記事の公開日)、dc:creator 要素 (著者の名前)、1 つ以上の category 要素 (記事のタグ)、説明 (通常は記事の概要または抜粋) が含まれます。

これがどのようなものかを単純化した例を次に示します。

<?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 のセマンティックカーネルフィードでは、AI のオーケストレーションと統合について説明しています。これは、AI が現代の開発の中心となるにつれてますます重要になっています。

Visual Studio フィード (devblogs.microsoft.com/visualstudio/feed) では、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 (Document Type Definition) 宣言が含まれる場合があります。 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}");
 }
}

ここでは 2 つのコレクションを管理しています。 allArticles リストには、見つかったすべての記事が、どのフィードから来たのかとともに保持されます。 seenUrls HashSet は、すでに見た記事の URL を追跡し、重複を避けるのに役立ちます。

各フィード URL をループし、取得操作を try-catch ブロックでラップします。特定のフィードの取得が失敗した場合 (おそらくサーバーが一時的にダウンしている可能性があります)、警告をログに記録し、次のフィードを続行します。このようにすると、1 つのフィードに問題があっても、他のフィードの処理が妨げられることはありません。

正常にフェッチされたフィードごとに、その項目を反復処理します。アイテムのリンクコレクションから記事の URL を抽出します。 URL がすでにセット内にある場合、HashSet.Add メソッドは false を返します。これは重複排除ロジックに最適です。記事が新しい場合にのみリストに追加します。

各記事の横にフィード URL を保存します。これは、この情報が後で役立つ可能性があるためです。たとえば、デバッグやログ記録の目的で、記事がどの特定のフィードから来たのかを知りたい場合があります。

重複の処理と状態の追跡

重複排除の課題

前に述べたように、Microsoft DevBlogs には階層的なフィード構造があり、これが興味深い課題を生み出しています。 .NET チームのメンバーが、たとえば .NET 10 のパフォーマンス向上に関する記事を公開すると、その記事はメインの DevBlogs フィードと .NET 固有のフィードの両方に表示される可能性があります。場合によっては、IDE 機能に関連する場合、Visual Studio フィードに表示されることもあります。

すべてのフィードのすべての記事を単純に処理すると、同じ記事を何度も分析して投稿することになります。これにより、Azure OpenAI への API 呼び出しが無駄になり、Telegram に重複した通知がスパム送信され、重複した通知を投稿するとフォロワーが迷惑する可能性があります。解決策は URL ベースの重複排除です。各記事には固有の URL があるため、それを識別子として使用できます。 HashSet データ構造は、O(1) の検索時間を提供し、重複を自動的に防止するため、これに最適です。すでにセット内にある URL を追加しようとすると、Add メソッドは単に false を返し、その記事をスキップする必要があることを知らせます。

マークダウンを使用した永続的な状態

重複排除は 1 回の実行内で重複を処理しますが、複数の実行ではどうなるでしょうか?アプリケーションが 6 時間ごとに実行される場合、どの記事がすでに処理されたかを記憶し、再度処理しないようにする必要があります。

この状態を posted-articles.md というマークダウンファイルに保存することにしました。なぜマークダウンなのか？理由はいくつかあります。まず、人間が判読できるという点です。ファイルを開いて、どの記事を共有したかをすぐに確認できます。 2 番目に、バージョン管理されています。このファイルは 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 が表面的に異なる場合でも記事が重複していると認識されるようになります。

新しい記事を保存する

記事が正常に処理されたら、それを追跡ファイルに追加する必要があります。

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 アプリケーションを構築するためのフレームワークを提供します。

このユースケースでは、セマンティックカーネルのチャット完了機能を使用しています。 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 など) の 3 つのパラメーターを取ります。これらは環境変数から渡され、認証情報を安全に保ちます。

完璧なプロンプトを作成する

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 コンテンツクリエイターです」という明確な役割を与えることから始めます。これにより、モデルは適切なスタイルと音声で応答できるようになります。

AI が必要とするすべてのコンテキスト (記事のタイトル、著者、URL、RSS フィードのタグ、記事の全コンテンツ) を提供します。提供するコンテキストが多ければ多いほど、分析はより適切になります。

次に、何を返したいかを正確に指定します。要約、重要なトピック、関連性の説明、LinkedIn への投稿の 4 つをお願いします。特に LinkedIn の投稿については、良い投稿の条件について詳しく説明します。フックがあり、価値が強調され、行動喚起が含まれ、絵文字が適切に使用され、プロフェッショナルな口調が維持される必要があります。

否定的な指示も同様に重要です。投稿にハッシュタグや URL を含めないよう AI に明示的に指示します。なぜ？これらを個別に追加するため、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 オブジェクトを作成し、プロンプトをユーザー メッセージとして追加します。これは、チャットベースの対話のためのセマンティック カーネルの抽象化です。これをチャット完了サービスに送信し、応答を返します。最後に、応答を解析して個々のセクションを抽出します。

### 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 にロードし、HTML をツリー構造に解析します。次に、XPath を使用して、削除するすべてのノードを選択します。 XPath 式 //script|//style|//nav|//footer|//header は、すべてのスクリプト要素 (不要な JavaScript コード)、スタイル要素 (不要な CSS)、nav 要素 (ナビゲーションメニュー)、フッター要素、およびヘッダー要素を選択します。

これらのノードを削除すると、HTML タグを削除しながらすべてのテキストコンテンツを抽出する InnerText プロパティを取得します。これにより、記事のプレーンテキストが得られます。最後に、空白を削除します。 HTML には、複数のスペース、タブ、改行など、書式設定のための余分な空白が多く含まれていることがよくあります。正規表現を使用して一連の空白文字を単一のスペースに置き換え、結果をトリミングします。

記事全文の取得

RSS フィードでは概要のみが提供され、記事の全内容は提供されません。完全なテキストを取得するには、記事の Web ページを取得する必要があります。

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 メソッドは ArticleAnalysis オブジェクトを受け取り、適切にフォーマットされたマークダウンドキュメントを生成します。

ファイル名には、日付とタイトルのサニタイズされたバージョンが含まれます。これにより、ファイルを時系列に簡単に並べ替えて、一目で識別できるようになります。

安全でないファイル名の処理

記事のタイトルには、ファイル名に使用できない文字 (コロン、スラッシュ、疑問符、引用符など) を含めることができます。これらをサニタイズする必要があります。

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 リクエストです。複雑な認証フローや、基本的な機能に必要な Webhook はありません。Telegram は、携帯電話、デスクトップ、Web ブラウザなど、どこでも機能します。どこにいても通知を受信し、すぐに応答できます。

メッセージはリッチフォーマットをサポートします。太字テキスト、斜体、さらにはコードブロックを使用して、通知を読みやすくすることができます。

Telegram ボットの作成

Telegram ボットのセットアップは驚くほど簡単です。 Telegram を開いて @BotFather を検索します。これは、ボットを作成および管理するための Telegram の公式ボットです。 BotFather との会話を開始し、コマンド /newbot を送信します。 BotFather は、ボットの名前 (これは表示名です) とユーザー名 (これは一意であり、「bot」で終わる必要があります) を尋ねます。これらを指定すると、BotFather がボットを作成し、API トークンを提供します。このトークンはパスワードのようなものです。秘密にして、パブリックリポジトリにコミットしないでください。

ボットがメッセージの送信先を認識できるようにチャット ID を見つけるには、チャット ID を検索して [開始] を押して、新しいボットとの会話を開始します。次に、ブラウザまたはカールを使用して URL https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates にアクセスします。応答で chat オブジェクトを探します。id フィールドはチャット ID です。

API 経由でメッセージを送信する

Telegram メッセージを送信するための関数は次のとおりです。

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 の場合、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 分析を行わずに、フィードを取得して記事を追跡します。### グレースフルデグラデーション

このグレースフルデグラデーションの概念は重要です。 1 つのオプション機能が構成されていないという理由だけでアプリケーションがクラッシュすることは望ましくありません。

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 アクションによる自動化

GitHub アクションを使用する理由

このソリューションの真の力は自動化によってもたらされます。アプリケーションを数時間ごとに手動で実行するのではなく、バックグラウンドで自動的に実行したいのです。

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 の午前 0 時、午前 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 は、最新の言語機能と優れたパフォーマンスによる強固な基盤を提供しました。セマンティックカーネルは AI の統合を簡単にし、複雑な API 呼び出しと応答管理をすべて処理します。 Azure OpenAI は、技術的な内容を実際に理解して分析する機能であるインテリジェンスを提供しました。 HtmlAgilityPack は、Web ページからクリーンテキストを抽出するという厄介な問題を解決しました。 System.ServiceModel.Syndication により、RSS の解析が簡単になりました。 Telegram Bot API は無料で信頼性の高い通知を提供してくれました。そして、GitHub Actions は、自動化されたスケジュールされた実行によってすべてを結び付けました。

コストについて考える

あなたが抱く疑問の 1 つは、「これを実行するのにどれくらいのコストがかかるのか?」ということです。答えは「あまり多くはない」です。

Telegram は完全に無料です。ボットを介してメッセージを送信するのに料金はかかりません。

GitHub Actions はパブリックリポジトリでは無料です。プライベートリポジトリの場合、無料枠で毎月 2,000 分を利用できますが、これはこのユースケースには十分以上です。

Azure OpenAI は唯一の有料コンポーネントであり、コストは最小限です。 GPT-4o を使用すると、一般的なブログ記事の分析にかかる費用は 1 ～ 3 セントになります。たとえ月に数十の記事を処理しているとしても、AI コストは 1 ドル未満です。

次はどこに行けばよいでしょうか

このソリューションは私のニーズにはうまく機能しますが、拡張する方法はたくさんあります。複数のソーシャルプラットフォームのサポートを追加できます。LinkedIn に加えて Twitter/X、Mastodon、または Bluesky に投稿することもできます。センチメント分析を実装すると、長期にわたる記事の論調を追跡し、傾向を特定できます。フィードごとに異なるプロンプトテンプレートを許可し、トピックごとに異なるスタイルの投稿を生成できます。 Telegram を使用する代わりに、投稿を確認および管理するための Web ダッシュボードを構築することもできます。投稿されたコンテンツのエンゲージメント指標を追跡して、どのトピックが視聴者に最も共感を呼んだかを確認できます。

最終的な考えこのプロジェクトで私が最も気に入っている点は、私が強く信じている哲学を体現していることです。つまり、退屈な部分は自動化で処理し、創造的で意思決定の部分は人間に任せるべきです。システムは、取得、解析、分析、生成などの面倒な作業をすべて実行しますが、共有する前にすべてを確認します。 AI によって生成された投稿は、カスタマイズおよびパーソナライズできる出発点となります。

.NET、セマンティックカーネル、Azure OpenAI の力を組み合わせることで、品質と一貫性を維持しながら毎週何時間もの手作業を節約できるツールを作成しました。これは、日常生活に大きな変化をもたらす実用的な自動化です。

同様のものを作成したり、改善のアイデアがある場合は、ぜひお知らせください。 LinkedIn でお気軽にご連絡ください。

コーディングを楽しんでください、そしてメリークリスマス! 🎄

Microsoft のエージェントフレームワークを使用したマルチエージェント AI システムの構築

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

はじめに

マルチエージェント AI システムの時代が到来しました。業界は、単一のモノリシック AI がすべてを処理するのではなく、よく組織された専門家チームのように、協力して複雑な問題を解決する専門エージェントに移行しています。 1 人のエージェントが調査を行い、もう 1 人が分析し、3 人目が書き込みを行い、コーディネーターが全員の進捗状況を把握します。

大規模な言語モデルを扱ったことがある場合は、1 つのプロンプトで実行できる処理の上限に達している可能性があります。コンテキストウィンドウがいっぱいになり、命令が複雑になり、品質が低下します。マルチエージェントアーキテクチャは、各エージェントが 1 つの分野の専門家となり、複雑なタスクを焦点を絞った責任に分解することでこの問題を解決します。

より広範なセマンティックカーネルエコシステムの一部である Microsoft のエージェントフレームワークは、.NET 開発者にまさにこの種のシステムを構築するための最上級のツールキットを提供します。この投稿では、ゼロからマルチエージェントパイプラインを完全に機能させるまでに取り組み、開始するために必要な中心的な概念、オーケストレーションパターン、実践的なコードを取り上げます。

Microsoft のエージェントフレームワークとは何ですか?

Agent Framework は、.NET で AI エージェントとマルチエージェントシステムを構築、オーケストレーション、展開するための Microsoft の答えです。これは、2023 年以来 Microsoft の AI オーケストレーション用のオープンソース SDK であるセマンティックカーネルと並行し、深く統合されています。

次のように考えてください。セマンティックカーネル はプリミティブ (カーネル、プラグイン、メモリ、プランナー) を提供し、エージェントフレームワーク は、エージェント間の通信と調整のために特別に設計された高レベルの抽象化を提供します。

このフレームワークは、Azure OpenAI、OpenAI、Azure AI Foundry でホストされるモデルなど、複数のモデルプロバイダーをサポートします。モデルに依存しない設計ですが、Azure エコシステムと深く統合されているため、エンタープライズシナリオにとって特に魅力的です。

主な機能は次のとおりです。

複数のエージェントタイプ: さまざまなバックエンドの ChatCompletionAgent、OpenAIAssistantAgent、および AzureAIAgent
オーケストレーションパターン: 順次、同時、ハンドオフ、グループチャットのワークフロー
プラグインエコシステム: ネイティブ C# 機能、OpenAPI 仕様、モデルコンテキストプロトコル (MCP) ツールを使用してエージェントを拡張します。
会話管理: 組み込みのスレッド化、履歴管理、および終了戦略
可観測性: エージェントの対話を追跡するための 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 は、複数のエージェント間のマルチターン会話を管理し、次に話す人、会話がいつ終了するか、履歴がどのように共有されるかを制御します。ここで、マルチエージェントのコラボレーションの魔法が起こります。

オーケストレーションパターン

このフレームワークは 4 つの主要なオーケストレーションパターンをサポートしており、それぞれが異なる問題に適しています。

シーケンシャル

エージェントは、定義された順序で次々に実行されます。エージェント 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}");

同時実行

複数のエージェントが同じ入力に対して同時に作業します。作業を扇状に広げてから、結果を集計します。 3 人のレビュー担当者が同じプルリクエストを検討するなど、多様な視点を得るのに最適です。

ハンドオフ

エージェントは、会話コンテキストに基づいて制御を別のエージェントに移すことを決定します。これはカスタマーサービスチームの仕組みを模倣しています。最前線のエージェントが基本的な問い合わせを処理し、必要に応じて専門家にエスカレーションします。

グループチャット

複数のエージェントがオープンな会話に参加し、選択戦略に基づいて交代します。 AgentGroupChat クラスは、構成可能な交代および終了ロジックを使用してこのパターンを実装します。

最初のエージェントを構築する

実践してみましょう。最初のエージェントを段階的に構築する方法を次に示します。

前提条件

必要なものは次のとおりです。

.NET 9 SDK
デプロイされたモデルを含む Azure OpenAI リソース (例: gpt-4o)
Visual Studio または VS Code

プロジェクトのセットアップ

新しいコンソールアプリケーションを作成し、必要なパッケージをインストールします。

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 クラスは、次に誰が話すか、いつ停止するかなどの会話フローを管理します。

エージェントの定義

ライター、レビューアー、編集者の 3 人のエージェントを作成します。

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 には 2 つの重要な設定が必要です。選択戦略 (次に誰が話すか) と 終了戦略 (いつ停止するか) です。

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 は 3 つの主要な拡張メカニズムをサポートしています。

ネイティブ関数 (カーネルプラグイン)

エージェントにツールとして 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 と統合されているため、エージェントのあらゆる対話、ツール呼び出し、トークンの使用状況を追跡できます。これは、どのエージェントが問題を引き起こしたかが必ずしも明らかではないマルチエージェントワークフローをデバッグする場合に不可欠です。

セマンティックカーネルテレメトリパッケージを追加し、優先エクスポーター (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 開発者にとってこれが実用的になります。エージェント、グループチャット、選択と終了の戦略などの抽象化はクリーンであり、自然に構成されています。セマンティックカーネルのプラグインエコシステムと Azure のモデルホスティングを組み合わせることで、運用グレードのマルチエージェントシステムを構築するためのフルスタックが得られます。

フレームワークはまだ進化中ですが (多くのパッケージはプレビュー段階です)、核となるパターンはしっかりしており、方向性は明確です。 .NET で AI を活用したアプリケーションを構築している場合は、今がマルチエージェントアーキテクチャの実験を開始する時期です。

小規模から始めて、単純なタスクで共同作業する 2 つのエージェントを構築します。単一エージェントのアプローチと比較して品質の向上が確認できたら、すべてをエージェントチームに分解したくなるでしょう。

コーディングを楽しんでください!

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 とともに出荷されました。いくつかのプロジェクトにわたって Entity Framework Core 9 の作業に十分な時間を費やした後、これはここしばらくで最も意味のあるリリースの 1 つであると言えます。車輪の再発明ではなく、クエリ変換、パフォーマンス、最新のデータパターンの操作など、これまで 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 の顕著な改善点の 1 つは、プリミティブ値のコレクションをクエリに直接渡す機能です。

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 リリースで最も魅力的な機能の 1 つであり、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 の問題点の 1 つは、JSON 列内の 1 つのプロパティを更新すると、JSON ドキュメント全体が書き換えられることです。 EF Core 9 では、JSON マップ型のより詳細な変更追跡によりこれが改善され、可能な場合はよりターゲットを絞った更新が生成されます。

var order = await context.Orders.FindAsync(orderId);
order.Address.ZipCode = "10001";
await context.SaveChangesAsync();

サポートされているプロバイダーでは、BLOB 全体を書き換えるのではなく、よりターゲットを絞った JSON 変更を生成できます。

複合型 - ID のない値オブジェクト

複合型は、ドメイン駆動設計の実践者が待ち望んでいた機能の 1 つです。所有型とは異なり、複合型にはアイデンティティがなく、純粋な値のオブジェクトです。

[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 を持つ 2 つの 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 は、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) コンパイルのサポートへの継続的な投資を高く評価するでしょう。

### コンパイルされたモデル

コンパイルされたモデルは、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 パイプラインで実行できるバイナリが生成されます。

パフォーマンスのベンチマーク以下は私自身のテストによる大まかなベンチマークです。これらは、SQL Server 2022 に対して実行されている約 200 のエンティティを含むプロジェクトからのもので、BenchmarkDotNet で測定されました。数値は異なりますが、相対的な改善は同様であるはずです。

シナリオ	EFコア8	EFコア9	改善
モデルのビルド (コールドスタート)	1,850ミリ秒	320ミリ秒	~5.8 倍高速 (コンパイル)
単純なクエリ (PK による単一エンティティ)	0.42ミリ秒	0.38ミリ秒	~10% 高速
複雑なクエリ (結合 + 集計)	3.1ミリ秒	2.4ミリ秒	~23% 高速
一括更新 (10,000 行)	145ミリ秒	118ミリ秒	~19% 高速
JSON 列クエリ	2.8ミリ秒	1.9ミリ秒	~32% 高速
SaveChanges (100 エンティティ)	48ミリ秒	41ミリ秒	~15% 高速

コンパイルされたモデルの改善は最も劇的ですが、特に 1 秒あたり数千のクエリを実行する高スループットのシナリオでは、全体的な着実な改善が積み重なっていきます。

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 サポートなどの機能により、以前は扱いにくかった、または不可能だったパターンが開かれます。

私のプロジェクトに最も影響を与えた機能を 3 つ挙げるなら:

パラメーター化されたプリミティブコレクション — クエリプランのキャッシュ効率が大規模に重要となるため
JSON 列の改善 — ハイブリッドリレーショナルドキュメントパターンが非常に便利であるため
コンパイル済みモデル — 起動時間は開発者の生産性と展開速度に直接影響するためEF Core チームは EF Core 5 以来堅実な軌道を歩んできており、バージョン 9 もその傾向を引き継いでいます。すでに EF Core 8 を使用している場合、アップグレードは低リスクであり、大きなメリットがあります。古いものを使用している場合は、今ほどジャンプするのに最適な時期はありません。

楽しいコーディングと楽しいクエリ。

セマンティックカーネルの入門: C# での AI オーケストレーション

Sun, 05 Oct 2025 00:00:00 +0000

.NET アプリケーションを構築し、AI 環境の進化を見てきた人なら、おそらく次のことを疑問に思ったことがあるでしょう: コードベースをスパゲッティにせずに大規模な言語モデルを C# プロジェクトに統合する最善の方法は何ですか? それはまさに Microsoft のセマンティックカーネルが解決する問題であり、昨年これを使用して実稼働アプリケーションを構築することに費やした後、セマンティックカーネルは私の開発者ツールキットの中で最も重要なツールの 1 つになったと言えます。

この投稿では、中心となる概念の理解から現実世界の AI アシスタントの構築まで、セマンティックカーネルを始めるために必要なすべてのことを説明します。 AI 開発に少しだけ足を踏み入れている場合でも、既存の .NET アプリケーションで LLM 呼び出しを調整するための構造化された方法を探している場合でも、このガイドは役に立ちます。

セマンティックカーネルとは何ですか?

セマンティックカーネル (SK) は、Microsoft のオープンソース SDK であり、アプリケーションコードと GPT-4o、Azure OpenAI、またはその他の AI サービスなどの大規模な言語モデルの間の オーケストレーションレイヤー として機能します。これは、従来の C# コードと AI 機能をクリーンで構成可能な方法で組み合わせることができる軽量のミドルウェアと考えてください。

しかし、なぜ OpenAI API を直接呼び出さないのでしょうか?絶対に可能です。単純な使用例の場合はそれで問題ありません。しかし、次のことが必要になった瞬間に：

ユーザー入力に基づいて どの関数を呼び出すかを AI に決定させます
複数の AI 呼び出しをパイプライン内の従来のコードと結合します
メモリとコンテキストを追加して、AI が以前のインタラクションを記憶できるようにします
複雑なタスクを推論する マルチステップエージェントを構築する

…車輪の再発明をしていることに気づくでしょう。セマンティックカーネルは、ファーストクラスの .NET サポート、依存関係注入の統合、および C# 開発者にとって自然に感じられるプラグインアーキテクチャを備え、これらすべてをすぐに提供します。

このプロジェクトは GitHub の microsoft/semantic-kernel リポジトリに存在し、C#、Python、Java 用の SDK があります。 C# SDK は最も成熟しており、ここではこれに焦点を当てます。

コアコンセプト

コードを書く前に、構成要素を理解しましょう。

カーネル

Kernel は、セマンティックカーネルの中心的なオブジェクトです。これはオーケストレーターであり、AI サービス、プラグイン、構成を結び付けるものです。これを作成し、サービスとプラグインを登録し、それを使用してプロンプトを実行したり、関数を呼び出したりします。 ASP.NET Core での依存関係の挿入に慣れている場合、カーネルは非常に親しみのあるものに感じられるでしょう。カーネルは本質的に AI の強力な機能を備えたサービスコンテナーです。

プラグインと関数

プラグインは、カーネルが呼び出すことができる関連する関数のコレクションです。関数には 2 つの種類があります。

プロンプト関数 — LLM に送信される自然言語テンプレートとして定義されます。
ネイティブ関数 — カーネルが検出して呼び出すことができる属性で装飾された通常の C# メソッド

たとえば、ネイティブ関数 GetCurrentWeather(string city) と気象データをわかりやすく要約するプロンプト関数を備えた WeatherPlugin があるとします。### AI コネクタ

コネクタは、セマンティックカーネルが AI サービスと通信する方法です。最も一般的なものは次のとおりです。

AzureOpenAIChatCompletion — Azure OpenAI サービス用
OpenAIChatCompletion — OpenAI の API を直接使用する場合
ベクトル検索とメモリ用の埋め込みコネクタ

これらを起動時にカーネルに登録すれば、その他はすべて正常に動作します。

プロジェクトのセットアップ

手を汚してみましょう。まず、新しいコンソールアプリケーションを作成します。

dotnet new console -n SemanticKernelDemo
cd SemanticKernelDemo

次に、セマンティックカーネル 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);

ここで、セマンティックカーネルが輝き始めます。再利用可能なプロンプトテンプレートを定義し、バージョンを付けて、より大きなワークフローを構成できます。

プラグインとネイティブ関数

プラグインは、セマンティックカーネルが 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();

サービスを挿入する、より複雑なプラグインを構築することもできます。セマンティックカーネルは 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 は関数の結果を使用して自然言語応答を作成しますこのループは 1 回の呼び出しで複数回発生する可能性があります。AI は必要な情報をすべて収集するために複数の関数を順番に呼び出すことがあります。 FunctionChoiceBehavior.Required() を使用して、AI に少なくとも 1 つの関数の呼び出しを強制したり、使用を許可する関数の特定のリストを提供したりすることもできます。

履歴付きチャット完了

会話型アプリケーションの場合は、 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 アプリケーションで最も強力なパターンの 1 つは 検索拡張生成 (RAG) です。これは、データをベクトル空間に埋め込み、クエリ時に関連するチャンクを取得することで、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 が必要になります。ここで、セマンティックカーネルのエージェントフレームワークが登場します。

基本: チャット完了エージェント

最も単純なエージェントタイプは、チャット完了モデルを命令とプラグインでラップします。

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);
}

マルチエージェントのコラボレーション

複数のエージェントが連携している場合、物事が非常に強力になります。セマンティックカーネルは、さまざまな専門分野を持つエージェントが協力するグループチャットパターンをサポートしています。

#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 は何をするのですか?」と尋ねてください。ファイルを読み取り、分析し、説明します。「認証モジュールのドキュメントを生成する」ように依頼すると、ファイルを調べて構造を理解し、フォーマットされた概要を生成します。

制作のヒント

セマンティックカーネルアプリケーションを出荷する前に、私が苦労して学んだことがいくつかあります。

依存関係の挿入を適切に使用します。 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 は、アプリケーションの構築に関する考え方を根本的に変えるライブラリの 1 つです。これは単なる API ラッパーではなく、保守可能、テスト可能、実稼働対応の方法で従来のコードを使用して AI 機能を構築できるオーケストレーションフレームワークです。

私が最も気に入っている点は、.NET エコシステムを尊重していることです。これは、依存関係の注入、属性、非同期/待機、インターフェイスなど、すでに知られているパターンを使用し、それらを AI の世界に拡張します。まったく新しいパラダイムを学ぶ必要はありません。 AI をツールキットの別の機能として追加するだけです。

.NET アプリケーションを構築していて、まだセマンティックカーネルを試していない場合は、今がその時期です。 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 ディレクティブが鍵です。これは、デフォルトの ComponentBase の代わりに基本クラスを使用するように Blazor に指示します。これで、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 パターンなどの共有動作に最適です。ただし、継承階層を深くしすぎないでください。2 レベル以上の階層を深くする場合は、(前の投稿の LoadingComponent アプローチのような) 合成を使用したほうがよいでしょう。

私は通常、ページの「タイプ」ごとに 1 つの基本クラスに保ちます。通常のページの場合は PageBase、フォームの場合は FormPageBase です。それだけです。

投稿が気に入っていただければ幸いです!ソーシャルメディアで**@emimontesdeoca**までお気軽にご連絡ください。

リソース

ASP.NET Core Razor コンポーネントの継承

.NET Aspire: クラウドネイティブアプリケーションを正しい方法で構築する

Wed, 20 Aug 2025 00:00:00 +0000

.NET で分散アプリケーションを構築したことがある場合は、その詳細をご存知でしょう。 Web API を起動し、バックグラウンドワーカーを追加し、キャッシュには Redis、永続化には PostgreSQL、おそらくメッセージングには RabbitMQ を投入します。そして突然、ビジネスロジックの作成よりもインフラストラクチャの配線に多くの時間を費やすことになります。 appsettings.json ファイルに散在する接続文字列、設定を忘れたヘルスチェック、常に「次のスプリントの問題」である可観測性。

私はそこに行ったことがある。私が認めたい以上の回数。

まさに、.NET Aspire が解決するために設計された問題です。実稼働環境で数か月間実行した後、良い点、素晴らしい点、そして欠点など、学んだことを共有したいと思います。

.NET Aspire とは何ですか?

.NET Aspire は、.NET を使用して、監視可能で本番環境に対応した分散アプリケーションを構築するための独自のスタックです。これは従来の意味でのフレームワークではありません。ASP.NET Core を置き換えたり、新しいプログラミングモデルを強制したりするものではありません。代わりに、すでに知っていることの上に置かれ、クラウドネイティブアプリを構築する際に常に存在していたギャップを埋めます。

Aspire はその中核として 4 つのことを提供します。

AppHost — 分散アプリケーショントポロジ全体を定義するプロジェクト。どのサービスが存在し、何に依存し、どのように接続するのか。
サービスのデフォルト — ヘルスチェック、復元ポリシー、OpenTelemetry などの横断的な懸念事項をすべてのサービスに対して 1 回で構成する共有プロジェクト。
コンポーネント — 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

これにより、4 つのプロジェクトを含むソリューションが生成されます。

MyCloudApp.AppHost — オーケストレーター
MyCloudApp.ServiceDefaults — 共有構成
MyCloudApp.ApiService — サンプル Web 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 では、1 行ですべての処理が行われます。

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

// Your service-specific configuration...

var app = builder.Build();
app.MapDefaultEndpoints();
app.Run();

この 1 回の AddServiceDefaults() 呼び出しで次のことが得られます。

OpenTelemetry による構造化ログ、メトリクス、分散トレース
ライブネスおよびレディネスエンドポイントによるヘルスチェック
サービス検出 により、サービスが名前で相互に検索できるようになります
すべての発信 HTTP 呼び出しに対する 復元ポリシー (再試行、サーキットブレーカー、タイムアウト)

これは、「自分のマシンで動作する」デモと運用準備が整ったシステムを区別するものです。そして、Aspire はそれを後付けではなくデフォルトにしています。

Aspire コンポーネント

Aspire コンポーネントは、サービスがバッキングインフラストラクチャに接続する方法を標準化する NuGet パッケージです。これらは単なるクライアントライブラリではなく、ヘルスチェック、ロギング、トレース、すぐに使える構成可能な復元機能が含まれています。

レディス

var builder = WebApplication.CreateBuilder(args);
builder.AddServiceDefaults();
builder.AddRedisDistributedCache("cache");

それだけです。接続文字列は、WithReference 経由で AppHost から取得されます。このコンポーネントは、Redis によってバックアップされた IDistributedCache を登録し、ヘルスチェックと OpenTelemetry インストルメンテーションがすでに接続されています。

Redis を出力キャッシュに使用することもできます。

builder.AddRedisOutputCache("cache");

Entity Framework Core を使用した PostgreSQL

builder.AddNpgsqlDbContext<CatalogDbContext>("catalogdb", settings =>
{
 settings.DisableRetry = false;
});

これにより、AppHost で定義された catalogdb データベースへの接続を使用して DbContext が登録されます。これには、接続プーリング、ヘルスチェック、および再試行ポリシーが含まれます。

RabbitMQ

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 で 1 行でリソースを定義し、1 行で使用側サービスでそれを使用します。接続の詳細は自動的に表示されます。

## 開発者ダッシュボード

Aspire ダッシュボードは、実際に使用するまでは、あったら便利だと思われる機能の 1 つです。実際に使用すると、これなしでの作業は考えられなくなります。

AppHost をローカルで実行すると、ダッシュボードが起動して次の情報が表示されます。

- **リソースの概要** — すべてのサービスとインフラストラクチャをステータス インジケーターとともに一目で確認できます。
- **構造化されたログ** — すべてのサービスからのリアルタイムのログ ストリーミング、フィルタリングと検索が可能
- **分散トレース** — フレーム チャートとして視覚化された、複数のサービスにわたるエンドツーエンドのリクエスト トレース
- **メトリクス** — リアルタイムの HTTP リクエスト レート、エラー レート、レイテンシ、およびカスタム メトリクス
- **コンソール ログ** — 各コンテナおよびプロジェクトからの生の stdout/stderr

分散トレースは特に価値があります。リクエストがフロントエンドに到達し、カタログ API を通過し、Redis と PostgreSQL にアクセスすると、チェーン全体が各ホップのタイミングとともに表示されます。ボトルネックがどこにあるのかを推測する必要はもうありません。

デバッグ中にダッシュボードが最も役立つことがわかりました。複数のターミナル ウィンドウをたどったり、ログ ファイル間を移動したりする代わりに、サービス全体で関連するイベントをリンクする相関 ID を使用して、すべてが 1 か所にまとめられます。

ダッシュボードはスタンドアロン コンテナーとしても利用できます。つまり、ステージング環境または CI パイプラインで使用できます。

```bash
docker run --rm -p 18888:18888 \
 mcr.microsoft.com/dotnet/aspire-dashboard:latest

デプロイメント

Aspire は開発中は役に立ちますが、本番環境ではどうなるのでしょうか?ここからが現実的なことになります。

Azure コンテナーアプリ

最も簡単なデプロイパスは、ファーストクラスの Aspire サポートを備えた Azure Container Apps (ACA) です。 Azure Developer CLI を使用して直接デプロイできます。

azd init
azd up

azd init コマンドは、Aspire AppHost を検出し、必要なコードとしてのインフラストラクチャを生成します。 azd up は、AppHost トポロジに基づいて、コンテナーレジストリ、コンテナーアプリ、データベース、Redis インスタンスなどすべてをプロビジョニングします。

AppHost は基本的に展開マニフェストになります。「catalog-api は PostgreSQL と Redis に依存する」を定義する同じコードがインフラストラクチャのプロビジョニングを推進します。

Kubernetes

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 ～ 3 GB の RAM を消費する可能性があります。制約のあるマシンを使用している場合は、より軽量なリソース構成の使用を検討してください。

var redis = builder.AddRedis("cache")
 .WithContainerRuntimeArgs("--memory=256m");

結論

.NET Aspire は、分散アプリケーションの構築方法を根本的に変えました。革新的な概念を導入しているからではありません。ヘルスチェック、OpenTelemetry、コンテナオーケストレーションは新しいものではありません。しかし、それはそれらを「デフォルト」にしてしまうからです。通常は行う必要がある 100 の小さな決定を必要とし、それらを適切なデフォルトで実装し、必要に応じて上書きできるようにします。私の意見では、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 を使用したことがある場合は、おそらく認証の仕組みについてのメンタルモデルを持っているでしょう。ミドルウェアが要求をインターセプトし、Cookie またはトークンをチェックし、HttpContext.User を設定して、レースに出発します。 Blazor は、微妙ではあるが重要な方法でそのメンタルモデルを変更します。これらの違いを早い段階で理解していないと、不可能と思われる認証の問題をデバッグすることになります。

この投稿では、サーバーホスティングモデルと WebAssembly ホスティングモデルの両方をカバーしながら、Blazor で認証と承認が実際にどのように機能するかを説明したいと思います。基本的なことから、カスタムプロバイダー、外部 OAuth、そして経験豊富な .NET 開発者さえも陥る落とし穴までを見ていきます。

Blazor の認証が異なる理由

従来の ASP.NET では、すべてのユーザー操作は HTTP リクエストです。サーバーは資格情報を検証し、Cookie を設定し、後続のすべてのリクエストにその Cookie が含まれます。認証パイプラインは線形で予測可能です。

Blazor サーバーは、永続的な SignalR 接続を介して動作します。最初の HTTP リクエストでページが読み込まれた後、それ以降のすべての対話は WebSocket 経由で行われます。ボタンがクリックされるたびに新しい HTTP リクエストが送信されることはないため、対話のたびにミドルウェアが再実行されることはありません。 HttpContext は最初の接続中に使用できますが、回路の存続期間全体を通してこれに依存するとバグが発生します。

Blazor WebAssembly は完全にブラウザー内で実行されます。サーバー側 HttpContext はまったくありません。認証状態は API から取得し、クライアント側に保存し、トークン (通常は JWT) を通じて管理する必要があります。サーバーは、トークンの検証が行われる限りにおいてのみクライアントを信頼します。

これは、Blazor には、ホスティングモデルに関係なく機能する認証状態用の独自の抽象化が必要であることを意味します。その抽象化は AuthenticationStateProvider です。

認証状態: 財団

Blazor の認証システムの中心となるのは AuthenticationStateProvider です。これは、単一の重要なメソッドを公開する抽象クラスです。

public abstract Task<AuthenticationState> GetAuthenticationStateAsync();

AuthenticationState オブジェクトは ClaimsPrincipal (.NET 全体で使用されるのと同じ ID モデル) をラップします。コンポーネントは Cookie やトークンと直接通信しません。彼らは 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 はここで 2 つの役割を果たしています。一致したページコンポーネントをレンダリングする前にユーザーが認証および許可されているかどうかをチェックし、そうでない場合にはフォールバック UI を提供します。

統合 Blazor モデルを使用する .NET 8 以降では、これを App.razor で構成すると、サービス登録で AddCascadingAuthenticationState() を使用するときにフレームワークがカスケードパラメーターを自動的に処理します。

ASP.NET ID の統合

ほとんどのプロジェクトでは、認証を最初から構築する必要はありません。 ASP.NET Identity を使用すると、すぐに使えるユーザー管理、パスワードハッシュ、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 Web App テンプレートでは、スキャフォールディングされた Identity UI が Razor コンポーネントを直接使用します。ログイン、登録、およびアカウント管理ページは、Blazor アプリケーションの他の部分と自然に統合されます。Razor ページと 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>

留意すべき点が 1 つあります。AuthorizeView は UI の問題です。要素を非表示または表示しますが、基礎となるロジックは保護されません。誰かがあなたの API エンドポイントを呼び出すか、あなたのメソッドを直接呼び出すことができる場合、その人は AuthorizeView を完全にバイパスします。サーバー側でも常に承認を強制します。

[承認] 属性

ページ全体を保護するには、 [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 はクライアント上で実行されるため、Cookie ベースの認証は同じようには適用されません。代わりに、通常はメモリに保存され、発信 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 のみの Cookie を使用するバックエンド対フロントエンド (BFF) パターンを採用することを検討してください。

Blazor サーバーと WebAssembly: セキュリティに関する考慮事項

ホスティングモデルはセキュリティ体制を根本的に変えます。

Blazor Server は、すべてのコンポーネントロジックをサーバー上に保持します。クライアントには、SignalR 上でレンダリングされた HTML の差分のみが表示されます。これは次のことを意味します。

機密性の高いロジックがサーバーから離れることはありません
コンポーネントからデータベースや内部サービスに直接アクセスできます。
認証状態は、初期接続時のサーバーの HttpContext から取得されます
回線は認証 Cookie よりも存続できます。ユーザーの Cookie の有効期限が切れても、回線は切断されるまで存続します。
回線の切断を適切に処理し、再接続時に認証状態を再検証する必要があります。

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 を呼び出す必要があります。フレームワークは、トークンが保存されたことや Cookie が設定されたことを魔法のように検出しません。

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 サーバー回線は何時間も稼働し続けることができます。トークンまたはセッションの有効期限が切れると、ユーザーは 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 ID と組み込みのテンプレートから始めます。これらは、ユーザー管理、パスワードのハッシュ化、トークン生成といった重労働を処理します。要件の拡大に応じて、ポリシーとクレームベースの承認を追加します。ユーザーが外部 OAuth プロバイダーを期待している場合は、外部 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 相互運用機能が利用できないため、モジュールを OnAfterRenderAsync にロードします
IJSObjectReference でモジュールへの参照を保持します。
コンポーネントが破棄されたときにモジュールをクリーンアップするために IAsyncDisposable を実装します

なぜこれが良いのか

以前は、すべてを 1 つの 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 を使用して Web アプリケーションを構築してきた場合は、このフレームワークが長い進歩を遂げたことをご存知でしょう。 Blazor Server と Blazor WebAssembly のどちらかを選択することから始まったものは、アプリケーション内の各コンポーネントに適切な対話性戦略を選択できるようにする、統合された柔軟なレンダリングモデルに進化しました。

.NET 8 では、デフォルトとしてのレンダリングモードと静的サーバーサイドレンダリング (SSR) の導入という、根本的な変更が加えられました。現在、.NET 9 と .NET 10 はその基盤の上に構築されており、開発者のエクスペリエンスをよりスムーズにし、エンドユーザーのエクスペリエンスを高速化する改良が加えられています。

この投稿では、現時点での Blazor のインタラクティブ性の全体像、つまりレンダリングモードの仕組み、ストリーミング SSR がもたらすもの、強化されたナビゲーションとフォーム処理がゲームにどのような変化をもたらすか、最新リリースの新機能について説明したいと思います。新しい Blazor プロジェクトを計画している場合、またはアップグレードを検討している場合、これは、これらすべてを詳しく調べ始めたときに私が入手したかったガイドです。

簡単に振り返ってみましょう: ここに至るまでの経緯

.NET 8 より前は、プロジェクトレベルでホスティングモデルにコミットする必要がありました。 Blazor サーバーとは、すべてが SignalR 接続を介してサーバー上で実行されることを意味します。 Blazor WebAssembly とは、すべてがブラウザーで実行されることを意味します。それぞれにトレードオフがあり、それらを組み合わせるのは困難でした。

.NET 8 では、両方のモデルを統合する単一のプロジェクトテンプレート (Blazor Web App) を導入することで状況が変わりました。重要な概念は レンダリングモードです。コンポーネントごとにどのようにレンダリングするか、どこでインタラクティブ性を発揮するかを決定します。デフォルトは静的 SSR になりました。これは、コンポーネントがサーバー上でレンダリングし、プレーン HTML をブラウザーに送信することを意味します。SignalR も WebAssembly も使用せず、高速 HTML だけを使用します。

.NET 9 では、これらの概念が洗練され、開発者のエクスペリエンスが向上し、パフォーマンスが最適化されました。 .NET 10 では、再接続処理の改善、レンダリングモード全体でのコンポーネントの状態の永続化、Blazor スクリプト自体の配信方法の改善により、さらに進化しています。

すべてを分解してみましょう。

.NET 9 のレンダリングモード

最新の Blazor の中心となるのは、レンダリングモードの概念です。知っておくべきモードが 4 つあります。

1. 静的 SSR (デフォルト)

新しい Blazor Web アプリを作成すると、コンポーネントは既定でサーバー上で静的にレンダリングされます。サーバーは 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 の動的更新など、リアルタイムの対話性が必要な場合は、Interactive Server モードを選択できます。これにより、ブラウザーとサーバーの間に 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. インタラクティブな WebAssembly

サーバー接続を維持せずに対話性が必要な場合は、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 対話のためのサーバーのラウンドトリップなしで完全にブラウザー内で実行されます。

使用する場合: 遅延が重要となる高度にインタラクティブなコンポーネント (リッチテキストエディター、描画ツール、リアルタイムフィルタリングなど) の場合、サーバーの負荷を軽減したい場合、またはプログレッシブ Web アプリ (PWA) を構築している場合。

4. インタラクティブオート

これは実用的な中間点であり、私のお気に入りの機能の 1 つです。 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 は、単純そうに見えますが、知覚されるパフォーマンスに大きな違いをもたらす機能の 1 つです。アイデアは次のとおりです。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 ページ。製品リストページ、ダッシュボード、レポートなど、初期データの読み込みに数百ミリ秒以上かかる可能性のある場所はどこでもです。

使用しない場合: データの読み込みが非常に速い場合 (100 ミリ秒未満)、ストリーミングのオーバーヘッドは価値がありません。また、ストリーミング SSR では継続的なインタラクティブ性が提供されません。そのためには、インタラクティブなレンダリングモードが必要です。

強化されたナビゲーションとフォーム処理

最新の Blazor における微妙だが強力な改良点の 1 つは、ナビゲーションの強化です。既定では、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 のコンポーネントモデルの間の橋渡しとなります。

ページごとおよびコンポーネントごとの対話性

新しいモデルの最も強力な側面の 1 つは、単一のアプリケーション内でレンダリングモードを混合できることです。製品リストページは静的 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 の対話性のハイライトは次のとおりです。

### 再接続エクスペリエンスの向上

運用環境で Interactive Server モードを使用したことがある場合は、おそらく再接続オーバーレイに遭遇したことがあるでしょう。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 の改良により、このパターンはより確実に動作するようになりました。プリレンダリング中にシリアル化された状態は、コンポーネントがインタラクティブモードで初期化されるときに適切に利用できるため、二重のデータフェッチやユーザーが目にする可能性のある短いちらつきが回避されます。

静的 Web アセットとしての Blazor スクリプト

以前のバージョンでは、Blazor JavaScript ファイル (blazor.web.js) はフレームワークの内部エンドポイントから提供されていました。 .NET 10 では、静的な Web アセットとして配信されます。これは小さな変更のように聞こえるかもしれませんが、実際的な利点があります。- キャッシュの改善: 静的 Web アセットは適切なキャッシュヘッダーとフィンガープリントされた URL を取得するため、ブラウザーはそれらをより効果的にキャッシュします。

CDN フレンドリー: これは通常の静的ファイルであるため、CDN はそれをキャッシュし、エッジロケーションから提供できます。
圧縮: 静的な Web アセット圧縮が自動的に適用され、ネットワーク上のスクリプトサイズが削減されます。

参照方法を変更する必要はありません。更新されたパスはフレームワークによって自動的に処理されます。

ベストプラクティス: 適切なレンダリングモードの選択

いくつかのプロジェクトでこれらすべてのモードを使用した後、私の意思決定フレームワークは次のとおりです。

静的 SSR から始める

静的 SSR をデフォルトにします。ほとんどのアプリケーションのほとんどのページは、主にデータの表示に関するものです。製品ページ、ブログ投稿、ユーザープロファイル、設定ページ - これらにはリアルタイムの対話性は必要ありません。静的 SSR は、最高のパフォーマンス、最小限のリソース使用量、そして最も単純なメンタルモデルを提供します。

必要な場合にのみインタラクティブ性を追加する

ユーザー操作にリアルタイムで応答する必要がある特定のコンポーネントを特定します。「いいね！」ボタン、チャットウィジェット、ドラッグアンドドロップインターフェイス - これらには対話性が必要です。しかし、それらを囲むページはおそらくそうではありません。

インタラクティブオートを頼りになるインタラクティブモードとして使用する

インタラクティブ性が必要な場合は、多くの場合、Interactive Auto がデフォルトの最適な選択になります。これにより、高速な初期読み込み (サーバーレンダリング) と、最終的なクライアント側の実行 (WebAssembly) が実現します。ユーザーは両方の長所を活用でき、コードを一度記述するだけで済みます。

Interactive Server を特定のケースのために予約する

次の場合に Interactive Server を使用します。

コンポーネントはサーバーリソース (データベース、ファイルシステム、内部 API) に直接アクセスする必要があります。
WebAssembly のダウンロードサイズが懸念されるため、自動は使用できません。
セキュリティ上の理由から (機密データの処理など)、コンポーネントをサーバー上で常に実行する必要があります。

ストリーミング 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 の対話性モデルは、Web アプリケーションを構築するための成熟した、よく考えられたアプローチを表しています。コンポーネントごとにレンダリングモードを選択できる機能、シームレスな強化されたナビゲーション、ストリーミング SSR、再接続と状態管理の継続的な改善により、幅広いアプリケーションにとって魅力的な選択肢となっています。重要な洞察は、インタラクティブ性はスペクトルであり、二者択一の選択ではないということです。アプリケーションのほとんどは静的にすることができます。一部の部分ではサーバー主導の対話性が必要です。ブラウザで実行するとメリットが得られるものもあります。 Blazor では、フレームワークと競合することなく、最も細かい粒度 (個々のコンポーネント) でその選択を行うことができるようになりました。

新しいプロジェクトを開始する場合、私のアドバイスはシンプルです。Blazor Web アプリを作成し、静的 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 について私が本当に感謝している点の 1 つは、パラメーターバインディングがいかに直感的であるかということです。フレームワークは、コンテキストと型に基づいて値をどこから取得するかを判断します。

ルートパラメータ

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 がコントローラーに比べてすぐに使える機能が少ない領域の 1 つは、モデルの検証です。 [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 の最も優れた機能の 1 つです。これらはミドルウェアと考えてください。ただし、スコープはパイプライン全体ではなく特定のエンドポイントに限定されます。これらは .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 コメントで得られるのと同じレベルのドキュメント制御が提供されますが、より明示的な、コードファーストの方法で実現されます。

認証と認可

Minimal 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 を非常にエレガントに感じさせる小さな点の 1 つです。

大規模な 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 はすべてのモジュールを自動的に検出して登録します。これは、生の Minimal 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 のセールスポイントの 1 つはパフォーマンスであり、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));
```また、コントローラーと Minimal 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 を使用するときに常に気になることの 1 つは、コンポーネント間で誤ってスタイルを壊すことが非常に簡単であるということでした。あるコンポーネントにクラスを追加すると、まったく別のページにある別のものが突然表示されなくなってしまいます。 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 分を費やすことになります。信じてください、私はそこに行ったことがあります。

子要素をターゲットにする

留意すべき点の 1 つは、デフォルトでは、分離 CSS は現在のコンポーネントの要素にのみ適用されるということです。子コンポーネント内の要素のスタイルを設定したい場合は、 ::deep コンビネータが必要です。

::deep .child-element {
 color: red;
}

これにより、Blazor は子コンポーネント内の一致する要素にもスタイルを適用するように指示されます。子をスタイルする必要があるラッパーコンポーネントがある場合に非常に便利です。

#いつ使用するか

私は現在、ほぼすべてのコンポーネントに CSS 分離を使用しています。物事をクリーンかつ予測可能な状態に保ちます。私がこれを使用しないのは、リセット、タイポグラフィー、テーマ変数などの真にグローバルなスタイルの場合だけです。これらは共有 CSS ファイルに入れられます。

投稿が気に入っていただければ幸いです!ソーシャルメディアで**@emimontesdeoca**までお気軽にご連絡ください。

リソース

ASP.NET Core Blazor CSS 分離

セマンティックカーネルでクリスマスの支出をコントロールする

Sat, 28 Dec 2024 00:00:00 +0000

はじめに

ホリデーシーズンが近づくと、特にショッピングやギフトの購入が増えるため、出費の管理が課題になることがあります。このブログ投稿では、人工知能を活用して、.NET テクノロジを使用してクリスマスの支出を追跡する方法を検討します。セマンティックカーネルと 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 も使用します。

前提条件

コードに入る前に、次の前提条件を満たしていることを確認してください。

.NET9
Azure OpenAI アクセス (API キー)
Visual Studio または Visual Studio Code
Blazor、HTTP クライアント、API 開発の基本的な知識

Visual Studio ソリューション

最終的には次のようなものになります。私は物事を分けてクールな名前を付けるのが好きなので、次のようになります。

でも、ステップバイステップで物を作っていきましょう！

ステップ 0: モデル

Receipt Scanner アプリケーションの中核は、フロントエンド、API、AI サービス間の対話を促進するいくつかの主要なモデルに依存しています。このプロジェクトで使用される主なモデルは次のとおりです。

受信リクエストの分析
このモデルは、レシートを分析するためのリクエスト構造を表します。これには、処理されるレシート画像のバイト配列を保持する 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 align="center">
<img src="https://imgur.com/BLswKhm.png">
</p>

## ステップ 3: .NET Aspire

<p align="center">
<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 はもはや単なるバズワードや SF 映画で見られるものではありません。このプロジェクトで私たちが取り組んだ問題、領収書から構造化データを抽出する問題など、今日の現実世界の問題を積極的に解決しています。 Azure OpenAI、.NET Aspire、Blazor の助けを借りて、時間がかかりエラーが発生しやすい手動タスクを自動化できます。 AI は単にチャットしたり、ChatGPT のようなプロンプトに応答したりするだけではありません。画像を解釈し、貴重な情報を抽出し、実用的な洞察を数秒で提供します。

領収書分析には Azure OpenAI、ログ記録とメトリクスとのシームレスな統合には .NET Aspire を使用することで、強力でスケーラブルなソリューションを作成しました。ビジネスプロセスを合理化し、退屈なタスクを自動化し、精度を向上させる AI の可能性は非常に大きく、これはその応用例の一例にすぎません。

この投稿は、Calendario de Adviento de Inteligencia Artificial 2024 en Español の一部です。このイベントは、現実世界の AI アプリケーションを紹介し、スペイン語圏のテクノロジーコミュニティに最新のトレンドを啓蒙するイベントです。 AI とその可能性についてさらに詳しく知りたい場合は、このイベントから始めるのが最適です。

AI は私たちの働き方を変革しつつあり、このプロジェクトは可能性を垣間見るだけです。 AI の真の力は、レシートの処理、画像の分析、傾向の予測など、実際の問題を解決する能力にあります。私たちは表面をなぞっただけです。

ソースコード

このプロジェクトの完全なソースコードは GitHub で入手できます。自由にダウンロードして、AI サービスと API サービスがどのように連携するかを調べて、独自のユースケースに合わせて調整してください。問題が発生した場合、または改善のアイデアがある場合は、ためらわずに問題を作成するか、プルリクエストを送信してください。貢献はいつでも歓迎されており、あなたのフィードバックはこのプロジェクトをさらに改善するのに役立ちます。

コーディングを楽しんでください!

コンテナを使用してクリスマスプレゼントの価格を追跡しますか?

Thu, 12 Dec 2024 00:00:00 +0000

クリスマスが近づいてきました。愛する人への完璧な贈り物を見つけるという楽しい仕事がやって来ます。あなたも私と同じなら、お得に買い物をするのが大好きかもしれませんが、ホリデーシーズン中に人気商品の価格が高騰する中を歩き回るのは、本物のそりに乗っているような気分になるかもしれません。エキサイティングではありますが、少し大変です。今年は、毎日の価格チェックに夢中になるのではなく、自分の技術スキルを有効に活用してプロセスを自動化することにしました。

ソフトウェア開発者として、またテクノロジーを活用して日常の問題を解決することに情熱を注いでいた私は、価格チェックのプロセスを自動化する方法を見つけました。価格を比較するために毎日複数のオンラインストアを手動で訪問するのではなく、それを実行できるシステムを作成することにしました。これにより、時間を節約できるだけでなく、毎日のチェックのストレスを感じることなく、最良の取引を確実に入手できるようになります。

価格監視を自動化する理由

価格監視の自動化は、サンタの妖精のチームを24時間体制で働かせて、何もせずに最高の取引を確実に入手できるようにするようなものです。気に入っていただける理由は次のとおりです:

高価なアイテム: クリスマスプレゼントは、特にガジェットやおもちゃがリストにある場合、かなり高価になる可能性があることは誰もが知っています。これらでお金を節約することは、在庫にある最後のツリートップを見つけるのと同じくらい満足できることです。
毎日のチェック: 毎日価格をチェックする時間 (または忍耐力) がある人はいるでしょうか?私じゃないよ！
自動化: ホリデーシーズンの寄付の精神を受け入れ、効率性という贈り物を自分自身に与えましょう。
精度: 自動化により、価格チェックがルドルフの鼻のように正確であることが保証されます。

コアテクノロジー

独自のサンタの小さなヘルパーを構築するために、いくつかの主要なテクノロジーを使用することにしました。

コンテナ

コンテナはソフトウェアのクリスマスラッピングのようなものです。アプリケーションをすべての機能 (依存関係) とバンドルして、すべてが新雪のそりのようにスムーズに動作するようにします。これらのコンテナを作成するには Docker が頼りになります。

ブレザー

Blazor は、.NET を使用してインタラクティブな Web アプリケーションを構築するための優れたフレームワークです。それは、一般的なクリスマスキャロルを、カスタマイズされ、効率的で、とても楽しい、独自のホリデープレイリストに置き換えるようなものです。

Docker-Compose

Docker-Compose は、北極の運営のマネージャーです。これは、API や Blazor フロントエンドなどのすべてのサービスを完全に調和して実行するのに役立ちます。それを私たちのホリデー交響楽団の指揮者だと考えてください。

ステップバイステップガイド

さあ、サンタさんのワークショップに飛び込んで、このプロジェクトを実現させましょう!

ステップ 1: API の作成

1.1 プロジェクトのセットアップ

コーディング用のサンタ帽をかぶって、新しい ASP.NET Core Web API プロジェクトをセットアップします。ターミナルを開いて (アドベントカレンダーを開くのと似ています)、次のコマンドを実行します。

dotnet new webapi -o PriceMonitorApi
cd PriceMonitorApi

このコマンドは、PriceMonitorApi という名前の新しいディレクトリを作成し、基本的な Web 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 がコンポーネントに挿入できるように、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 の作成

すべてのドット (クリスマスライト) を 1 つの 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 を使用して、RefreshPrices メソッドを毎分定期的に呼び出します。
StartTimer メソッドは、タイマーを初期化してすぐに開始し、その後 60 秒ごとにトリガーします。
OnInitialized ライフサイクルメソッドは、コンポーネントが初期化されて定期更新を開始するときに StartTimer を呼び出します。

4.3 ソリューションの実行

新しい機能を備えた更新された Blazor アプリケーションを実行するには、Docker コンテナーを再構築して再起動します。

docker-compose build
docker-compose up

ブラウザーに http://localhost:5001 を読み込んだ後、Blazor アプリは手動更新と URL 管理に加えて、商品価格を 1 分ごとに自動的に更新するようになります。

結論

この価格監視システムの構築は非常に楽しいものでした。毎日の価格チェックのストレスから解放されただけでなく、最新の Web テクノロジーの魔法を見せてくれました。

フェスティブテックカレンダー2024

私はこの投稿を Festive Tech Calendar 2024 イベントの一環として作成しました。このイベントでは、テクノロジー愛好家、イノベーター、デジタル夢想家が集まり、知識を共有し、お祭り気分とテクノロジーの驚異の融合を祝います。この取り組みは、学び、つながるだけでなく、恩返しすることも目的としています。

Festive Tech Calendar 2024 は今年、Beatson Cancer Charity をサポートしています。 Beatson Cancer Charity は、がんに苦しむ人々、その家族、そして彼らの世話をする医療従事者を支援することに専念しています。彼らの素晴らしい仕事についての詳細は、https://www.beatsoncancercharity.org/ でご覧いただけます。

よくある質問とイベントの詳細については、Festive Tech Calendar Web サイト (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)]

カスタムバリデーター

そこで、特定のビジネスケースに必要なバリデーターを用意しました。これは、最初の 20 文字をカウントし、9 つの数字とハイフンを省略し、通常は国コードとなる 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();
}

これを実行するとすぐに、次のエラーが表示されます。

そして、必要なものをそのまま入力すると、次のことがわかります。

正直に言うと、少なくともこれらのフォームを検証するロジックをカスタム検証属性に移動する必要があることは明らかです。これにより、そのログインのコードを 1 か所に自由に保存できるようになり、後で API や別のアプリケーションで使用できるようになります。

気に入っていただければ幸いです。ご質問がある場合、または連絡したい場合は、ためらわずにご連絡ください。

.NET API でのカスタム例外処理

Sun, 01 Oct 2023 00:00:00 +0000

例外は悪いことです、私たちは知っていますよね?しかし、それらを処理しなければならない場合はどうすればよいでしょうか?

たとえば API で例外が発生すると、ユーザーが受け取る応答から削除したい可能性のある多くの情報を含むスタックメッセージが表示されます。

デモ用に、ドットネット 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 では次のように表示されます。

カスタム例外の作成

どのような例外がスローされるか (この場合は Exception] であることがわかっているため、このステップを回避することもできますが、私にとっては、スローするものをより詳細に制御できるため、カスタム例外を持つ方が良いと考えています。

この場合、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) をオーバーライドする必要がありますが、両方をオーバーライドすることはできません。

それでは、作成しましょう。 CustomExceptionFilterAttribute を作成し、その中で OnException をオーバーライドします。

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 にある最高の機能の 1 つです。どのような場合でも、これを使用しないわけはありません。そのため、あなたが私と同じであれば、作成するすべての実装にそれを追加したいと思うでしょう。

公式 Microsoft のドキュメントによるフィルター:

ASP.NET Core のフィルターを使用すると、要求処理パイプラインの特定のステージの前後でコードを実行できます。

組み込みフィルターは次のようなタスクを処理します。

認可。ユーザーが認可されていないリソースへのアクセスを防止します。

応答キャッシュ。要求パイプラインを短絡して、キャッシュされた応答を返します。

横断的な問題に対処するためにカスタムフィルターを作成できます。横断的な問題の例としては、エラー処理、キャッシュ、構成、認可、ロギングなどが挙げられます。フィルターはコードの重複を避けます。

私は API をよく使うのですが、すべてのリクエスト、またはほぼすべてのリクエストを実行する必要があるものがいくつかあります。そのため、理想的には API に加えて依存関係の注入を実行したいと考えています。

しかし、これは時々ちょっとしたトリックです。ActionAttribute から継承したい場合は希望どおりに動作しないため、TypeFilterAttribute を操作する必要があります。これにより、OnActionExecutionAsync をオーバーライドするときに処理を行うことができます。

通常、ログを記録するためにこのフィルターを作成するので、それを例として使用します。

/// <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

将来の場合に備えて、複数のライブラリを使用してコードを分割することは良いことです。個人的には、ロジックを分割して他のプロジェクトやプロジェクトの一部で再利用できるのであれば、そうするのが大好きです。

少なくとも私にとっては、Console application、Blazor application、または API で参照および使用できるように、Entity Framework を含むデータモデルを分割することが必須です。

私がどのように作業を行っているかの例を見てみましょう。これは、いくつかのアプリケーションとすべてのモデルを含む共有ライブラリを含むプロジェクトのスクリーンショットです。

これは、各プロパティとクラスに関する 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

地元の支店が多すぎる状態になったことはありますか?私たちは機能、バグ、雑用ごとにブランチを使用するため、このようなことがよく起こります。

結局このようなものになり、しばらくすると非常に汚くなります

それは本当にイライラするので、このクリーンアップを行うためにコンソールで実行できる簡単なコマンドを共有します。

このコマンドは、Robert Corvus による次の answer の Stack Overflow で見つかりました。これは Powerhsell で実行されるバージョンです。

このコマンドを実行するときは、変更内容が失われる可能性があるので注意してください

実行する前に、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 Web プロジェクトであることにすぐに気づいたことはありますか?

作成したプロジェクトにはデフォルトでログインと登録プロセスを実行するための URL が設定されているため、これはよく起こります (他のページもたくさんあります)。

そこで、このチュートリアルでは、プロジェクトの見栄えを良くするために、これらの URL を更新する方法を説明します。

デフォルトの動作

Blazor プロジェクトを作成し、それを Identity で使用することにすると、次のように表示されます。

そして、ログインまたは登録プロセスを実行しようとすると、/Identity/Account/Login または /Identity/Account/Register のいずれかになります。

しかし、これらの URL を実際に異なるものに更新できると言ったらどうなるでしょうか?

`Login` および `Register` ページのスキャフォールディング

これらのページを更新するために、Microsoft はページを非表示にしますが、すぐにページを足場にして、必要な変更を行うことができます。

これを行うには、次のように、プロジェクトのコンテキストメニューで Add Scaffolded Item に移動する必要があります。

次にモーダルがポップアップするので、Identity を 2 回選択して、Add をクリックする必要があります。

このモーダルの後に、さらに別のモーダルがポップアップ表示され、アイデンティティ全体から更新するページを選択できます。更新できるページはたくさんありますが、ここでは Account/Login と Account/Register に焦点を当てます。

ここで少し動作させてから、ソリューションエクスプローラーを確認すると、いくつかの新しいファイルが見つかります。

これらの新しいファイルは、ID を追加するためにプロジェクトを選択したときに、ASP.NET がプロジェクトに追加するログインページと登録ページです。

URLを更新しています

お気づきかと思いますが、拡張子が cshtml であるため、このファイルは razor ファイルです。そのため、ディレクティブを使用してページの 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"

まあ、簡単でしたね。それでは、簡単なテストを行って、それが機能するかどうかを確認してみましょう。

まず最初に、最初に表示されているデフォルトのページに移動して、それがまだ機能しているかどうかを確認してみましょう。

それは違います！それでは、新しい URL /login をテストしてみましょう。

そしてそれはうまくいきます!!

次に、レジスタに対して同じことを行い、そのページを更新して、必要なパスを @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

カスタム属性は非常に使いやすく、私はごく最近使い始めました。カスタム属性を使用すると、カスタム属性を 1 つ作成し、コントローラー、クラス、またはメソッド自体で再利用できるからです。

これらは、ヘッダーのチェックなどのセキュリティ関連の作業を行う場合や、絶対に必要なパラメーターの値を確認する場合に非常に役立ちます。

私の場合は、.NET Core API プロジェクトでこれを使用し、すべてのリクエストに特定のヘッダーが含まれているかどうかを確認します。

HeaderCheckAttribute

クールな .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 という 2 つの関数があります。そのうちの 1 つは失敗し、もう 1 つは失敗しません。しかし、Swagger で確認してみましょう。

ご覧のとおり、一方はメッセージとともに 400 エラーを返し、もう一方は値を返します。これを完全にテストするために、Postman を実行してヘッダーを追加し、GetWeatherForecastWithCheck を使用してデータも確認できるようにします。

#郵便屋さん

Postman で実行中、ヘッダーを追加すると、ヘッダーは提供していますが、値が存在しないため、エラーメッセージが変更されていることがわかります。

それに値を追加すると、最終的に値が得られます。

#それだけです

それはそれです！かなりシンプルですよね？これで、属性を作成してメソッドとコントローラーに割り当てる方法がわかりました。

彼らと一緒に楽しんでください！

コード

このプロジェクト全体は Github にあり、ここで見つけることができます。

問題や質問がある場合は、ソーシャルメディアで @emimontesdeoca までお気軽にご連絡ください (Twitter では実際には @emimontesdeocaa で最後に aa が 2 つ付いています)。私のソーシャルのほとんどはブログのヘッダーからも見つけることができます。

投稿が気に入っていただければ幸いです!キャー！

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();
 }
}

次に、複数の FakeLoadingComponent コンポーネントを使用して Loading ページを更新し、結果を確認します。

@page "/loading"
@using LoadingBoxes.Components

<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>
<FakeLoadingComponent/>

これで見た目がかなり良くなりました

それで終わりです！

投稿が気に入っていただければ幸いです!

証明書から有効期限を取得する

Fri, 27 May 2022 00:00:00 +0000

弊社が使用しているドメインの証明書の現在のステータスを確認するのに役立つ Web アプリがいくつかあります。

1 日に 1 回実行され、確認する必要があるいくつかのドメインをチェックする 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 ゲームに取り組んだ後、非常に単純な機能を追加する必要がありました。それは、ゲームに入るときにゲーム全体にフォーカスするというものです。

ユーザーはスクリーンキーボードを使用するだけでなく、実際にゲーム上で入力できるため、これを行う必要がありました。

JavaScript ファイル

これを行うには、関数を保持する app.js という Javascript ファイルを作成する必要があります。

window.FocusElement = (element) => {
 element.focus();
};

それが完了したら、スクリプトを index.html ファイルに含める必要があります。

<script src="js/app.js"></script>

ブレザーコンポーネント

スクリプトを初期化したら、注目する要素を見つける必要があるため、どのコンポーネントでもその要素をオブジェクトに参照する必要があります。

そこで、blazor コンポーネントに を含む div を追加しましょう。 @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 Database プロジェクトから *.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 にあり、ここで見つけることができます。

投稿が気に入っていただければ幸いです!キャー！

Blazor の Javascript Interop を使用してテーマを切り替える

Fri, 01 Apr 2022 00:00:00 +0000

Web ページを開くたびにフラッシュバックに悩まされている私のような人のために、JavaScript を使用してライトモードとダークモードを切り替え、JavaScript Interop を使用して Blazor から呼び出す方法に関する非常に簡単な解決策を思いつきました。

親属性の設定

まず第一に、親要素を識別子で識別する必要があります。これは、その識別子の値に応じて色を変更するためです。

これを Javascript で行うには、次のコマンドを実行する必要があります。

document.documentElement.setAttribute('data-theme', 'YOUR_IDFENTIFIER');

この場合、スタイルのタイプごとに light と dark という 2 つの識別子が必要になります。

ロジックを処理するための Javascript ファイルの作成

識別子を更新する関数ができたので、そのロジックを実行する関数を含む Javascript ファイルを作成しましょう。私たちのファイルは 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 Storage サービスは、Azure エコシステムで最も使用されているサービスの 1 つであり、非常に安価でありながら大量のファイルをクラウドにアップロードできます。また、直観的な Web を備えており、直接リンクでアクセスしたりダウンロードしたりできます。

全体的に非常に優れたサービスで、私は仕事と個人のプロジェクトの両方でこれを使用してきましたが、正直に言って、最も優れている点は、それを機能させる方法がシンプルであることです。

私が Azure Blob Storage を使用したほとんどのケースはバックエンドで、操作などの結果として得られたものを直接アップロードしています。したがって、Web サイトなどからファイルをアップロードするようなことは実際には行っていません。不運！

私は Blazor のファンなので、HTML5 からのネイティブファイル入力を使用して Azure Blob Storage にファイルをアップロードする方法を紹介します。

前提条件

Azure アカウント (お持ちでない場合は、ここに $$$ を集めてアクセスしてください)。
IDE (VS、Code、どれでも動作します)
.NET Core 3.0以降

Azure Blob Storage の作成

Azure portal に移動し、ストレージアカウントの作成に進みましょう。

まず Storage accounts を検索し、結果をクリックします。

ロードしたら、Create をクリックします。

多数の手順が記載されたフォームが表示されるので、先に進んで入力してください。

必要な設定をすべて入力したら、検証に合格してリソースを作成します。

作成したら、Go to resource をクリックします。 API を操作できるようにする接続文字列を取得します。

リソースキーを取得する

新しく作成したリソースに到達したら、Security + networking の下の Security + networking に移動します。ロードすると、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 ストアにアップロードする

ここで、実際にファイルをアップロードするためのロジックを実行しましょう。通常、接続文字列と app.config のキーを使用しますが、このチュートリアルのために、入力を使用し、そこにデータを提供します。

まず、Azure Blob Storage クラスの using を追加しましょう

@using Azure.Storage.Blobs
@using Azure.Storage.Blobs.Models

次に、HandleValidSubmit メソッドに取り組みます。これは、BLOB ストレージに接続し、コンテナーが存在しない場合は作成して、ファイルをアップロードします。

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 ポータルにアクセスして確認してください。

ご覧のとおり、コンテナーも作成されました。コンテナー内に入ると、アップロードしたファイルが表示されます。

頑張ってね！

リファクタリング

すべてがうまくいったので、コードを .razor ページから .razor.cs クラスに移動して、見栄えを良くしましょう。

Visual Studio 2022 を使用している場合、@code にマウスを移動すると電球が表示され、Extract block to code behind のオプションが表示され、そのとおりに動作します。

これで、すべてが分離されて完了します。

コード

このプロジェクト全体は Github にあり、ここで見つけることができます。

投稿が気に入っていただければ幸いです!キャー！

リソース

Pimcore のコアコントローラーをオーバーライドする

Thu, 10 Dec 2020 00:00:00 +0000

私はしばらくの間 Pimcore プロジェクトに取り組んでいますが、これまで PHP や Symfony に触れたことはなかったので、これは大きな挑戦でした。

ドキュメントは素晴らしい、つまり真剣に素晴らしいのですが、言語やフレームワークの初心者向けに作られていないように見えるので、私がやったことはすべてメモを取る必要がありました。

バンドルを使用して Pimcore を拡張できることを知ってから、私はコントローラーや JavaScript メソッドなどをオーバーライドするのに何時間も費やしてきました。

そこでこの記事では、コントローラーをオーバーライドする方法を説明します。 JavaScript ファイルをオーバーライドする方法は後ほど説明します 😎。

バンドルの作成

まず最初にバンドルを作成する必要があります。これは 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 内のすべてのファイルを検索することです。

おそらく複数のものが見つかるので、調べてどれが 1 つであるかを決定する必要があります。この場合、アセットを使用しているため、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 コアコントローラーをいかに簡単にオーバーライドできるかがわかります。いくつかの手順に従わなければなりませんが、難しいことは何もありません。変更を加えている間は、コントローラーを公開し、キャッシュを時々クリアするようにしてください。コントローラーがキャッシュされてしまい、コントローラーが機能していないのにキャッシュされているだけだと思い込んでしまうことがあります。

JavaScript ファイルをオーバーライドする方法について疑問がある場合は、別のチュートリアルで説明します 😁。

Windows 10 で Apple Magic Keyboard 2 を構成する

Wed, 11 Nov 2020 00:00:00 +0000

つい昨日、メカニカルキーボードを 5 つほど持っていますが、Apple Magic Keyboard 2 を購入しました。試してみたかったし、ワイヤレスだったからです。

私のメイン OS は Windows 10 で、気に入っているので変更したくありません。そのことを念頭に置いて、キーボードを完璧に動作させるにはいくつかの作業が必要であることがわかりました。私は Apple がどのように機能するのか、そして彼らが自社のデバイスを自社のエコシステムにどのように維持したいのかを知っています。

問題

キーボードをペアリングすると、次のことがわかります。

※ファンクションキーが効かない

いくつかのキーが間違ってマッピングされています (これはスペイン語版で発生しました)

ドキュメント

これを機能させるには、Web からたくさんの情報を読む必要がありましたが、次の 2 つのリンクが役に立ちました。

Apple キーボードドライバーのインストール

この手順の一部は、前述のドキュメントからのものです。

7zip をお持ちでない場合は、コンピュータにインストールします。
Python (バージョン 2.x) がない場合は、コンピューターにインストールします。
- 重要: Python の最新バージョンは 3.x です。ただし、准将スクリプトはバージョン 3.x と互換性がないため、バージョン 2.x が必要です。
- (オプション) デフォルトでは、インストーラーは python.exe を PATH に追加しません。必要に応じて、このオプションを有効にする必要があります。 (右側のスクリーンショットを参照)
- すでに別のバージョンの Python を使用している場合は、このオプションを有効にしたくない可能性があります。
brigadier (Boot Camp の最新バージョンのダウンロードに役立つ Python スクリプト) をダウンロードします。
次のリンクを右クリックし、「名前を付けてリンク先を保存」を使用してファイルを保存してください。 https://raw.githubusercontent.com/timsutton/brigadier/master/brigadier
コマンドプロンプトウィンドウ (別名 DOS ボックス) を開き、准将スクリプトをダウンロードしたディレクトリに変更します。
准将スクリプトが「brigadier.txt」として保存されていると仮定して、次のコマンドを実行してください。
- Python バージョン 2.x が PATH にある場合: python brigadier.txt –model=MacBook13,2
- それ以外の場合: [Python バージョン 2.x へのパス]\python.exe brigadier.txt –model=MacBook13,2
Bootcamp からすべてのドライバーを含む大きなバンドルがダウンロードされます
BootCamp という名前のフォルダーを作成し、その中に BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\BootCamp.msi と BootCamp-xxx-yyyyyy\BootCamp\Drivers\Apple\AppleKeyboardMagic2 をコピーします。
管理者用パワーシェルを実行し、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

つい先日、アップロードした nuget パッケージからのものであるため、存在するはずのライブラリが欠落している NullReferenceException に関するバグを発見しました。

基本的に、いくつかのプロジェクトを参照するライブラリクラスをコンパイルしました。ビルドフェーズでは、dll ファイルを bin フォルダーに追加しますが、それを nuget パッケージとして 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 ディストリビューションでそれを使用しないのは愚かです。

このコンソールは明らかに優れていますが、ターミナルを一度使用すると、もう戻ることはできません。とても良くなりました、c o l o r s も。

ここで、ターミナルを起動し、新しいタブを開いて WSL ディストリビューションをロードすると、マウントされたユーザーフォルダーがロードされます。

cd ~ を実行するだけでは、ディストリビューションユーザーフォルダーが読み込まれるだけなので、これは実際には問題ではありません。

問題は、これを何度もやりたくないので、ファイルを更新して単独で実行しましょう。

.bashrc

ターミナルまたはコンソールを起動し、プロファイルフォルダーに移動し、お気に入りのテキストエディターを使用して .bashrc ファイルを編集します。

cd ~ をファイルの末尾の最後の命令の前に追加します。

保存し、ターミナルで WSL コンソールを再度開くと、プロファイルフォルダーが表示されるはずです。

1 つの WSL インストールに対して bashrc ファイルを更新するため、これをすべての WSL インストールに対して行う必要があることに注意してください。

ExpandoObject を使用した動的オブジェクト生成

Fri, 06 Mar 2020 00:00:00 +0000

独自に定義された列を含む Excel ファイルを、動的列を含む新しいファイルに変換する必要がありましたが、重大なパフォーマンスの問題を発生させずに適切に変換する方法について少し混乱しました。

私は、.NET ExpandoObject を使用するチュートリアルを思いつきました。ここでは、オブジェクトを作成して動的メンバーを追加できます。

ExpandoObject

Microsoft の定義は次のとおりです。

実行時にメンバーを動的に追加および削除できるオブジェクトを表します。

そして、いくつかのコメントがあります。

ExpandoObject クラスを使用すると、実行時にインスタンスのメンバーを追加および削除したり、これらのメンバーの値を設定および取得したりすることができます。このクラスは動的バインディングをサポートしているため、sampleObject.GetAttribute(“sampleMember”) のような複雑な構文の代わりに、sampleObject.sampleMember のような標準構文を使用できます。

現在の動作

ExcelExportService がありますが、これは List<T> (この場合は ExcelItem) を渡すことによって、 Reflection を使用して xlsx ファイルを作成します。

これまでのところ、コードは次のようになります。

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 オブジェクトを使用することになります。

たとえば、大量のような多くのプロパティを持つオブジェクトがあり、変更を加えるたびに ExcelItem オブジェクトを変更するのはあまり望ましくなく、その ExcelItem の生成に使用される ColumnExcelItem テーブルを作成します。

データベース構造

この定義を次のようにしてデータベースに保存します。

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 テーブルに挿入することだけです。

件

この例では 1 つのケースを使用しましたが、一部のユーザーに対して異なるレポートを作成したいとします。 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

最近、master ブランチにプッシュした、またはプッシュしようとしたコードを自動的にテストするツールとして Travis CI を使用する方法に関するチュートリアルを行いました。それをコンパイルしてテストし、最終的にその変更のステータスを報告します。

しかし、より良い にし続けることはできます。たとえば、最後のチュートリアルで作成されたコアライブラリを 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

ご覧のとおり、3 つの異なるステージ 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 を受け入れ、ビルドを再度チェックして、2 つではなく 3 つのジョブがあることを確認しましょう。

ビルドがキューに入れられていることがわかるとすぐに、最後に Deploy-prod を含む 3 つのジョブが表示されます。

このビルド全体が完了すると、パッケージがソースにプッシュされたことがログですぐに確認できます。

そして明らかに、NuGet ページで確認できます。

#それだけです

このチュートリアルでは、NuGet パッケージの配信を自動化する方法について学びました。 TravisCI、stages、dotnet nuget などのツールを使用しました。

私の意見では、それが適切に設定するには時間がかかり、場合によっては非常に複雑すぎる可能性があるとしてもです。すべてを完璧かつ自動化するために、この種のテクニックに時間を投資する価値があります。

ソースコードは .travis.yml ファイルで [ここ] (https://github.com/emimontesdeoca/CalculatorCLI-demo) にあります。ご質問がある場合は、私の twitter までお気軽にご連絡ください。

TravisCI を使用した .NET Core 3.0 プロジェクトの継続的統合

Tue, 14 Jan 2020 00:00:00 +0000

先週末、私はさまざまなリポジトリで行ってきたスクレイパー・チェッカー・ダウンローダー・プロジェクトを適切に開始したいと決心しました。

さらに別のプロジェクトを開始した後、これは、CI/CD、プルリクエスト、ドキュメント、Readme のバッジなど、私がこれまで見てきたクールで実際にベストプラクティスであるすべてを使用して、本当にクール のようにクールでなければなりませんでした。

そして充実した週末を過ごした後、最終的に Dramarr というさまざまなソースから番組をスクラップしてダウンロードするツールセットを作成することになりました。

組織内にはさまざまなリポジトリがあり、それらのほとんどは、プルリクエストやマスターブランチにマージされるときにコンパイル、テスト、デプロイされるライブラリです。

それが CI/CD または継続的インテグレーション/継続的デリバリーと呼ばれるものです。

ただし、このチュートリアルでは CI についてのみ説明します。

継続的インテグレーション

＃＃それは何ですか？

Martin Fowler のブログから引用したもので、これが私が読んだ中で最も優れた説明です。

継続的インテグレーションは、チームのメンバーが自分の作業を頻繁に統合するソフトウェア開発手法であり、通常は各人が少なくとも毎日統合するため、1 日に複数の統合が行われます。統合エラーをできるだけ早く検出するために、各統合は自動ビルド (テストを含む) によって検証されます。

ツール

ワークフローを CI/CD と統合するためのツールは多数ありますが、このチュートリアルでは、Github を使用してコードを保存し、TravisCI ツールを使用して CI をセットアップします。言語とフレームワークに関しては、C# と新しい .NET Core 3.0 を使用します。

要件

これを機能させるには、次の 3 つの簡単なことが必要です。

Visual Studio 2019の最新バージョン 2.Githubアカウント
Github アカウントにリンクされた Travis-CI アカウント

プロジェクト

このチュートリアルでは、簡単な計算機を使用します。すべてをテストするためのライブラリ、コマンドラインツール、およびテストプロジェクトを作成します。

このテストプロジェクトは、CI のセットアップ時にも実行されます。つまり、将来コードに変更を加え、最初に作成したテストが合格しなかった場合は、通知を受け取るか、単純にプルリクエストを拒否することができます。

Github リポジトリの作成

まず、Github リポジトリを作成するので、Github にアクセスしてリポジトリを作成し、ローカル環境にクローンを作成します。この新しいリポジトリを CalculatorCLI-demo と呼ぶことにしました。

ソリューションの作成

次に、クローンされたリポジトリのルートフォルダーに CalculatorCLI という名前の空のソリューションを作成しましょう。

コアライブラリ

実際のプロジェクトと同様に、ライブラリを生成する別のプロジェクトにロジックを保存するので、それを作成しましょう。

Class Library (.NET Standard) を作成し、CalculatorCLI.Core という名前を付けます。

NET Core のバージョンプロジェクトを作成したらすぐに、プロジェクトのプロパティに移動し、`.NET Core 3.0` でビルドされたプロジェクトと互換性を持たせるために、`Target framework` を `.NET Standard 2.1` に変更します。

コード

チュートリアルのために、操作を処理する簡単なクラスを作成しましょう。

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

操作ロジック内に侵入することはなく、値を TryParse するなどの将来のチェックを保存します。

テスト

コアライブラリとコマンドラインはありますが、CI でやりたいことなので、ここでテストする必要があります。

それでは、新しい MSTest Test Project (.NET Core) を作成し、 CalculatorCLI.Tests という名前を付けましょう。

NET Core のバージョン

次に、ConsoleCLI.Core および ConsoleCLI.Core への参照を、新しく作成したテストプロジェクトに追加します。

コード

テストを 2 つの異なるファイル 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 という名前の静的ディクショナリがあり、そこにすべての項目が保存されます。これはアプリケーションの実行中にのみ持続することに注意してください。そのため、この チュートリアル タイトルにはメモリ内キャッシュが含まれています。

CacheRepository クラスがロードされると、Cache 項目が初期化されることに注意してください。

CacheRepository クラスを呼び出すときに使用できる唯一のメソッドは、3 つのパラメーターを必要とする 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 に要求します。

そのキーが存在する場合は、有効期限がチェックされます。これらの条件のいずれかが false の場合、コールバックを使用してオブジェクトの値を (usersRepo.Get で) 設定し、有効期限を DateTime.UtcNow + TimeSpan.FromMinutes(10) に設定してキャッシュに保存して返します。

Devtools を使用してページのスクリーンショットを撮る

Thu, 09 May 2019 00:00:00 +0000

Web サイトの現在の状態の完全なスクリーンショット、またはその一部をクライアントやチームメイトに見せる必要がある場合があったため、全ページスクリーンキャプチャを使用し、他の種類のスクリーンショットには Windows のスニペットツールまたは Snaggit を使用してきました。この投稿のようにオンラインでホストしたい場合は、Gyazo にも GIF メーカーがあります。

最近、Devtools に拡張機能を必要とせずにページ全体のスクリーンショットを実行するツールがあることを発見しました。

これは新しい考えではなく、2017 年 4 月の Devtools アップデートに含まれていました。しかし、私は岩の下に住んでいて、今まで気づかなかったようです…

開発ツール

公式 Devtools ページに記載されているとおり:

Chrome DevTools は、Google Chrome ブラウザに直接組み込まれた Web 開発者ツールのセットです。 DevTools は、ページをその場で編集し、問題を迅速に診断するのに役立ち、最終的にはより良い Web サイトをより迅速に構築するのに役立ちます。

Devtools でのコマンドの実行

Devtools を開く方法はすでに知っていますが、この投稿のために忘れてしまった場合に備えて、キー F12 またはショートカット Ctrl + Shift + I を使用して開いてください。次に、Devtools 内のメニューで Run command を開くか、Ctrl + Shift + P を使用する必要があります。

スクリーンショットツール

screenshot と入力するとコマンドがフィルタリングされ、使用できるスクリーンショット方法は 4 種類あります。

エリアのスクリーンショット
フルサイズのスクリーンショット
ノードのスクリーンショット
スクリーンショットをキャプチャする

すべてのスクリーンショット方法を確認する前に、devtools が画像の処理を完了した後、画像は Web ページの名前で自動的にダウンロードされます。

エリアのスクリーンショット

area screenshot を使用すると、Web サイトの一部を選択してスクリーンショットを作成できます。

結果:

フルサイズのスクリーンショット

full size screenshot は、Web ページ全体の最初から最後までのスクリーンショットを撮ります。

結果:

ノードのスクリーンショット

node screenshot を使用すると、inspect 要素で選択したノードのスクリーンショットを作成できます。

結果:

スクリーンショットをキャプチャする

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>

英語とスペイン語という 2 つの異なる言語のリソースを作成するので、ファイルの命名法は 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 の使用は非常に簡単なので、Embedded プロパティにアクセスするには `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 に変更し、さらに別の値に変更します。 それは非常識です!

解決策

私たちのチームリーダーは、フォールバックシステムのような非常に良い方法を考えました。リソースの基本モデルが必要です。そして、クライアントごとに、そのリソースでファイルを更新するリソースファイルが必要です。これで、最終的に 1 つのリソースのリストが得られます。

クライアントがカスタムリソースを望まない場合はベースリソースを使用し、クライアントが必要な場合はクライアントのリソースを使用します。

これをチェックリストに入れるには、次のことを行う必要があります。

すべてのキー/値を埋め込みリソースの辞書にマップする方法を見つけます。
すべてのキー/値を外部リソースの辞書にマッピングする方法を見つける
両方のファイルを混合し、言語ごとに 1 つの辞書を作成します
辞書にアクセスして値を返すメソッドを作成します。

図

コードを書いてみましょう

まず、リソースファイルの取得からそれらの混合、値の返しまでのすべてのロジックが含まれる分離クラスを作成しましょう。そのクラスは 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)
 {
 ...
 }
 }

プロパティの遅延読み込みを実装していることに注意してください。これにより、パフォーマンスが向上し、辞書が 1 回読み込まれるようになります。

GetDictionaryFromEmbedded: 埋め込みリソースから辞書を返します。
GetDictionaryFromFile: 外部リソースから辞書を返します。
OverwriteDictionary: 2 つの辞書を混合し、1 つの辞書を返します。
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;
}

2 つのこと:- embedded というパラメーターが必要であることに注意してください。パラメーターはデザイナーに表示されるファイルの名前であり、この場合は 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}";
 }
}

さらに言語を追加する場合は、スイッチを変更する必要があることに注意してください。

プロパティゲッターにコードを追加する

これですべてのメソッドが揃ったので、パブリックプロパティのゲッターを変更して値を取得できます。

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 から識別子を取得します。
次に、基本リソース、つまり埋め込みリソースを取得します。
その後、カスタムリソースを取得します。そのためにはフォルダー名 (識別子) が必要です。
次に、それらを混合して値を返します。

遅延読み込みなので、これはすべて 1 回で実行されます。

テスト

コードに関連するすべてが完了したので、テストしましょう。辞書から値を取得するには、値を返すメソッド CustomResources.GetText(string key) を呼び出す必要があります。

リソースファイル全体を更新する

このテストは、リソースファイルのキー/値全体を更新する場合です。図からわかるように、キーは同じですが値が異なります。

John をテストします。それを設定するために、app.config を <add key="CustomResources.Folder" value="John" /> に設定します。

次に、基本リソースファイル (Properties/Resource.es.resx) を確認してみましょう。

次に、外部リソースファイル (Properties/John/Resource.es.resx):

OK、すべての設定が完了しました。コンソールアプリケーションを実行します。プロパティの get 部分に戻ってすべてを確認しましょう。

folderIdentifier には appseting の値があります。

baseResources には、基本リソース、つまり埋め込まれたリソースの値が含まれます。

customResources には、フォルダー John 内の外部リソースの値があります。

そして最後に、_ResourcesSpanish には、基本リソースから外部リソースまで混合された値が含まれます。

1 つだけ更新しています

次に、同じものを異なるシナリオでテストしてみましょう。一方のキーを更新し、もう一方のキーを同じにするだけです。

ご覧のとおり、ファイルは 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

最初の 2 つの値は英語の resources.resx からのもので、最後の 2 つの値はスペイン語で、値は resources.es.resx から取得されます。

#それだけです

このチュートリアルでは、言語に埋め込みリソースと外部リソースの両方を混合する方法を見つけました。これはチーム内で抱えていた問題の解決策であり、それ以来問題なく実行されています。

ソースコードはここで確認できます。

ご質問がございましたら、@emimontesdeocaa までお気軽にツイートしてください。時間ができたら折り返しご連絡いたします。

フローケースの Bot Framework と DirectLine を使用した統合テスト

Wed, 25 Apr 2018 00:00:00 +0000

はじめに

前回のブログ投稿では、単一のケースに対していくつかの統合テストを実行しました。「単一ケース」とは、ボットに何かを質問した後、ボットが 1 回だけ応答し、その結果を比較するケースです。

このガイドでは、認証と API 呼び出しがどのように行われるかについては説明しません。確認したい場合は、単一のケースのガイドを参照してください。

フロー会話についてはどうですか?

現在の方法では、会話にいかなる流れもありません。たとえば、助けを求めたい場合に、さまざまなオプションを含むメニューが表示され、そのうちの 1 つを選択した後に別のメニューが表示される場合です。これにより、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 の結合テストを担当することになりました。

グループでの私の仕事は、ボットを可能な限り安定させることですが、まず、ボットフレームワークとは何でしょうか?

インテリジェントなボットを構築、接続、展開、管理して、Web サイト、アプリ、Cortana、Microsoft Teams、Skype、Slack、Facebook Messenger などでユーザーと自然に対話します。使用した分だけ料金を支払うだけで、完全なボット構築環境をすぐに始められます。

Bot Framework の詳細については、ここをご覧ください。

なぜ統合テストが必要なのでしょうか?

統合テストが必要なのは、同僚が修正、新機能、さらには新しいバグをプッシュするたびに、コードを運用環境にプッシュする前にこのテストが実行され、テストのいずれかが失敗した場合、コードは運用環境に移行しないためです。つまり、エンドユーザーにはバグが発生しません。

ボットでの統合テスト?

ボットでは、統合テストが非常に重要であると私は信じています。一部のメニューが機能しない、または一部の機能が何も返さないボットは使用できません。

企業が顧客のためにボットを使用しているのは、人々に自分たちの問題で忙しくしてほしくないからです。ボットがユーザーを助けることができれば、他の従業員は自分の時間をより重要なことに費やすことができるでしょう。

ソリューションの概要。

これを機能させるために、Visual Studio でテストプロジェクトを使用しました。このプロジェクトでは、API レストに 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"
 }
 ]
}

ご覧のとおり、次のものがあります。

ダイレクトラインシークレット -> 公開ボットからのシークレット
直接トークン生成エンドポイント -> シークレットを使用してトークンを取得するエンドポイント
直接会話エンドポイント -> 会話を操作するためのエンドポイント
エントリ -> テストケース
- リクエスト -> 会話に送信するもの
- 応答 -> 取得が期待されるもの
- アサート -> 何を比較しているのか

デシリアライゼーション

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 の認証が含まれます。すべてのコードは this リポジトリの github に保存されていることに注意してください。

Bot FrameworkとDirectLineを使った連携テスト(2)

Tue, 24 Apr 2018 00:00:00 +0000

このパートでは、DirectLine 承認を作成し、ボットの応答から値を取得します。

逆シリアル化が完了したので、今度はコレクションと全体から情報を取得し、承認の取得、API 呼び出しの実行、結果のアサートに使用します。

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 に保存した応答。これは予想される応答です) とボットから取得した応答を比較する必要があります。

Microsoft.CodeAnalysis をソリューションに追加する

まず、CodeAnalysis を 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

私について

私はエミリアーノ・モンテスデオカ（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

講演

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でレベル3サポートを強化：Azure Functions + OpenAI実践

Azure Functions、Azure Monitorアラート、Azure OpenAIが連携してレベル3サポートを加速する方法。自動アラートトリアージからインテリジェントなログ分析まで — 実際のサポートワークフローにAIを追加する実践的な解説。

ダッシュボードからエージェントへ：オブザーバビリティの次のステップ

AIエージェントと本番オブザーバビリティの世界をつなぐハンズオンセッション。Semantic Kernelから、OpenTelemetryデータをクエリし、MCPを介してGrafanaと対話し、実際のシステムの運用と最適化を支援する自律型エージェントまで。

予定: Global Azure 2026 — 2026年4月、スペイン・マドリード

2025

クリスマスを救うMicrosoftエージェントフレームワーク

Microsoft Agent Frameworkを使って複数のAIエージェントを構築・調整し、完璧なクリスマスプレゼントを見つけます。各エージェントは専門化され — ギフトアイデア生成から価格比較まで — よりスマートなホリデーショッピングのために連携します。

AIでレベル3サポートを強化：Azure Functions + Semantic Kernel実践

Azure Functions、Azure Monitor、Semantic Kernelが連携してレベル3サポートをより速く効率的に — 自動アラート検出からインテリジェントなログ分析まで。

.NET 10でBlazorの何が新しくなった？

パフォーマンスの向上、フォーム、永続状態、より強力なJavaScriptインターオプなど、.NET 10向けBlazorの主要な新機能を探ります。

C#、Semantic Kernel、GeminiによるハイブリッドAI：スマートなエンタープライズアプリを作る

C#でハイブリッドAIワークフローをオーケストレーション — ローカルモデル(Phi-3)とVertex AI経由のGemini Pro/Ultraを組み合わせ、Semantic KernelプラグインでAIエージェントを構築し、適応型アーキテクチャを設計します。

.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がCloud-native開発をいかに単純化するかを示す実践的なデモ中心セッション。

Power Platform：Low-codeからPro-codeへの旅

同じプラットフォーム内でTypeScriptを使用して、Low-code Power AppsからAdvancedな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ですべてのセッションを見る →

Emiliano Montesdeoca

Blazor をゼロから: 第3章 — スケールするコンポーネント設計

Blazor コンポーネントとは何か

ステップ1: 役割が明確な小さなコンポーネントから始める

ステップ2: パラメーターで振る舞いを明示する

ステップ3: RenderFragment でレイアウトを合成する

ステップ4: 巨大ページよりコンポジションを選ぶ

ステップ5: マークアップとロジックのバランスを取る

ステップ6: 実用的なフォルダー構成

初期の Blazor プロジェクトでよくあるミス

次回予告

Blazor をゼロから: 第2章 — 最初の Blazor アプリ

ステップ1: プロジェクトを作成する

ステップ2: ローカルで実行する

ステップ3: プロジェクト構成を理解する

ステップ4: 最初の変更を加える

ステップ5: Program.cs を一度読む

よくある問題

次回

ゼロから始めるBlazor：第1章 — Blazorとは何か？

簡単な歴史

Blazorが実際に何であるか

レンダリングモデル

静的SSR

インタラクティブサーバー

インタラクティブWebAssembly

Autoモード

同じアプリでモードを混在させる

BlazorとJavaScriptフレームワークの比較

一緒に進めるために必要なもの

次回

Blazorをゼロから始める: 新シリーズ

このシリーズの対象者

カバーする内容

なぜシリーズを、なぜ今

シリーズのフォロー方法

C# ユニオン型: 差別的なユニオンがついに登場

差別的な組合とは何ですか?

今日の組合のシミュレーション方法

継承のある抽象レコード

手動列挙 + データ パターン

C# 提案: union キーワード

価値のみのメンバー

ジェネリックユニオン

メソッドとの結合

ネストされたパターンマッチング

ガード条項

実用的な例

結果のパターン: 予期されるエラーの例外を置き換える

ドメイン モデリング: 支払いタイプ

ステートマシン

試してみる方法

既存のアプローチとの比較

これが .NET エコシステムにとって何を意味するか

結論

セマンティック カーネルを使用した C# での RAG システムの構築

はじめに

RAG の仕組み

前提条件

カーネルのセットアップ

データモデルの定義

ドキュメントのチャンク化

ドキュメントの取り込み

関連するチャンクの検索

コンテキストを含む回答の生成

それを使用する

本番環境への移行

Microsoft Agent Framework を使用したエージェント ワークフローの構築

はじめに

エージェントのワークフローとは何ですか?

前提条件

順次ワークフローの構築

エージェントの定義

順次実行

並列実行

条件分岐

ワークフロー エージェントへのプラグインの追加

ワークフローでのエラー処理

ベストプラクティス

結論

ステップ3: `RenderFragment` でレイアウトを合成する

手動列挙 + データパターン

C# 提案: `union` キーワード

ドメインモデリング: 支払いタイプ

セマンティックカーネルを使用した C# での RAG システムの構築

Microsoft Agent Framework を使用したエージェントワークフローの構築

ワークフローエージェントへのプラグインの追加

クリスマスを救う Microsoft のエージェントフレームワーク

フェスティブテックカレンダー 2025

Microsoft のエージェントフレームワークとは何ですか?

ギフトショッピングエージェント

より詳細な制御のためのカスタムエグゼキュータより複雑なシナリオの場合は、ワークフローをきめ細かく制御できるカスタムエグゼキューターを作成できます。

AI を活用した RSS フィードアグリゲーターの構築

RSS フェッチロジックの構築

トラッキングファイルのロードと解析

マークダウンファイルを生成する理由