Emiliano Montesdeoca

Blazor с нуля: Глава 3 — Компоненты, которые масштабируются

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

Добро пожаловать в главу 3 серии Blazor с нуля. Если вы пропустили главу 2, лучше сначала прочитать её, чтобы базовый проект уже был готов.

В главе 2 мы запустили приложение. В этой главе сделаем его поддерживаемым.

Blazor-проекты быстро становятся запутанными, когда каждая страница превращается в огромный .razor-файл. Компоненты помогают этого избежать: дают единообразие, переиспользование и чёткие границы между частями UI.

Что такое компонент Blazor на практике

Компонент — это .razor-файл, который умеет:

Рендерить разметку
Хранить локальное состояние
Принимать входные данные через параметры
Отправлять события в родительский компонент
Рендерить дочернее содержимое

Во время выполнения Blazor рассматривает компонент как маленькую машину состояний. При изменении состояния выполняется повторный рендер и применяется diff 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: Баланс между разметкой и логикой

Для простых компонентов inline @code — нормально.

Для крупных компонентов лучше вынести логику в code-behind:

UserCard.razor
UserCard.razor.cs

Так и разметка, и C#-логика остаются читаемыми.

Шаг 6: Практичная структура папок

Структура, которая хорошо масштабируется:

Components/Pages/ -> маршрутизируемые страницы
Components/Layout/ -> shell приложения и навигация
Components/Common/ -> общие универсальные блоки
Components/Features/<FeatureName>/ -> компоненты по функциональности

Частые ошибки в ранних Blazor-проектах

Слишком много параметров вместо отдельной модели
Бизнес-правила прямо в page-компонентах
Один “god component” на сотни строк
Дублирование разметки вместо выделения переиспользуемых частей

Что дальше

В главе 4 разберём data binding и события: @bind, обработку событий, компромиссы two-way binding и паттерны предсказуемого состояния.

Blazor с нуля: Глава 2 — Ваше первое приложение Blazor

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

Добро пожаловать в главу 2 Blazor с нуля. Если вы пропустили главу 1, сначала прочитайте ее, чтобы освежить контекст рендеринга.

В этой главе мы создадим новое приложение Blazor, запустим его локально и поймем, за что отвечают основные файлы.

Шаг 1: Создайте проект

В терминале:

dotnet new blazor -o BlazorFromScratch
cd BlazorFromScratch

Команда создаст Blazor Web App на .NET 9 со стандартной структурой.

Если инструмент предлагает выбрать модель интерактивности, начните с 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/ — общий 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>() сопоставляет корневой компонент с endpoint-ами.

Эти строки показывают, как приложение запускается и какие возможности рендеринга активны.

Частые проблемы

Если что-то не работает, обычно причина одна из этих:

Старый 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

Добро пожаловать в Главу 1 серии Blazor с нуля. Если вы пропустили вводный пост, в котором я объяснил, о чём эта серия и для кого она предназначена, начните с него — он короткий.

В этой главе мы ответим на фундаментальный вопрос: что такое Blazor? Звучит просто, но ответ многослоен — особенно потому, что за эти годы «Blazor» приобрёл несколько разные значения. К концу этого поста вы будете знать, что такое Blazor, как он вписывается в экосистему .NET, какие существуют модели рендеринга и почему вы могли бы выбрать его вместо JavaScript-фреймворка — или нет.

Краткая история

Blazor начался как экспериментальный проект Стива Сандерсона в Microsoft примерно в 2017 году. Идея была провокационной: запустить C# в браузере с помощью WebAssembly, полностью устранив необходимость в JavaScript. Это было доказательство концепции, а имя было намеренным слиянием Blazer и Razor — движка шаблонов, на котором Blazor в итоге и был построен.

Эксперимент вызвал достаточно энтузиазма, чтобы Microsoft отнеслась к нему серьёзно. Blazor вышел в составе ASP.NET Core 3.0 в сентябре 2019 года — сначала как Blazor Server: модель, выполняющая C#-код на сервере и использующая соединение SignalR в реальном времени для отправки обновлений интерфейса в браузер. Blazor WebAssembly последовал в мае 2020 года в рамках ASP.NET Core 3.1, принеся фреймворку настоящее выполнение на стороне клиента.

.NET 6 и 7 улучшили опыт разработчиков. Затем .NET 8, выпущенный в ноябре 2023 года, коренным образом пересмотрел модель рендеринга с тем, что Microsoft назвала full-stack web UI. Статический рендеринг на стороне сервера, потоковый рендеринг, интерактивный сервер, интерактивный WebAssembly и новый режим Auto — всё это теперь живёт под одной крышей в одном проекте. .NET 9 развил эту основу и сгладил шероховатости.

Вот где мы находимся сегодня.

Что такое Blazor на самом деле

В своей основе Blazor — это компонентный UI-фреймворк для .NET. Вы строите интерфейс из компонентов — самодостаточных единиц C# и HTML-разметки, которые могут хранить состояние, реагировать на события и компоноваться в более крупные структуры. Если вы работали с React или Vue, эта ментальная модель покажется знакомой. Ключевое отличие в том, что вместо JavaScript вы пишете C#.

Компоненты Blazor пишутся в файлах .razor. Файл .razor смешивает HTML-разметку с C#-кодом, используя синтаксис Razor, который вы, возможно, уже знаете по представлениям ASP.NET MVC. Вот как выглядит простой компонент:

@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, который затем отправляется в браузер. Нет постоянного соединения, нет WebAssembly и по умолчанию нет интерактивности на стороне клиента. По сути это то, что делает Razor Pages, но с использованием компонентной модели.

Используйте для страниц с большим количеством контента, лендингов, всего, что не требует живой интерактивности.

Интерактивный сервер

Код компонента выполняется на сервере. Между браузером и сервером устанавливается WebSocket-соединение SignalR. Когда вы нажимаете кнопку или вводите что-то в поле ввода, событие передаётся по 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 (Parameters в Blazor), локальное состояние (поля в блоке @code), хуки жизненного цикла и тот же паттерн: данные вниз, события вверх. Если вы знаете React, освоитесь за несколько часов.

Ключевое отличие — язык. В Blazor вы пишете C#. Бизнес-логика, правила валидации и модели данных могут быть общими для вашего Blazor-фронтенда и ASP.NET Core-бэкенда. Больше не нужно дублировать класс User в TypeScript, если он уже есть на C#.

Разрыв экосистем реален, но сокращается. Экосистема npm огромна. Экосистема NuGet для UI-компонентов меньше, хотя существенно выросла. Если нужна специфическая библиотека графиков или виджет drag-and-drop, у JavaScript по-прежнему больше вариантов. Но для большинства бизнес-приложений того, что доступно в мире .NET, более чем достаточно.

JavaScript-взаимодействие есть, когда оно нужно. Blazor позволяет вызывать JavaScript из C# и C# из JavaScript. Для браузерных API без .NET-обёртки или при необходимости использовать существующую JS-библиотеку interop доступен. Он добавляет слой, но не причиняет боли.

Честный ответ: если вся ваша команда — JavaScript-разработчики, создающие публичный продукт, где критичны SEO, производительность и экосистема npm, оставайтесь на JavaScript. Если ваша команда — .NET-разработчики, если вы создаёте внутренние или бизнес-приложения, или если для вас важно совместное использование кода между фронтендом и бэкендом, Blazor — убедительный выбор.

Что нужно для дальнейшего изучения

Для остальной части серии вам понадобится:

.NET 9 SDK — загрузить с dot.net
IDE — Visual Studio 2022 (Community-редакция бесплатна), VS Code с расширением C# Dev Kit или JetBrains Rider
Базовое знание C# — классы, свойства, интерфейсы, async/await

Это всё. Никакого Node, npm или webpack.

Что дальше

В Главе 2 мы создадим ваше первое приложение Blazor, разберём структуру проекта и убедимся, что вы можете запустить его локально. В итоге у вас будет работающее приложение и чёткое понимание того, что делает каждый файл.

До встречи там.

Blazor с нуля: Новая серия

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

Я уже довольно давно пишу о Blazor — жизненные циклы компонентов, изолированный CSS, модели интерактивности, аутентификация. Эти публикации были полезны сами по себе, но мне всегда казалось, что им не хватает фундамента. Они исходят из того, что вы уже знаете, что такое Blazor, зачем он нужен и как вписывается в экосистему .NET. Знают это далеко не все — и это абсолютно нормально.

Поэтому я начинаю кое-что новое: Blazor с нуля. Настоящая серия, выстроенная от основ, для разработчиков, которые хотят действительно понять, что они строят, — а не просто копировать и вставлять, пока не заработает.

Для кого эта серия

Серия для вас, если:

вы .NET-разработчик, который слышал о Blazor, но никогда не находил времени или подходящей точки входа, чтобы разобраться.
вы пробовали Blazor, запустили его, но чувствуете, что просто угадываете, почему что-то работает.
вы пришли из мира JavaScript/React/Angular и хотите понять, каким Microsoft видит современный фронтенд.
вам нужен один связный ресурс вместо разрозненной документации и отдельных статей.

Быть старшим разработчиком не обязательно. Но нужно уверенно знать основы C# — классы, интерфейсы, async/await. Если вы умеете писать простое CRUD API на ASP.NET Core, вы готовы.

Что мы рассмотрим

Вот примерная дорожная карта того, что я планирую. Некоторые темы при необходимости разрастутся в несколько публикаций:

Что такое Blazor? — Модели хостинга, история, сравнение с традиционной веб-разработкой
Ваше первое приложение на Blazor — Scaffolding, структура проекта, запуск локально
Компоненты — Основной строительный блок любого интерфейса в Blazor
Привязка данных и события — Как сделать интерфейс реактивным
Взаимодействие компонентов — Параметры, EventCallbacks, каскадные значения
Маршрутизация и навигация — Как Blazor работает с URL и переходами между страницами
Внедрение зависимостей — Сервисы, скоупы и DI-контейнер в Blazor
Формы и валидация — EditForm, DataAnnotations, пользовательские валидаторы
HTTP и внешние данные — Вызов API из приложения на Blazor
Аутентификация и авторизация — Как правильно защитить приложение
JavaScript-интероп — Когда нужно обратиться напрямую к браузеру
Производительность и оптимизация — Виртуализация, ленивая загрузка, стратегии рендеринга
Тестирование компонентов Blazor — bUnit и как выглядит хороший тест
Деплой — Публикация в Azure, IIS и на статических хостах

Список будет развиваться. Некоторые темы разделятся на несколько публикаций, другие могут объединиться. Буду обновлять эту запись по мере продвижения серии и добавлять ссылки на каждую часть по мере выхода.

Почему серия, почему сейчас

Blazor значительно повзрослел. В .NET 8 и 9 модель рендеринга была кардинально переработана — статический SSR, потоковый рендеринг, интерактивный Server, интерактивный WebAssembly и режим Auto теперь уживаются под одной крышей. Это по-настоящему интересный и мощный фреймворк, но возросшая сложность делает первоначальный опыт дезориентирующим.

Хочу создать ресурс, который встретит вас там, где вы находитесь, и методично проведёт через всё целиком. Не замена официальной документации — она хороша, и её стоит читать, — а попутчик, объясняющий почему стоит за что.

Как следить за серией

Каждая публикация в серии будет достаточно самостоятельной, чтобы читать её отдельно, но они также будут опираться друг на друга. Если начинаете с нуля — рекомендую идти по порядку. Если подключаетесь, чтобы заполнить конкретный пробел, — это тоже нормально: буду ссылаться на предыдущие материалы там, где это важно.

Код к каждой публикации будет доступен на GitHub. Ссылки буду делиться по ходу.

До встречи в следующей части.

Типы объединений C#: наконец-то появляются размеченные объединения

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

Если вы пишете на C# какое-то значительное время, велика вероятность, что вы уперлись в стену, пытаясь смоделировать что-то, что может быть «одной из нескольких вещей». Возможно, вам нужен метод, возвращающий либо успешное значение, либо ошибку. Возможно, вы создавали платежную систему, которая обрабатывает кредитные карты, банковские переводы и цифровые кошельки — каждый с совершенно разными данными. Или, может быть, вы просто посмотрели на F# или Rust и подумали: «Почему я не могу этого сделать на C#?»

Ожидание почти закончилось. Дискриминированные объединения приходят в C#.

Это была одна из самых востребованных функций языка на протяжении многих лет, а обсуждения в сообществе начались еще в 2017 году и раньше. Группа разработчиков языка C# работала над предложением, которое вводит ключевое слово union для определения иерархий закрытого типа с исчерпывающим сопоставлением шаблонов. В этом посте я хочу рассказать вам, что такое дискриминируемые объединения, почему они так важны, как мы до сих пор их подделывали и как на самом деле выглядит предлагаемый синтаксис — с реальными примерами кода для каждого.

Небольшое примечание, прежде чем мы углубимся: на момент написания этой статьи функция объединения типов все еще находится на стадии предложения и предварительного просмотра. Синтаксис и поведение, которые я описываю здесь, основаны на последних общедоступных документах по проектированию и обсуждениях группы разработчиков языка C#. Все может измениться до финального релиза. Я буду четко объяснять, что подтверждено, а что еще обсуждается.

Что такое дискриминируемые профсоюзы?

По своей сути дискриминируемое объединение (иногда называемое «теговым объединением» или «типом суммы») — это тип, который может содержать одно из фиксированного набора возможных значений, причем каждый вариант может нести разные данные. «Дискриминируемая» часть означает, что среда выполнения всегда знает, какой это вариант — существует тег, который его идентифицирует.

Думайте об этом как о enum, но каждый участник может нести свою собственную полезную нагрузку данных.

Если вы использовали другие языки, вы, вероятно, видели эту концепцию раньше:

В F# профсоюзы дискриминируются с самого первого дня:

[[[ТОК_2]]]

Rust использует enum для той же идеи:

[[[ТОК_4]]]

TypeScript достигает чего-то похожего с теговыми объединениями:

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

Во всех этих случаях компилятор знает все возможные варианты и может заставить вас обработать их все. Это суперсила: полная проверка. Если вы добавите новый вариант, компилятор везде сообщит вам, что вы забыли его обработать.

В C# никогда не было первоклассного способа выразить это. До настоящего времени.

Как мы моделируем профсоюзы сегодня

За прошедшие годы сообщество C# придумало несколько обходных путей, каждый из которых имел свои недостатки. Позвольте мне рассказать о наиболее распространенных подходах.

Абстрактные записи с наследованием

Самый идиоматический обходной путь в современном C# — использование абстрактных записей с запечатанными производными типами:

[[[ТОК_6]]]

Это работает достаточно хорошо. Вы получаете неизменяемость, равенство значений и можете использовать сопоставление с образцом:

[[[ТОК_7]]]Но есть существенные недостатки. Компилятор не знает, что иерархия закрыта, поэтому вам всегда нужен этот рычаг сброса _, иначе вы получите предупреждение. Если вы добавите новый вариант, компилятор не сообщит вам обо всех местах, где вы забыли его обработать — сброс молча проглотит его. Это полностью противоречит цели.

Библиотека OneOf

Другой популярный подход — пакет NuGet OneOf:

[[[ТОК_10]]]

OneOf обеспечивает проверку полноты во время компиляции с помощью параметров универсального типа, и это здорово. Но он полагается на позиционное сопоставление (первого типа, второго типа и т. д.), общие сигнатуры быстро становятся громоздкими и не интегрируются с сопоставлением шаблонов языка. Это умный хак, но это всё равно хак.

Ручное перечисление + шаблон данных

Некоторые разработчики идут по классическому пути, используя тег enum и контейнер данных:

[[[ТОК_11]]]

Это хрупко. Ничто не мешает вам установить для Type значение CreditCard, кроме заполнения свойства BankTransfer. Компилятор не сможет вам помочь, и вы получите повсюду ошибки времени выполнения и нулевые проверки. Это «строчно типизированный» подход к моделированию типов, и он не масштабируется.

Все эти подходы имеют общую фундаментальную проблему: они борются с языком, а не работают с ним. Компилятор не может рассуждать о закрытом наборе возможностей, поэтому вы теряете самое ценное свойство дискриминируемых объединений — исчерпывающую проверку.

Предложение C#: ключевое слово `union`

В предложении группы языка C# представлено выделенное ключевое слово union, которое определяет закрытый набор именованных членов, каждый из которых может необязательно нести данные. Вот основной синтаксис, как он был предложен:

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

Вот и все. Четко, лаконично и сразу читается. Каждый член внутри союза определяет отдельный вариант со своими собственными данными. Компилятор знает, что Shape может быть только одним из этих трех объектов.

Под капотом компилятор генерирует иерархию запечатанных типов — аналогично тому, что вы пишете вручную с абстрактными записями, но с полным пониманием компилятором закрытой природы типа. Это означает, что компилятор может обеспечить полноту сопоставления с образцом, что является ключевым преимуществом.

Члены, имеющие только значение

Членам профсоюза не нужно переносить данные. Вы можете смешивать элементы, переносящие данные, с простыми элементами-значениями:

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

Это классический тип Option/Maybe, который функциональные программисты просили в C# в течение многих лет. None не содержит данных — это просто тег.

Общие союзы

Как видно из примера Option<T> выше, объединения поддерживают дженерики. Вот более сложный пример:

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

Это открывает целый стиль обработки ошибок, который не основан на исключениях для ожидаемых случаев сбоя — то, что уже много лет является стандартной практикой в Rust и функциональных языках.

Объединения с методами

Предложение также позволяет объединениям иметь методы, вычисляемые свойства и реализовывать интерфейсы, как и любой другой тип:```csharp union Shape { Circle(double Radius), Rectangle(double Width, double Height), Triangle(double Base, double Height);

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

}


Обратите внимание, что выражение `switch` внутри `Area` и `Perimeter` не требует руки по умолчанию. Компилятор знает, что объединение является исчерпывающим — существует только три варианта, и все три обрабатываются. Если позже вы добавите четвертый вариант, компилятор пометит каждый `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"
};

Практические примеры

Позвольте мне рассказать о некоторых реальных сценариях, в которых типы объединения значительно улучшают код.

Шаблон результата: замена исключений на ожидаемые ошибки

Одним из наиболее распространенных шаблонов в разработке современных приложений является представление операций, которые могут быть успешными или неудачными, без использования исключений для потока управления. Исключения должны быть исключительными — например, сбои сети или нехватка памяти. Ошибка проверки или результат «не найден» — это ожидаемый результат, а не исключение.

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

Сравните это с текущим подходом, в котором у вас есть интерфейс или абстрактный класс с пятью различными реализациями, распределенными по пяти файлам, возможно, с шаблоном посетителя сверху. Подход объединения сохраняет определение данных и операции вместе, читабельными и полностью проверяемыми.

Государственные машины

Конечные автоматы присутствуют повсюду в программном обеспечении — обработка заказов, механизмы рабочих процессов, управление соединениями, состояние пользовательского интерфейса. Объединения делают их явными и безопасными:

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

Каждое состояние несет в себе именно те данные, которые относятся к этому состоянию. Вы не можете случайно получить доступ к TcpClient в состоянии Connecting, поскольку он не существует в этом варианте. Система типов обеспечивает соблюдение инвариантов конечного автомата.

Вопросы сериализации и взаимодействияОдин из практических вопросов, который сразу же возникает в связи с типами объединения: как их сериализовать? Если вы создаете 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 все еще разрабатывается, но инфраструктура для обработки иерархий закрытого типа уже существует.

Стоит отметить, что взаимодействие с другими языками .NET должно быть плавным, поскольку объединения будут компилироваться в стандартные иерархии классов IL. Код F#, использующий объединение C#, будет рассматривать его как стандартную иерархию типов, и наоборот.

Как попробовать

На момент написания объединенные типы доступны в качестве предварительной функции в последних предварительных версиях .NET SDK. Чтобы поэкспериментировать с предложенным синтаксисом, вам необходимо:

Установите последнюю версию SDK предварительной версии .NET.
Включите языковую версию предварительного просмотра в файле проекта:

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

Имейте в виду, что функции предварительной версии могут быть изменены. Синтаксис, поведение и диагностика компилятора могут значительно измениться до окончательного выпуска. Не отправляйте рабочий код, полагаясь на функции языка предварительной версии, но обязательно экспериментируйте с ними и оставляйте отзывы. Команда C# активно следит за обсуждениями репозитория csharplan.

Если вы хотите следить за ходом рассмотрения предложения, обратите внимание на следующие ключевые места:

Репозиторий dotnet/csharplan для обсуждений языкового дизайна. — Репозиторий dotnet/roslyn для информации о ходе реализации компилятора.
Блог .NET для официальных объявлений.

Сравнение с существующими подходами

Позвольте мне провести быстрое сравнение, чтобы вы могли увидеть, как складываются различные подходы:

Особенность	Абстрактные записи	OneOf<T1,T2>	Перечисление + Данные	Типы союзов
Проверка полноты	❌ Нет	✅ Да	❌ Нет	✅ Да
Сопоставление с образцом	✅ Да	❌ Ограниченная	❌ Руководство	✅ Родной
Закрытие, принудительное компилятором	❌ Нет	✅ Да	❌ Нет	✅ Да
Данные по варианту	✅ Да	✅ Да	⚠️ Хрупкий	✅ Да
Читабельность	⚠️ Подробный	⚠️ Позиционный	❌ Бедный	✅ Отлично
Сериализация	✅ Руководство	⚠️Комплекс	✅ Руководство	✅ Встроенный
Шаблон	⚠️ Умеренный	✅ Низкий	⚠️ Высокий	✅ Минимальный
Нет внешней зависимости	✅ Да	❌ NuGet	✅ Да	✅ Да

Что это значит для экосистемы .NET

Введение дискриминационных профсоюзов отразится на всей экосистеме .NET. Вот что я ожидаю увидеть:

Дизайн библиотеки будет улучшен. API, которые в настоящее время возвращают null для обозначения «не найдено» или выдают исключения в случае сбоев проверки, смогут вместо этого возвращать типы Result<T, E> . Это делает режимы сбоя явными в сигнатуре типа — вы можете увидеть, что может пойти не так, взглянув на сигнатуру метода, а не читая документацию или исходный код.

Моделирование предметной области становится более выразительным. Разрыв между предметной областью задачи и представлением кода резко сокращается. Когда ваш эксперт в предметной области говорит: «Платеж может быть кредитной картой, банковским переводом или наложенным платежом», вы можете смоделировать это непосредственно как объединение, а не переводить его в иерархию наследования.

Идеи F# становятся доступными разработчикам C#. Многие разработчики C# восхищались системой типов F# на расстоянии, но не смогли внедрить F# в своих организациях. Типы объединения привносят в C# одну из самых мощных функций F#, что является победой для всей экосистемы .NET.

Меньше ошибок во время выполнения. Одна только проверка полноты позволит предотвратить целые категории ошибок. Каждый раз, когда вы добавляете в объединение новый вариант, компилятор покажет вам все места в кодовой базе, требующие обновления. Больше никаких забытых случаев switch и NotImplementedException в ветках по умолчанию, которые появляются только в рабочей среде.

Заключение

Дискриминированные профсоюзы уже почти десять лет находятся на вершине списка пожеланий сообщества C#, и не без причины. Они устраняют фундаментальный пробел в системе типов — возможность моделировать данные, которые могут быть «одной из нескольких вещей» с безопасностью, обеспечиваемой компилятором.

Предлагаемое ключевое слово union обеспечивает чистый, лаконичный синтаксис, который глубоко интегрируется с сопоставлением шаблонов C#, работает с универсальными шаблонами, поддерживает методы и интерфейсы и обеспечивает исчерпывающую проверку, которая выявляет ошибки во время компиляции, а не во время выполнения.

Создаете ли вы модели предметной области, разрабатываете API с явными типами ошибок, реализуете конечные автоматы или просто пытаетесь заменить неудобные иерархии наследования чем-то более естественным — типы объединения изменят то, как вы пишете на C#.

Мы долго этого ждали. Синтаксис элегантен, интеграция с существующими функциями языка продумана, а практическое влияние будет ощущаться во всей экосистеме .NET.

Следите за предварительными версиями, экспериментируйте с этой функцией и оставляйте отзывы команде разработчиков языка. Это одна из тех функций, воспользовавшись которой, вы удивитесь, как вы раньше жили без нее.

Создание системы RAG на C# с семантическим ядром

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

Введение

Если вы пытались использовать LLM для ответа на вопросы о ваших собственных данных — документах компании, спецификациях продуктов, внутренних базах знаний — вы, вероятно, заметили, что это либо галлюцинирует, либо просто говорит: «У меня нет информации об этом». Это потому, что модель знает только то, чему она обучалась.

RAG (Расширенная генерация извлечения) исправляет это. Вместо точной настройки модели на основе ваших данных вы извлекаете соответствующие фрагменты своих документов во время запроса и передаете их в LLM в качестве контекста. Затем модель генерирует ответы, основанные на ваших фактических данных.

В этом посте я расскажу вам, как создать полный конвейер RAG на C# с использованием семантического ядра.

Как работает 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 или любую другую поддерживаемую базу данных векторов. Но in-memory идеально подходит для обучения и прототипирования.

Настройка ядра

[[[ТОК_1]]]

Нам нужны две модели: одна для завершения чата (ответы на вопросы) и одна для генерации вложений (преобразование текста в векторы).

Определение модели данных

Нам нужен класс для представления фрагментов нашего документа в векторном хранилище:

[[[ТОК_2]]]

Атрибут 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;
 }
}

Перекрытие важно — оно гарантирует, что контекст на границе между фрагментами не будет потерян. Если соответствующее предложение разделено на два фрагмента, перекрытие означает, что оно появится полностью хотя бы в одном из них.

Загрузка документов

Теперь давайте соберем все это вместе, чтобы загрузить документы в наше векторное хранилище:

[[[ТОК_6]]]

Поиск соответствующих фрагментов

Когда пользователь задает вопрос, мы генерируем вложение для его запроса и ищем похожие фрагменты:

[[[ТОК_7]]]

Генерация ответов с учетом контекста

Теперь часть RAG — мы берем полученные фрагменты и включаем их в качестве контекста в нашу подсказку:

[[[ТОК_8]]]

Использование этого

[[[ТОК_9]]]

Переезд в производство

Хранилище векторов в памяти отлично подходит для прототипирования, но для производства вам понадобится постоянная база данных векторов. Семантическое ядро имеет коннекторы для нескольких опций:

[[[ТОК_10]]]

Заменить местами очень просто, поскольку все они реализуют один и тот же интерфейс IVectorStore:

[[[ТОК_12]]]Все остальное остается прежним. В этом красота абстракции.

Советы по созданию RAG-систем

Несколько вещей, которые я усвоил на собственном горьком опыте:

Размер блока имеет большое значение. Если он слишком мал, вы теряете контекст. Слишком большой размер — и вы потратите токены на нерелевантный контент. Начните с 500-800 токенов и корректируйте их в зависимости от ваших данных.
Перекрытие предотвращает проблемы с границами. Обычно достаточно перекрытия в 50–100 токенов между фрагментами.
Получите больше, чем вы думаете. Начните с topK = 5 и уменьшите, если вы слышите слишком много шума. Лучше иметь дополнительный контекст, чем пропустить соответствующий фрагмент. – Системные подсказки имеют решающее значение. Будьте предельно откровенны, используя только предоставленный контекст. Без этой инструкции модель будет с радостью галлюцинировать «на основе своих обучающих данных».
Отслеживайте источники. Всегда сохраняйте метаданные вместе с фрагментами, чтобы вы могли указать, откуда пришел ответ. Пользователи больше доверяют ответам, когда могут проверить источник.
При необходимости измените ранжирование. Сходство векторов не является идеальным. Для критически важных приложений добавьте этап переранжирования с использованием модели перекрестного кодирования для повышения точности.

Заключение

RAG на данный момент является одним из самых практичных шаблонов в области искусственного интеллекта. Он позволяет создавать системы вопросов и ответов на основе искусственного интеллекта на основе ваших собственных данных без тонкой настройки, а семантическое ядро делает их на C# удивительно чистыми. Начните с хранилища в памяти, правильно разбейте фрагменты и подсказки, а затем замените реальную векторную базу данных, когда будете готовы к работе.

Приятного кодирования!

Ресурсы

Создание рабочих процессов агента с помощью Microsoft Agent Framework

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

Введение

Если вы читали мои предыдущие публикации об Agent Framework от Microsoft, вы знаете, как создавать отдельных агентов и даже групповые чаты с несколькими агентами. Но в реальных сценариях вам часто требуется что-то более структурированное — рабочий процесс, в котором агенты выполняются в определенном порядке, передают результаты друг другу и обрабатывают логику ветвления на основе результатов.

Именно это дают вам возможности рабочего процесса в Agent Framework. Вместо того, чтобы бросать агентов в групповой чат и надеяться, что они это поймут, вы определяете явные шаги, зависимости и поток данных между агентами.

Что такое рабочие процессы агента?

Думайте о рабочих процессах агентов как о конвейере. Каждый шаг обрабатывается специализированным агентом, а результаты одного шага передаются на следующий. Вы можете выполнять шаги последовательно, параллельно или условно в зависимости от результатов.

Несколько примеров:

Контроллер контента: Исследование → Черновик → Обзор → Публикация.
Обработка данных: Извлечение → Преобразование → Проверка → Загрузка.
Поддержка клиентов: Классифицировать → Маршрут → Ответ → Последующие действия.

Предварительные условия

Убедитесь, что у вас установлены последние версии пакетов Agent Framework:

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

И настроена конечная точка Azure OpenAI или OpenAI.

Построение последовательного рабочего процесса

Давайте построим рабочий процесс создания контента с тремя агентами: исследователем, писателем и редактором.

Определение агентов

[[[ТОК_1]]]

Выполнение последовательно

Самый простой рабочий процесс является последовательным — каждый агент обрабатывает выходные данные предыдущего:

[[[ТОК_2]]]

Каждый агент получает накопленный контекст, обрабатывает его, и результат переходит на следующий шаг.

Параллельное выполнение

Иногда агенты могут работать независимо. Например, вы можете захотеть исследовать несколько подтем одновременно:

[[[ТОК_3]]]

Затем вы можете передать все исследовательские обзоры одному агенту-писателю, чтобы создать один связный пост.

Условное ветвление

Реальные рабочие процессы требуют решений. Возможно, вам нужен этап проверки качества, который направляется обратно автору, если сообщение недостаточно хорошее:

[[[ТОК_4]]]

Этот шаблон очень полезен. Средство проверки качества действует как шлюз, и рабочий процесс повторяется до тех пор, пока результат не станет достаточно хорошим или не достигнет максимального предела версии.

Добавление плагинов к агентам рабочих процессов

Агенты в рабочих процессах могут использовать плагины так же, как и автономные агенты. Здесь все становится действительно мощно — агенты могут вызывать 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");

[[[ТОК_6]]]

Обработка ошибок в рабочих процессах

Когда вы объединяете несколько агентов, обработка ошибок становится критически важной. Вы не хотите, чтобы один неудачный шаг незаметно привел к сбою всего рабочего процесса:

[[[ТОК_7]]]

Лучшие практики

Построив несколько рабочих процессов агентов, я узнал следующее:- Соблюдайте четкость инструкций — каждый агент должен хорошо выполнять одну задачу. Не пытайтесь сделать агента, использующего швейцарский армейский нож.

Ограничить контекст — не передавайте всю историю разговоров каждому агенту. Давайте каждому шагу только то, что ему нужно.
Устанавливайте ограничения на версии — циклы контроля качества хороши, но могут работать вечно, если вы не будете осторожны. Всегда имейте максимальное количество итераций.
Записывайте все — результаты работы агента могут быть непредсказуемыми. Регистрируйте ввод и вывод каждого шага для отладки.
Используйте параллельное выполнение с умом — это ускоряет работу, но следите за ограничениями скорости API и стоимостью токенов.
Сначала протестируйте модели меньшего размера. Разработайте и протестируйте логику рабочего процесса с помощью GPT-3.5, прежде чем переходить на GPT-4o для производства.

Заключение

Рабочие процессы агентов позволяют создавать сложные многоэтапные конвейеры искусственного интеллекта, в которых каждый агент является специалистом. Начните с последовательных рабочих процессов, добавьте параллельное выполнение, где шаги независимы, и используйте условное ветвление для контроля качества. Шаблоны можно компоновать — как только вы освоите их, вы сможете создать довольно сложную систему автоматизации.

Приятного кодирования!

Ресурсы

Жизненный цикл компонента Blazor: полное руководство

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

Я использую Blazor уже некоторое время, и, честно говоря, методы жизненного цикла поначалу меня смутили. OnInitialized против OnInitializedAsync? OnParametersSet против OnAfterRender? Когда StateHasChanged фактически запускает повторный рендеринг? После многих проб и ошибок у меня наконец появилась твердая мысленная модель всего этого.

Краткий обзор жизненного цикла

При рендеринге компонента Blazor он проходит через следующие методы по порядку:

[[[ТОК_5]]]
[[[ТОК_6]]] / [[[ТОК_7]]]
[[[ТОК_8]]] / [[[ТОК_9]]]
[[[ТОК_10]]] / [[[ТОК_11]]]
[[[ТОК_12]]] / [[[ТОК_13]]]

Давайте пройдемся по каждому.

УстановитьПараметрыАсинхронно

Это самый первый вызываемый метод. Он получает необработанный ParameterView от родительского компонента. В большинстве случаев вы не переопределяете это — Blazor автоматически обрабатывает параметры сопоставления. Но если вам нужна обработка или проверка пользовательских параметров перед их назначением:

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

 await base.SetParametersAsync(parameters);
}

Я использовал это ровно один раз в реальном проекте. Большую часть времени вы пропустите это.

OnInitialized/OnInitializedAsync

Здесь вы выполняете работу по настройке — загружаете данные, инициализируете службы, устанавливаете значения по умолчанию. Он запускается один раз при первом создании компонента.

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

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

Одна вещь, которая меня смутила: на Blazor Server OnInitializedAsync вызывается дважды во время предварительного рендеринга. Первый раз во время предварительной отрисовки на стороне сервера, а второй раз — при установке соединения SignalR. Если ваш вызов API является дорогостоящим, вы можете решить эту проблему:

private bool isPrerendering = true;

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

Или, что еще лучше, используйте PersistentComponentState, чтобы полностью избежать двойного вызова.

OnParametersSet / OnParametersSetAsync

Это срабатывает каждый раз, когда родительский компонент выполняет повторную визуализацию и передает новые значения параметров. Он также срабатывает после OnInitialized. Это подходящее место для реагирования на изменения параметров:

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

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

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

Проверка на CategoryId != previousCategoryId важна — без нее вы бы перезагружали данные каждый раз, когда родительский элемент выполняет повторную визуализацию, даже если категория не изменилась.

OnAfterRender / OnAfterRenderAsync

Это срабатывает после того, как компонент отображается в DOM. Параметр firstRender сообщает вам, является ли это первоначальным рендерингом. Это место для вызовов JS Interop, поскольку на этом этапе существуют элементы DOM:

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

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

Я часто использую firstRender, чтобы избежать повторной инициализации библиотек JavaScript при каждом повторном рендеринге. Если вы настраиваете прослушиватели событий, библиотеки диаграмм или что-то, что напрямую касается DOM, это то, что вам нужно.

ДолженRender

Этот менее известен, но очень полезен. Он контролирует, будет ли компонент выполнять повторную визуализацию при вызове 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
}

Я использовал это для оптимизации компонентов, обрабатывающих большие списки. Вместо повторного рендеринга при каждом изменении элемента вы выполняете пакетную обработку обновлений и выполняете рендеринг один раз в конце.

Dispose/DisposeAsync

Когда компонент удаляется из пользовательского интерфейса, вам следует очистить все ресурсы. Реализуйте 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 Agent Framework спасет Рождество

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

Введение

Поиск идеальных рождественских подарков может оказаться стрессом. Между мозговым штурмом идей подарков, сравнением цен в разных магазинах и проверкой того, чтобы все было доставлено вовремя, праздничные покупки быстро становятся непосильными. Что, если бы мы могли делегировать эти задачи специализированным агентам ИИ, которые работали бы вместе? В этом посте мы рассмотрим, как использовать Microsoft Agent Framework для создания многоагентной системы, в которой каждый агент специализируется на определенной задаче, от генерации идей для подарков до сравнения цен, и все это координируется посредством рабочих процессов.

Праздничный технический календарь на 2025 год

Этот проект является частью моего выступления на Праздничном техническом календаре 2025, замечательном общественном мероприятии, посвященном технологиям в праздничный сезон. Дополнительную информацию о мероприятии можно найти на странице Sessionize.

Что такое платформа агентов Microsoft?

Agent Framework — это решение Microsoft для создания, координации и развертывания агентов искусственного интеллекта и многоагентных систем. Он обеспечивает гибкую основу для создания агентов, которые могут работать последовательно, одновременно или по шаблонам передачи обслуживания. Платформа поддерживает модели OpenAI, Azure OpenAI и Microsoft Foundry, что делает ее невероятно универсальной.

Ключевые особенности включают в себя:

Многоагентная оркестровка: групповой чат, последовательный, одновременный и шаблоны передачи обслуживания.
Экосистема плагинов: расширение за счет встроенных функций, OpenAPI и протокола контекста модели (MCP).
Поддержка рабочих процессов: создавайте сложные конвейеры агентов с исполнителями и границами.

Предварительные условия

Прежде чем углубляться в код, убедитесь, что у вас есть:

.NET 9
Доступ к Azure OpenAI (или ключ API OpenAI)
Visual Studio или код Visual Studio

Установите необходимые пакеты (обратите внимание, что в предварительной версии требуется флаг --prerelease:

[[[ТОК_3]]]

Агенты по покупке подарков

Наш поисковик рождественских подарков будет состоять из трех специализированных агентов, работающих вместе:

Агент по идеям подарков — генерирует креативные предложения подарков на основе профиля получателя.
Агент сравнения цен — находит лучшие цены в разных магазинах.
Агент сводки – собирает окончательные рекомендации.

Модели

Давайте начнем с определения наших моделей данных, которые будут проходить через конвейер агента:

[[[ТОК_4]]]

Создание агентов

Прелесть Agent Framework в том, насколько легко создавать специализированные агенты. Каждый агент представляет собой просто ChatClientAgent со специальным системным приглашением, определяющим его опыт.

[[[ТОК_6]]]

Создание рабочего процесса

Теперь самое интересное — подключение наших агентов к последовательному рабочему процессу. Платформа агентов предоставляет WorkflowBuilder и AgentWorkflowBuilder для объединения агентов в различные шаблоны.

[[[ТОК_9]]]

Одновременный запуск агентов

Что делать, если мы хотим искать подарки для нескольких человек одновременно? Agent Framework поддерживает одновременное выполнение, что идеально подходит для этого сценария:

[[[ТОК_10]]]

Пользовательские исполнители для большего контроляДля более сложных сценариев вы можете создавать собственные исполнители, которые дают вам детальный контроль над рабочим процессом:

[[[ТОК_11]]]

Затем вы можете вставить этот исполнитель в свой рабочий процесс:

[[[ТОК_12]]]

Добавление реального веб-поиска с заземлением Bing

На данный момент наши агенты генерируют ответы на основе знаний модели ИИ. Но что, если мы хотим найти в Интернете актуальные цены и наличие товаров? Именно здесь на помощь приходит Обоснование с помощью Bing Search. Это инструмент, доступный в Microsoft Foundry (ранее Azure AI Foundry), который позволяет вашим агентам включать общедоступные веб-данные в реальном времени при формировании ответов.

Сначала вам необходимо создать ресурс Заземление с помощью поиска Bing на Портале Azure. Обязательно создайте его в той же группе ресурсов, что и ваш проект ИИ.

Настройка заземления с помощью поиска Bing

Прелесть заземления с помощью Bing Search заключается в том, что оно напрямую интегрируется с агентами Azure AI. Агент решает, когда использовать инструмент поиска, на основе запроса пользователя, выполняет поиск в Интернете и использует результаты для генерации обоснованного ответа.

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

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

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

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

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

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

 return agent;
 }
}

Создание агента сравнения цен с помощью реального поиска

Теперь давайте создадим полноценный агент сравнения цен, который ищет в Интернете реальную информацию о продуктах:

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

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

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

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

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

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

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

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

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

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

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

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

Интеграция заземления Bing в рабочий процесс

Вот как можно использовать ценового агента на базе 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 является то, что ответы включают цитаты со ссылками на исходные веб-сайты. Вот как их извлечь и отобразить:

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 для поиска реальных списков продуктов, текущих цен и доступных предложений в Интернете. Агент автоматически решает, когда выполнять поиск, на основе запроса и возвращает обоснованные ответы с соответствующими цитатами.

Полная программа

Вот как все устроено в 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 Agent Framework позволяет на удивление легко создавать многоагентные системы, в которых каждый агент специализируется на определенной задаче. Координируя рабочие процессы этих агентов, мы можем структурированным и эффективным образом решать сложные проблемы, такие как рождественские покупки.

Что делает это еще более мощным, так это возможность добавлять реальные возможности с помощью инструментов. Благодаря интеграции Grounding с Bing Search от Microsoft Foundry наш агент по сравнению цен может фактически искать в Интернете текущие цены, предложения и наличие товаров, превращая простого чат-бота с искусственным интеллектом в действительно полезного помощника по покупкам с соответствующими цитатами.

Поддержка структурой последовательных, параллельных шаблонов и шаблонов передачи обслуживания означает, что вы можете разрабатывать системы агентов, которые точно соответствуют вашим потребностям. Будь то поиск подарков, планирование поездок или любая другая многоэтапная задача, Agent Framework предоставляет все необходимые элементы для ее реализации.В этот праздничный сезон позвольте ИИ-агентам заняться исследованиями, а вы сосредоточитесь на упаковке подарков и приятном времяпрепровождении с семьей!

Исходный код

Концепции, показанные в этом посте, основаны на официальных образцах Agent Framework. Дополнительные примеры можно найти в репозитории Microsoft Agent Framework GitHub.

Счастливых праздников и удачного кодирования! 🎄

Создание агрегатора RSS-каналов на базе искусственного интеллекта

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

Будучи MVP Microsoft и энтузиастом технологий, я постоянно тону в океане потрясающего контента, публикуемого в блогах разработчиков Microsoft. От анонсов .NET до обновлений Visual Studio, от инноваций Azure до глубокого изучения семантического ядра — в экосистеме Microsoft всегда происходит что-то новое и интересное.

Проблема? Успеть за всем этим практически невозможно.

Я хотел быть в курсе последних объявлений и делиться ими со своей сетью, но проверка вручную семи различных RSS-каналов, чтение статей, создание интересных постов в социальных сетях и отслеживание того, чем я уже поделился, само по себе становилось работой на полный рабочий день. Каждое утро я открывал несколько вкладок браузера, просматривал десятки статей, пытался вспомнить, какими из них я уже поделился, а затем тратил драгоценное время на написание сообщений о тех, которые привлекли мое внимание.

Поэтому я сделал то, что сделал бы любой разработчик: я автоматизировал это.

В этом подробном руководстве я расскажу вам, как я создал агрегатор RSS-каналов на базе искусственного интеллекта, который отслеживает несколько RSS-каналов Microsoft DevBlogs на наличие нового контента, использует Azure OpenAI и семантическое ядро для анализа статей и создания интересных публикаций, создает подробную документацию по уценке для каждой проанализированной статьи, отправляет уведомления через Telegram, чтобы я мог просматривать и делиться контентом, отслеживает все, чтобы избежать дублирования сообщений, и автоматически запускается через GitHub Actions.

Давайте углубимся в каждый аспект этого решения.

История этого проекта

Жизнь с информационной перегрузкой

Позвольте мне нарисовать вам картину моего типичного утра до того, как я создал этот инструмент. Я просыпался, брал кофе и открывал ноутбук, чтобы проверить, что нового в экосистеме разработчиков Microsoft. Сначала я зашел на главный сайт DevBlogs, чтобы посмотреть, есть ли какие-нибудь важные объявления. Затем я специально проверял блог .NET, потому что это мой основной технологический стек. После этого я бы перешел к блогу Semantic Kernel, поскольку ИИ становится все более важным. Блог Visual Studio был следующим в списке, поскольку обновления IDE могут существенно повлиять на мой ежедневный рабочий процесс. Затем последовал блог DevOps с новостями, связанными с CI/CD и GitHub, за ним последовал блог All Things Azure, посвященный обновлениям облачной инфраструктуры, и, наконец, блог Azure SQL, посвященный инновациям в области баз данных.

Это семь разных каналов, которые нужно проверить. Каждый из этих блогов публикует несколько статей в неделю, иногда несколько в день в периоды важных объявлений, таких как .NET Conf или Build. Это потенциально десятки статей, которые можно отслеживать, читать и делиться. И вот в чем дело: как человек, который ценит обмен знаниями с сообществом, я не хотел просто читать эти статьи. Я хотел поделиться наиболее ценными из них со своей сетью LinkedIn, помогая другим разработчикам тоже оставаться в курсе.Но создание хорошего поста в LinkedIn требует времени. Вам нужно внимательно прочитать статью, понять ключевые моменты, подумать, почему она важна для вашей аудитории, написать увлекательную зацепку и красиво все отформатировать. Умножьте это на несколько статей в неделю, и вы получите количество часов работы.

Чего я действительно хотел

Проработав с этим несколько месяцев, я сел и задумался о том, как должно выглядеть идеальное решение. Прежде всего, я больше никогда не хотел пропускать важные объявления. Система должна автоматически обнаруживать новые статьи сразу после их публикации. Я также хотел сэкономить время на создании контента, позволив ИИ помогать создавать интересные посты — не для того, чтобы полностью заменить мой голос, а для того, чтобы дать мне надежную отправную точку, которую я мог бы настроить.

Последовательность была еще одним важным фактором. Я хотел регулярно делиться контентом, не забывая делать это вручную каждый день. Аспект отслеживания также имел решающее значение: мне нужен был способ узнать, чем я уже поделился, чтобы не публиковать дубликаты и не раздражать своих подписчиков. Наконец, я хотел оставаться организованным и вести постоянную запись всего, что я обработал, чтобы иметь возможность оглянуться назад и посмотреть, какие темы я затронул.

Решение обретает форму

Решение, которое я предполагал, будет запускаться по расписанию с использованием GitHub Actions, полностью без помощи рук. Он будет автоматически получать все семь каналов, и мне не придется открывать ни одну вкладку браузера. Компонент ИИ фактически прочитает и поймет контент, а затем обобщит его так, чтобы это было полезно для моей аудитории. Вместо того, чтобы писать сообщения с нуля, он создавал готовый контент для социальных сетей, который я мог бы настроить при необходимости. Все будет отправлено в мой Telegram для проверки, чтобы я мог быстро взглянуть на свой телефон и решить, чем поделиться. И, конечно же, он будет постоянно записывать все для дальнейшего использования.

Прежде чем мы начнем строить

Что вам понадобится на вашей машине

Чтобы следовать этому руководству, вам понадобится несколько вещей, установленных на вашей машине разработки. Наиболее важным из них является .NET SDK версии 9.0 или более поздней. Это наша среда выполнения, которая предоставляет все необходимые нам инструменты сборки. Если он у вас не установлен, зайдите на dot.net и загрузите последнюю версию. Установка проста в Windows, macOS или Linux.

Вам также понадобится установить Git для контроля версий. Мы будем размещать наш код на GitHub и использовать GitHub Actions для автоматизации, поэтому крайне важно настроить Git локально. Любая последняя версия будет работать нормально.

Для вашей среды разработки я рекомендую Visual Studio или VS Code. Лично я сейчас использую VS Code для большей части своей работы, потому что он легкий и имеет отличную поддержку C# через расширение C# Dev Kit. Но если вам удобнее работать с полной версией Visual Studio, она тоже отлично работает.

Сервисы и учетные записи, которые вам понадобятсяПомимо локальных инструментов, вам понадобятся учетные записи с несколькими сервисами. Самым важным из них является Azure OpenAI, на котором основан наш анализ ИИ. Это услуга с оплатой по мере использования, но затраты для этого варианта использования минимальны — мы говорим о центах за проанализированную статью. Если у вас нет учетной записи Azure, вы можете подписаться на бесплатную пробную версию, которая включает в себя некоторые кредиты для начала работы.

Для уведомлений мы будем использовать Telegram-бот. Самое замечательное в Telegram то, что API их ботов можно использовать совершенно бесплатно. Вы можете создать столько ботов, сколько захотите, и отправлять неограниченное количество сообщений. Я расскажу вам о процессе установки позже в этом руководстве.

Наконец, вам понадобится учетная запись GitHub для размещения вашего кода и запуска действий GitHub. Уровень бесплатного пользования более чем достаточен для этого проекта. GitHub предоставляет вам 2000 минут выполнения Actions в месяц в частных репозиториях и неограниченное количество минут в публичных репозиториях.

Библиотеки, которые делают это возможным

Наш проект опирается на три основных пакета NuGet, каждый из которых служит определенной цели.

Первый — HtmlAgilityPack, который является золотым стандартом анализа HTML в .NET. Когда мы извлекаем статью из блога, мы получаем полный HTML-код страницы, включая навигационные меню, нижние колонтитулы, рекламные объявления и всевозможные элементы, которые нас не интересуют. HtmlAgilityPack позволяет нам анализировать этот HTML и извлекать только необходимое нам содержимое статьи.

Второй пакет — Microsoft.SemanticKernel, который представляет собой SDK Microsoft для интеграции моделей искусственного интеллекта в приложения. Думайте об этом как о мосте между вашим кодом .NET и большими языковыми моделями, такими как GPT-4. Он берет на себя всю сложность вызовов API, управления токенами и анализа ответов, позволяя вам сосредоточиться на том, что на самом деле вы хотите от ИИ.

Третий пакет — System.ServiceModel.Syndicate, который обеспечивает встроенную поддержку анализа каналов RSS и Atom. RSS может показаться старой технологией, но это по-прежнему лучший способ получать структурированные обновления из блогов и новостных сайтов. Этот пакет превращает необработанные XML-каналы в строго типизированные объекты C#, с которыми легко работать.

Понимание архитектуры

Как части соединяются друг с другом

Прежде чем мы углубимся в код, позвольте мне объяснить, как все компоненты работают вместе. Понимание общей картины сделает детали реализации намного яснее.

На самом высоком уровне у нас есть основной файл Program.cs, который действует как оркестратор. Это точка входа нашего приложения, и она координирует все остальные компоненты. Когда приложение запускается, оно сначала загружает конфигурацию из переменных среды — таких как ключи API и учетные данные Telegram. Затем он выходит и получает RSS-каналы из всех семи источников Microsoft DevBlogs. Обрабатывая эти каналы, он дедуплицирует статьи, чтобы обрабатывать случаи, когда одна и та же статья появляется в нескольких каналах. Он сверяет каждую статью с нашим файлом отслеживания, чтобы узнать, обрабатывали ли мы ее уже. Новые статьи передаются на обработку ИИ-анализатору.Класс ArticleAnalyzer — это место, где творится магия искусственного интеллекта. Этот компонент получает статью и выполняет с ней несколько действий. Сначала он извлекает полное HTML-содержимое из URL-адреса статьи. Затем он извлекает из этого HTML-кода чистый текст, удаляя все ненужные элементы навигации, скрипты и стили. Получив чистый текст, он отправляет его в Azure OpenAI через семантическое ядро с тщательно составленным приглашением. ИИ анализирует статью и возвращает структурированный ответ, который включает в себя краткое изложение, ключевые темы, релевантное объяснение и, самое главное, готовую к использованию публикацию в LinkedIn. Анализатор анализирует этот ответ и возвращает объект ArticleAnaлиз, содержащий всю эту информацию.

Класс MarkdownGenerator берет этот объект ArticleAnaлиз и создает его постоянную запись. Он генерирует красиво отформатированный файл уценки, который включает в себя все метаданные статьи, анализ ИИ и сгенерированный пост. Эти файлы хранятся в каталоге сгенерированных сообщений, что дает вам доступный для поиска архив всего, что вы обработали.

Наконец, интеграция с Telegram отправляет сгенерированный контент сообщения на ваш телефон. Это момент, когда вы, как человек, можете просмотреть работу ИИ и решить, стоит ли ею делиться. Бот отправляет вам сообщение с содержимым публикации, и вы можете либо скопировать его непосредственно в LinkedIn, либо сначала изменить.

Поток данных

Позвольте мне рассказать вам, что происходит, когда в блоге .NET публикуется новая статья. Рабочий процесс начинается, когда GitHub Actions запускает наше приложение по расписанию — скажем, каждые шесть часов. Приложение просыпается и начинает получать все семь RSS-каналов. Каждый канал возвращает XML-документ, содержащий самые последние статьи из этого блога.

Анализируя каждый канал, мы извлекаем отдельные статьи и сохраняем их в списке. Но есть одна сложность: основная лента DevBlogs часто включает в себя статьи, которые также появляются в лентах отдельных категорий. Таким образом, статья о «.NET 10» может появиться как в основной ленте, так и в ленте, посвященной .NET. Мы справляемся с этим, отслеживая URL-адреса в HashSet, который автоматически предотвращает дублирование.

Получив дедуплицированный список статей, мы отфильтровываем его только до последних — обычно статей, опубликованных в последний день или около того. Мы не хотим обрабатывать старые статьи, которые уже обрабатывались в предыдущих запусках. Затем мы сверяем каждую недавнюю статью с нашим файлом отслеживания. Если мы уже обработали и опубликовали статью, мы ее пропускаем.

Для каждой новой статьи мы запускаем конвейер анализа ИИ. Анализатор извлекает полный HTML-код статьи, очищает его и отправляет в GPT-4 с нашей подсказкой. ИИ читает статью и генерирует всесторонний анализ вместе с публикацией в LinkedIn. Мы сохраняем этот анализ в файл уценки для наших записей.После завершения анализа форматируем сообщение и отправляем его в Telegram. Сообщение включает в себя сгенерированный контент публикации с добавленными URL-адресом и хэштегами. На свой телефон я получаю уведомление, просматриваю публикацию и, если она мне нравится, могу скопировать ее и поделиться в LinkedIn всего несколькими нажатиями.

Наконец, мы обновляем наш файл отслеживания, чтобы пометить эту статью как обработанную, чтобы больше не обрабатывать ее при будущих запусках. Если какие-либо файлы были созданы или изменены, GitHub Actions фиксирует эти изменения обратно в репозиторий, сохраняя все в синхронизации.

Настройка проекта с нуля

Создание структуры решения

Начнем строить. Откройте терминал и перейдите туда, где вы хотите создать проект. Мне нравится хранить свои проекты в папке «Разработка», но вы можете разместить их там, где вам удобно.

Сначала мы создадим новый файл решения. В .NET решение — это контейнер, в котором может храниться несколько проектов. Несмотря на то, что на данный момент у нас есть только один проект, начав с решения, при необходимости будет проще добавить больше проектов позже. Запустите команду dotnet new sln -n vs-feed-linkedin для создания решения с именем vs-feed-linkedin.

Далее нам нужно создать проект консольного приложения. Мы поместим это в подкаталог src, чтобы все было организовано. Запустите dotnet new console -n VsFeedLinkedin -o src для создания консольного проекта с именем VsFeedLinkedin в папке src. Затем добавьте этот проект в наше решение с помощью dotnet sln add src/VsFeedLinkedin.csproj.

Теперь перейдите в каталог src с помощью cd src. Здесь мы добавим пакеты NuGet и выполним большую часть разработки.

Добавление необходимых пакетов

После создания нашего проекта нам нужно добавить три пакета NuGet, о которых я упоминал ранее. Запустите каждую из этих команд последовательно:

[[[ТОК_4]]]

После выполнения этих команд файл вашего проекта должен выглядеть примерно так:

<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, что мы создаем исполняемый файл (OutputType — Exe), ориентированный на .NET 9.0 и использующий современные функции C#, такие как неявное использование и ссылочные типы, допускающие значение NULL. В разделе ItemGroup перечислены три зависимости наших пакетов с указанием их точных версий.

Глубокое погружение в RSS-каналы

Что такое RSS?

Прежде чем мы начнем писать код для получения каналов, давайте удостоверимся, что мы понимаем, с чем работаем. RSS означает Really Simple Syndicate и представляет собой стандартизированный формат XML для распространения обновлений контента. Идея проста: вместо того, чтобы требовать от пользователей посещения вашего веб-сайта для проверки наличия нового контента, вы публикуете машиночитаемый файл, в котором перечислены ваши последние материалы. Приложения могут затем периодически опрашивать этот файл для обнаружения новых статей.

RSS существует с конца 1990-х — начала 2000-х годов. Вы можете подумать, что это устаревшая технология, но на самом деле она все еще широко используется – особенно в блогах, новостных сайтах и подкастах. Прелесть RSS в его простоте. Это просто XML с определенной структурой, и любое приложение может его анализировать.

Структура ленты DevBlogsКогда вы получаете RSS-канал из Microsoft DevBlogs, вы получаете обратно XML-документ, имеющий определенную структуру. На верхнем уровне есть элемент rss, содержащий один элемент канала. Канал представляет сам блог и включает метаданные, такие как заголовок, URL-адрес и описание блога.

Внутри канала вы найдете несколько элементов item, каждый из которых представляет отдельную публикацию в блоге. Каждый элемент включает заголовок (заголовок статьи), ссылку (URL-адрес, по которому можно прочитать полную статью), дату публикации (когда статья была опубликована), элемент dc:creator (имя автора), один или несколько элементов категории (теги для статьи) и описание (обычно краткое изложение или отрывок статьи).

Вот упрощенный пример того, как это выглядит:

[[[ТОК_6]]]

Самое замечательное в пакете System.ServiceModel.Syndicate .NET заключается в том, что он анализирует все это за нас. Нам не нужно вручную перемещаться по узлам XML или беспокоиться о разных версиях RSS. Мы просто загружаем фид и получаем обратно строго типизированные объекты.

Семь каналов, которые мы отслеживаем

В своей реализации я отслеживаю семь различных каналов Microsoft DevBlogs. Основной канал DevBlogs по адресу devblogs.microsoft.com/feed дает нам общее представление обо всем, что Microsoft публикует во всех своих блогах разработчиков. Лента, посвященная .NET, по адресу devblogs.microsoft.com/dotnet/feed посвящена выпускам, функциям и передовым практикам .NET. Лента Semantic Kernel на сайте devblogs.microsoft.com/semantic-kernel/feed посвящена оркестровке и интеграции ИИ, что становится все более важным, поскольку ИИ становится центральным элементом современного развития.

Лента Visual Studio по адресу devblogs.microsoft.com/visualstudio/feed позволяет мне быть в курсе улучшений IDE и функций повышения производительности. Канал DevOps по адресу devblogs.microsoft.com/devops/feed охватывает темы Azure DevOps, GitHub и CI/CD. Канал All Things Azure по адресу devblogs.microsoft.com/all-things-azure/feed посвящен облачным сервисам и шаблонам архитектуры. Наконец, канал Azure SQL по адресу devblogs.microsoft.com/azure-sql/feed посвящен инновациям и функциям баз данных.

Вы можете задаться вопросом, почему я проверяю как основной канал, так и каналы отдельных категорий. Основной канал дает мне простор: я вижу статьи из любого блога разработчиков Microsoft, включая те, о которых я, возможно, не знаю. Ленты категорий дают мне глубину — они гарантируют, что я не пропущу ничего важного в моих основных областях интересов, даже если эти статьи будут вытеснены из основного канала новым контентом.

Построение логики получения RSS

Основная функция выборки

Теперь давайте напишем немного кода. Основой нашего приложения является возможность получения и анализа RSS-каналов. Вот функция, которая это обрабатывает:

[[[ТОК_7]]]

Позвольте мне рассказать, что делает этот код. Начнем с создания HttpClient — встроенного класса .NET для выполнения HTTP-запросов. Мы устанавливаем заголовок User-Agent, потому что некоторые серверы блокируют запросы, которые не идентифицируют себя. Рекомендуется устанавливать это значение, даже если серверы этого не требуют.Затем мы делаем запрос GET к URL-адресу канала и получаем ответ в виде строки. Эта строка содержит необработанный XML-файл RSS-канала.

Чтобы проанализировать этот XML, мы создаем StringReader для переноса нашей строки ответа, а затем настраиваем некоторые XmlReaderSettings. Параметр DtdProcessing важен: RSS-каналы иногда включают объявления DTD (определение типа документа), которые необходимо обработать. Параметр MaxCharactersFromEntities — это мера безопасности, которая предотвращает атаки XML-бомбы, ограничивая степень расширения сущности.

Наконец, мы создаем XmlReader с этими настройками и используем SyndictionFeed.Load для анализа XML в строго типизированный объект SyndictionFeed. Это дает нам доступ к метаданным канала и всем его элементам через удобные свойства C# вместо простой навигации по XML.

Получение нескольких каналов с обработкой ошибок

В реальном мире сетевые запросы не выполняются. Серверы выходят из строя, время соединения истекает, а XML может быть искажен. Нам нужно обращаться с такими случаями изящно. Вот как мы получаем все наши каналы, сохраняя при этом устойчивость к сбоям:

[[[ТОК_8]]]

Мы храним здесь две коллекции. Список allArticles будет содержать все найденные нами статьи, а также из какого канала они взяты. Набор хэшей «seenUrls» отслеживает URL-адреса статей, которые мы уже видели, что помогает нам избежать дублирования.

Мы перебираем каждый URL-адрес канала и заключаем операцию выборки в блок try-catch. Если получение определенного канала не удается (возможно, сервер временно не работает), мы регистрируем предупреждение и продолжаем работу со следующим каналом. Таким образом, проблема с одним фидом не мешает нам обрабатывать остальные.

Для каждого успешно полученного канала мы перебираем его элементы. Мы извлекаем URL-адрес статьи из коллекции ссылок элемента. Метод HashSet.Add возвращает false, если URL-адрес уже находится в наборе, что идеально подходит для нашей логики дедупликации. Мы добавляем статью в наш список только в том случае, если она новая.

Мы сохраняем URL-адрес канала рядом с каждой статьей, поскольку эта информация может пригодиться позже — например, нам может потребоваться узнать, из какого конкретного канала пришла статья, в целях отладки или регистрации.

Обработка дубликатов и отслеживание состояния

Проблема дедупликации

Как я упоминал ранее, Microsoft DevBlogs имеет иерархическую структуру каналов, что создает интересную проблему. Когда член команды .NET публикует статью, скажем, об улучшении производительности в .NET 10, эта статья, скорее всего, появится как в основной ленте DevBlogs, так и в ленте, посвященной .NET. Иногда оно может даже появиться в ленте Visual Studio, если оно относится к функциям IDE.

Если бы мы наивно обрабатывали каждую статью из каждого канала, нам пришлось бы анализировать и публиковать одну и ту же статью несколько раз. Это приведет к пустой трате вызовов API к Azure OpenAI, спаму в Telegram дубликатами уведомлений и потенциально раздражению наших подписчиков, если мы опубликуем дубликаты.Решением является дедупликация на основе URL-адресов. Каждая статья имеет уникальный URL-адрес, поэтому мы можем использовать его в качестве идентификатора. Структура данных HashSet идеально подходит для этого, поскольку обеспечивает время поиска O(1) и автоматически предотвращает дублирование. Когда мы пытаемся добавить URL-адрес, который уже есть в наборе, метод Add просто возвращает false, давая нам понять, что эту статью следует пропустить.

Постоянное состояние с Markdown

Дедупликация обрабатывает дубликаты за один прогон, а как насчет нескольких прогонов? Когда наше приложение запускается каждые шесть часов, нам необходимо запомнить, какие статьи мы уже обработали, чтобы больше не обрабатывать их.

Я решил сохранить это состояние в файле уценки под названием Posted-articles.md. Почему уценка? Несколько причин. Во-первых, он удобен для чтения человеком. Я могу открыть файл и сразу увидеть, какими статьями я поделился. Во-вторых, он контролируется версиями. Поскольку этот файл находится в нашем репозитории Git, у меня есть полная история обработки статей. В-третьих, он служит документацией. Любой, кто заглянет в репозиторий, сможет увидеть, что сделало приложение.

Формат этого файла простой. Он имеет заголовок, временную метку, показывающую дату последнего запуска приложения, а затем список статей в формате ссылки уценки:

[[[ТОК_9]]]

Загрузка и анализ файла отслеживания

Чтобы проверить, обрабатывали ли мы уже статью, нам нужно загрузить этот файл и извлечь URL-адреса. Вот функция, которая это делает:

[[[ТОК_10]]]

Эта функция возвращает HashSet, содержащий все URL-адреса, которые мы уже обработали. Начнем с проверки существования файла — при первом запуске его не будет, поэтому мы возвращаем пустой набор.

Для каждой строки файла мы используем регулярное выражение для извлечения 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);
}

Эта функция создает запись в формате уценки с заголовком статьи в виде ссылки, за которой следуют временные метки, показывающие, когда мы ее опубликовали и когда она была первоначально опубликована. Если файл еще не существует, мы сначала создаем его с заголовком.

Механизм анализа ИИ

Понимание семантического ядраТеперь мы переходим к самой интересной части нашего приложения — анализу ИИ. Семантическое ядро — это пакет SDK Microsoft с открытым исходным кодом для интеграции больших языковых моделей в приложения. Это больше, чем просто оболочка вызовов API. Он обеспечивает основу для создания сложных приложений искусственного интеллекта с такими функциями, как плагины, планировщики и память.

В нашем случае мы используем возможности завершения чата семантического ядра. Мы отправим запрос в 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). Они передаются из переменных среды, обеспечивая безопасность наших учетных данных.

Создание идеальной подсказки

Подсказка, которую мы отправляем ИИ, имеет решающее значение. Хорошо продуманная подсказка обеспечивает стабильные и высококачественные результаты. Расплывчатая или плохо структурированная подсказка приводит к непоследовательным и посредственным результатам. Я потратил много времени на повторение этого запроса, чтобы получить результаты, которые меня устраивают:

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]
 """;

Позвольте мне объяснить здесь дизайнерские решения. Начнем с того, что дадим ИИ четкую роль: «Вы — профессиональный аналитик технического контента и создатель контента LinkedIn». Это побуждает модель реагировать соответствующим стилем и голосом.

Мы предоставляем весь контекст, необходимый ИИ: название статьи, автора, URL-адрес, теги из RSS-канала и полное содержание статьи. Чем больше контекста мы дадим, тем лучше будет анализ.

Затем мы точно указываем, что мы хотим получить обратно. Я прошу четыре вещи: краткое изложение, ключевые темы, релевантное объяснение и публикацию в LinkedIn. В частности, для публикации в LinkedIn я даю подробные инструкции о том, что делает публикацию хорошей: она должна иметь зацепку, подчеркивать ценность, включать призыв к действию, правильно использовать смайлы и поддерживать профессиональный тон.

Негативные инструкции не менее важны. Я прямо говорю ИИ НЕ включать хэштеги или URL-адрес в сообщение. Почему? Потому что я добавляю их отдельно, и если бы ИИ включил их, у меня были бы дубликаты. Подобные явные инструкции предотвращают распространенные ошибки.

Наконец, я указываю точный формат вывода. Запрашивая разделы, отмеченные заголовками ##, я упрощаю программный анализ ответа. ИИ очень хорошо выполняет инструкции по форматированию, и такая согласованность делает наш код синтаксического анализа более простым и надежным.

Выполнение анализа

Вот как мы все это собрали:

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 (я объясню это в следующем разделе). Затем мы обрезаем контент, если он слишком длинный. Большие языковые модели имеют ограничения по токенам, а очень длинные статьи могут их превышать. Ограничивая текст до 8000 символов, мы гарантируем, что не выйдем за рамки ограничений, сохраняя при этом существенный контекст.

Мы создаем объект ChatHistory и добавляем наше приглашение в качестве сообщения пользователя. Это абстракция семантического ядра для взаимодействия в чате. Мы отправляем это в службу завершения чата и получаем ответ. Наконец, мы анализируем ответ, чтобы извлечь отдельные разделы.

### Анализ ответа ИИ

ИИ возвращает свой ответ в виде текста, отформатированного в соответствии с запрошенной нами структурой. Нам нужно разобрать это на отдельные поля:

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

Мы разделяем ответ по маркерам ##, что дает нам каждый раздел. Для каждого раздела мы разделяем новую строку, чтобы отделить заголовок от содержимого. Затем мы используем оператор переключения, чтобы назначить содержимое каждого раздела соответствующему свойству.

Мы также сохраняем необработанный, неанализированный ответ. Это полезно для отладки — если при парсинге что-то пойдет не так, мы сможем посмотреть, что на самом деле вернул ИИ.

Извлечение контента из HTML

Почему нам нужно чистить HTML

Когда мы получаем статью из блога, мы получаем полный HTML-код страницы. Это включает в себя гораздо больше, чем просто содержимое статьи: здесь есть навигационные меню, верхние и нижние колонтитулы, боковые панели, виджеты связанных статей, разделы комментариев, сценарии для аналитики и отслеживания, таблицы стилей и всевозможные другие элементы.

Если бы мы отправили все это нашему ИИ, произошло бы несколько плохих вещей. ИИ пришлось бы обрабатывать много ненужного текста, тратя токены и потенциально запутывая анализ. Текст навигации и нижнего колонтитула может быть включен в сводку. Скрипты и CSS будут рассматриваться как контент, что еще больше затруднит анализ.

Нам нужно извлечь только содержание статьи — ту часть, которую на самом деле прочитает читатель.

Использование HtmlAgilityPack

HtmlAgilityPack — это надежная библиотека анализа HTML для .NET. В отличие от XML, HTML часто имеет неправильный формат: теги могут быть неправильно закрыты, атрибуты могут быть заключены в кавычки неправильно. HtmlAgilityPack прекрасно справляется со всем этим, предоставляя нам структуру, подобную DOM, которую мы можем запрашивать и манипулировать ею.

Вот наша функция извлечения:

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

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

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

 var text = doc.DocumentNode.InnerText;

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

Мы загружаем HTML в HtmlDocument, который анализирует его в древовидную структуру. Затем мы используем XPath, чтобы выбрать все узлы, которые хотим удалить. Выражение XPath //script|//style|//nav|//footer|//header выбирает все элементы скрипта (код JavaScript нам не нужен), элементы стиля (CSS нам не нужен), элементы навигации (меню навигации), элементы нижнего колонтитула и элементы заголовка.

После удаления этих узлов мы получаем свойство InnerText, которое извлекает весь текстовый контент, удаляя при этом HTML-теги. Это дает нам простой текст статьи.Наконец, мы очищаем пробелы. HTML часто имеет много дополнительных пробелов для форматирования — несколько пробелов, табуляции, новой строки. Мы используем регулярное выражение для замены любой последовательности пробельных символов одним пробелом, а затем обрезаем результат.

Получение полной статьи

RSS-канал предоставляет нам только краткое изложение, а не полное содержание статьи. Чтобы получить полный текст, нам нужно получить веб-страницу статьи:

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

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

Это просто: мы делаем HTTP-запрос GET к URL-адресу статьи и возвращаем ответ в формате HTML. Мы обертываем его в try-catch, потому что сетевые запросы могут завершиться неудачно, и мы предпочитаем вернуть пустую строку, чем привести к сбою всего приложения.

Создание постоянной документации

Зачем создавать файлы Markdown

Каждый раз, когда мы анализируем статью, мы создаем подробный файл уценки, документирующий этот анализ. Это служит нескольким целям.

Во-первых, он создает архив с возможностью поиска. Со временем вы создадите коллекцию проанализированных статей. Вы можете выполнить поиск по этим файлам, чтобы найти прошлый контент по определенным темам.

Во-вторых, это обеспечивает прозрачность. Вы можете увидеть, что именно сгенерировал ИИ для каждой статьи, включая полный анализ и публикацию в LinkedIn.

В-третьих, это полезно для отладки. Если с публикацией что-то пойдет не так, вы можете посмотреть файл уценки, чтобы понять, что произошло.

Класс генератора Markdown

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(analysis.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 принимает объект ArticleAnaлиз и создает красиво отформатированный документ с уценкой.

Имя файла включает дату и исправленную версию названия. Это позволяет легко сортировать файлы в хронологическом порядке и сразу идентифицировать их.

Обработка небезопасных имен файлов

Заголовки статей могут содержать символы, которые не разрешены в именах файлов, например двоеточия, косую черту, вопросительные знаки и кавычки. Нам нужно продезинфицировать следующее:

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 символами и преобразуем в нижний регистр для обеспечения единообразия.

Настройка уведомлений Telegram

Почему я выбрал Telegram

Для компонента уведомлений я рассматривал несколько вариантов — электронная почта, SMS, Slack, Discord и Telegram. В конечном итоге я выбрал Telegram по нескольким причинам.

API полностью бесплатен и не имеет ограничений по скорости для разумного использования. Многие службы уведомлений имеют ограничения на количество сообщений, которые вы можете отправить бесплатно, но Telegram не ограничивает сообщения ботов отдельными пользователями.

API бота невероятно прост. Это просто HTTP-запросы с полезной нагрузкой JSON. Никаких сложных потоков аутентификации и веб-перехватчиков, необходимых для базовой функциональности.Telegram работает везде – на моем телефоне, на моем рабочем столе, в моем веб-браузере. Я могу получать уведомления, где бы я ни находился, и немедленно отвечать на них.

Сообщения поддерживают расширенное форматирование. Я могу использовать жирный текст, курсив и даже блоки кода, чтобы сделать мои уведомления более читабельными.

Создание бота в Telegram

Настроить бота Telegram на удивление просто. Откройте Telegram и найдите @BotFather — это официальный бот Telegram для создания ботов и управления ими. Начните разговор с BotFather и отправьте команду /newbot. BotFather запросит у вас имя для вашего бота (это отображаемое имя) и имя пользователя (оно должно быть уникальным и заканчиваться на «bot»). Как только вы их предоставите, BotFather создаст вашего бота и предоставит вам токен API. Этот токен подобен паролю — храните его в секрете и не передавайте в публичные репозитории.

Чтобы найти свой идентификатор чата, чтобы бот знал, куда отправлять сообщения, начните разговор с новым ботом, выполнив поиск и нажав «Старт». Затем откройте URL-адрес https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates в браузере или с помощью Curl. Найдите в ответе объект chat — поле 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}");
 }
}

API Telegram Bot основан на REST. Мы делаем POST-запрос к конечной точке sendMessage с телом JSON, содержащим идентификатор чата (куда отправлять), текст сообщения (что отправлять) и, при необходимости, режим анализа (для форматирования).

Установка parse_mode на «HTML» позволяет нам использовать в наших сообщениях базовые HTML-теги – такие, как <b>bold</b> и <i>italic</i>. Это может сделать уведомления более читабельными, хотя в нашем текущем случае мы отправляем простой текст.

Если запрос завершается неудачей, мы выдаем исключение с подробной информацией о том, что пошло не так. Это помогает при отладке, если что-то не работает.

Настройка приложения

Переменные среды

Нашему приложению требуется несколько частей конфиденциальной информации — ключи API, токены ботов и URL-адреса конечных точек. Мы никогда не должны жестко запрограммировать их или передать их под контроль версий. Вместо этого мы используем переменные среды, которые можно безопасно установить в каждой среде, в которой работает приложение.

Для Telegram нам нужен TELEGRAM_BOT_TOKEN (токен, который вам дал BotFather) и TELEGRAM_CHAT_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. Это позволяет приложению работать в ухудшенном режиме, если Azure OpenAI не настроен — оно по-прежнему будет получать каналы и отслеживать статьи, только без анализа ИИ.### Грациозная деградация

Эта концепция изящной деградации важна. Мы не хотим, чтобы приложение аварийно завершало работу только потому, что не настроена одна дополнительная функция:

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 включен, создаем анализатор и генератор уценки. Если нет, мы оставляем их нулевыми и пропускаем шаги, связанные с ИИ, во время обработки. Приложение по-прежнему приносит пользу, получая каналы и отправляя базовые уведомления, даже без усовершенствования искусственного интеллекта.

Автоматизация с помощью действий 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 * * * означает «в 0-ю минуту каждого 6-го часа». Таким образом, рабочий процесс выполняется в полночь, 6 утра, полдень и 18:00 по всемирному координированному времени. Триггер workflow_dispatch позволяет запускать вручную из пользовательского интерфейса GitHub, что полезно для тестирования.

Задание выполняется на Ubuntu-latest, виртуальной машине Linux. Мы проверяем наш репозиторий, настраиваем .NET 9, восстанавливаем пакеты NuGet и собираем проект.

На этапе «Запуск приложения» происходит волшебство. Мы передаем наши секреты как переменные среды, используя синтаксис ${{ secrets.SECRET_NAME }}. Эти секреты надежно хранятся в GitHub и никогда не раскрываются в журналах.

Наконец, мы фиксируем все изменения обратно в репозиторий. Мы настраиваем Git с идентификатором бота, проверяем, есть ли какие-либо изменения в нашем файле отслеживания или каталоге сгенерированных сообщений, и если да, создаем коммит и отправляем его.

Настройка секретов

Чтобы добавить секреты в свой репозиторий GitHub, перейдите в «Настройки» вашего репозитория, затем «Секреты и переменные», затем «Действия». Нажмите «Новый секрет репозитория» и добавьте каждую переменную среды. Имена должны точно соответствовать тем, на которые мы ссылаемся в файле рабочего процесса.

Подведение итогов

Что мы создали

Оглядываясь назад на все, что мы рассмотрели, мы создали комплексный агрегатор RSS-каналов на базе искусственного интеллекта, который автоматизирует то, что раньше было утомительным ручным процессом. Приложение автоматически отслеживает семь каналов Microsoft DevBlogs, отслеживая каждую новую статью сразу после ее публикации. Он справляется со сложностями дедупликации, распознавая, когда одна и та же статья появляется в нескольких каналах.Анализ ИИ на основе семантического ядра и Azure OpenAI считывает и понимает содержание статей, создает резюме, определяет ключевые темы и объясняет актуальность — и все это автоматически. Самое главное, он создает интересные публикации в LinkedIn, которыми я могу поделиться с минимальным редактированием.

Интеграция Telegram означает, что я получаю уведомления на свой телефон, когда появляется новый контент для просмотра. Я могу взглянуть на сообщение, решить, хочу ли я им поделиться, и действовать немедленно.

А поскольку он запускается в GitHub Actions по расписанию, мне не нужно ничего не забывать делать. Система работает в фоновом режиме, и я подключаюсь только тогда, когда есть что-то, чем стоит поделиться.

Технологии, которые сделали это возможным

Этот проект объединил несколько технологий, каждая из которых сыграла решающую роль. .NET 9 обеспечил прочную основу благодаря своим современным языковым функциям и превосходной производительности. Семантическое ядро упростило интеграцию ИИ, справившись со всей сложностью вызовов API и управлением ответами. Azure OpenAI предоставил интеллект — возможность действительно понимать и анализировать технический контент. HtmlAgilityPack решил сложную проблему извлечения чистого текста с веб-страниц. System.ServiceModel.Syndicate упростил анализ RSS. API Telegram Bot предоставил нам бесплатные и надежные уведомления. А GitHub Actions связал все это вместе с автоматическим запланированным выполнением.

Думая о затратах

У вас может возникнуть один вопрос: сколько стоит его эксплуатация? Ответ: совсем немного.

Telegram полностью бесплатен — за отправку сообщений через вашего бота плата не взимается.

GitHub Actions бесплатен для общедоступных репозиториев. Для частных репозиториев вы получаете 2000 минут в месяц на бесплатном уровне, чего более чем достаточно для нашего варианта использования.

Azure OpenAI — единственный платный компонент, а затраты минимальны. Используя GPT-4o, анализ типичной статьи в блоге стоит от одного до трех центов. Даже если вы обрабатываете десятки статей в месяц, затраты на ИИ составляют менее доллара.

Где вы могли бы взять это дальше

Хотя это решение отлично подходит для моих нужд, существует множество способов его расширения. Вы можете добавить поддержку нескольких социальных платформ — например, публиковать сообщения в Twitter/X, Mastodon или Bluesky в дополнение к LinkedIn. Вы можете реализовать анализ настроений, чтобы отслеживать тон статей с течением времени и выявлять тенденции. Вы можете разрешить разные шаблоны подсказок для разных каналов, создавая разные стили сообщений для разных тем. Вы можете создать веб-панель для просмотра и управления публикациями вместо использования Telegram. Вы можете отслеживать показатели вовлеченности публикуемого контента, чтобы увидеть, какие темы больше всего резонируют с вашей аудиторией.

Заключительные мыслиЧто мне больше всего нравится в этом проекте, так это то, что он воплощает философию, в которую я твердо верю: автоматизация должна выполнять утомительные части, оставляя творческую часть и принятие решений людям. Система выполняет всю тяжелую работу — выборку, анализ, анализ, генерацию — но я все равно проверяю все, прежде чем поделиться. Публикации, созданные с помощью ИИ, — это отправная точка, которую я могу настроить и персонализировать.

Объединив возможности .NET, семантического ядра и Azure OpenAI, мы создали инструмент, который каждую неделю экономит часы ручной работы, сохраняя при этом качество и согласованность. Это своего рода практическая автоматизация, которая действительно меняет повседневную жизнь.

Если вы создадите что-то подобное или у вас есть идеи по улучшению, я буду рад об этом услышать. Не стесняйтесь обращаться к LinkedIn!

Приятного кодирования и счастливого Рождества! 🎄

Создание многоагентных систем искусственного интеллекта с помощью Microsoft Agent Framework

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

Введение

Мы вступили в эпоху мультиагентных систем искусственного интеллекта. Вместо единого монолитного искусственного интеллекта, управляющего всем, отрасль движется к специализированным агентам, которые сотрудничают для решения сложных проблем — во многом подобно хорошо организованной команде экспертов. Один агент исследует, другой анализирует, третий пишет, а координатор держит всех в курсе.

Если вы работали с большими языковыми моделями, вы, вероятно, достигли потолка того, что может сделать одно приглашение. Контекстные окна заполняются, инструкции путаются, качество ухудшается. Мультиагентные архитектуры решают эту проблему путем разложения сложных задач на конкретные обязанности, где каждый агент является экспертом в одном деле.

Microsoft Agent Framework, являющаяся частью более широкой экосистемы семантического ядра, предоставляет разработчикам .NET первоклассный набор инструментов для создания именно таких систем. В этом посте мы пройдем путь от нуля до полностью работающего многоагентного конвейера, охватывая основные концепции, шаблоны оркестрации и практический код, необходимый для начала работы.

Что такое платформа агентов Microsoft?

Agent Framework — это ответ Microsoft на создание, оркестрацию и развертывание агентов искусственного интеллекта и многоагентных систем в .NET. Он находится рядом и глубоко интегрируется с семантическим ядром, которое с 2023 года является SDK Microsoft с открытым исходным кодом для оркестрации ИИ.

Подумайте об этом так: Семантическое ядро предоставляет вам примитивы (ядра, плагины, память, планировщики), а Agent Framework предоставляет вам абстракции более высокого уровня, специально предназначенные для взаимодействия и координации между агентами.

Платформа поддерживает несколько поставщиков моделей, включая Azure OpenAI, OpenAI и модели, размещенные в Azure AI Foundry. Его дизайн не зависит от модели, но он глубоко интегрирован с экосистемой Azure, что делает его особенно привлекательным для корпоративных сценариев.

Ключевые возможности включают в себя:

Несколько типов агентов: ChatCompletionAgent, OpenAIAssistantAgent и AzureAIAgent для разных серверов.
Шаблоны оркестровки: последовательные, одновременные, перераспределяющие и групповые рабочие процессы чата.
Экосистема плагинов: расширяйте возможности агентов с помощью встроенных функций C#, спецификаций OpenAPI и инструментов протокола контекста модели (MCP).
Управление беседами: встроенные функции управления потоками, историей и стратегиями завершения.
Наблюдаемость: интеграция с OpenTelemetry для отслеживания взаимодействия агентов.

Ключевые понятия

Прежде чем писать какой-либо код, давайте определимся со словарем. Agent Framework вращается вокруг нескольких основных абстракций.

Агенты

Агент — это объект, поддерживаемый моделью искусственного интеллекта, настроенный с использованием определенных инструкций (системного приглашения), имени и, при необходимости, набора плагинов или инструментов. Каждый агент — специалист — вы определяете, что он знает, что он может делать и как ему следует себя вести.

ChatCompletionAgentСамый простой тип агента. Он оборачивает конечную точку завершения чата (Azure OpenAI, OpenAI и т. д.) и поддерживает разговор. Между вызовами он не имеет состояния — вы предоставляете историю, и он отвечает. Это делает его легким и понятным.

[[[ТОК_3]]]

OpenAIAssistantAgent

Этот тип агента использует API-интерфейс OpenAI Assistants, который обеспечивает состояние диалога на стороне сервера, обработку файлов и интерпретацию кода. Он более тяжелый, но дает вам постоянные потоки и встроенные инструменты, такие как интерпретатор кода и поиск файлов.

[[[ТОК_4]]]

###ГрупповойЧат Агента

Это оркестратор. AgentGroupChat управляет многоэтапными разговорами между несколькими агентами, контролируя, кто говорит следующим, когда разговор заканчивается и как передается история. Именно здесь происходит волшебство многоагентного сотрудничества.

Шаблоны оркестровки

Платформа поддерживает четыре основных шаблона оркестровки, каждый из которых подходит для решения различных задач.

Последовательный

Агенты выполняются один за другим в определенном порядке. Выходные данные агента A передаются агенту B, чьи выходные данные передаются агенту C. Это идеально подходит для конвейеров: черновик → просмотр → редактирование → публикация.

[[[ТОК_6]]]

Параллельно

Несколько агентов одновременно работают с одним и тем же входом. Вы распределяете работу, а затем суммируете результаты. Отлично подходит для получения разных точек зрения — например, когда три рецензента рассматривают один и тот же запрос на включение.

Передача

Агент решает передать управление другому агенту в зависимости от контекста разговора. Это имитирует работу команды обслуживания клиентов: агент первой линии обрабатывает базовые запросы и при необходимости передает их специалистам.

Групповой чат

В открытом разговоре участвуют несколько агентов, по очереди, в зависимости от стратегии выбора. Класс AgentGroupChat реализует этот шаблон с настраиваемой логикой очередности и завершения.

Создайте своего первого агента

Давайте перейдем к практике. Вот как шаг за шагом создать своего первого агента.

Предварительные условия

Вам понадобится:

.NET 9 SDK — Ресурс Azure OpenAI с развернутой моделью (например, gpt-4o).
Visual Studio или VS Code

Настройка проекта

Создайте новое консольное приложение и установите необходимые пакеты:

[[[ТОК_9]]]

Создание простого агента

Сначала настройте ядро с вашей конфигурацией Azure OpenAI:

[[[ТОК_10]]]

Теперь создайте агента и вызовите его:

[[[ТОК_11]]]

Вот и все. У вас есть работающий агент. Но настоящая сила приходит, когда агенты работают вместе.

Многоагентная оркестровка с помощью AgentGroupChat

Давайте создадим что-то более интересное — групповой чат, в котором сотрудничают несколько агентов. Класс AgentGroupChat управляет ходом разговора, включая то, кто говорит следующим и когда остановиться.

Определение агентов

Мы создадим трех агентов: писателя, рецензента и редактора.

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

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

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

Настройка группового чата

Для AgentGroupChat необходимы две ключевые конфигурации: стратегия выбора (кто говорит следующим) и стратегия завершения (когда остановиться).

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

Пользовательская стратегия завершенияСтратегия завершения определяет, когда разговор заканчивается. Вот специальный вариант, который ищет ключевое слово «COMPLETE»:

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

 return Task.FromResult(isComplete);
 }
}

Ведение разговора

Начните разговор с пользовательского сообщения и позвольте агентам сотрудничать:

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

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

Поток будет выглядеть примерно так:

Автор создает черновик
Рецензент оставляет отзыв.
Автор вносит правки на основе отзывов.
Рецензент говорит: «УТВЕРЖДЕНО».
Редактор доводит до ума и говорит: «ЗАВЕРШЕНО».
Разговор завершается.

Это движение вперед и назад продолжается автоматически до тех пор, пока не будет выполнено условие завершения или не будет достигнуто MaximumIterations.

Плагины и инструменты

Агенты становятся по-настоящему мощными, когда они могут взаимодействовать с внешними системами. Agent Framework поддерживает три основных механизма расширения.

Собственные функции (плагины ядра)

Вы можете предоставить агентам доступ к методам C# в качестве инструментов. Агент вызовет эти функции, когда определит, что они необходимы:

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

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

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

 double avgWordsPerSentence = (double)words / sentences;

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

Зарегистрируйте плагин в ядре перед созданием агента:

kernel.Plugins.AddFromType<ContentToolsPlugin>();

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

Протокол контекста модели (MCP)

MCP — это открытый стандарт для подключения моделей ИИ к внешним инструментам и источникам данных. Платформа агентов поддерживает MCP, то есть ваши агенты могут использовать инструменты, предоставляемые любым MCP-совместимым сервером. Это открывает двери для файловых систем, баз данных, API и многого другого — и все это через стандартизированный интерфейс.

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

Это особенно интересно, поскольку означает, что ваши агенты не ограничиваются тем, что вы создаете — они могут подключиться к экосистеме инструментов MCP, которые другие разрабатывают и которыми делятся.

Пример из реальной жизни: конвейер проверки контента

Давайте объединим все это с практическим сценарием. Представьте, что вы создаете внутренний инструмент, который автоматизирует проверку контента для группы документации. Трубопровод состоит из четырех этапов:

Исследователь — собирает соответствующую техническую информацию.
Писатель — создает черновик на основе исследований.
Рецензент — проверяет точность и полноту.
Издатель — форматирует и подготавливает окончательный результат.

Вот сокращенная реализация:

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

НаблюдаемостьПлатформа агента интегрируется с OpenTelemetry, что означает, что вы можете отслеживать каждое взаимодействие агента, вызов инструмента и использование токена. Это важно для отладки многоагентных рабочих процессов, где не всегда очевидно, какой агент вызвал проблему.

Настройте базовую телеметрию, добавив пакеты телеметрии семантического ядра и настроив предпочитаемый экспортер (Application Insights, Jaeger и т. д.):

builder.Services.AddOpenTelemetry()
 .WithTracing(tracing =>
 {
 tracing.AddSource("Microsoft.SemanticKernel*");
 tracing.AddOtlpExporter();
 });

Управление затратами

Мультиагентные системы увеличивают ваши затраты на API: каждый поворот агента — это вызов API, а групповые чаты могут генерировать множество поворотов. Некоторые стратегии, позволяющие держать расходы под контролем:

Используйте более дешевые модели для более простых агентов: не каждому агенту требуется GPT-4o. Рецензент может прекрасно работать с моделью меньшего размера, в то время как мощный нападающий нужен только автору.
Ограничить историю: используйте ReducedHistoryCount в настройках выполнения, чтобы ограничить объем контекста разговора, который получает каждый агент.
Установите строгие ограничения на итерацию: предотвращайте неконтролируемые разговоры с разумными значениями MaximumIterations.
Кэшировать, когда это возможно: если агент неоднократно выполняет один и тот же поиск, кэшируйте результаты в плагине.

Дизайн агента

Соблюдайте четкость инструкций: у каждого агента должна быть единая и четкая ответственность. Широкие инструкции приводят к посредственной производительности во всех задачах. – Четко указывайте формат вывода. Сообщите агентам, как именно структурировать свои ответы. Это делает последующий синтаксический анализ надежным. – Используйте ключевые слова завершения. Определите четкие сигналы (например, «УТВЕРЖДЕНО» или «ЗАВЕРШЕНО»), которые агенты будут использовать, чтобы указать, что они закончили. Это делает стратегии завершения простыми и предсказуемыми.

Заключение

Многоагентные системы искусственного интеллекта представляют собой фундаментальный сдвиг в том, как мы создаем интеллектуальные приложения. Вместо того, чтобы бороться с единым запросом, чтобы справиться со всем, мы можем разложить проблемы на специализированные роли и позволить агентам сотрудничать.

Microsoft Agent Framework делает это практичным для разработчиков .NET. Абстракции чистые — агенты, групповые чаты, стратегии выбора и прекращения — и они складываются естественным образом. В сочетании с экосистемой подключаемых модулей Semantic Kernel и хостингом моделей Azure у вас есть полный стек для создания многоагентных систем производственного уровня.

Платформа все еще развивается (многие пакеты находятся в предварительной версии), но основные шаблоны надежны и направление ясно. Если вы создаете приложения на основе искусственного интеллекта в .NET, сейчас самое время начать экспериментировать с многоагентными архитектурами.

Начните с малого — создайте двух агентов, которые совместно выполняют одну простую задачу. Как только вы увидите улучшение качества по сравнению с подходами с одним агентом, вам захочется разложить все на команды агентов.

Приятного кодирования!

Рендеринг необработанного HTML в Blazor с помощью MarkupString

Sat, 22 Nov 2025 00:00:00 +0000

На днях я создавал компонент, который должен был отображать HTML-код, полученный из CMS. У меня была строка HTML в переменной, и я просто поместил ее в шаблон, например @myHtml. И, конечно же, Blazor избегал всего и отображал настоящие теги в виде текста на странице. Не то, что я хотел.

Проблема

По умолчанию Blazor кодирует любую строку, отображаемую в шаблоне. Итак, если у вас есть:

[[[ТОК_1]]]

И вы делаете это:

[[[ТОК_2]]]

На странице вы увидите буквальный текст <strong>Hello</strong> <em>world</em> вместо Hello world. Blazor делает это специально, чтобы предотвратить XSS-атаки, что является правильным поведением по умолчанию.

Решение: MarkupString

Если вам действительно нужно отобразить необработанный HTML, вы заключаете строку в MarkupString:

<div>@((MarkupString)content)</div>

И все! Теперь Blazor будет отображать HTML как фактическую разметку. Вы также можете присвоить его переменной:

[[[ТОК_6]]]

[[[ТОК_7]]]

Реальный пример

Я извлекал контент блога из API, и мне нужно было отобразить его в компоненте предварительного просмотра. В контенте были все виды HTML — заголовки, блоки кода, ссылки, изображения. Вот примерно как это выглядело:

[[[ТОК_8]]]

Работает отлично. HTML из API отображается как фактическая разметка.

Будьте осторожны с ненадежным контентом

Это важно: MarkupString не очищает HTML. Он отображает все, что вы ему дадите, включая теги <script>. Поэтому, если контент получен пользователем или из ненадежного источника, вам необходимо сначала его очистить.

В Blazor нет встроенного средства очистки HTML, но вы можете использовать такую библиотеку, как HtmlSanitizer:

[[[ТОК_12]]]

<div>@SafeHtml(untrustedContent)</div>

Это удаляет опасные элементы, такие как обработчики <script>, onclick и другие элементы, которые вы не хотите отображать из пользовательского контента.

Когда его использовать

Я использую MarkupString для:

Содержимое CMS или уценка, преобразованные в HTML на стороне сервера.
Вывод расширенного текстового редактора
Предварительный просмотр шаблонов электронной почты
Любой готовый HTML из надежных источников.

Все, что исходит от пользователя, всегда сначала очищайте. Лучше перестраховаться, чем потом сожалеть.

Надеюсь, вам понравился пост! Не стесняйтесь обращаться ко мне в любой социальной сети по адресу @emimontesdeoca.

Ресурсы

Что нового в EF Core 9: функции, которые вам нужно знать

Tue, 18 Nov 2025 00:00:00 +0000

Entity Framework Core 9 был выпущен вместе с .NET 9 в ноябре 2024 года, и, потратив немало времени на работу с ним в нескольких проектах, я могу сказать, что это один из самых значимых выпусков за последнее время. Не потому, что он заново изобретает велосипед, а потому, что он оттачивает те области, в которых EF Core исторически вызывал больше всего проблем — преобразование запросов, производительность и работу с современными шаблонами данных.

В этом посте я расскажу о функциях, которые оказали наибольшее влияние на мою повседневную работу. Если вы все еще используете EF Core 8 (или даже 7), это должно дать вам четкое представление о том, что вас ждет по другую сторону обновления.

EF Core 9 в экосистеме .NET 9

EF Core 9 ориентирован на .NET 8 и .NET 9, а это значит, что вам не обязательно обновлять все приложение до .NET 9, чтобы воспользоваться большинством этих функций. Тем не менее, некоторые улучшения AOT и производительности тесно связаны с изменениями среды выполнения .NET 9, поэтому вы получите максимальную отдачу, пройдя весь путь.

Выпуск следует за нечетной/четной периодичностью, установленной Microsoft: выпуски с нечетными номерами (например, .NET 9) имеют стандартную поддержку (STS) с 18 месяцами поддержки, а четные выпуски (например, .NET 8) — долгосрочную поддержку (LTS). Имейте это в виду при планировании графика обновления.

Улучшения перевода LINQ

Именно здесь большинство разработчиков сразу почувствуют разницу. EF Core 9 добился значительных успехов в переводе выражений LINQ в SQL, что действительно имеет смысл.

Лучшие переводы GroupBy

Если вы когда-либо писали запрос GroupBy в EF Core и в итоге получали предупреждения при оценке на стороне клиента или странный SQL, вы знаете, что это за боль. EF Core 9 обрабатывает гораздо более широкий набор сценариев GroupBy непосредственно в SQL.

[[[ТОК_2]]]

В предыдущих версиях запросы, включающие агрегирование свойств навигации внутри GroupBy иногда возвращались к оценке клиента. EF Core 9 аккуратно преобразует это в один SQL-запрос с помощью GROUP BY, SUM, AVG и COUNT.

Сложные проекции и подзапросы

Вложенные подзапросы и сложные проекции также получили серьезное обновление. Рассмотрим что-то вроде этого:

[[[ТОК_8]]]

EF Core 9 теперь может преобразовать все это выражение в SQL, не запуская оценку на стороне клиента. Сгенерированный запрос использует коррелированные подзапросы и боковые соединения, где это необходимо, а план SQL значительно более эффективен, чем тот, который создавался в более ранних версиях.

Параметризованные примитивные коллекции

Одним из выдающихся улучшений LINQ является возможность передавать коллекции примитивных значений непосредственно в запросы:

[[[ТОК_9]]]

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

При этом генерируется один оператор UPDATE с JOIN для таблицы категорий — нет необходимости загружать сущности в память, нет накладных расходов на отслеживание изменений.

Условное массовое удаление с подзапросами

Массовые удаления с помощью фильтров подзапросов теперь полностью поддерживаются:

await context.AuditLogs
 .Where(log => log.CreatedAt < DateTime.UtcNow.AddYears(-2))
 .Where(log => !context.ProtectedRecords
 .Any(pr => pr.AuditLogId == log.Id))
 .ExecuteDeleteAsync();

Это преобразуется в DELETE с подзапросом NOT EXISTS — именно то, что вы написали бы вручную. Никаких сущностей не загружено, никаких обращений туда и обратно.

Улучшения столбца JSON

Столбцы JSON были одной из самых интересных функций в последних выпусках EF Core, а EF Core 9 развивает их дальше.

Запрос внутри JSON

Теперь вы можете фильтровать и проецировать данные из столбцов JSON с улучшенной поддержкой перевода:

public class Order
{
 public int Id { get; set; }
 public string CustomerName { get; set; }
 public ShippingAddress Address { get; set; } // Stored as JSON
 public List<OrderNote> Notes { get; set; } // Stored as JSON
}

public class ShippingAddress
{
 public string Street { get; set; }
 public string City { get; set; }
 public string State { get; set; }
 public string ZipCode { get; set; }
 public string Country { get; set; }
}

public class OrderNote
{
 public DateTime CreatedAt { get; set; }
 public string Text { get; set; }
 public string Author { get; set; }
}

Конфигурация в вашем DbContext:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
 modelBuilder.Entity<Order>(builder =>
 {
 builder.OwnsOne(o => o.Address, ab =>
 {
 ab.ToJson();
 });

 builder.OwnsMany(o => o.Notes, nb =>
 {
 nb.ToJson();
 });
 });
}

Теперь вы можете делать запросы непосредственно в JSON:

var newYorkOrders = await context.Orders
 .Where(o => o.Address.State == "NY")
 .OrderByDescending(o => o.Notes.Count)
 .Select(o => new
 {
 o.CustomerName,
 o.Address.City,
 LatestNote = o.Notes
 .OrderByDescending(n => n.CreatedAt)
 .Select(n => n.Text)
 .FirstOrDefault()
 })
 .ToListAsync();

EF Core 9 генерирует правильные вызовы JSON_VALUE и JSON_QUERY для SQL Server (или эквивалента у других поставщиков), а перевод охватывает гораздо более широкий диапазон операций LINQ с элементами JSON, чем раньше.

Обновление свойств JSON

Одним из проблем в EF Core 8 было то, что обновление одного свойства внутри столбца JSON приводило к переписыванию всего документа JSON. EF Core 9 улучшает эту ситуацию за счет более детального отслеживания изменений для типов, отображаемых в формате JSON, и по возможности генерирует более целевые обновления.

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

У поддерживаемых поставщиков это может привести к более целенаправленной модификации JSON, а не к переписыванию всего большого двоичного объекта.

Сложные типы — объекты-значения без идентификатора

Сложные типы — это одна из функций, которую так ждали специалисты по предметно-ориентированному проектированию. В отличие от принадлежащих типов, сложные типы не имеют идентичности — это чистые объекты значений.

[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 — без необходимости использования отдельной таблицы или какого-либо ключа.

Ключевое отличие от принадлежащих типов: сложные типы сравниваются по значению, а не по ссылке. Два экземпляра Money с одинаковыми Amount и Currency считаются равными, независимо от того, какой сущности они принадлежат.

var expensiveProjects = await context.Projects
 .Where(p => p.Budget.Amount > 100_000m && p.Budget.Currency == "USD")
 .OrderByDescending(p => p.Budget.Amount)
 .ToListAsync();

Это напрямую приводит к фильтрации по сглаженным столбцам — чистой, эффективной и именно такой, как вы ожидаете.

Поддержка HierarchyId для SQL Server

Если вы когда-либо работали с иерархическими данными в SQL Server — организационными диаграммами, деревьями категорий, файловыми системами — вы знаете, что HierarchyId — это встроенный тип для этого. EF Core 9 обеспечивает первоклассную поддержку.

public class Employee
{
 public int Id { get; set; }
 public string Name { get; set; }
 public string Title { get; set; }
 public HierarchyId PathFromCeo { get; set; }
}

Теперь вы можете напрямую запрашивать иерархические отношения:

var managerId = HierarchyId.Parse("/1/3/");

// All direct and indirect reports
var allReports = await context.Employees
 .Where(e => e.PathFromCeo.IsDescendantOf(managerId))
 .Where(e => e.PathFromCeo != managerId) // exclude the manager
 .OrderBy(e => e.PathFromCeo)
 .ToListAsync();

// Direct reports only (one level down)
var directReports = await context.Employees
 .Where(e => e.PathFromCeo.GetAncestor(1) == managerId)
 .ToListAsync();

// Get an employee's depth in the hierarchy
var employeesWithDepth = await context.Employees
 .Select(e => new
 {
 e.Name,
 e.Title,
 Level = e.PathFromCeo.GetLevel()
 })
 .OrderBy(e => e.Level)
 .ToListAsync();
```Все это преобразуется в собственные методы SQL Server `HierarchyId`. Если вы реализуете древовидные структуры с самоссылающимися внешними ключами и рекурсивными CTE, это гораздо более чистый подход.

## Скомпилированные модели и поддержка AOT

Разработчики, заботящиеся о производительности, оценят постоянные инвестиции в скомпилированные модели и поддержку предварительной компиляции (AOT).

### Скомпилированные модели

Скомпилированные модели предварительно создают метаданные модели, которые 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

Полная встроенная поддержка AOT для EF Core все еще находится в стадии разработки, но EF Core 9 добился значительных успехов. Многие пути кода с большим количеством отражений были реорганизованы для обеспечения возможности обрезки, а скомпилированные модели являются ключевой частью истории AOT. Если вы ориентируетесь на такие сценарии, как функции Azure или микросервисы, где важен холодный запуск, эти улучшения имеют непосредственное значение.

Обновления поставщика Cosmo 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

Больше операций LINQ теперь переводится на диалект SQL Cosmos DB, включая улучшенную поддержку Contains, Any, операций с вложенными массивами и математических функций. Запросы, которые раньше возвращались к оценке клиента, теперь обрабатываются на стороне сервера.

Поддержка векторного поиска

В EF Core 9 на ранней стадии реализована поддержка поиска по сходству векторов с помощью Cosmos DB, что полезно, если вы создаете приложения, которые интегрируются с внедрениями или поиском на основе искусственного интеллекта:

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

В результате создается двоичный файл, который можно запустить в конвейере CI/CD без необходимости установки .NET SDK на целевой объект развертывания.

Тесты производительностиВот некоторые грубые тесты из моего собственного тестирования. Они взяты из проекта, насчитывающего примерно 200 сущностей, работающего на SQL Server 2022, измеренного с помощью BenchmarkDotNet. Ваши цифры будут различаться, но относительные улучшения должны быть одинаковыми.

Сценарий	EF Core 8	EF Core 9	Улучшение
Сборка модели (холодный старт)	1850 мс	320 мс	~5,8 раз быстрее (скомпилировано)
Простой запрос (один объект по ПК)	0,42 мс	0,38 мс	~10% быстрее
Сложный запрос (объединение + агрегация)	3,1 мс	2,4 мс	~ на 23% быстрее
Массовое обновление (10 тыс. строк)	145 мс	118 мс	~ на 19% быстрее
Запрос столбца JSON	2,8 мс	1,9 мс	~32% быстрее
СохранитьИзменения (100 объектов)	48 мс	41 мс	~ на 15 % быстрее

Улучшение скомпилированной модели является наиболее значительным, но устойчивые улучшения по всем направлениям суммируются, особенно в сценариях с высокой пропускной способностью, когда вы выполняете тысячи запросов в секунду.

Обновление с EF Core 8

Если вы используете EF Core 8, путь обновления относительно гладкий. Вот контрольный список:

1. Обновите свои пакеты:

<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="9.0.0" />

2. Проверьте наличие критических изменений. Список EF Core 9 относительно короткий по сравнению с некоторыми предыдущими выпусками. Наиболее примечательные из них:

Некоторые ранее устаревшие API были удалены.
Изменения в том, как преобразуются определенные запросы GroupBy (теперь они выполняются на стороне сервера, что меняет поведение, если вы полагались на оценку клиента).
Незначительные изменения в выходных данных миграции.

3. Повторно сгенерируйте скомпилированные модели, если вы их используете. Формат изменился, поэтому старые скомпилированные модели не будут работать с EF Core 9.

4. Запустите набор тестов. Обратите особое внимание на запросы, которые ранее оценивались на клиенте — теперь они могут оцениваться на сервере, что обычно лучше, но может выявить различия в данных.

5. Проверьте свои запросы Cosmos DB, если вы используете этого поставщика. Улучшенные переводы означают, что некоторые запросы будут выполняться по-другому (обычно быстрее), но стоит убедиться, что результаты идентичны.

Минимальный апгрейд для типичного проекта выглядит так:

dotnet add package Microsoft.EntityFrameworkCore --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 9.0.0
dotnet add package Microsoft.EntityFrameworkCore.Design --version 9.0.0
dotnet build
dotnet test

Если все компилируется и тесты проходят успешно, возможно, вы в хорошей форме. Если у вас возникнут проблемы, документация по критическим изменениям EF Core 9 содержит подробные инструкции по миграции для каждого изменения.

Подведение итогов

EF Core 9 — это не революционный выпуск, а эволюционный, и именно таким он и должен был быть. Одни только улучшения LINQ оправдывают обновление для большинства проектов, а такие функции, как усовершенствования столбцов JSON, сложные типы и поддержка HierarchyId открывают шаблоны, которые ранее были неуклюжими или невозможными.

Если бы мне пришлось выбрать три функции, которые оказали наибольшее влияние на мои проекты:

Параметризованные коллекции примитивов — поскольку эффективность кэша плана запроса имеет значение в масштабе
Усовершенствования столбцов JSON — потому что шаблон гибридного реляционного документа невероятно полезен.
Скомпилированные модели — поскольку время запуска напрямую влияет на продуктивность разработчиков и скорость развертывания.Команда EF Core добилась уверенного прогресса со времен EF Core 5, и версия 9 продолжает эту тенденцию. Если вы уже используете EF Core 8, обновление сопряжено с низким риском и высокой прибылью. Если вы используете что-то старое, сейчас лучшее время, чтобы совершить прыжок.

Удачного кодирования — и удачных запросов.

Начало работы с семантическим ядром: оркестровка ИИ в C#

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

Если вы создавали .NET-приложения и наблюдали за развитием ИИ-среды, вы, вероятно, задавались вопросом: какой лучший способ интегрировать большие языковые модели в мои проекты на C#, не превращая мою кодовую базу в спагетти? Именно эту проблему решает семантическое ядро Microsoft, и, потратив последний год на создание производственных приложений с его помощью, я могу вам сказать, что оно стало одним из самых важных инструментов в моем наборе инструментов разработчика.

В этом посте я расскажу вам обо всем, что вам нужно для начала работы с семантическим ядром — от понимания основных концепций до создания реального помощника ИИ. Если вы только начинаете заниматься разработкой ИИ или ищете структурированный способ организации вызовов LLM в существующих приложениях .NET, это руководство поможет вам.

Что такое семантическое ядро?

Семантическое ядро (SK) — это пакет SDK с открытым исходным кодом от Microsoft, который действует как уровень оркестрации между кодом вашего приложения и большими языковыми моделями, такими как GPT-4o, Azure OpenAI или другими службами искусственного интеллекта. Думайте об этом как о легком промежуточном программном обеспечении, которое позволяет вам простым и компонуемым образом сочетать традиционный код C# с возможностями искусственного интеллекта.

Но почему бы просто не вызвать API OpenAI напрямую? Вы абсолютно можете — и для простых случаев использования это нормально. Но в тот момент, когда вам нужно:

Пусть ИИ решает какие функции вызывать на основе пользовательского ввода.
Объедините несколько вызовов ИИ с традиционным кодом в конвейере.
Добавьте память и контекст, чтобы ИИ запоминал предыдущие взаимодействия.
Создавайте многоэтапных агентов, которые рассуждают посредством сложных задач.

…вы изобретаете велосипед. Semantic Kernel предоставляет вам все это «из коробки» с первоклассной поддержкой .NET, интеграцией внедрения зависимостей и архитектурой плагинов, которая кажется естественной любому разработчику C#.

Проект находится на GitHub в репозитории microsoft/semantic-kernel и имеет SDK для C#, Python и Java. C# SDK является наиболее зрелым, и именно на нем мы здесь сосредоточимся.

Основные понятия

Прежде чем писать какой-либо код, давайте разберемся со строительными блоками.

Ядро

Kernel — это центральный объект в семантическом ядре. Это оркестратор — то, что связывает воедино ваши службы искусственного интеллекта, плагины и конфигурацию. Вы создаете его, регистрируете в нем свои службы и плагины, а затем используете его для выполнения подсказок или вызова функций. Если вы знакомы с внедрением зависимостей в ASP.NET Core, ядро покажется вам очень знакомым — по сути, это сервисный контейнер со сверхспособностями искусственного интеллекта.

Плагины и функции

Плагин — это набор связанных функций, которые может вызывать ядро. Функции бывают двух видов:

Функции подсказок — определяются как шаблоны естественного языка, которые отправляются в LLM.
Встроенные функции — обычные методы C#, украшенные атрибутами, которые ядро может обнаружить и вызвать.

Например, у вас может быть WeatherPlugin со встроенной функцией GetCurrentWeather(string city) и функцией подсказки, которая в удобной форме суммирует данные о погоде.### AI-коннекторы

Коннекторы — это то, как семантическое ядро взаимодействует со службами ИИ. Наиболее распространенными из них являются:

AzureOpenAIChatCompletion — для службы Azure OpenAI.
OpenAIChatCompletion — напрямую для API OpenAI.
Встраивание коннекторов для векторного поиска и памяти

Вы регистрируете их в ядре при запуске, и все остальное просто работает.

Настройка вашего проекта

Давайте запачкаем руки. Начните с создания нового консольного приложения:

[[[ТОК_6]]]

Теперь добавьте пакеты NuGet семантического ядра:

[[[ТОК_7]]]

Если вы используете OpenAI напрямую вместо Azure OpenAI:

[[[ТОК_8]]]

Для поддержки памяти и встраивания (мы воспользуемся этим позже):

[[[ТОК_9]]]

Ваш .csproj должен быть ориентирован на .NET 8 или более позднюю версию. Последние версии Semantic Kernel в полной мере используют современные функции .NET.

Ваше первое ядро

Начнем с самого простого примера — создания ядра, подключения его к сервису ИИ и задания ему вопроса.

[[[ТОК_11]]]

Если вы используете OpenAI напрямую, поменяйте местами регистрацию сервиса:

[[[ТОК_12]]]

Вот и все. Запустите его, и вы получите краткое объяснение внедрения зависимостей. Но это лишь поверхностный взгляд.

Использование шаблонов подсказок

Шаблоны подсказок позволяют параметризовать подсказки переменными, используя синтаксис в стиле Handlebars:

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

Именно здесь семантическое ядро начинает проявлять себя — вы можете определять многократно используемые шаблоны подсказок, создавать их версии и объединять их в более крупные рабочие процессы.

Плагины и встроенные функции

Плагины — это место, где семантическое ядро устраняет разрыв между искусственным интеллектом и существующим кодом 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]. Это очень важно: описания — это то, что читает ИИ, чтобы понять, когда и как вызывать ваши функции. Хорошие описания определяют разницу между ИИ, который эффективно использует ваши инструменты, и тем, кто запутался.

Зарегистрируйте плагин в своем ядре:

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

Вызов функций и автовызов

Здесь все становится действительно интересно. С помощью вызова функции (также известного как вызов инструмента) вы позволяете модели ИИ решать, какую из ваших зарегистрированных функций вызывать в зависимости от контекста разговора. Модель не выполняет код — она возвращает структурированный запрос «Я хочу вызвать функцию 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() ядро будет:

Отправьте ИИ запрос вместе с описанием всех доступных функций.
ИИ решает, что ему необходимо вызвать get_time_in_timezone и get_weather
Ядро автоматически выполняет эти функции.
Результаты отправляются обратно в ИИ.
ИИ формирует ответ на естественном языке, используя результаты функции.Этот цикл может происходить несколько раз за один вызов — ИИ может последовательно вызывать несколько функций, чтобы собрать всю необходимую информацию. Вы также можете использовать FunctionChoiceBehavior.Required(), чтобы заставить ИИ вызвать хотя бы одну функцию или предоставить определенный список функций, которые ему разрешено использовать.

Завершение чата с историей

Для диалоговых приложений вы захотите использовать 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}");
}

Это дает вам полностью интерактивный чат-бот, который сохраняет историю разговоров и может вызывать ваши плагины по мере необходимости.

Память и встраивания

Одним из самых мощных шаблонов в приложениях ИИ является Расширенная генерация данных (RAG) — предоставление ИИ доступа к вашим собственным данным путем их внедрения в векторное пространство и извлечения соответствующих фрагментов во время запроса.

Семантическое ядро предоставляет абстракции для работы с векторными хранилищами и внедрениями. Вот как настроить векторное хранилище в памяти для разработки:

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 как функцию ядра, ИИ может автоматически решать, когда ему нужно выполнить поиск в вашей базе знаний, сохраняя чистоту оркестрации и позволяя модели делать то, что она делает лучше всего.

Планировщики и агенты

По мере усложнения ваших приложений ИИ вам понадобится ИИ для планирования и выполнения многоэтапных задач. Именно здесь на помощь приходит структура агента Semantic Kernel.

Основы: агент завершения чата

Самый простой тип агента включает в себя модель завершения чата с инструкциями и плагинами:

using Microsoft.SemanticKernel.Agents;

#pragma warning disable SKEXP0110

var agent = new ChatCompletionAgent
{
 Name = "DevAssistant",
 Instructions = """
 You are a senior .NET developer assistant. Help users with code
 reviews, architecture decisions, and debugging. Always provide
 code examples when relevant. Use your available tools to look up
 current information when needed.
 """,
 Kernel = kernel,
 Arguments = new KernelArguments(settings)
};

var history = new ChatHistory();

history.AddUserMessage("How should I structure a clean architecture project in .NET 8?");

await foreach (var message in agent.InvokeAsync(history))
{
 Console.WriteLine(message.Content);
 history.Add(message);
}

Многоагентное сотрудничество

По-настоящему эффектно получается, когда у вас несколько агентов, работающих вместе. Семантическое ядро поддерживает шаблоны групповых чатов, в которых сотрудничают агенты с разными специализациями:

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

Этот шаблон невероятно полезен для сложных задач, где необходимо учитывать различные точки зрения или области знаний. Каждый агент работает со своей собственной системной подсказкой и может иметь свой собственный набор плагинов.

Пример из реальной жизни: создание помощника по проектной документации

Давайте свяжем все вместе на практическом примере — ИИ-помощнике, который помогает разработчикам понимать кодовую базу, читая файлы и отвечая на вопросы.

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

Этот помощник может:- Список и чтение файлов из каталога вашего проекта.

Отвечайте на вопросы о кодовой базе, читая реальные исходные файлы.
Создать документацию в формате уценки. – Сохраняйте контекст разговора, чтобы дополнительные вопросы работали естественно.

ИИ автоматически решает, когда вызывать 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());

Сохраняйте точность описаний функций. Расплывчатые описания приводят к неправильному вызову функций ИИ. Проверьте свои описания, задав вопрос: «Если бы я только прочитал описание, знал бы я точно, когда и как использовать эту функцию?»

Заключение

Семантическое ядро — одна из тех библиотек, которая фундаментально меняет ваше представление о создании приложений. Это не просто оболочка API — это среда оркестровки, которая позволяет объединять возможности ИИ с традиционным кодом таким образом, чтобы его можно было поддерживать, тестировать и готовить к использованию.

Что мне больше всего в нем нравится, так это то, что он уважает экосистему .NET. Он использует уже знакомые вам шаблоны — внедрение зависимостей, атрибуты, async/await, интерфейсы — и распространяет их на мир ИИ. Вам не нужно изучать совершенно новую парадигму; вы просто добавляете ИИ в качестве еще одной возможности в свой набор инструментов.

Если вы создаете .NET-приложения и еще не изучили семантическое ядро, сейчас самое время. SDK стабилен, сообщество активно, а шаблоны, которые он обеспечивает — от простой быстрой оркестровки до многоагентной совместной работы — становятся важными навыками для современных разработчиков.

Начните с малого. Создайте ядро, зарегистрируйте плагин и наблюдайте, как ИИ вызывает ваш код. Как только это произойдет, вы начнете видеть возможности для добавления интеллекта повсюду в ваших приложениях.

Официальная документация и репозиторий GitHub — отличные ресурсы для продолжения вашего путешествия. Приятного строительства!

Наследование компонентов в Blazor

Thu, 04 Sep 2025 00:00:00 +0000

Я создавал проект, в котором было несколько страниц форм, и каждая из них имела одинаковую логику состояния загрузки, одинаковую обработку ошибок и одинаковые всплывающие уведомления. Копирование всего этого казалось неправильным, поэтому я изучил наследование компонентов в Blazor. Оказывается, это довольно просто, поскольку компоненты Blazor — это всего лишь классы C#.

Основы

Каждый компонент Blazor по умолчанию наследует от ComponentBase . Вы можете создать свой собственный базовый класс, расширяющий ComponentBase, а затем наследовать от него свои компоненты.

Допустим, большинству наших страниц требуется состояние загрузки и обработка ошибок. Мы можем создать базовый класс:

[[[ТОК_2]]]

Использование базового класса

Теперь в любом компоненте страницы вместо наследования от ComponentBase мы наследуем от нашего PageBase:

@page "/users"
@inherits PageBase

@if (IsLoading)
{
 <div class="spinner"></div>
}
else if (ErrorMessage is not null)
{
 <div class="alert alert-danger">@ErrorMessage</div>
}
else
{
 <ul>
 @foreach (var user in users)
 {
 <li>@user.Name</li>
 }
 </ul>
}

@code {
 private List<User> users = new();

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

Директива @inherits PageBase является ключевой. Он сообщает Blazor использовать наш базовый класс вместо стандартного ComponentBase. Теперь мы получаем IsLoading, ErrorMessage и LoadDataAsync() бесплатно на каждой странице, которая наследуется от него.

Внедрение сервисов в базовый класс

Вы также можете внедрить сервисы в базовый класс, чтобы они были доступны всем дочерним компонентам:

[[[ТОК_11]]]

Каждый компонент, который наследует от PageBase, теперь имеет доступ к Navigation, Toast, NavigateBack() и ShowSuccess() без необходимости чего-либо внедрять.

Углубляемся в общие базовые классы

Вы даже можете создать общие базовые классы для распространенных шаблонов CRUD:

public abstract class CrudPageBase<T> : PageBase
{
 protected List<T> Items { get; set; } = new();
 protected T? SelectedItem { get; set; }

 protected abstract Task<List<T>> FetchItems();
 protected abstract Task DeleteItem(T item);

 protected override async Task OnInitializedAsync()
 {
 await LoadDataAsync(async () =>
 {
 Items = await FetchItems();
 });
 }

 protected async Task OnDelete(T item)
 {
 await LoadDataAsync(async () =>
 {
 await DeleteItem(item);
 Items = await FetchItems();
 ShowSuccess("Item deleted.");
 });
 }
}

Тогда ваша фактическая страница станет очень чистой:

@page "/products"
@inherits CrudPageBase<Product>

@* just the markup, all logic lives in the base class *@

@code {
 protected override Task<List<Product>> FetchItems()
 => Http.GetFromJsonAsync<List<Product>>("api/products");

 protected override Task DeleteItem(Product item)
 => Http.DeleteAsync($"api/products/{item.Id}");
}

Когда его использовать, а когда нет

Наследование компонентов отлично подходит для общего поведения, такого как состояния загрузки, обработка ошибок, проверки подлинности или шаблоны CRUD. Но не переусердствуйте с глубокими иерархиями наследования — если вы обнаружите, что углубляетесь более чем на два уровня, вам, вероятно, лучше использовать композицию (например, подход LoadingComponent из предыдущего поста).

Обычно я придерживаюсь одного базового класса для каждого «типа» страницы: PageBase для обычных страниц, FormPageBase для форм, и это все.

Надеюсь, вам понравился пост! Не стесняйтесь обращаться ко мне в любой социальной сети по адресу @emimontesdeoca.

Ресурсы

Наследование компонентов ASP.NET Core Razor

.NET Aspire: правильное создание облачных приложений

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

Если вы когда-либо создавали распределенное приложение на .NET, вы знаете суть. Вы запускаете веб-API, добавляете фонового работника, добавляете Redis для кэширования, PostgreSQL для сохранения, возможно, RabbitMQ для обмена сообщениями — и внезапно вы тратите больше времени на подключение инфраструктуры, чем на написание бизнес-логики. Строки подключения, разбросанные по файлам appsettings.json, проверки работоспособности, которые вы забыли настроить, наблюдаемость, которая всегда является «проблемой следующего спринта».

Я был там. Больше раз, чем мне хотелось бы признать.

Именно для решения этой проблемы был создан .NET Aspire. После нескольких месяцев эксплуатации его в производстве я хочу поделиться тем, что я узнал — хорошим, замечательным и ошибками.

Что такое .NET Aspire?

.NET Aspire — это продуманный стек для создания наблюдаемых, готовых к использованию распределенных приложений с помощью .NET. Это не платформа в традиционном смысле — она не заменяет ASP.NET Core и не заставляет вас использовать новую модель программирования. Вместо этого он опирается на то, что вы уже знаете, и заполняет пробелы, которые всегда существовали при создании облачных приложений.

По своей сути Aspire дает вам четыре вещи:

AppHost — проект, определяющий всю топологию распределенного приложения. Какие сервисы существуют, от чего они зависят и как подключаются.
Настройки службы по умолчанию – общий проект, который настраивает сквозные задачи, такие как проверки работоспособности, политики устойчивости и OpenTelemetry, – один раз для всех ваших служб.
Компоненты — пакеты NuGet, обеспечивающие стандартизированную интеграцию с вспомогательными службами, такими как Redis, PostgreSQL, RabbitMQ, Azure Storage и другими.
Панель разработчика — пользовательский интерфейс, работающий в режиме реального времени, который отображает журналы, трассировки и метрики для всего распределенного приложения во время локальной разработки.

Философия проста: если каждое облачное приложение .NET нуждается в этих вещах, почему мы все каждый раз реализуем их с нуля?

Настройка вашего первого проекта Aspire

Начать работу очень просто. Вам потребуется .NET 8 или более поздняя версия и установленная рабочая нагрузка Aspire:

[[[ТОК_1]]]

Теперь создайте новый стартовый проект Aspire:

[[[ТОК_2]]]

Это генерирует решение с четырьмя проектами:

MyCloudApp.AppHost — Оркестратор
MyCloudApp.ServiceDefaults — Общая конфигурация
MyCloudApp.ApiService — пример веб-API.
MyCloudApp.Web — интерфейс Blazor

Запустите AppHost, и вы сразу же увидите в браузере открытую панель управления Aspire, показывающую все ваши службы, их журналы и состояние их работоспособности. Нет файла Docker Compose. Никакого ручного управления портами. Это просто работает.

[[[ТОК_7]]]

Именно этот первый опыт меня и зацепил. Менее чем за минуту вы получите полностью оркестрованное распределенное приложение со встроенной возможностью наблюдения.

Шаблон AppHost

AppHost — это место, где живет волшебство. Это небольшое консольное приложение, которое использует шаблон компоновщика для определения топологии вашего распределенного приложения — какие ресурсы существуют и как к ним подключаются службы.

Вот как выглядит реалистичный AppHost:

[[[ТОК_8]]]Прочтите этот код вслух. Он практически документирует себя. «API каталога ссылается на PostgreSQL, Redis и RabbitMQ. Интерфейс ссылается на API каталога и API заказа». Это ваша архитектура, выраженная в коде.

Несколько вещей, которые стоит отметить:

WithReference выполняет тяжелую работу. Он автоматически вводит строки подключения и URL-адреса служб в потребляющий проект через переменные среды и конфигурацию. Вашим службам не нужно знать, где работает Redis — Aspire справится с этим.
WithPgAdmin() и WithManagementPlugin() расширяют пользовательские интерфейсы администратора для PostgreSQL и RabbitMQ наряду с реальными службами. Во время разработки они неоценимы.
WithExternalHttpEndpoints() отмечает службу как доступную извне, что имеет значение во время развертывания.

Конфигурация ресурса

Вы можете настроить ресурсы с детальным контролем:

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. Это общая библиотека, на которую ссылается каждая служба в вашем решении, и она настраивает все сквозные проблемы, которые вы в противном случае забыли бы или реализовали непоследовательно.

Вот как выглядит типичный Extensions.cs в ServiceDefaults:

public static class Extensions
{
 public static IHostApplicationBuilder AddServiceDefaults(
 this IHostApplicationBuilder builder)
 {
 builder.ConfigureOpenTelemetry();
 builder.AddDefaultHealthChecks();
 builder.Services.AddServiceDiscovery();

 builder.Services.ConfigureHttpClientDefaults(http =>
 {
 http.AddStandardResilienceHandler();
 http.AddServiceDiscovery();
 });

 return builder;
 }

 public static IHostApplicationBuilder ConfigureOpenTelemetry(
 this IHostApplicationBuilder builder)
 {
 builder.Logging.AddOpenTelemetry(logging =>
 {
 logging.IncludeFormattedMessage = true;
 logging.IncludeScopes = true;
 });

 builder.Services.AddOpenTelemetry()
 .WithMetrics(metrics =>
 {
 metrics.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddRuntimeInstrumentation();
 })
 .WithTracing(tracing =>
 {
 tracing.AddAspNetCoreInstrumentation()
 .AddHttpClientInstrumentation()
 .AddGrpcClientInstrumentation();
 });

 builder.AddOpenTelemetryExporters();
 return builder;
 }

 public static IHostApplicationBuilder AddDefaultHealthChecks(
 this IHostApplicationBuilder builder)
 {
 builder.Services.AddHealthChecks()
 .AddCheck("self", () => HealthCheckResult.Healthy(),
 ["live"]);

 return builder;
 }
}

Затем в Program.cs каждой службы одна строка делает все это:

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

// Your service-specific configuration...

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

Этот единственный вызов AddServiceDefaults() дает вам:

OpenTelemetry со структурированным журналированием, метриками и распределенной трассировкой.
Проверки работоспособности с указанием конечных точек работоспособности и готовности.
Обнаружение служб, чтобы службы могли находить друг друга по имени.
Политики устойчивости для всех исходящих HTTP-вызовов (повторные попытки, автоматические выключатели, тайм-ауты).

Это то, что отличает демоверсию «работает на моей машине» от готовой к использованию системы. И Aspire делает это значением по умолчанию, а не второстепенным вопросом.

Компоненты Aspire

Компоненты Aspire — это пакеты NuGet, которые стандартизируют способ подключения ваших сервисов к поддерживающей инфраструктуре. Это больше, чем просто клиентские библиотеки — они включают в себя проверку работоспособности, ведение журналов, трассировку и настраиваемую устойчивость.

Редис

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

Вот и все. Строка подключения поступает от AppHost через WithReference. Компонент регистрирует IDistributedCache, поддерживаемый Redis, с уже подключенными проверками работоспособности и инструментами OpenTelemetry.

Вы также можете использовать Redis для кэширования вывода:

builder.AddRedisOutputCache("cache");

PostgreSQL с Entity Framework Core

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

При этом ваш DbContext будет подключен к базе данных catalogdb, определенной в AppHost. Он включает в себя пул соединений, проверки работоспособности и политики повторных попыток.

КроликMQ

builder.AddRabbitMQClient("messaging");

Регистрирует IConnection из клиентской библиотеки RabbitMQ, полностью настроенный и проверенный на работоспособность.

Интеграции Azure

Aspire также имеет первоклассные компоненты для сервисов Azure:

// Azure Blob Storage
builder.AddAzureBlobClient("blobs");

// Azure Service Bus
builder.AddAzureServiceBusClient("servicebus");

// Azure Key Vault
builder.AddAzureKeyVaultClient("secrets");
```Шаблон всегда один и тот же: одна строка в AppHost для определения ресурса, одна строка в службе-потребителе для его использования. Детали подключения передаются автоматически.

## Панель разработчика

Панель управления Aspire — одна из тех функций, которая кажется приятной, пока вы ее не используете — тогда вы не сможете представить себе работу без нее.

Когда вы запускаете AppHost локально, запускается панель мониторинга, которая предоставляет вам:

- **Обзор ресурсов** — Краткий обзор всех ваших услуг и инфраструктуры с индикаторами состояния.
- **Структурированные журналы** — потоковая передача журналов в реальном времени из каждой службы с возможностью фильтрации и поиска.
- **Распределенные трассировки** — сквозные трассировки запросов, охватывающие несколько служб, визуализированные в виде флейм-диаграмм.
- **Метрики** – частота HTTP-запросов, частота ошибок, задержки и пользовательские метрики в режиме реального времени.
- **Журналы консоли** — необработанные данные stdout/stderr из каждого контейнера и проекта.

Распределенная трассировка особенно ценна. Когда запрос попадает в ваш интерфейс, проходит через API каталога, касается Redis и PostgreSQL — вы видите всю цепочку с указанием времени для каждого перехода. Больше не нужно гадать, где находится узкое место.

Я считаю, что панель мониторинга наиболее полезна во время отладки. Вместо отслеживания нескольких окон терминала или перехода между файлами журналов все находится в одном месте с идентификаторами корреляции, связывающими связанные события между службами.

Панель мониторинга также доступна в виде автономного контейнера, что означает, что вы можете использовать ее в промежуточных средах или конвейерах CI:

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

Развертывание

Aspire помогает во время разработки, но как насчет производства? Здесь все становится практичным.

Приложения-контейнеры Azure

Самый простой путь развертывания — это приложения-контейнеры Azure (ACA), которые имеют первоклассную поддержку Aspire. Вы можете выполнить развертывание напрямую с помощью интерфейса командной строки разработчика Azure:

azd init
azd up

Команда azd init обнаруживает ваш Aspire AppHost и генерирует необходимую инфраструктуру в виде кода. azd up подготавливает все — реестр контейнеров, приложения-контейнеры, базы данных, экземпляры Redis — на основе вашей топологии AppHost.

Ваш AppHost по сути становится манифестом вашего развертывания. Тот же код, который определяет, что «catalog-api зависит от PostgreSQL и Redis», управляет подготовкой инфраструктуры.

Кубернетес

Для развертываний Kubernetes Aspire не создает манифесты напрямую, но ваша топология AppHost четко сопоставляется с ресурсами Kubernetes. Инструмент сообщества aspirate (Aspir8) может создавать диаграммы Helm или манифесты Kubernetes из вашего AppHost:

dotnet tool install -g aspirate
aspirate generate
aspirate apply

Реальные советы

После некоторого запуска 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. Мониторинг использования ресурсов локально

При локальном запуске нескольких контейнеров следите за потреблением ресурсов. Экземпляр PostgreSQL, Redis и RabbitMQ с пользовательским интерфейсом управления может легко занимать 2–3 ГБ ОЗУ. Если вы используете машину с ограниченными возможностями, рассмотрите возможность использования более легких конфигураций ресурсов:

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

Заключение

.NET Aspire фундаментально изменил мой подход к созданию распределенных приложений. Не потому, что он вводит революционные концепции — проверки работоспособности, OpenTelemetry и оркестровка контейнеров не новы. А потому, что это делает их по умолчанию. Он принимает сотни небольших решений, которые вам обычно приходится принимать, реализует их с разумными значениями по умолчанию и позволяет вам переопределить их, когда это необходимо.На мой взгляд, шаблон AppHost — это самая большая победа. Если топология распределенного приложения выражена в виде кода, а не разбросана по файлам Docker Compose, манифестам Kubernetes и документам README, это делает систему понятной. Новые члены команды могут открыть Program.cs в AppHost и понять всю архитектуру за считанные минуты.

Если вы создаете распределенные приложения с помощью .NET, присмотритесь к Aspire серьезно. Начните с шаблона aspire-starter, изучите панель мониторинга и постепенно внедряйте компоненты по мере необходимости. Вам не обязательно идти ва-банк в первый же день — Aspire по своей сути аддитивен.

Дни, когда вы тратили свой первый спринт на подключение шаблона инфраструктуры, прошли. Позвольте Aspire позаботиться о сантехнике, чтобы вы могли сосредоточиться на том, что действительно важно: на вашем приложении.

Аутентификация и авторизация в Blazor: практическое руководство

Sat, 12 Jul 2025 00:00:00 +0000

Если вы работали с ASP.NET MVC или Razor Pages, у вас, вероятно, есть мысленная модель того, как работает аутентификация: промежуточное программное обеспечение перехватывает запрос, проверяет файл cookie или токен, заполняет HttpContext.User, и вы готовы к гонкам. Blazor меняет эту ментальную модель тонкими, но важными способами — и если вы не поймете эти различия на ранней стадии, вам придется отлаживать проблемы аутентификации, которые кажутся невозможными.

В этом посте я хочу рассказать, как на самом деле работают аутентификация и авторизация в Blazor, охватывая модели хостинга Server и WebAssembly. Мы пройдем от основ до пользовательских поставщиков, внешнего OAuth и ловушек, которые, как я видел, сбивают с толку даже опытных разработчиков .NET.

Почему аутентификация в Blazor отличается

В традиционном ASP.NET каждое взаимодействие с пользователем представляет собой HTTP-запрос. Сервер проверяет учетные данные, устанавливает файл cookie, и каждый последующий запрос передает этот файл cookie. Конвейер аутентификации линеен и предсказуем.

Blazor Server работает через постоянное соединение SignalR. После того как первоначальный HTTP-запрос загружает страницу, все последующие взаимодействия происходят через WebSockets. Для каждого нажатия кнопки не создается новый HTTP-запрос, поэтому промежуточное программное обеспечение не выполняется повторно при каждом взаимодействии. HttpContext доступен во время первоначального соединения, но полагаться на него на протяжении всего срока службы схемы — верный путь к ошибкам.

Blazor WebAssembly полностью работает в браузере. Серверной части HttpContext вообще нет. Состояние аутентификации должно быть получено из API, сохранено на стороне клиента и управляемо с помощью токенов — обычно JWT. Сервер доверяет клиенту только в рамках проверки токена.

Это означает, что Blazor нужна собственная абстракция для состояния аутентификации, которая работает независимо от модели хостинга. Эта абстракция — AuthenticationStateProvider.

Состояние аутентификации: Фонд

В основе системы аутентификации Blazor лежит AuthenticationStateProvider. Это абстрактный класс, предоставляющий единственный критический метод:

public abstract Task<AuthenticationState> GetAuthenticationStateAsync();

Объект AuthenticationState оборачивает ClaimsPrincipal — ту же модель идентификации, которая используется во всем .NET. Компоненты не взаимодействуют напрямую с файлами cookie или токенами; они запрашивают AuthenticationStateProvider о текущем состоянии.

Чтобы сделать это состояние доступным для всего вашего дерева компонентов, Blazor предоставляет CascadingAuthenticationState. Обычно вы оборачиваете свой маршрутизатор в App.razor или в свой макет:

[[[ТОК_11]]]

AuthorizeRouteView здесь выполняет двойную функцию: он проверяет, прошел ли пользователь аутентификацию и авторизацию, прежде чем отображать соответствующий компонент страницы, и предоставляет запасной пользовательский интерфейс, если это не так.

В .NET 8 и более поздних версиях с унифицированной моделью Blazor вы настроите это в своем App.razor и платформа автоматически обрабатывает параметр каскадирования, когда вы используете AddCascadingAuthenticationState() при регистрации службы.

Интеграция удостоверений ASP.NET

Для большинства проектов вам не нужно создавать аутентификацию с нуля. ASP.NET Identity обеспечивает управление пользователями, хеширование паролей, двухфакторную аутентификацию и подтверждение учетной записи «из коробки».Настройка с помощью 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;
 });

Благодаря шаблону веб-приложения Blazor в .NET 8+ шаблонный пользовательский интерфейс Identity напрямую использует компоненты Razor. Вы получаете страницы входа, регистрации и управления учетной записью, которые естественным образом интегрируются с остальной частью вашего приложения Blazor — больше не нужно неудобного сочетания страниц Razor и компонентов Blazor.

ApplicationDbContext наследуется от IdentityDbContext и вам потребуется выполнить миграцию для создания таблиц идентификации:

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
 public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
 : base(options) { }
}

dotnet ef migrations add InitialIdentity
dotnet ef database update

Компонент AuthorizeView

Как только состояние аутентификации проходит через ваше дерево компонентов, AuthorizeView позволяет вам условно отображать пользовательский интерфейс:

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

Параметр context внутри <Authorized> предоставляет вам доступ к AuthenticationState, поэтому вы можете проверять утверждения, роли и личность пользователя непосредственно в вашей разметке.

Вы также можете использовать AuthorizeView с ролями и политиками:

<AuthorizeView Roles="Admin,Moderator">
 <Authorized>
 <button @onclick="DeletePost">Delete Post</button>
 </Authorized>
</AuthorizeView>

<AuthorizeView Policy="CanEditArticles">
 <Authorized>
 <button @onclick="EditArticle">Edit</button>
 </Authorized>
</AuthorizeView>

Следует иметь в виду одну вещь: AuthorizeView — это проблема пользовательского интерфейса. Он скрывает или показывает элементы, но не защищает основную логику. Если кто-то может вызвать конечную точку вашего 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

Поддержка «Войти с помощью Google» или «Войти с помощью GitHub» проста с помощью промежуточного программного обеспечения аутентификации ASP.NET. Они настраиваются на стороне сервера, поскольку поток 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 вам понадобится пакет NuGet AspNet.Security.OAuth.GitHub NuGet, поскольку он не включен в библиотеки ASP.NET по умолчанию.

Пользовательский интерфейс входа затем предоставляет ссылки, которые запускают внешний вызов:

@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 всегда требует полностраничной навигации — вы не можете выполнить перенаправление OAuth внутри схемы SignalR или приложения WebAssembly, минуя сервер.

Платформа предоставляет 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"));

Для автономных приложений Blazor WASM, которые проходят аутентификацию по собственному API, вы реализуете собственный AuthenticationStateProvider для анализа JWT:

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-атакам. Для приложений с более высоким уровнем безопасности рассмотрите возможность хранения токенов только в памяти и использования токенов обновления или принятия шаблона Backend-for-Frontend (BFF), где сервер управляет токенами, а клиент использует файлы cookie только для HTTP.

Blazor Server против WebAssembly: соображения безопасности

Модель хостинга фундаментально меняет вашу безопасность.

Blazor Server хранит всю логику ваших компонентов на сервере. Клиент видит только отображаемые различия HTML через SignalR. Это означает:

Чувствительная логика никогда не покидает сервер
Вы можете получить доступ к базам данных и внутренним сервисам непосредственно из компонентов.
Состояние аутентификации поступает от HttpContext сервера при первоначальном подключении.
Схема может пережить файл cookie аутентификации — если срок действия файла cookie пользователя истечет, схема останется активной до тех пор, пока не будет отключена.
Вы должны корректно обрабатывать отключение канала и повторно проверять состояние аутентификации при повторном подключении.

Blazor WebAssembly полностью работает в браузере. Это означает:

Весь код вашего компонента можно загрузить и проверить.
Никогда не помещайте секреты, строки подключения или конфиденциальную бизнес-логику в компоненты WASM. — Аутентификация применяется только на клиенте для UX; реальное соблюдение требований должно происходить на уровне вашего API.
Управление токенами — ваша ответственность. – Рассмотрите возможность использования размещенной модели, в которой серверный проект обрабатывает аутентификацию и обслуживает приложение WASM.

Шаблон, который я рекомендую для приложений WebAssembly, заключается в том, чтобы рассматривать каждый компонент так, как будто это «ненадежный пользовательский интерфейс», а каждую конечную точку 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 в вашем дереве компонентов. Вот как вы заставляете пользовательский интерфейс реагировать на события входа/выхода без полного обновления страницы.

Распространенные ошибки и решения

После работы с авторизацией Blazor во многих проектах я чаще всего вижу следующие проблемы:

1. Использование HttpContext в серверных компонентах Blazor`HttpContext` доступен во время первоначального HTTP-запроса, но он `null` или устарел во время взаимодействия SignalR. Не вводите `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 входа в систему, это удается, но пользовательский интерфейс по-прежнему показывает «Войти».

Решение: Вы должны вызвать NotifyAuthenticationStateChanged на своем AuthenticationStateProvider после изменения состояния аутентификации. Платформа не может волшебным образом обнаружить, что токен был сохранен или был установлен файл cookie.

3. Атрибут авторизации не работает с компонентами

Вы добавляете [Authorize] в компонент, но он не блокирует неаутентифицированных пользователей.

Решение. Убедитесь, что вы используете AuthorizeRouteView вместо обычного RouteView в своем App.razor. Стандарт RouteView полностью игнорирует атрибуты авторизации.

4. Предварительный рендеринг нарушает состояние аутентификации

Во время предварительной отрисовки на стороне сервера в Blazor WebAssembly токен аутентификации недоступен. Компоненты отображаются как не прошедшие проверку подлинности, а затем после загрузки WASM переходят в состояние проверки подлинности.

Решение. Либо отключите предварительную отрисовку для страниц, чувствительных к аутентификации, с помощью @rendermode InteractiveWebAssembly (без предварительной отрисовки), либо корректно обработайте состояние загрузки:

<AuthorizeView>
 <Authorized>
 <p>Welcome back, @context.User.Identity?.Name</p>
 </Authorized>
 <Authorizing>
 <p>Loading...</p>
 </Authorizing>
 <NotAuthorized>
 <a href="/login">Sign in</a>
 </NotAuthorized>
</AuthorizeView>

5. Срок действия токена в долгоработающих схемах

Цепи Blazor Server могут оставаться активными часами. Если срок действия вашего токена или сеанса истекает, пользователь остается «аутентифицированным» в пользовательском интерфейсе, но вызовы API начинают завершаться сбоем.

Решение. Внедрите периодическую проверку или используйте RevalidatingServerAuthenticationStateProvider:

public class RevalidatingAuthStateProvider
 : RevalidatingServerAuthenticationStateProvider
{
 private readonly IServiceScopeFactory _scopeFactory;

 public RevalidatingAuthStateProvider(
 ILoggerFactory loggerFactory,
 IServiceScopeFactory scopeFactory)
 : base(loggerFactory)
 {
 _scopeFactory = scopeFactory;
 }

 protected override TimeSpan RevalidationInterval => TimeSpan.FromMinutes(30);

 protected override async Task<bool> ValidateAuthenticationStateAsync(
 AuthenticationState authenticationState, CancellationToken cancellationToken)
 {
 await using var scope = _scopeFactory.CreateAsyncScope();
 var userManager = scope.ServiceProvider
 .GetRequiredService<UserManager<IdentityUser>>();

 var user = await userManager.GetUserAsync(authenticationState.User);
 return user is not null;
 }
}

Это подтверждает, что пользователь все еще существует (и его отметка безопасности не изменилась) каждые 30 минут.

Заключение

Аутентификация и авторизация в Blazor требуют отхода от традиционного ASP.NET типа «запрос-ответ». Абстракция AuthenticationStateProvider — это ключ к пониманию того, как все это сочетается друг с другом. Как только вы это усвоите, все остальное вытекает само собой.

Для большинства приложений начните с ASP.NET Identity и встроенных шаблонов. Они берут на себя тяжелую работу по управлению пользователями, хешированию паролей и генерации токенов. Добавляйте политики и авторизацию на основе утверждений по мере роста ваших требований. Добавляйте внешних поставщиков OAuth, когда ваши пользователи этого ожидают.

Модель хостинга имеет значение: Blazor Server предлагает более традиционную схему безопасности, при которой код остается на сервере, а WebAssembly подталкивает вас к мышлению, ориентированному на приоритет API, где клиент не заслуживает доверия по своей конструкции. Ни один из них по своей сути не является более безопасным — просто у них разные модели угроз.

Какой бы подход вы ни выбрали, помните золотое правило: авторизация в пользовательском интерфейсе предназначена для удобства пользователя, авторизация на сервере — для обеспечения безопасности. Всегда применяйте и то, и другое.

Изолированный JavaScript в Blazor с совмещенными файлами JS

Wed, 18 Jun 2025 00:00:00 +0000

Если вы раньше работали с Blazor и JS Interop, вы, вероятно, получили огромный файл app.js со случайными функциями для разных компонентов. Это работает, но быстро портится. К счастью, есть гораздо более простой подход: совместное размещение файлов JavaScript.

Идея

Как и в случае с изоляцией CSS, Blazor позволяет разместить файл .razor.js рядом с вашим компонентом. Модуль JavaScript загружается по требованию, только тогда, когда компоненту это действительно необходимо. Никаких глобальных сценариев, никакого загрязнения.

Настройка

Допустим, у нас есть компонент Clipboard.razor который копирует текст в буфер обмена. Создайте файл с именем Clipboard.razor.js рядом с ним:

[[[ТОК_4]]]

Обратите внимание на ключевое слово export — это важно. Blazor загружает его как стандартный модуль ES.

Загрузка модуля в Blazor

В вашем компоненте вы используете IJSRuntime для импорта модуля. Путь соответствует соглашению: ./_content/{ASSEMBLY_NAME}/{COMPONENT_PATH}.razor.js для библиотек или просто относительный путь для текущего проекта.

[[[ТОК_8]]]

Здесь следует отметить несколько вещей:

Мы загружаем модуль в OnAfterRenderAsync, поскольку JS Interop недоступен во время предварительного рендеринга на стороне сервера.
Сохраняем ссылку на модуль с помощью IJSObjectReference
Мы реализуем IAsyncDisposable для очистки модуля при уничтожении компонента.

Почему это лучше

Раньше я сбрасывал все в один wwwroot/js/app.js. Это работало, но поиск функций был трудной задачей, и каждая страница загружала ненужный JavaScript. С совмещенными файлами JS:

Каждый компонент имеет свой собственный JavaScript.
Модули загружаются лениво, только при необходимости
Отсутствие конфликтов имен глобальных функций.
Легче поддерживать и удалять — при удалении компонента вы удаляете вместе с ним и JS.

Ошибка с путем

Путь, который вы передаете к import зависит от того, находитесь ли вы в автономном приложении Blazor или в библиотеке классов Razor. Для обычного приложения Blazor путь указывается относительно wwwroot. Файл .razor.js копируется туда во время сборки, поэтому вы ссылаетесь на него из местоположения компонента в проекте.

Если при загрузке модуля вы получаете ошибку 404, дважды проверьте путь и убедитесь, что файл заканчивается на .razor.js, а не только на .js.

Надеюсь, вам понравился пост! Не стесняйтесь обращаться ко мне в любой социальной сети по адресу @emimontesdeoca.

Ресурсы

ASP.NET Core Blazor JavaScript с совмещенным JS

Интерактивность Blazor в .NET 9 и .NET 10: полное руководство

Sun, 15 Jun 2025 00:00:00 +0000

Если вы создавали веб-приложения с помощью Blazor в течение последних нескольких лет, вы знаете, что эта платформа прошла долгий путь. То, что началось с выбора между Blazor Server и Blazor WebAssembly, превратилось в унифицированную гибкую модель рендеринга, которая позволяет вам выбрать правильную стратегию интерактивности для каждого компонента вашего приложения.

В .NET 8 мы получили фундаментальный сдвиг — введение режимов рендеринга и статического рендеринга на стороне сервера (SSR) по умолчанию. Теперь .NET 9 и .NET 10 построены на этой основе с усовершенствованиями, которые делают работу разработчиков более удобной, а работу конечных пользователей — более быстрой.

В этом посте я хочу познакомить вас с полной картиной интерактивности Blazor в ее нынешнем виде: как работают режимы рендеринга, что дает потоковая SSR, как улучшенная навигация и обработка форм меняют игру и что нового в последних выпусках. Если вы планируете новый проект Blazor или думаете об обновлении, мне хотелось бы иметь это руководство, когда начал во всем этом разбираться.

Быстрый взгляд назад: как мы сюда попали

До .NET 8 вам приходилось использовать модель хостинга на уровне проекта. Blazor Server означал, что все работало на сервере через соединение SignalR. Blazor WebAssembly означал, что все работает в браузере. У каждого были свои компромиссы, и смешивать их было болезненно.

.NET 8 изменил правила игры, представив единый шаблон проекта — веб-приложение Blazor — который объединяет обе модели. Ключевой концепцией являются режимы рендеринга: вы решаете для каждого компонента, как он должен отображаться и где происходит интерактивность. По умолчанию выбран статический SSR, что означает, что компоненты визуализируются на сервере и отправляют в браузер обычный HTML — без SignalR, без WebAssembly, только быстрый HTML.

В .NET 9 эти концепции были усовершенствованы, улучшены условия для разработчиков и оптимизирована производительность. .NET 10 идет дальше благодаря улучшенной обработке повторного подключения, сохранению состояния компонента в разных режимах рендеринга и улучшениям доставки самого скрипта Blazor.

Давайте разберем все это.

Режимы рендеринга в .NET 9

В основе современного Blazor лежит концепция режимов рендеринга. Есть четыре режима, о которых вам следует знать:

1. Статический SSR (по умолчанию)

Когда вы создаете новое веб-приложение Blazor, компоненты по умолчанию отображаются статически на сервере. Сервер обрабатывает компонент Razor, генерирует HTML и отправляет его в браузер. Нет постоянного соединения, нет среды выполнения WebAssembly — только традиционный запрос/ответ.

Это идеально подходит для страниц с большим количеством контента, информационных панелей, которые в основном отображают данные, или любой страницы, где вам не требуется взаимодействие в реальном времени.

@page "/products"

<h1>Our Products</h1>

@foreach (var product in products)
{
 <div class="product-card">
 <h3>@product.Name</h3>
 <p>@product.Description</p>
 <span class="price">@product.Price.ToString("C")</span>
 </div>
}

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

 protected override async Task OnInitializedAsync()
 {
 products = await ProductService.GetAllAsync();
 }
}

Этот компонент отображает на сервере, создает HTML и все. Нет постоянной связи. Быстрая начальная загрузка, отлично подходит для SEO, минимальное использование ресурсов сервера.

2. Интерактивный серверЕсли вам нужна интерактивность в реальном времени — обработка нажатий кнопок, обработка ввода пользователя, динамическое обновление пользовательского интерфейса — вы можете выбрать режим интерактивного сервера. При этом устанавливается соединение SignalR между браузером и сервером, и обновления пользовательского интерфейса происходят через это соединение.

[[[ТОК_1]]]

Директива @rendermode InteractiveServer — это все, что нужно. Компонент сначала отображается на сервере, а затем устанавливается соединение SignalR для обработки последующих взаимодействий. Обработчики событий C# выполняются на сервере, а различия пользовательского интерфейса отправляются в браузер.

Когда его использовать: Когда вам нужна интерактивность, вашим компонентам необходим доступ к ресурсам на стороне сервера (базам данных, API, файловым системам), и вам нужна быстрая начальная загрузка, не дожидаясь загрузки WebAssembly.

3. Интерактивная веб-сборка

Если вам нужна интерактивность без поддержания соединения с сервером, Interactive WebAssembly запускает логику вашего компонента непосредственно в браузере, используя среду выполнения .NET WebAssembly.

[[[ТОК_3]]]

Компромисс: существует первоначальная стоимость загрузки среды выполнения .NET и ваших сборок. Но после загрузки компонент полностью запускается в браузере без каких-либо обращений к серверу для взаимодействия с пользовательским интерфейсом.

Когда его использовать: для высокоинтерактивных компонентов, где важна задержка (например, редакторы форматированного текста, инструменты рисования, фильтрация в реальном времени), когда вы хотите снизить нагрузку на сервер или когда вы создаете прогрессивное веб-приложение (PWA).

4. Интерактивный авто

Это прагматичная золотая середина и одна из моих любимых особенностей. Interactive Auto начинается с рендеринга на стороне сервера через SignalR для первой загрузки, затем автоматически загружает среду выполнения WebAssembly в фоновом режиме. При последующих посещениях компонент запускается на WebAssembly.

[[[ТОК_4]]]

Это дает вам лучшее из обоих миров: быстрый первый рендеринг (без ожидания загрузки WASM) и, в конечном итоге, компонент запускается на стороне клиента. Пользователь не замечает перехода.

Когда его использовать: Когда вам нужна как быстрая начальная загрузка, так и возможное выполнение на стороне клиента. Это отличный выбор по умолчанию для многих интерактивных компонентов.

Потоковое SSR: лучшее из обоих миров

Потоковая SSR — одна из тех функций, которая звучит просто, но существенно влияет на воспринимаемую производительность. Вот идея: вместо того, чтобы ждать загрузки всех ваших данных перед отправкой любого HTML, сервер немедленно отправляет оболочку страницы, а затем транслирует обновления контента по мере того, как данные становятся доступными.

@page "/reports"
@attribute [StreamRendering]

<h1>Monthly Reports</h1>

@if (reports is null)
{
 <div class="loading-spinner">
 <p>Loading reports...</p>
 </div>
}
else
{
 <table class="table">
 <thead>
 <tr>
 <th>Month</th>
 <th>Revenue</th>
 <th>Growth</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var report in reports)
 {
 <tr>
 <td>@report.Month</td>
 <td>@report.Revenue.ToString("C")</td>
 <td class="@(report.Growth >= 0 ? "text-success" : "text-danger")">
 @report.Growth.ToString("P1")
 </td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private List<MonthlyReport>? reports;

 protected override async Task OnInitializedAsync()
 {
 // This might take a couple of seconds
 reports = await ReportService.GetMonthlyReportsAsync();
 }
}

С атрибутом [StreamRendering] происходит следующее:

Сервер немедленно отправляет HTML с помощью счетчика загрузки.
OnInitializedAsync запускается и извлекает данные.
Когда данные поступают, сервер передает обновленный HTML (таблицу) в браузер.
Браузер исправляет DOM без полной перезагрузки страницы.

Пользователь видит страницу мгновенно с индикатором загрузки, затем содержимое заполняется. Никакой инфраструктуры JavaScript не требуется. Нет подключения к WebSocket. Просто умное использование потоковой передачи HTTP.Когда использовать: Любая статическая страница SSR, которая извлекает данные во время рендеринга. Страницы со списком продуктов, информационные панели, отчеты — везде первоначальная загрузка данных может занять более нескольких сотен миллисекунд.

Когда НЕ использовать: Если данные загружаются очень быстро (менее 100 мс), затраты на потоковую передачу того не стоят. Кроме того, потоковая SSR не обеспечивает постоянной интерактивности — для этого вам все равно нужен интерактивный режим рендеринга.

Улучшенная навигация и обработка форм

Одним из тонких, но мощных улучшений современного Blazor является улучшенная навигация. По умолчанию Blazor перехватывает клики по внутренним ссылкам и отправку форм, получая новое содержимое страницы через fetch и исправляя DOM вместо полной навигации по браузеру.

Это означает, что навигация между статическими страницами SSR ощущается как SPA — полная страница не мигает, положение прокрутки может быть сохранено, а работа очень плавная.

Как это работает

При загрузке скрипта Blazor (blazor.web.js) он автоматически перехватывает клики по внутренним ссылкам. Вместо традиционной навигации в браузере он:

Делает запрос fetch к целевому URL.
Получает ответ в формате HTML.
Объединяет новый контент с существующим DOM.
Обновляет URL-адрес и историю браузера.

Вам не нужно ничего делать, чтобы включить эту функцию — она включена по умолчанию. Но вы можете это контролировать:

[[[ТОК_11]]]

Улучшенная обработка форм

Формы обрабатываются одинаково. Когда вы используете EditForm или стандартный элемент <form> с обработкой формы Blazor, отправки перехватываются и обрабатываются через 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();
 }
}

Атрибут Enhance в EditForm указывает Blazor перехватить отправку формы. Форма отправляется на сервер, сервер обрабатывает ее и повторно отображает страницу, а обновленный HTML-код передается обратно — и все это без полноценной навигации по странице. Он кажется интерактивным, но полностью визуализируется на сервере.

Обратите внимание на атрибут [SupplyParameterFromForm] — именно так Blazor привязывает опубликованные данные формы к вашей модели в статических сценариях SSR. Это мост между традиционными формами и компонентной моделью Blazor.

Постраничная и покомпонентная интерактивность

Одним из наиболее мощных аспектов новой модели является то, что вы можете смешивать режимы рендеринга в одном приложении. Ваша страница со списком продуктов может быть статической SSR, ваша корзина покупок может быть Interactive Server, а конфигуратор вашего продукта может быть Interactive WebAssembly — и все это в одном приложении.

Настройка режимов рендеринга на уровне компонента

Вы можете установить режим рендеринга непосредственно на компоненте с помощью директивы @rendermode:

@* This component is interactive via Server *@
@rendermode InteractiveServer

<h3>Live Chat</h3>
<!-- chat UI here -->

Или вы можете установить его при использовании компонента из родителя:

@page "/product/{Id:int}"

<h1>@product?.Name</h1>
<p>@product?.Description</p>

<!-- This child component gets its own interactive render mode -->
<ProductConfigurator Product="product" @rendermode="InteractiveWebAssembly" />

<!-- This stays static -->
<ProductReviews ProductId="Id" />

@code {
 [Parameter] public int Id { get; set; }
 private Product? product;

 protected override async Task OnInitializedAsync()
 {
 product = await ProductService.GetByIdAsync(Id);
 }
}

В этом примере сама страница является статической SSR. Компонент ProductConfigurator работает на WebAssembly для обеспечения богатой интерактивности на стороне клиента. Компонент ProductReviews остается статическим, поскольку он просто отображает данные.

Глобальная настройка режимов рендеринга

Если вы хотите, чтобы все страницы были интерактивными по умолчанию, вы можете установить режим рендеринга на корневом уровне в App.razor:

<Routes @rendermode="InteractiveServer" />
```Это делает каждую страницу интерактивной посредством рендеринга на сервере. Отдельные компоненты все равно могут переопределить это, если это необходимо.

### Важные правила, которые следует запомнить

При смешивании режимов рендеринга следует учитывать несколько ограничений:

- **Дочерний компонент не может иметь более интерактивный режим рендеринга, чем его родительский компонент.** Если родительский компонент является статическим, дочерние элементы могут быть статическими или интерактивными. Но если родительским элементом является Interactive Server, дочерним элементом не может быть Interactive WebAssembly (он должен быть Server или Auto).
- **Интерактивные компоненты не могут напрямую использовать службы с ограниченной областью действия из статических родительских элементов.** Если компонент работает на WebAssembly, он не может напрямую обращаться к серверным экземплярам `DbContext` — вам понадобится уровень API.
— **Состояние не переключается автоматически между режимами рендеринга.** Если компонент выполняет предварительную отрисовку на сервере, а затем переключается на WebAssembly, вам необходимо явно обрабатывать сохранение состояния — подробнее об этом в разделе .NET 10.

## Что нового в .NET 10

.NET 10 продолжает подход постепенного улучшения, уделяя особое внимание надежности и опыту разработчиков. Вот основные моменты интерактивности Blazor:

### Улучшенный процесс повторного подключения

Если вы использовали режим интерактивного сервера в рабочей среде, вы, вероятно, сталкивались с наложением повторного подключения — моментом, когда соединение SignalR разрывается и пользователь видит сообщение «Повторное подключение...». В .NET 10 эта возможность становится значительно лучше.

Логика повторного подключения теперь более разумна в отношении повторных попыток. Вместо фиксированного интервала повторных попыток он использует стратегию отсрочки, которая адаптируется к ситуации. Пользовательский интерфейс во время повторного подключения также стал более совершенным, и у вас есть лучшие возможности для настройки:

```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 (или переключается между режимами отрисовки), состояние компонента теряется. Компонент эффективно повторно инициализируется, что может привести к дублированию выборок данных и мерцанию пользовательского интерфейса.

В .NET 10 улучшена служба PersistentComponentState для более плавной работы при переходах между режимами рендеринга:

@page "/weather"
@rendermode InteractiveWebAssembly
@inject PersistentComponentState ApplicationState

<h1>Weather Forecast</h1>

@if (forecasts is null)
{
 <p>Loading...</p>
}
else
{
 @foreach (var forecast in forecasts)
 {
 <div class="forecast-card">
 <h4>@forecast.Date.ToShortDateString()</h4>
 <p>@forecast.Summary — @forecast.TemperatureC°C</p>
 </div>
 }
}

@code {
 private List<WeatherForecast>? forecasts;
 private PersistingComponentStateSubscription persistingSubscription;

 protected override async Task OnInitializedAsync()
 {
 persistingSubscription = ApplicationState.RegisterOnPersisting(PersistData);

 if (!ApplicationState.TryTakeFromJson<List<WeatherForecast>>(
 "weather-forecasts", out var restored))
 {
 // Data wasn't persisted from prerendering — fetch it
 forecasts = await Http.GetFromJsonAsync<List<WeatherForecast>>("api/weather");
 }
 else
 {
 forecasts = restored;
 }
 }

 private Task PersistData()
 {
 ApplicationState.PersistAsJson("weather-forecasts", forecasts);
 return Task.CompletedTask;
 }

 public void Dispose()
 {
 persistingSubscription.Dispose();
 }
}

Благодаря улучшениям в .NET 10 этот шаблон работает более надежно. Состояние, сериализованное во время предварительного рендеринга, правильно доступно, когда компонент инициализируется в интерактивном режиме, что позволяет избежать двойной выборки данных и кратковременного мерцания, которое могут видеть пользователи.

Blazor Script как статический веб-ресурс

В предыдущих версиях файл JavaScript Blazor (blazor.web.js) обслуживался из внутренней конечной точки платформы. В .NET 10 он поставляется как статический веб-ресурс. Это может показаться небольшим изменением, но оно имеет практические преимущества:– Улучшенное кеширование. Статические веб-ресурсы получают правильные заголовки кэша и URL-адреса с отпечатками пальцев, поэтому браузеры кэшируют их более эффективно.

Удобство для CDN: поскольку это обычный статический файл, CDN могут кэшировать и обслуживать его из периферийных расположений. – Сжатие. Статическое сжатие веб-ресурсов применяется автоматически, уменьшая размер передаваемого сценария.

Вам не нужно менять способ ссылки на него — платформа автоматически обрабатывает обновленный путь.

Лучшие практики: выбор правильного режима рендеринга

После работы со всеми этими режимами в нескольких проектах, вот моя схема принятия решений:

Начните со статического SSR

Сделайте статический SSR по умолчанию. Большинство страниц в большинстве приложений предназначены в первую очередь для отображения данных. Страницы продуктов, сообщения в блогах, профили пользователей, страницы настроек — им не нужна интерактивность в реальном времени. Статический SSR обеспечивает наилучшую производительность, минимальное использование ресурсов и простейшую мысленную модель.

Добавляйте интерактивность только там, где это необходимо

Определите конкретные компоненты, которые должны реагировать на взаимодействия с пользователем в режиме реального времени. Кнопка «Мне нравится», виджет чата, интерфейс с возможностью перетаскивания — все это требует интерактивности. Но страница вокруг них, вероятно, этого не делает.

Используйте интерактивный автоматический режим в качестве интерактивного режима

Если вам действительно нужна интерактивность, Interactive Auto часто является лучшим выбором по умолчанию. Он обеспечивает быструю начальную загрузку (рендеринг на сервере) с последующим выполнением на стороне клиента (WebAssembly). Пользователь получает лучшее из обоих миров, а вы пишете свой код один раз.

Резервный интерактивный сервер для особых случаев

Используйте Interactive Server, когда:

Вашему компоненту необходим прямой доступ к ресурсам сервера (базам данных, файловой системе, внутренним API).
Размер загрузки WebAssembly вызывает беспокойство, и вы не можете использовать Auto.
Вам необходимо, чтобы компонент всегда запускался на сервере из соображений безопасности (например, для обработки конфиденциальных данных).

Щедро используйте потоковую SSR

Если ваши статические страницы SSR извлекают какие-либо данные, добавьте [StreamRendering]. Затраты минимальны, а ощутимое улучшение производительности значительно. Пользователи видят, что контент появляется постепенно, а не смотрит на пустую страницу.

Осторожно обращайтесь с переходами состояний

Если вы используете Interactive Auto или совмещаете предварительную визуализацию с WebAssembly, всегда используйте PersistentComponentState во избежание дублирования выборки данных. Ваши пользователи скажут вам спасибо за отсутствие мерцающего контента.

Помните о дереве компонентов

Помните правила иерархии режимов рендеринга. Спланируйте дерево компонентов так, чтобы интерактивные границы имели смысл. Распространенным шаблоном является наличие статического макета с интерактивными «островками», встроенными там, где это необходимо:

@* Layout: Static SSR *@
<header>
 <NavMenu />
 <UserMenu @rendermode="InteractiveServer" /> @* Needs real-time auth state *@
</header>

<main>
 @Body
</main>

<footer>
 <ChatWidget @rendermode="InteractiveAuto" /> @* Rich interactivity *@
</footer>

Заключение

Модель интерактивности Blazor в .NET 9 и .NET 10 представляет собой зрелый, хорошо продуманный подход к созданию веб-приложений. Возможность выбирать режимы рендеринга для каждого компонента, улучшенная плавная навигация, потоковая SSR, а также постоянные улучшения в переподключении и управлении состоянием делают его привлекательным выбором для широкого спектра приложений.Ключевой вывод заключается в том, что интерактивность — это спектр, а не бинарный выбор. Большая часть вашего приложения может быть статической. Некоторым частям требуется интерактивность, управляемая сервером. Некоторым может быть полезно работать в браузере. Blazor теперь позволяет вам сделать этот выбор с максимальной степенью детализации — отдельного компонента — без нарушения структуры.

Если вы начинаете новый проект, мой совет прост: создайте веб-приложение Blazor, начните со статического SSR, добавьте [StreamRendering] на страницы с большим объемом данных и переводите отдельные компоненты в интерактивные режимы только тогда, когда они вам нужны. В итоге вы получите быстрое, эффективное и хорошо масштабируемое приложение.

Удачного программирования. Как всегда, если у вас возникнут вопросы, обращайтесь!

Минимальные API в .NET: создание облегченных HTTP API

Thu, 10 Apr 2025 00:00:00 +0000

Если вы какое-то время создавали API с помощью ASP.NET Core, вы, вероятно, хорошо знакомы с подходом на основе контроллера: создайте класс контроллера, украсьте его атрибутами, внедрите свои сервисы через конструктор и соедините свои маршруты. Это работает, и работает хорошо, но иногда кажется, что вы пишете много церемоний, что означает «принять этот запрос, сделать что-нибудь, вернуть ответ».

Это именно та проблема, которую призваны решить минимальные API. Минимальные API, представленные в .NET 6, позволяют определять конечные точки HTTP с помощью минимального шаблонного кода. Никаких контроллеров, никаких атрибутов, никакой манипуляции с классами запуска — только прямое сопоставление маршрутов с обработчиками в чистом, функциональном стиле.

В этом посте я хочу познакомить вас со всем, что вам нужно знать о минимальных API: от вашей первой конечной точки до организации больших приложений, обработки аутентификации, проверки, документации OpenAPI и вопросов производительности. Давайте перейдем к этому.

Почему минимальные API?

Прежде чем мы начнем, давайте поговорим о том, почему вы предпочитаете минимальные API традиционному подходу на основе контроллера.

Контроллеры отлично подходят, когда вам нужна структурированная, продуманная структура. Они предоставляют вам привязку модели, фильтры, согласование контента и четкое разделение задач прямо из коробки. Для крупных корпоративных приложений с десятками разработчиков согласованность, которую обеспечивают контроллеры, может оказаться реальным преимуществом.

С другой стороны, минимальные API сияют, когда вам нужно:

Меньше шаблонов — нет классов контроллера, нет атрибутов [ApiController], нет отдельной конфигурации запуска.
Более быстрый запуск — меньше операций, связанных с отражением, во время загрузки.
Упрощенная ментальная модель — маршрут сопоставляется непосредственно с обработчиком. Вот и все.
Удобство для микросервисов — если ваш API имеет 5–10 конечных точек, полная настройка контроллера может показаться излишним.

Хорошей новостью является то, что это не решение «или-или». Вы можете смешивать контроллеры и минимальные API в одном проекте. Но как только вы освоитесь с минимальным подходом, вы, возможно, обнаружите, что будете обращаться к нему чаще, чем ожидали.

Начало работы

Давайте создадим минимальный API с нуля. Если у вас установлен .NET SDK, это так же просто, как:

[[[ТОК_1]]]

Это дает вам Program.cs, который выглядит примерно так:

[[[ТОК_3]]]

Вот и все. Это рабочий API. Нет Startup.cs, нет класса контроллера, нет конфигурации маршрутизации. Вы запускаете dotnet run, нажимаете http://localhost:5000 и получаете «Hello World!» назад. Вся суть здесь в простоте.

Давайте сделаем его немного более полезным с помощью классического API todo:

[[[ТОК_7]]]

У нас есть полный CRUD менее чем в 30 строках. В этом сила минимального подхода.

Обработчики маршрутов

Обработчики маршрутов — это функции, которые выполняются, когда запрос соответствует маршруту. У вас есть несколько вариантов их определения.

Лямбда-выражения

Самый распространенный подход и то, что вы увидите в большинстве примеров:

[[[ТОК_8]]]

Группы методов

Для более сложной логики вы можете указать именованный метод:

[[[ТОК_9]]]Это мой предпочтительный подход ко всему, что выходит за рамки однострочника. Он сохраняет раздел сопоставления маршрутов чистым и читабельным — вы можете сразу увидеть, какие конечные точки существуют, не вдаваясь в подробности реализации.

Локальные функции

Вы также можете использовать локальные функции, что полезно, если вы хотите, чтобы обработчики были близки к определениям их маршрутов:

[[[ТОК_10]]]

Привязка параметра

Одна из вещей, которые мне очень нравятся в минимальных API, — это интуитивно понятное связывание параметров. Платформа определяет, откуда брать значения, в зависимости от контекста и типа.

Параметры маршрута

[[[ТОК_11]]]

Параметры строки запроса

[[[ТОК_12]]]

Типы, допускающие значение 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);
});

Это невероятно мощно. Вы определяете логику привязки один раз и повторно используете ее на всех своих конечных точках.

Проверка

Одна из областей, в которой минимальные API не дают вам столько возможностей по сравнению с контроллерами, — это проверка модели. Автоматического применения [Required] или [StringLength] не предусмотрено. Но есть четкие шаблоны для решения этой проблемы.

Ручная проверка

Самый простой подход — просто валидируем в обработчике:

app.MapPost("/users", (CreateUserRequest request) =>
{
 if (string.IsNullOrWhiteSpace(request.Email))
 return Results.BadRequest(new { Error = "Email is required" });

 if (request.Name?.Length > 100)
 return Results.BadRequest(new { Error = "Name must be 100 characters or less" });

 // Create user...
 return Results.Created($"/users/{request.Email}", request);
});

Использование библиотеки проверки

Для чего-то нетривиального я бы рекомендовал использовать FluentValidation или аналогичную библиотеку:

public class CreateUserValidator : AbstractValidator<CreateUserRequest>
{
 public CreateUserValidator()
 {
 RuleFor(x => x.Email).NotEmpty().EmailAddress();
 RuleFor(x => x.Name).NotEmpty().MaximumLength(100);
 RuleFor(x => x.Age).InclusiveBetween(0, 150);
 }
}

Вы можете подключить это к своим конечным точкам через фильтры конечных точек, что подводит нас к следующему разделу.

Фильтры конечных точек

Фильтры конечных точек — одна из лучших функций минимальных API. Думайте о них как о промежуточном программном обеспечении, но ограниченном конкретными конечными точками, а не всем конвейером. Они были представлены в .NET 7 и отлично подходят для решения сквозных задач.

Базовый фильтр

app.MapPost("/todos", (Todo todo) =>
{
 // Handle the request
 return Results.Created($"/todos/{todo.Id}", todo);
})
.AddEndpointFilter(async (context, next) =>
{
 var todo = context.GetArgument<Todo>(0);

 if (string.IsNullOrEmpty(todo.Title))
 {
 return Results.BadRequest(new { Error = "Title is required" });
 }

 return await next(context);
});

Фильтр проверки с FluentValidation

Вот где он становится действительно мощным — многоразовый фильтр проверки:

public class ValidationFilter<T> : IEndpointFilter where T : class
{
 private readonly IValidator<T> _validator;

 public ValidationFilter(IValidator<T> validator)
 {
 _validator = validator;
 }

 public async ValueTask<object?> InvokeAsync(
 EndpointFilterInvocationContext context,
 EndpointFilterDelegate next)
 {
 var model = context.Arguments
 .OfType<T>()
 .FirstOrDefault();

 if (model is null)
 return Results.BadRequest(new { Error = "Request body is required" });

 var result = await _validator.ValidateAsync(model);

 if (!result.IsValid)
 {
 var errors = result.Errors
 .GroupBy(e => e.PropertyName)
 .ToDictionary(g => g.Key, g => g.Select(e => e.ErrorMessage).ToArray());

 return Results.ValidationProblem(errors);
 }

 return await next(context);
 }
}

// Usage
app.MapPost("/users", (CreateUserRequest request) =>
{
 // Only reached if validation passes
 return Results.Created($"/users/{request.Email}", request);
})
.AddEndpointFilter<ValidationFilter<CreateUserRequest>>();

Фильтр журналов

app.MapGet("/products", (AppDbContext db) => db.Products.ToList())
 .AddEndpointFilter(async (context, next) =>
 {
 var logger = context.HttpContext
 .RequestServices.GetRequiredService<ILogger<Program>>();

 var sw = Stopwatch.StartNew();
 var result = await next(context);
 sw.Stop();

 logger.LogInformation("Endpoint executed in {Elapsed}ms", sw.ElapsedMilliseconds);

 return result;
 });

Вы можете объединить несколько фильтров, и они будут выполняться в том порядке, в котором они добавлены — точно так же, как промежуточное программное обеспечение.

Интеграция OpenAPI/Swagger

Хорошая документация по API больше не является обязательной. К счастью, минимальные API имеют первоклассную поддержку OpenAPI через пакет Microsoft.AspNetCore.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;
 });

Это дает вам тот же уровень управления документацией, который вы получаете с XML-комментариями Swashbuckle к контроллерам, но более явным способом, ориентированным на код.

Аутентификация и авторизация

Защита конечных точек минимального 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 непосредственно в параметры вашего обработчика — обо всем остальном позаботится инфраструктура. Это одна из тех мелочей, благодаря которым минимальные API выглядят по-настоящему элегантно.

Организация больших API

Слон в комнате с минимальными API — это организация. Когда ваш Program.cs имеет 50 конечных точек, это становится беспорядком. Вот шаблоны, которые я использую, чтобы все было управляемо.

Группы маршрутов

Группы маршрутов (представленные в .NET 7) позволяют совместно использовать конфигурацию между связанными конечными точками:

var todos = app.MapGroup("/todos")
 .WithTags("Todos")
 .RequireAuthorization();

todos.MapGet("/", (AppDbContext db) => db.Todos.ToListAsync());
todos.MapGet("/{id:int}", (int id, AppDbContext db) => db.Todos.FindAsync(id));
todos.MapPost("/", (Todo todo, AppDbContext db) =>
{
 db.Todos.Add(todo);
 db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
});

Все конечные точки в группе имеют общий префикс /todos, тег Todos и требование авторизации. Чистый.

Методы расширения

Это модель, которая действительно масштабируется. Переместите каждую группу конечных точек в отдельный статический класс:

// Endpoints/TodoEndpoints.cs
public static class TodoEndpoints
{
 public static RouteGroupBuilder MapTodoEndpoints(this WebApplication app)
 {
 var group = app.MapGroup("/todos").WithTags("Todos");

 group.MapGet("/", GetAll);
 group.MapGet("/{id:int}", GetById);
 group.MapPost("/", Create);
 group.MapPut("/{id:int}", Update);
 group.MapDelete("/{id:int}", Delete);

 return group;
 }

 private static async Task<IResult> GetAll(AppDbContext db)
 => Results.Ok(await db.Todos.ToListAsync());

 private static async Task<IResult> GetById(int id, AppDbContext db)
 => await db.Todos.FindAsync(id) is { } todo
 ? Results.Ok(todo)
 : Results.NotFound();

 private static async Task<IResult> Create(Todo todo, AppDbContext db)
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 }

 private static async Task<IResult> Update(int id, Todo updated, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 todo.Title = updated.Title;
 todo.IsComplete = updated.IsComplete;
 await db.SaveChangesAsync();

 return Results.Ok(todo);
 }

 private static async Task<IResult> Delete(int id, AppDbContext db)
 {
 var todo = await db.Todos.FindAsync(id);
 if (todo is null) return Results.NotFound();

 db.Todos.Remove(todo);
 await db.SaveChangesAsync();

 return Results.NoContent();
 }
}

// Program.cs — stays clean
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapTodoEndpoints();
app.MapUserEndpoints();
app.MapOrderEndpoints();

app.Run();

Ваш Program.cs становится оглавлением вашего API. Каждая группа конечных точек находится в своем собственном файле. Именно такой подход я рекомендую для производственных приложений.

Библиотека Картера

Если вам нужно еще больше структуры, библиотека Carter предлагает подход на основе модулей:

public class TodoModule : ICarterModule
{
 public void AddRoutes(IEndpointRouteBuilder app)
 {
 app.MapGet("/todos", async (AppDbContext db) =>
 await db.Todos.ToListAsync());

 app.MapPost("/todos", async (Todo todo, AppDbContext db) =>
 {
 db.Todos.Add(todo);
 await db.SaveChangesAsync();
 return Results.Created($"/todos/{todo.Id}", todo);
 });
 }
}

Картер автоматически обнаруживает и регистрирует все модули. Это хорошая золотая середина между необработанным подходом минимального API и полноценными контроллерами.

Типизированные результаты и типы ответов

Начиная с .NET 7, вы можете использовать TypedResults вместо Results для типобезопасных ответов. Это может показаться небольшим изменением, но оно имеет реальные преимущества для документирования и тестируемости 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 во всех новых проектах. Компилятор выявляет несоответствия между объявленными типами возвращаемых данных и тем, что вы на самом деле возвращаете, что устраняет целый класс неожиданностей во время выполнения.

Вопросы производительности

Одним из преимуществ минимальных API является производительность, и стоит понять, почему они быстрее.

Сокращение затрат при запуске. Контроллеры в значительной степени полагаются на отражение при обнаружении конечных точек, привязке моделей и применении фильтров. Минимальные API используют генераторы исходного кода (начиная с .NET 7) для создания кода привязки во время компиляции. Это означает меньше работы при запуске и меньшее выделение памяти на запрос.

Нет конвейера MVC. API на основе контроллера проходят через полный конвейер MVC: выбор действия, привязка модели, фильтры действий, выполнение результатов. Минимальные API пропускают все это и сразу переходят от маршрутизации к вашему обработчику.

Компиляция RequestDelegate. Платформа компилирует ваши лямбда-выражения в оптимизированные экземпляры RequestDelegate . Полученный код очень близок к тому, что вы написали бы вручную, если бы работали напрямую с HttpContext.

Вот несколько практических советов по повышению производительности:

// Use AsNoTracking for read-only queries
app.MapGet("/products", async (AppDbContext db) =>
 await db.Products.AsNoTracking().ToListAsync());

// Return results directly — avoid unnecessary allocations
app.MapGet("/count", async (AppDbContext db) =>
 await db.Products.CountAsync());

// Use cancellation tokens for long-running operations
app.MapGet("/report", async (AppDbContext db, CancellationToken ct) =>
 await db.Orders
 .AsNoTracking()
 .GroupBy(o => o.Status)
 .Select(g => new { Status = g.Key, Count = g.Count() })
 .ToListAsync(ct));
```Также стоит отметить, что разрыв в производительности между контроллерами и минимальными API продолжает сокращаться с каждым выпуском .NET. Для большинства приложений разница будет не вашим узким местом — вашими запросами к базе данных и вызовами внешних служб. Выбирайте, основываясь на опыте разработчиков и потребностях проекта, а не на тестах.

## Заключение

Минимальные API прошли долгий путь с момента их появления в .NET 6. То, что начиналось как демонстрационная функция «привет, мир», превратилось в законный выбор для рабочих API. Благодаря фильтрам конечных точек, группам маршрутов, типизированным результатам и надежной поддержке OpenAPI у вас есть все необходимое для создания хорошо структурированных и удобных в обслуживании сервисов.

Моя рекомендация? Если вы начинаете новый проект API — особенно микросервис или специализированный внутренний API — серьезно попробуйте Minimal API. Используйте шаблон метода расширения для организации, используйте фильтры конечных точек для решения сквозных задач и используйте `TypedResults` для обеспечения безопасности типов.

Для существующих проектов на базе контроллеров мигрировать не нужно. Оба подхода работают хорошо, и вы даже можете использовать их одновременно. Но в следующий раз, когда вам понадобится добавить небольшой сервис или быстрый внутренний API, пропустите контроллеры и используйте минимум. Ты можешь не вернуться.

Приятного кодирования!

Использование изолированного CSS в компонентах Blazor

Wed, 12 Mar 2025 00:00:00 +0000

При работе с Blazor меня всегда беспокоило то, насколько легко случайно нарушить стили разных компонентов. Вы добавляли класс в один компонент, и внезапно что-то еще на совершенно другой странице выглядело не так. Оказывается, у Blazor есть встроенное решение для этой проблемы: изоляция CSS.

Что такое изоляция CSS?

Изоляция CSS позволяет ограничить стили конкретным компонентом. Blazor делает это, генерируя уникальный атрибут для каждого компонента во время сборки и добавляя его к селекторам CSS. Таким образом, ваши стили применяются только к тому компоненту, которому они принадлежат.

Нет необходимости в БЭМ-именовании, нет необходимости в сумасшедших хаках со спецификой. Просто чистый CSS с ограниченной областью действия.

Как его использовать

Допустим, у вас есть компонент под названием Card.razor:

[[[ТОК_1]]]

Чтобы добавить изолированные стили, вы просто создаете файл с тем же именем, но с расширением .razor.css. В данном случае: Card.razor.css.

[[[ТОК_4]]]

И все! Blazor автоматически подберет его и распространит эти стили только на компонент Card. Если у вас есть другой класс .card где-то еще, это не повлияет.

Как это работает под капотом

Когда вы создаете свой проект, Blazor переписывает HTML и CSS. Ваш компонент получает уникальный атрибут, например b-3x8qz7k2f1, а селекторы CSS добавляют этот атрибут:

[[[ТОК_8]]]

Сгенерированный пакет CSS обслуживается как {ProjectName}.styles.css. Убедитесь, что это есть в вашем index.html или _Host.cshtml:

[[[ТОК_12]]]

Если вам не хватает этой ссылки, ваши изолированные стили не будут отображаться, и вы потратите 30 минут, задаваясь вопросом, что происходит. Поверьте мне, я был там.

Нацеливание на дочерние элементы

Следует иметь в виду, что по умолчанию изолированный CSS применяется только к элементам текущего компонента. Если вы хотите стилизовать элементы внутри дочернего компонента, вам понадобится комбинатор ::deep:

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

Это говорит Blazor применять стиль и к совпадающим элементам внутри дочерних компонентов. Очень удобно, когда у вас есть компонент-оболочка, которому нужно стилизовать своих дочерних элементов.

Когда его использовать

Сейчас я использую изоляцию CSS практически для каждого компонента. Это делает вещи чистыми и предсказуемыми. Единственный раз, когда я не использую его, — это для действительно глобальных стилей, таких как сброс, типографика или переменные темы — они хранятся в общем файле CSS.

Надеюсь, вам понравился пост! Не стесняйтесь обращаться ко мне в любой социальной сети по адресу @emimontesdeoca.

Ресурсы

Изоляция CSS ASP.NET Core Blazor

Контроль рождественских расходов с помощью Semantic Kernel

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

## Введение

По мере приближения курортного сезона управление расходами может стать проблемой, особенно с учетом большого количества покупок и покупок подарков. В этой записи блога мы рассмотрим, как использовать искусственный интеллект, чтобы отслеживать ваши рождественские расходы с помощью технологий .NET. Анализируя квитанции с помощью семантического ядра и искусственного интеллекта, мы можем эффективно извлекать ключевые детали, такие как названия магазинов, даты, списки товаров и общие суммы. Это решение позволяет вам легко отслеживать и управлять своими рождественскими расходами, гарантируя, что вы будете оставаться в рамках своего бюджета без необходимости вручную проверять квитанции.

Calendario de Adviento de Inteligencia Artificial 2024 на испанском языке

Этот проект был вдохновлен моим участием в Calendario de Adviento de Inteligencia Artificial 2024 en Español, онлайн-мероприятии, посвященном искусственному интеллекту. Дополнительную информацию о мероприятии можно найти по ссылке Dev.to.

Проект

В этом проекте мы будем использовать Azure OpenAI, сервис, который позволяет нам использовать мощные модели искусственного интеллекта, такие как GPT-4, для обработки и анализа изображений. Этот процесс включает в себя несколько этапов: от настройки внутренней службы API до интеграции с внешним интерфейсом Blazor для загрузки изображений. Мы также будем использовать .NET Aspire, компонент, который помогает легко соединить все.

Предварительные условия

Прежде чем мы углубимся в код, убедитесь, что у вас есть следующие предварительные условия:

.NET 9
Доступ к Azure OpenAI (ключ API)
Visual Studio или код Visual Studio
Базовые знания Blazor, HTTP-клиентов и разработки API.

Решение Visual Studio

В конечном итоге у нас получится что-то вроде этого. Мне нравится, когда все вещи разделены и имеют классные названия, вот как это выглядит:

Но давайте шаг за шагом создавать вещи!

Шаг 0: Модели

Ядро приложения Receipt Scanner опирается на несколько ключевых моделей, которые облегчают взаимодействие между внешним интерфейсом, API и службами искусственного интеллекта. Ниже приведены основные модели, использованные в этом проекте:

АнализReceiptRequest
Эта модель представляет собой структуру запроса для анализа чека. Он содержит свойство ImageBytes, которое содержит массив байтов изображения чека, который будет обработан.

[[[ТОК_4]]]
ReceiptAnalyzeResult
Эта модель фиксирует результат после обработки квитанции. Он содержит структурированные данные, извлеченные из квитанции, такие как название магазина, дата, товары и общая сумма.
```
public class ReceiptAnalyzeResult
{
 public DateTime CreatedAt { get; set; }
 public ReceiptData Result { get; set; }
}
```
Данные квитанции
Это модель, содержащая структурированные данные квитанции. Он включает в себя свойства названия магазина, даты, списка товаров (с названием и ценой каждого товара) и общую сумму в чеке.

[[[ТОК_6]]]
Элемент получения
Каждый товар в чеке представлен этой моделью. Он содержит название товара и его цену.

[[[ТОК_7]]]Эти модели служат основой для передачи данных между клиентом и сервером, обеспечивая плавный поток информации. API получает изображение квитанции и взамен обрабатывает и возвращает структурированный объект JSON, который может быть легко использован внешним интерфейсом.

Шаг 1. Настройка внутренней службы API

Первым шагом в создании этого приложения является настройка службы API для анализа изображений квитанций. Мы будем использовать API Azure OpenAI для извлечения информации из изображений квитанций. Вот разбивка того, как все сочетается друг с другом:

Служба искусственного интеллекта – глубокое погружение

Служба искусственного интеллекта лежит в основе нашей системы анализа квитанций. Он отвечает за взаимодействие с API Azure OpenAI для обработки данных изображения и получения значимой информации. Класс AiApiClient — это клиент, который будет обрабатывать все взаимодействия с API Azure OpenAI.

Реализация AI-клиента

AiApiClient — это ключевой компонент, отвечающий за отправку изображения квитанции (в формате массива байтов) в API Azure OpenAI. Он управляет связью, регистрирует ошибки и анализирует данные:

[[[ТОК_9]]]

В этой части кода мы определяем метод AnalyzeAsync, который отвечает за:

Отправка массива байтов изображения в API Azure OpenAI.
Обработка любых ошибок или неудачных ответов API.
Анализ возвращенных данных JSON в структурированный результат (ReceiptAnalyzeResult).

Преимущества выделения этой функции в выделенную службу (AiApiClient) включают в себя:

Обработка ошибок. Централизованная обработка ошибок, таких как проблемы с сетью или неверные ответы.
Журналирование: Надлежащее протоколирование запросов и ответов для мониторинга поведения системы.

Служба API — обработка запросов и ответов

Служба API выступает в качестве посредника между интерфейсным приложением Blazor и службой AI. Эта служба отвечает за прием данных изображения, передачу их службе AI и возврат результатов анализа клиенту.

Конечная точка API

На этом этапе мы определяем простую конечную точку API, которая будет принимать изображения квитанций, пересылать их в службу AI для обработки и возвращать результаты клиенту:

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

Эта конечная точка:

Принимает изображение квитанции как часть тела запроса.
Вызывает метод endopint AiService для отправки изображения в Azure OpenAI для обработки.
Возвращает результат анализа обратно клиенту.

Шаг 2. Настройка внешнего интерфейса Blazor

Теперь, когда у нас настроена серверная часть, давайте обратим внимание на интерфейс Blazor. Здесь пользователи могут загружать изображения своих квитанций для анализа и видеть результаты.

Реализация страницы Blazor

Страница Blazor предоставляет простой интерфейс, в котором пользователи могут загружать несколько изображений квитанций, а затем просматривать результаты анализа, отображаемые в таблице. Вот код страницы:

@page "/analyzer"
@using ReceiptScanner.Shared.Clients
@using ReceiptScanner.Shared.Models
@using System.Globalization
@inject ApiServiceClient ApiClient
@inject ILogger<Program> Logger

@attribute [StreamRendering]
@rendermode InteractiveServer

<PageTitle>Receipt Analyzer</PageTitle>

<h1 class="text-center my-4">Receipt Analyzer</h1>

<div class="container">
 <p class="lead text-center mb-4">Upload receipt images below to extract their data.</p>

 <!-- File Upload Section -->
 <div class="card mb-4">
 <div class="card-body">
 <InputFile OnChange="HandleFileSelected" multiple class="form-control mb-3" />
 <button class="btn btn-primary w-100" @onclick="ProcessReceipts" disabled="@(!hasFiles)" type="button">
 <span class="@(!processing ? "d-none" : "") spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>
 @if (processing)
 {
 <span>Processing...</span>
 }
 else
 {
 <span>Process Receipts</span>
 }
 </button>
 </div>
 </div>

 <!-- Uploaded Images Preview -->
 @if (fileBytesList.Any())
 {
 <div class="card mb-4">
 <div class="card-header">
 <h5 class="mb-0">Uploaded Receipt Images</h5>
 </div>
 <div class="card-body">
 <div class="row">
 @foreach (var fileBytes in fileBytesList)
 {
 <div class="col-12 col-md-4 mb-3">
 <img src="@($"data:image/jpeg;base64,{Convert.ToBase64String(fileBytes)}")" class="img-fluid rounded" alt="Uploaded receipt" />
 </div>
 }
 </div>
 </div>
 </div>
 }

 <!-- Processing Indicator -->
 @if (processing)
 {
 <div class="alert alert-info text-center" role="alert">
 <strong>Processing receipts...</strong> Please wait while we analyze the uploaded files.
 </div>
 }

 <!-- Analysis Results Section -->
 @if (analyzedReceipts != null && analyzedReceipts.Any())
 {
 <div class="card">
 <div class="card-header">
 <h5 class="mb-0">Analysis Results</h5>
 </div>
 <div class="card-body">
 <table class="table table-striped table-bordered">
 <thead>
 <tr>
 <th>Store</th>
 <th>Date</th>
 <th>Total</th>
 <th>Items</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var receipt in analyzedReceipts)
 {
 <tr>
 <td>@(receipt.Result?.Store ?? "Unknown")</td>
 <td>@(receipt.Result?.Date?.ToString() ?? "Unknown")</td>
 <td>@(receipt.Result?.Total?.ToString("C", ci) ?? "Unknown")</td>
 <td>
 <ul class="list-unstyled">
 @if (receipt.Result?.Items is not null)
 {
 @foreach (var item in receipt.Result?.Items!)
 {
 <li><strong>@item.Name</strong> - @item.Price?.ToString("C", ci)</li>
 }
 }
 </ul>
 </td>
 </tr>
 }
 </tbody>
 </table>
 </div>
 </div>
 }
 else if (processed && (analyzedReceipts == null || !analyzedReceipts.Any()))
 {
 <div class="alert alert-warning text-center" role="alert">
 <strong>No results found.</strong> Please try again with different images or ensure they are clear and legible.
 </div>
 }
</div>

@code {
 private bool hasFiles;
 private bool processing;
 private bool processed;
 private List<byte[]> fileBytesList = new();
 private List<ReceiptAnalyzeResult> analyzedReceipts = new();
 CultureInfo ci = new CultureInfo("es-es");

 private async Task HandleFileSelected(InputFileChangeEventArgs e)
 {
 try
 {
 fileBytesList.Clear();

 foreach (var file in e.GetMultipleFiles())
 {
 var memoryStream = new MemoryStream();
 await file.OpenReadStream().CopyToAsync(memoryStream);
 fileBytesList.Add(memoryStream.ToArray());
 }

 hasFiles = fileBytesList.Any();
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while handling file upload.");
 }
 }

 private async Task ProcessReceipts()
 {
 if (!hasFiles)
 return;

 processing = true;
 analyzedReceipts.Clear();

 try
 {
 foreach (var fileBytes in fileBytesList)
 {
 var result = await ApiClient.AnalyzeReceiptAsync(fileBytes);
 if (result != null)
 {
 analyzedReceipts.Add(result);
 }
 }
 }
 catch (Exception ex)
 {
 Logger.LogError(ex, "Error while processing receipts.");
 }
 finally
 {
 processing = false;
 processed = true;
 }
 }
}

```Эта страница позволяет пользователям загружать квитанции и отображает результаты анализа в таблице с названиями магазинов, датами, общими суммами и списком товаров.

<p выравнивание="центр">
<img src="https://imgur.com/BLswKhm.png">
</p>

## Шаг 3: .NET Aspire

<p выравнивание="центр">
<img src="https://imgur.com/ja56RWN.png">
</p>

### Что такое .NET Aspire?

.NET Aspire — это набор мощных инструментов, шаблонов и пакетов для создания наблюдаемых, готовых к использованию приложений. .NET Aspire поставляется в виде набора пакетов NuGet, которые решают специфические проблемы облачной среды. Облачные приложения часто состоят из небольших взаимосвязанных частей или микросервисов, а не из единой монолитной базы кода. Облачные приложения обычно используют большое количество сервисов, таких как базы данных, обмен сообщениями и кэширование. Информацию о поддержке см. в Политике поддержки .NET Aspire.

Распределенное приложение — это приложение, которое использует вычислительные ресурсы на нескольких узлах, например контейнерах, работающих на разных хостах. Такие узлы должны обмениваться данными через границы сети, чтобы доставлять ответы пользователям. Облачное приложение — это особый тип распределенного приложения, которое в полной мере использует преимущества масштабируемости, устойчивости и управляемости облачных инфраструктур.

Использование **.NET Aspire** для этого проекта дает ряд преимуществ, улучшающих общее качество системы, например:

### 1. **Централизованное ведение журнала**

.NET Aspire автоматически интегрирует ведение журнала во всем приложении, что означает, что вам не придется вручную настраивать ведение журнала для каждой службы. Это гарантирует согласованность журналов и их централизованное хранение, что значительно упрощает отладку и мониторинг.

Например, класс `AiApiClient` использует журналирование для записи байтов изображения, отправленных в службу AI, ответов API и любых ошибок, возникающих в процессе анализа.

```csharp
_logger.LogInformation("Sending analyze request with image bytes of length: {Length}",

 imageBytes.Length);

2. Автоматический сбор показателей

.NET Aspire также автоматически отслеживает и сообщает важные показатели приложения, такие как время ответа, количество запросов и частота ошибок. Это поможет вам понять, как работает приложение, и быстро обнаружить любые узкие места или проблемы.

3. Улучшенная производительность

.NET Aspire оптимизирует HTTP-вызовы, что помогает сократить время ответа и сократить ненужное потребление ресурсов. Он предоставляет такие функции, как объединение пулов соединений, повторные попытки запросов и интеллектуальную маршрутизацию.

4. Бесшовная интеграция

.NET Aspire упрощает интеграцию различных сервисов (например, сервисов искусственного интеллекта и API в этом проекте) и оптимизирует процесс развертывания. Вам не нужно беспокоиться о низкоуровневых конфигурациях, поскольку Aspire позаботится о задачах, связанных с инфраструктурой, за вас.

ЗаключениеИИ больше не является просто модным словечком или чем-то, что мы видим в научно-фантастических фильмах. Сегодня он активно решает реальные проблемы, подобные той, которую мы решали в этом проекте — извлечение структурированных данных из квитанций. С помощью Azure OpenAI, .NET Aspire и Blazor мы можем автоматизировать то, что в противном случае было бы трудоемким и подверженным ошибкам ручным заданием. ИИ не просто общается или отвечает на запросы, такие как ChatGPT; он интерпретирует изображения, извлекает ценную информацию и дает нам ценную информацию за считанные секунды.

Используя Azure OpenAI для анализа квитанций и .NET Aspire для плавной интеграции с журналами и метриками, мы создали мощное и масштабируемое решение. Потенциал искусственного интеллекта для оптимизации бизнес-процессов, автоматизации утомительных задач и повышения точности огромен, и это лишь один пример того, как его можно применить.

Этот пост является частью Calendario de Adviento de Inteligencia Artificial 2024 en Español — мероприятия, которое демонстрирует реальные приложения искусственного интеллекта и знакомит испаноязычное технологическое сообщество с последними тенденциями. Если вы хотите глубже погрузиться в искусственный интеллект и его возможности, это мероприятие — отличное место для начала.

ИИ меняет то, как мы работаем, и этот проект — лишь проблеск того, что возможно. Настоящая сила ИИ заключается в его способности решать реальные проблемы — будь то обработка квитанций, анализ изображений или прогнозирование тенденций. Мы только царапаем поверхность.

Исходный код

Полный исходный код этого проекта доступен на GitHub. Не стесняйтесь загружать его, изучать, как службы искусственного интеллекта и API работают вместе, и адаптировать его для своих собственных сценариев использования. Если у вас возникнут какие-либо проблемы или у вас есть идеи по улучшению, не стесняйтесь создавать проблему или отправлять запрос на включение. Вклад всегда приветствуется, а ваши отзывы помогут сделать этот проект еще лучше!

Приятного кодирования!

Используете контейнеры, чтобы... отслеживать цены на рождественские подарки?

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

Рождество не за горами, а вместе с ним и радостная задача найти идеальные подарки для близких. Если вы чем-то похожи на меня, вы, вероятно, любите заключать выгодные сделки, но ориентироваться в стремительно растущих ценах на популярные товары во время курортного сезона может показаться настоящей поездкой на санях — захватывающей, но немного ошеломляющей! В этом году вместо того, чтобы сводить себя с ума ежедневными проверками цен, я решил найти хорошее применение своим техническим навыкам и автоматизировать процесс.

Как разработчик программного обеспечения и человек, увлеченный использованием технологий для решения повседневных проблем, я нашел способ автоматизировать процесс проверки цен. Вместо того, чтобы каждый день вручную посещать несколько интернет-магазинов для сравнения цен, я решил создать систему, которая сможет сделать это за меня. Это не только экономит время, но и гарантирует, что я получу лучшие предложения без стресса от ежедневных проверок.

Зачем автоматизировать мониторинг цен?

Автоматизировать мониторинг цен — это все равно, что ваша собственная команда эльфов Санты работает круглосуточно, чтобы гарантировать, что вы получите лучшие предложения, не пошевелив и пальцем. Вот почему вам это понравится:

Дорогие предметы. Мы все знаем, что рождественские подарки могут оказаться довольно дорогими, особенно если в вашем списке есть гаджеты и игрушки. Экономия на них может быть столь же приятной, как и поиск последней вершины дерева на складе.
Ежедневные проверки. У кого есть время (или терпение) проверять цены каждый день? Не я!
Автоматизация. Ощутите праздничный дух щедрости — подарите себе эффективность.
Точность. Автоматизация гарантирует, что ваши проверки цен будут такими же точными, как у Рудольфа блестящий нос.

Основные технологии

Чтобы создать своего маленького помощника Санты, я решил использовать несколько ключевых технологий:

Контейнеры

Контейнеры — это своего рода рождественская упаковка для программного обеспечения. Они объединяют ваши приложения со всеми их вкусностями (зависимостями), так что все работает так же гладко, как поездка на санях по свежему снегу. Docker — наш инструмент для создания таких контейнеров.

Блазор

Blazor — это отличная платформа для создания интерактивных веб-приложений с использованием .NET. Это все равно что заменить обычные рождественские гимны собственным праздничным плейлистом — адаптированным, эффективным и очень веселым.

Docker-Compose

Docker-Compose — менеджер по эксплуатации нашего Северного полюса. Это помогает нам поддерживать идеальную совместную работу всех наших сервисов, таких как API и интерфейс Blazor. Думайте о нем как о дирижере нашей праздничной симфонии.

Пошаговое руководство

А теперь давайте окунемся в мастерскую Санты и воплотим этот проект в жизнь!

Шаг 1. Создание API

1.1 Настройка проекта

Наденьте шляпу Санты-кодировщика и настройте новый проект веб-API ASP.NET Core. Откройте терминал (это немного похоже на открытие адвент-календаря) и запустите:

[[[ТОК_1]]]

Эта команда создает новый каталог с именем PriceMonitorApi и настраивает базовый проект веб-API. Представьте, что это похоже на создание прочной основы для пряничного домика.

1.2 Добавление HttpClient и библиотек парсингаЗатем добавьте `HttpClient` и библиотеку для анализа HTML. Это будут наши верные сани для получения и чтения данных о ценах.

[[[ТОК_4]]]

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 Реализация службы парсера

Наш парсерный сервис похож на маленького помощника Санты: он собирает и обрабатывает для нас информацию:

[[[ТОК_6]]]

Этот фрагмент превращает наш HtmlAgilityPack в праздничную волшебную палочку.

1.5 Создание API-контроллера

Давайте создадим контроллер, который будет действовать как привратник наших данных:

[[[ТОК_8]]]

Наш контроллер обеспечивает доставку данных быстрее, чем Санта в дымоход.

1.6 Регистрация сервисов в DI-контейнере

Наконец, зарегистрируйте свой ScraperService, чтобы он был доступен при необходимости.

[[[ТОК_10]]]

Теперь ваш API готов — как сани Санты в канун Рождества!

Шаг 2. Создание приложения Blazor

Blazor помогает нам украсить наш проект как рождественскую елку, сделав его визуально привлекательным и интерактивным.

2.1 Настройка проекта Blazor

Далее мы создадим проект Blazor, который будет служить интерфейсом для нашей поездки на санях для мониторинга цен.

[[[ТОК_11]]]

Эта команда добавляет немного праздничного волшебства для настройки базового проекта Blazor WebAssembly.

2.2 Добавление моделей

Так же, как и при настройке орнаментов, добавьте модель ProductInfo в проект Blazor:

namespace PriceMonitorBlazor.Models
{
 public class ProductInfo
 {
 public string Title { get; set; }
 public decimal Price { get; set; }
 public DateTime Date { get; set; }
 }
}

2.3 Создание службы для вызовов API

Создайте сервис для получения данных из нашего API — думайте о нем как о нашем приятеле по онлайн-шоппингу:

using PriceMonitorBlazor.Models;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"https://localhost:5001/api/scraper/productinfo?url={url}");
 return response;
 }
 }
}

2.4 Регистрация служб в DI-контейнере

Убедитесь, что ScraperService зарегистрирован, чтобы мы могли внедрить его в наши компоненты.

builder.Services.AddScoped<ScraperService>();

2.5 Создание компонента Blazor

Обновите Pages/Index.razor для включения интересного и интерактивного интерфейса:

@page "/"
@using PriceMonitorBlazor.Models
@using PriceMonitorBlazor.Services
@inject ScraperService ScraperService

<h3>Price Monitor</h3>

<p>
 <label for="urlInput">Product URL:</label>
 <input id="urlInput" @bind="productUrl" />
 <button @onclick="FetchProductInfo">Fetch Price</button>
</p>

@if (productInfos.Any())
{
 <table class="table">
 <thead>
 <tr>
 <th>Title</th>
 <th>Price</th>
 <th>Date</th>
 </tr>
 </thead>
 <tbody>
 @foreach (var product in productInfos)
 {
 <tr>
 <td>@product.Title</td>
 <td>@product.Price</td>
 <td>@product.Date</td>
 </tr>
 }
 </tbody>
 </table>
}

@code {
 private string productUrl;
 private List<ProductInfo> productInfos = new List<ProductInfo>();

 private async Task FetchProductInfo()
 {
 if (!string.IsNullOrEmpty(productUrl))
 {
 var productInfo = await ScraperService.GetProductInfoAsync(productUrl);
 productInfos.Add(productInfo);
 }
 }
}

Это похоже на праздничную презентацию — сделать наше приложение интерактивным и восхитительным.

Шаг 3. Соединяем все с помощью Docker-Compose

Теперь давайте соединим все с помощью Docker-Compose, превратив наш проект в отлаженную поездку на санях.

3.1 Создание Dockerfiles

Создайте файлы Dockerfile для проектов API и Blazor:

PriceMonitorApi/Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorApi/PriceMonitorApi.csproj", "PriceMonitorApi/"]
RUN dotnet restore "PriceMonitorApi/PriceMonitorApi.csproj"
COPY . .
WORKDIR "/src/PriceMonitorApi"
RUN dotnet build "PriceMonitorApi.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorApi.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorApi.dll"]

PriceMonitorBlazor/Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:6.0 AS build
WORKDIR /src
COPY ["PriceMonitorBlazor/PriceMonitorBlazor.csproj", "PriceMonitorBlazor/"]
RUN dotnet restore "PriceMonitorBlazor/PriceMonitorBlazor.csproj"
COPY . .
WORKDIR "/src/PriceMonitorBlazor"
RUN dotnet build "PriceMonitorBlazor.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "PriceMonitorBlazor.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "PriceMonitorBlazor.dll"]

3.2 Создание docker-compose.yml

Соедините все точки (рождественские гирлянды) одним файлом docker-compose.yml:

version: '3.4'

services:
 api:
 image: pricemonitorapi
 build:
 context: ./PriceMonitorApi
 dockerfile: Dockerfile
 ports:
 - "5000:80"
 networks:
 - price-monitor-network

 blazor:
 image: pricemonitorblazor
 build:
 context: ./PriceMonitorBlazor
 dockerfile: Dockerfile
 ports:
 - "5001:80"
 depends_on:
 - api
 networks:
 - price-monitor-network

networks:
 price-monitor-network:
 driver: bridge

Диаграммы

Ниже приведены диаграммы, помогающие визуализировать различные компоненты и поток данных. Это поможет нам понять, что на самом деле происходит в нашем мире Санты:

Схема архитектуры системы

Схема потока данных

Диаграмма последовательности

Схема компонентов для настройки Docker

Шаг 4. Управление URL-адресами, обновление и автоматическое периодическое обновлениеВ этой демонстрации мы просто сохраним его в памяти, но в реальном приложении вы будете использовать базу данных. В этом забавном проекте давайте остановимся на хранении в памяти.

4.1 Изменение службы для управления URL-адресами

Во-первых, мы убедимся, что наш сервис может обрабатывать добавление и получение URL-адресов, а также получение информации о продукте:

Обновление Services/ScraperService.cs:

using PriceMonitorBlazor.Models;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

namespace PriceMonitorBlazor.Services
{
 public class ScraperService
 {
 private readonly HttpClient _httpClient;
 private List<string> urls = new List<string>();

 public ScraperService(HttpClient httpClient)
 {
 _httpClient = httpClient;
 }

 public async Task<ProductInfo> GetProductInfoAsync(string url)
 {
 var response = await _httpClient.GetFromJsonAsync<ProductInfo>($"http://localhost:5000/api/scraper/productinfo?url={url}");
 return response;
 }

 public void AddUrl(string url)
 {
 if (!urls.Contains(url))
 {
 urls.Add(url);
 }
 }

 public List<string> GetUrls()
 {
 return urls;
 }

 public void ClearUrls()
 {
 urls.Clear();
 }
 }
}

4.2 Обновление компонента Blazor для управления URL-адресами и обновления

Затем обновите 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-адресами.

Заключение

Создание этой системы мониторинга цен было настоящим праздником! Это не только избавило меня от стресса, связанного с ежедневными проверками цен, но и продемонстрировало волшебство современных веб-технологий.

Праздничный технический календарь на 2024 год

Я создал этот пост в рамках мероприятия Festive Tech Calendar 2024, которое объединяет энтузиастов технологий, новаторов и цифровых мечтателей, чтобы поделиться знаниями и отпраздновать слияние праздничного духа и технологических чудес. Эта инициатива направлена не только на обучение и общение, но и на отдачу.

Праздничный технологический календарь на 2024 год в этом году поддерживает благотворительную организацию Beatson Cancer Charity. Благотворительная организация Beatson Cancer Charity занимается поддержкой людей, страдающих раком, их семей и медицинских работников, которые о них заботятся. Более подробную информацию об их невероятной работе можно найти на сайте https://www.beatsoncancercharity.org/.

Посетите веб-сайт Festive Tech Calendar по адресу https://festivetechcalendar.com, где можно найти часто задаваемые вопросы и получить более подробную информацию о мероприятии.

ХО ХО ХО!

Создание этого проекта стало прекрасным способом внести свой вклад в праздничное технологическое сообщество и в то же время поддержать великое дело.

Я надеюсь, что это руководство оказалось для вас полезным и вдохновило вас на изучение новых способов использования технологий для упрощения повседневных задач.

Если у вас есть какие-либо вопросы или вам нужна дополнительная помощь, пожалуйста, не стесняйтесь обращаться к нам.

Приятного кодирования!

Пользовательская проверка ValidationAttribute и Blazor

Fri, 29 Mar 2024 00:00:00 +0000

# Все на заказ

Как вы, наверное, заметили во всех моих постах, я действительно стараюсь держать все как можно более чистым, поскольку я уже писал посты, касающиеся пользовательских атрибутов, пользовательской обработки исключений, внедрения коллекций сервисов и т. д.

Со временем я понял, что такой способ кодирования дает мне и моей команде возможность совершенствоваться со временем, легче находить проблемы и максимально разделять код.

Да, после этой крутой истории, которую я только что рассказал вам, в последнее время я, как обычно, работаю над Blazor и обнаружил, что после многих лет разработки вы можете создавать собственные атрибуты проверки.

Да, это забавно, спустя столько лет…

Пользовательские атрибуты проверки

На самом деле идея пришла из работы: мы всегда выполняем проверку во всех местах, но у меня были некоторые поля, которые требовали одного и того же процесса проверки, поэтому я подумал, что там может быть что-то… например, пользовательские атрибуты проверки!

Итак, я открыл документацию Microsoft и обнаружил, что да, вы можете создавать собственные атрибуты проверки и назначать их свойствам, вот так:

public class StringLengthRangeAttribute : ValidationAttribute
{
 public int Minimum { get; set; }
 public int Maximum { get; set; }

 public StringLengthRangeAttribute()
 {
 this.Minimum = 0;
 this.Maximum = int.MaxValue;
 }

 public override bool IsValid(object value)
 {
 string strValue = value as string;
 if (!string.IsNullOrEmpty(strValue))
 {
 int len = strValue.Length;
 return len >= this.Minimum && len <= this.Maximum;
 }
 return true;
 }
}

и используйте его в простом классе, например:

[[[ТОК_1]]]

Пользовательский валидатор

Итак, у меня есть этот валидатор, который мне нужен для какого-то конкретного бизнес-кейса, который будет содержать 20 первых символов, которые будут дополнять 9 цифр и дефис и заканчиваться 2 символами, которые обычно будут кодом страны, что-то вроде этого: 123456789-123456789-ES

В итоге я пришел к чему-то вроде этого, это действительно просто, но работает:

[[[ТОК_2]]]

Тесты

Для них я тоже написал тест, на всякий случай:

[[[ТОК_3]]]

И когда я запустил, у меня были такие результаты:

[[[ТОК_4]]]

Пользовательская проверка и Blazor

Итак, теперь, когда я знаю, что его можно использовать, очевидно, что реализовать его в Blazor — хорошая идея, верно?

Предположим, у меня есть эта форма, которая будет использовать модель Person, которую я показывал ранее:

[[[ТОК_6]]]

Как только мы запустим это, мы получим следующие ошибки:

А если просто поставить то, что хотим, то получим следующую вещь, все понятно:

Честно говоря, для меня совершенно очевидно, что мы должны переместить логику, по крайней мере, для проверки этих форм, в пользовательские атрибуты проверки. Это дает нам свободу хранить код для этого входа в одном месте, и мы можем использовать его позже для API или другого приложения.

Надеюсь, вам понравилось. Если у вас есть какие-либо вопросы или вы хотите связаться со мной, не стесняйтесь и свяжитесь со мной!

Пользовательская обработка исключений в .NET API

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

Исключения – это плохо, мы знаем, верно? Но что, если нам придется с ними справиться?

Что происходит, когда у нас есть исключение, например в API, оно отображает сообщение стека, содержащее много информации, которую мы, возможно, захотим удалить из ответа, который получают наши пользователи.

Для демонстрации я создал API dotnet и добавил метод, который выдает исключение:

[HttpGet]
[Route("GetWithoutExceptionHandler")]
public Task GetWithoutExceptionHandler()
{
 throw new Exception("This is a custom exception!");
}

Если мы создадим исключение, это будет выглядеть так:

[[[ТОК_1]]]

Это выглядит нормально, это то, что вы получаете из исключения, но для меня это отображение большого количества информации. Если у вас есть библиотеки и прочее, оно может показать полезную информацию о вашем клиенте, вашем проекте или других вещах тому, кто может пытаться что-то увидеть.

Вот как это выглядит на Swagger:

Создание собственного исключения

Этого шага можно было бы избежать, поскольку мы знаем, какое исключение будет выдано, в данном случае Exception, но для меня лучше иметь собственные исключения, поскольку у вас больше контроля над тем, что вы выбрасываете.

В данном случае я только что создал объект CustomException, который наследуется от Exception:

[[[ТОК_6]]]

После того, как мы создали собственное исключение, давайте обновим наш метод, чтобы он выдавал CustomException вместо Exception:

[[[ТОК_9]]]

На данный момент это ничего не изменит, но трассировка стека покажет, что созданный объект является CustomException вместо Exception, взгляните на начало трассировки стека:

[[[ТОК_12]]]

Создание атрибута 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 и чтобы вернуть результат, мы должны обновить context.Result, передав ему объект, унаследованный от ActionResult.

Это фильтр, поэтому нам нужно что-то добавить, добавив [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>(); для внедрения сервиса.

Что-то вроде этого:

[[[ТОК_2]]]

Я имею в виду, это работает, но я придирчив, и мне это не очень нравится.

Допустим, у нас есть несколько внедрений зависимостей, которые мы хотим сделать, и на самом деле это не одно и то же. В моем случае это может быть что-то вроде библиотеки, содержащей все репозитории, другой библиотеки, содержащей все сервисы, и, наконец, еще одной библиотеки, содержащей атрибуты.

В таком случае, можете ли вы представить себе, сколько строк нам придется добавить в Program.cs.

Допустим, у нас есть библиотека, содержащая некоторые сервисы. Если мы хотим включить все наши сервисы, нам придется работать с IServiceCollection.

Итак, мы собираемся создать static class с методом static под названием AddServices, который возвращает IServiceCollection.

В этом случае он будет называться 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;
 }
}

Мало того, у нас также есть еще одна библиотека, включающая несколько репозиториев, используемых этими сервисами, поэтому давайте сделаем то же самое.

[[[ТОК_11]]]

Теперь у нас есть репозитории и методы сервисов для внедрения, но как их использовать?

Давайте вернемся к нашему Program.cs и добавим следующее:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();

// Repositories
builder.Services.AddRepositories(); // 👀

// Services
builder.Services.AddServices(); // 👀

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
 app.UseExceptionHandler("/Error");
 // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
 app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Это выглядит намного чище, не так ли? Итак, мы успешно внедрили некоторые сервисы и репозитории, но теперь это выглядит лучше, и у нас действительно есть то, что мы внедрили, во внешней библиотеке.

Внедрение зависимостей с помощью атрибутов в .NET API

Tue, 22 Aug 2023 00:00:00 +0000

Внедрение зависимостей, вероятно, является одной из лучших функций, которые мы имеем в .NET на данный момент. Ни в коем случае вы не сможете его не использовать, поэтому, если вы похожи на меня, вам наверняка захочется добавить его во все создаваемые вами реализации.

Фильтры согласно официальной [документации] Microsoft(https://learn.microsoft.com/en-us/aspnet/core/mvc/controllers/filters?view=aspnetcore-3.1):

Фильтры в ASP.NET Core позволяют запускать код до или после определенных этапов конвейера обработки запросов.

Встроенные фильтры решают такие задачи, как:

Авторизация, предотвращающая доступ к ресурсам, к которым пользователь не авторизован.

Кэширование ответов, замыкание конвейера запросов для возврата кэшированного ответа.

Могут быть созданы пользовательские фильтры для решения сквозных задач. Примеры сквозных проблем включают обработку ошибок, кэширование, настройку, авторизацию и ведение журнала. Фильтры позволяют избежать дублирования кода.

Я много работаю с API, и есть некоторые вещи, которые должны выполнять каждый отдельный запрос или почти все из них, поэтому в идеале мы хотим работать с ним плюс… внедрение зависимостей!

Но иногда это небольшая хитрость: это не работает так, как мы хотим, если мы хотим наследовать от ActionAttribute поэтому нам нужно работать с TypeFilterAttribute, что позволяет нам делать что-то при переопределении OnActionExecutionAsync.

Обычно я создаю эти фильтры для ведения журналов, поэтому мы будем использовать их в качестве примера:

[[[ТОК_4]]]

Логика довольно проста: мы получаем тело, обращаясь к объекту context с помощью context.ActionArguments.First().Value, а также получаем вызов метода с помощью context.HttpContext.Request.Path.Value.

Затем мы просто вызываем наш метод из нашего сервиса, в данном случае это _loggingService.LogCustomEvent(call).

Затем мы должны вызвать await next();, потому что конвейер должен продолжить работу.

Это атрибут, теперь мы должны включить этот атрибут в метод.

[[[ТОК_10]]]

Документация Swagger с внешними библиотеками

Fri, 17 Feb 2023 00:00:00 +0000

Использование нескольких библиотек для разделения кода для будущих случаев — это хорошо. Лично мне нравится это делать, если я могу разделить свою логику, чтобы ее можно было повторно использовать в других проектах или частях проектов.

По крайней мере, для меня необходимо разделить модели данных, включая Entity Framework, чтобы на них можно было ссылаться и использовать в Console application, Blazor application или API.

Давайте посмотрим на пример того, как я это делаю. Это снимок экрана проекта, в котором есть несколько приложений и общая библиотека со всеми моделями.

Это пример класса, который я перенес из проекта API с документацией с summary по каждому свойству и классу.

[[[ТОК_7]]]

Если мы ссылаемся на 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

Вы когда-нибудь доходили до того, что у вас было слишком много местных филиалов? Со мной это случается часто, поскольку мы используем ветки для каждой функции, ошибки или работы.

В итоге у меня получается что-то вроде этого, и через некоторое время оно становится очень грязным

Меня это очень раздражает, поэтому я просто поделюсь быстрой командой, которую вы можете запустить на консоли, чтобы выполнить эту очистку!

Я нашел эту команду в Stack Overflow в следующем ответе Роберта Корвуса, версии, работающей на Powerhsell.

Пожалуйста, будьте осторожны при выполнении этой команды, потому что вы можете потерять изменения

Прежде чем запускать его, не забудьте обновить MY_MASTER_BRANCH_NAME до вашей основной ветки, это может быть master, как я использую, или новые, которые по умолчанию называются main.

[[[ТОК_6]]]

После запуска этой команды вы получите такой вывод

Надеюсь, это будет полезно для вас!

Обновление маршрутов Identity в ASP.NET Core 7

Mon, 23 Jan 2023 00:00:00 +0000

Даже интересно, как Microsoft называет такие редкие вещи? Я всегда думал, что на самом деле они делают это не так уж и хорошо, но, ну, вот что это такое!

Хорошая вещь в этом то, что вы можете изменить практически все, пока разрабатываете!

Вы когда-нибудь заходили на страницу и сразу понимали, что это веб-проект ASP.NET, просто выполнив процесс регистрации или входа в систему?

Со мной это часто случалось, потому что по умолчанию в создаваемом вами проекте у вас есть эти URL-адреса для входа в систему и регистрации (а также у вас есть много других страниц).

В этом уроке показан способ обновить эти URL-адреса, чтобы ваш проект выглядел лучше!

Поведение по умолчанию

Когда мы создаем проект Blazor и решаем использовать его с Identity, он отображает что-то вроде этого:

И когда мы пытаемся выполнить вход или регистрацию, мы выбираем либо /Identity/Account/Login либо /Identity/Account/Register.

Но что, если я скажу вам, что вы можете действительно обновить эти URL-адреса, чтобы они стали другими?

Формирование страниц `Login` и `Register`

Чтобы обновить эти страницы, Microsoft скрывает их, но вы можете быстро создать их и внести нужные изменения!

Для этого вам нужно зайти и Add Scaffolded Item в контекстном меню проекта, вот так:

Затем появится модальное окно, и вам придется дважды выбрать Identity и нажать Add:

После этого появится еще одно модальное окно, в котором вы сможете выбрать, какие страницы из всей идентичности вы хотите обновить. Есть много страниц, которые вы можете обновить, но мы сосредоточимся на Account/Login и Account/Register:

Теперь дайте ему немного поработать, а затем проверьте обозреватель решений, вы найдете несколько новых файлов:

Эти новые файлы представляют собой страницу входа и регистрации, которую ASP.NET добавляет в ваш проект, когда вы выбираете ее для добавления Identity!

Обновление URL-адресов

Как вы, наверное, заметили, эти файлы являются Razor-файлами, поскольку их расширение — cshtml, поэтому мы просто собираемся использовать директиву для обновления URL-адреса страницы:

@page "/login"
@model LoginModel

@{
 ViewData["Title"] = "Log in";
}

<h1>@ViewData["Title"]</h1>
<div class="row">
 <div class="col-md-4">
 <section>
 <form id="account" method="post">
 <h2>Use a local account to log in.</h2>
 <hr />
 <div asp-validation-summary="ModelOnly" class="text-danger" role="alert"></div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Email" class="form-control" autocomplete="username" aria-required="true" placeholder="name@example.com" />
 <label asp-for="Input.Email" class="form-label">Email</label>
 <span asp-validation-for="Input.Email" class="text-danger"></span>
 </div>
 <div class="form-floating mb-3">
 <input asp-for="Input.Password" class="form-control" autocomplete="current-password" aria-required="true" placeholder="password" />
 <label asp-for="Input.Password" class="form-label">Password</label>
 <span asp-validation-for="Input.Password" class="text-danger"></span>
 </div>
 <div class="checkbox mb-3">
 <label asp-for="Input.RememberMe" class="form-label">
 <input class="form-check-input" asp-for="Input.RememberMe" />
 @Html.DisplayNameFor(m => m.Input.RememberMe)
 </label>
 </div>
 <div>
 <button id="login-submit" type="submit" class="w-100 btn btn-lg btn-primary">Log in</button>
 </div>
 <div>
 <p>
 <a id="forgot-password" asp-page="./ForgotPassword">Forgot your password?</a>
 </p>
 <p>
 <a asp-page="./Register" asp-route-returnUrl="@Model.ReturnUrl">Register as a new user</a>
 </p>
 <p>
 <a id="resend-confirmation" asp-page="./ResendEmailConfirmation">Resend email confirmation</a>
 </p>
 </div>
 </form>
 </section>
 </div>
 <div class="col-md-6 col-md-offset-2">
 <section>
 <h3>Use another service to log in.</h3>
 <hr />
 @{
 if ((Model.ExternalLogins?.Count ?? 0) == 0)
 {
 <div>
 <p>
 There are no external authentication services configured. See this <a href="https://go.microsoft.com/fwlink/?LinkID=532715">article
 about setting up this ASP.NET application to support logging in via external services</a>.
 </p>
 </div>
 }
 else
 {
 <form id="external-account" asp-page="./ExternalLogin" asp-route-returnUrl="@Model.ReturnUrl" method="post" class="form-horizontal">
 <div>
 <p>
 @foreach (var provider in Model.ExternalLogins!)
 {
 <button type="submit" class="btn btn-primary" name="provider" value="@provider.Name" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>
 }
 </p>
 </div>
 </form>
 }
 }
 </section>
 </div>
</div>

@section Scripts {
 <partial name="_ValidationScriptsPartial" />
}

Как вы можете видеть, большая часть материала осталась прежней, но если вы посмотрите на самую первую строку в классе, я обновил то, что у нас было раньше:

@page

чтобы

@page "/login"

Ну, это было легко, не так ли? Теперь давайте проведем быстрый тест и проверим, работает ли это.

Прежде всего, давайте перейдем на страницу по умолчанию, которая у нас есть изначально, чтобы проверить, работает ли она еще:

Но это не так! Итак, теперь давайте проверим наш новый 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-адреса определенным образом, а затем Identity выглядит по-другому, это отстой, ха-ха!

Если вам что-нибудь понадобится, просто напишите мне в Твиттере или отправьте электронное письмо, и я постараюсь помочь!

Пользовательские атрибуты в .NET 6 Core API

Fri, 09 Dec 2022 00:00:00 +0000

Пользовательские атрибуты действительно полезны, я начал использовать их совсем недавно, потому что они позволяют мне создавать один из них и повторно использовать их либо в контроллере, либо в классе, либо в самом методе.

Они действительно помогают, когда вы хотите выполнить некоторые действия по обеспечению безопасности, например проверить заголовки или проверить значение параметра, который вам определенно нужен.

В моем случае мы собираемся использовать его в проекте API .NET Core, где мы собираемся проверить, содержат ли все запросы определенный заголовок.

Атрибут проверки заголовка

Итак, после того как мы создали наш классный API .NET Core, давайте создадим папку для хранения наших материалов, потому что нам нравится использовать папки.

А затем мы добавим логику в наш класс HeaderCheckAttribute.

[[[ТОК_2]]]

По сути, логика такова: сначала он проверяет заголовок с ключом x-dotnet-6-custom-attribute и, если он там, проверяет, есть ли у него значения.

Если оба этих выражения истинны, он повторно отправит BadRequestObjectResult с определенным сообщением.

Добавляем его в контроллер

Мы можем добавить эту логику в несколько мест, мы можем добавить ее непосредственно ко всему контроллеру или мы можем добавить ее к некоторым методам, мы собираемся добавить ее сначала к методам, а затем ко всему контроллеру.

Итак, давайте украсим ими класс WeatherForecastController .

[[[ТОК_6]]]

Давайте запустим проект!

У нас есть две функции: GetWeatherForecastWithCheck и GetWeatherForecastWithoutCheck, одна из них завершится неудачей, а другая — нет, но давайте проверим это на Swagger!

Как вы можете видеть, один из наших сообщений возвращает ошибку 400, а другой возвращает значения. Теперь, чтобы полностью проверить это, давайте запустим Postman и добавим заголовок, чтобы мы также видели данные, используя GetWeatherForecastWithCheck.

Почтальон

Теперь, работая в Postman, мы добавляем заголовок и видим, что сообщение об ошибке изменилось, поскольку теперь мы предоставляем заголовок, но он не имеет никакого значения.

Если мы добавим к нему значение, мы наконец получим значения!

Вот и все

Ну вот и все! Довольно просто, правда? Что ж, теперь вы знаете, как создать атрибут и назначить его методам и контроллерам!

Веселитесь с ними!

Код

Весь этот проект находится на Github, и вы можете найти его здесь!

Если у вас есть какие-либо проблемы или вопросы, не стесняйтесь обращаться ко мне в любой социальной сети по адресу @emimontesdeoca (в Твиттере на самом деле это @emimontesdeocaa с двумя aa в конце). Большую часть моих соцсетей вы также можете найти в шапке блога.

Надеюсь, вам понравился пост! Сайя!

Обработка загрузки компонентов в Blazor

Tue, 19 Jul 2022 00:00:00 +0000

Blazor потрясающий, действительно потрясающий, особенно когда мы делаем асинхронные вещи, такие как загрузка ящиков, и это выглядит просто хорошо.

Я пытался придумать несколько способов обработки загрузки страниц, состояний, компонентов и т. д. И я думаю, что наконец нашел идеальный способ сделать это так, как я хочу.

Идея

Вместо того, чтобы переписывать логику загрузки каждой страницы или компонента, мы создаем родительский компонент с помощью ChildComponent, это даст нам возможность просто повторно использовать его несколько раз.

Код загрузки компонента

Хотя код довольно прост, делать не так уж и много: базовый if со свойством загрузки, функцией переключения внутри и все готово!

[[[ТОК_2]]]

Использование

Использование довольно простое: для тестирования мы собираемся использовать новую страницу и поместить наш контент внутрь только что созданного компонента LoadingComponent .

[[[ТОК_4]]]

Вот как это выглядит

Еще забавный пример

Допустим, у нас есть несколько компонентов, каждый из которых имеет свое время загрузки, и на основе этого мы можем создать что-то, что будет хорошо выглядеть!

Давайте создадим фиктивный загрузочный компонент, который мы сможем использовать повторно, под названием FakeLoadingComponent.

[[[ТОК_7]]]

Затем мы просто обновляем страницу Loading несколькими компонентами FakeLoadingComponent и проверяем результат!!

[[[ТОК_10]]]

Теперь это выглядит намного лучше

И все!

Надеюсь, вам понравился пост!

Получение срока действия сертификата

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

Есть несколько веб-приложений, которые помогут вам проверить текущий статус сертификатов используемых нами доменов, и у нас их несколько.

Я создал функцию Azure, которая запускается один раз в день и проверяет несколько доменов, которые мне нужно просмотреть. Это очень простое консольное приложение, которое, если срок действия сертификата меньше 30 дней, отправляет электронное письмо.

Саму логику работы функции показывать не буду, хотелось бы показать функцию, которая выполняет базовую проверку сертификата и какие данные мы получаем.

Функция

static async Task<X509Certificate2> CheckCertificateAsync(string urlPath)
{
 var certificate = new X509Certificate2();
 var httpClientHandler = new HttpClientHandler
 {
 ServerCertificateCustomValidationCallback = (request, cert, chain, policyErrors) =>
 {
 certificate = new X509Certificate2(cert);
 return true;
 }
 };

 using HttpClient httpClient = new HttpClient(httpClientHandler);
 await httpClient.SendAsync(new HttpRequestMessage(HttpMethod.Head, urlPath));

 return certificate;
}

Этот метод CheckCertificateAsync вернет нам сертификат X509Certificate2 который позволит нам сделать множество вещей, включая проверку даты истечения срока действия.

Сериализованный результат

Это сериализованное значение объекта certificate:

[[[ТОК_4]]]

Срок годности

Чтобы узнать срок действия, нам нужно взглянуть на NotAfter и NotBefore, которые находятся внутри этого объекта:

[[[ТОК_7]]]

Консольное приложение

Следующий фрагмент представляет собой простое консольное приложение, созданное на базе .NET 6, которое выдаст следующий результат, в котором вы можете проверить любой сертификат, который вам нужен:

[[[ТОК_8]]]

Демо-проект

Вы можете найти консольное приложение на моем Github, в репозитории под названием expiration-date-certificate.

Фокусировка элемента в Blazor

Thu, 05 May 2022 00:00:00 +0000

После недавней работы над игрой Wordlzor мне нужно было добавить довольно простую функциональность: фокусировать всю игру при входе.

Это необходимо было сделать, потому что пользователь действительно мог печатать в игре, а не только использовать экранную клавиатуру.

Файл Javascript

Для этого нам нужно создать файл Javascript с именем app.js, который будет содержать функцию

[[[ТОК_1]]]

После того, как мы это сделали, нам нужно включить скрипт в файл index.html:

[[[ТОК_3]]]

Компонент Blazor

После инициализации сценария нам нужно найти элемент, на котором можно сосредоточиться, поэтому в любом из наших компонентов нам нужно ссылаться на этот элемент на объект.

Итак, в наш компонент blazor давайте добавим div с Свойство @ref:

[[[ТОК_4]]]

Затем в логике компонента вы можете использовать это свойство как ElementReference:

[[[ТОК_6]]]

Внедрение JSInterop

Теперь, чтобы вызвать функцию, которая есть в нашем файле Javascript, нам нужно использовать JSInterop.

Прежде всего, мы должны внедрить его в компонент со следующим синтаксисом:

[[[ТОК_8]]]

После внедрения сервиса мы теперь можем вызывать любой из имеющихся у него методов, например InvokeVoidAsync, который будет вызывать функцию:

[[[ТОК_10]]]

И когда вы вызываете функцию Focus(), она фокусирует элемент, который мы создали, очевидно, вы можете провести рефакторинг и передать сам элемент в качестве параметра.

Если вы хотите посмотреть, как я это реализовал, взгляните на исходный код Wordlzor, я использовал его для оповещений и фокусировки при закрытии модального окна инструкций.

Создание файлов *.dacpac из проекта базы данных VS в GitHub Actions

Mon, 18 Apr 2022 00:00:00 +0000

Если вам нужно работать с базами данных и вы хотите заниматься гибкой разработкой, у вас должен быть поток, в котором всякий раз, когда вы добавляете или изменяете таблицу, SP, функцию, он компилирует их и генерирует файл развертывания для базы данных.

Я использую этот подход уже давно: мы вносим изменения локально, сравниваем их с нашим проектом базы данных, а затем, когда мы фиксируем и отправляем наши изменения, они генерируют файл bacpac, который будет отправлен в базу данных.

Это избавляет от необходимости делать это вручную, что может привести к человеческой ошибке, а в базе данных это действительно плохие новости.

Проект базы данных

Когда мы создадим проект базы данных в Visual Studio и импортируем базу данных, в конечном итоге все будет так:

Когда мы запустим компиляцию этого проекта, он сгенерирует файл dacpac, который будет включать всю нашу структуру.

конвейер Github

Теперь, когда наш код опубликован в репозитории, нам нужно создать действие, которое скомпилирует этот проект, сгенерирует этот файл dacpac и поместит его куда-нибудь, чтобы мы могли его загрузить или использовать для другого шага.

[[[ТОК_4]]]

Это действие выполнит ряд действий: создаст решение и поместит результат в папку artifacts, созданную заранее, а затем загрузит файлы из этой папки в артефакты.

Запуск конвейера

Теперь запустите сборку, результат должен быть следующим

Если мы на самом деле загрузим артефакт и посмотрим на содержимое, это то, что нам понадобится в будущем, когда мы реализуем этап непрерывного развертывания, файл dacpac!

Код

Весь этот проект находится на Github, и вы можете найти его здесь!

Надеюсь, вам понравился пост! Сайя!

Переключение тем с помощью Javascript Interop в Blazor

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

Для таких людей, как я, которые страдают от воспоминаний каждый раз, когда я открываю веб-страницу, я придумал очень простое решение, как переключаться между светлым и темным режимами с помощью Javascript и вызывать его из Blazor с помощью Javascript Interop.

Установка родительского атрибута

Прежде всего, мы должны идентифицировать родительский элемент с помощью идентификатора, потому что мы меняем цвета в зависимости от значения этого идентификатора.

Чтобы сделать это в Javascript, нам нужно будет запустить эту команду

[[[ТОК_1]]]

В нашем случае мы хотим иметь два идентификатора для каждого типа стиля: light и dark.

Создание файла Javascript для обработки логики

Теперь у нас есть функция для обновления идентификатора, теперь давайте создадим файл Javscript с функцией, которая выполняет эту логику. Наш файл будет называться app.js

В этом файле у нас будет функция, которая будет вызывать код, о котором мы упоминали ранее.

[[[ТОК_6]]]

Добавление файла Javascript в Blazor

Добавьте сценарий в приложение Blazor, добавив его туда, где расположены сценарии.

[[[ТОК_7]]]

Создание сервиса

Теперь, когда у нас есть код Javascript, нам нужно создать сервис, который будет называться ThemeToggleService.

Этот сервис будет обрабатывать логику переключения между темами light и dark.

Внедрение JSInterop

Чтобы вызвать любой Javascipt, нам нужно вызвать JSInterop, поэтому нам нужно создать свойство, которое будет выполнять внедрение.

[[[ТОК_12]]]

Функция для установки идентификатора

Теперь, когда у нас есть служба, давайте создадим функцию для установки идентификатора. Эта функция будет просто обновлять 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);
}

Не забудьте добавить файл в приложение Blazor, добавив его в head.

<link href="css/app.css" rel="stylesheet" />

Звонок от Blazor

Итак, как мы собираемся это проверить? Для простоты мы просто добавим элемент div с классом app-background и внутри него будет p с классом app-text.Итак, давайте создадим страницу с именем Theme.razor в папке Pages и добавим для нее немного кода.

@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, и вы можете найти его здесь!

Надеюсь, вам понравился пост!

Ресурсы

Вызов функций JavaScript из методов .NET в ASP.NET Core Blazor

Загрузка файлов в хранилище BLOB-объектов Azure в Blazor

Wed, 23 Mar 2022 00:00:00 +0000

Служба хранения BLOB-объектов Azure — одна из наиболее часто используемых служб в экосистеме Azure. Она позволяет загружать в облако большое количество файлов и при этом стоит очень дешево. Он также имеет интуитивно понятный веб-сайт, к которому вы можете получить доступ или загрузить его по прямой ссылке.

В целом довольно хороший сервис, я использую его как для работы, так и для личных проектов, и, честно говоря, самое лучшее — это простота того, как заставить его работать.

В большинстве случаев хранилище BLOB-объектов Azure используется на серверной стороне, напрямую загружая что-то, что является результатом операции или чего-то еще. Так что я на самом деле не загружал файлы с веб-сайта или что-то в этом роде. Не повезло!

Поскольку я фанат Blazor, я предлагаю вам способ загрузки файлов в хранилище BLOB-объектов Azure с использованием встроенного ввода файлов из HTML5.

Предварительные требования

Учетная запись Azure (если у вас ее нет, перейдите здесь с кучей $$$).
IDE (VS, Code, подойдет любая)
.NET Core 3.0 или выше

Создание хранилища BLOB-объектов Azure

Перейдите на свой портал Azure и приступим к созданию учетной записи хранения.

Сначала найдите Storage accounts и нажмите на результат.

После загрузки нажмите Create.

Появится форма с множеством шагов, так что продолжайте и заполните их.

Заполнив все нужными настройками, пройдите проверку и создайте ресурс.

После того, как он будет создан, нажмите Go to resource. Мы собираемся получить строку подключения, которая позволит нам поиграть с API.

Получите ключи ресурсов

После того, как мы добрались до нашего вновь созданного ресурса, перейдите к Acccess keys под Security + networking. После загрузки вы увидите Connection string и Key, скопируйте их, потому что они нам понадобятся позже!

Создание крутого проекта Blazor Server

Для этого урока я буду использовать Visual Studio 2022, но, как я уже говорил ранее, вы можете использовать любую другую IDE и просто создать проект с помощью интерфейса командной строки dotnet .

Тогда давайте продолжим и очень быстро создадим проект Blazor с помощью Visual Studio всего за несколько шагов.

Если мы запустим то, что только что создали, оно будет выглядеть так: простое обычное приложение Blazor.

Теперь, когда у нас создан проект, давайте сделаем некоторые элементы пользовательского интерфейса, чтобы у нас была новая страница с набором входных данных, чтобы мы могли заполнить ключи из ресурса, InputFile для файла(ов), кнопку для выполнения чего-либо и сообщение, которое будет результатом действия.

Создание модели

Чтобы сделать это правильно, нам понадобятся несколько моделей. Сначала у нас будет класс BlobRequest, который будет обрабатывать строку подключения, имя контейнера и файлы.

Кроме того, чтобы все было аккуратно, мы создадим класс с именем BlobFile, в котором будем хранить Name и Data.

Я создал папку под названием 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; }
 }
}

Изменение пользовательского интерфейса

Теперь, когда наша модель создана, давайте продолжим и поколдуем с ее помощью над пользовательским интерфейсом!

Прежде всего создайте страницу в папке 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!");
 }
}

Это небольшой код, но в основном он отображает форму и выполняет проверку.

Если вы нажмете кнопку загрузки и все в порядке, отобразится предупреждение.

Загрузка в хранилище BLOB-объектов Azure

Теперь, когда у нас готова большая часть пользовательского интерфейса, давайте установим пакет, который будет обрабатывать API хранилища BLOB-объектов Azure и позволит нам загружать файлы. Довольно просто.

Добавьте пакет NuGet

Давайте управлять пакетами NuGet из проекта и добавим Azure.Storage.Blob.

Отправка в хранилище BLOB-объектов Azure

Теперь давайте реализуем логику фактической загрузки файла. Обычно мы используем строку подключения и ключ из файла app.config, но в целях этого руководства мы используем входные данные и передаем туда данные.

Сначала добавим using для класса хранилища BLOB-объектов Azure.

@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!");
 }
}

Тестирование кода

Теперь пришло время протестировать код. Для этого просто заполните форму и нажмите «Отправить».

Мы отобразим предупреждение, и файл должен быть загружен в хранилище BLOB-объектов Azure, перейдите на портал Azure и посмотрите.

Как видите, контейнер тоже был создан, теперь если мы попадем внутрь контейнера, то увидим загруженный нами файл.

Хорошая работа!

Рефакторинг

Теперь, когда все готово, давайте переместим код со страницы .razor в класс .razor.cs, чтобы он выглядел лучше.

Если вы используете Visual Studio 2022, при наведении курсора мыши прямо на @code загорится лампочка, она покажет вам опцию Extract block to code behind и сделает то, что сказано!

Теперь вы все разделите и сделаете!

Код

Весь этот проект находится на Github, и вы можете найти его здесь!

Надеюсь, вам понравился пост! Сайя!

Ресурсы

[[[[ТОК_51]]])
[[[[ТОК_52]]])

Переопределение основного контроллера 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

Вероятно, он найдет более одного, поэтому вам нужно посмотреть и решить, какой из них является именно тем. В нашем случае мы работаем с активами, поэтому ясно, что мы хотим использовать 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!!

Давайте просто ничего не будем возвращать и посмотрим, что теперь мы можем видеть страницу такой, какой она была раньше.

Закомментируйте оператор возврата и перезагрузите компьютер.

Вот и все

И с помощью этой небольшой демонстрации вы увидите, насколько легко можно переопределить существующий базовый контроллер Pimcore. Есть несколько шагов, которым вы должны следовать, но в этом нет ничего сложного. Просто убедитесь, что вы открываете контроллер и время от времени очищаете кеш, пока вносите изменения, иногда он кэшируется, и вы застреваете, думая, что он не работает и просто кэшируется.

Если вам интересно, как переопределить файлы JavaScript, это будет описано в другом уроке 😁.

Настройка Apple Magic Keyboard 2 в Windows 10

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

Буквально вчера я купил Apple Magic Keyboard 2, хотя у меня около 5 механических клавиатур, потому что я хотел попробовать ее, и она была беспроводной.

Моя основная ОС — Windows 10, она мне нравится, и я не хочу ее менять, поэтому, помня об этом, я знал, что необходимо будет сделать некоторые вещи, чтобы клавиатура работала идеально. Я знаю, как работает Apple и как им нравится сохранять свои устройства в своей экосистеме.

Проблемы

Если вы подключите клавиатуру, вы узнаете несколько вещей:

Функциональные клавиши не работают
Некоторые клавиши неправильно назначены (это случилось со мной в испанской версии)

Документация

Чтобы заставить его работать, мне пришлось много читать в Интернете, но именно эти две ссылки помогли мне заставить его работать:

Установка драйвера клавиатуры Apple

Некоторые из этих шагов взяты из документации, упомянутой ранее:

Установите 7zip на свой компьютер, если у вас его нет.
Установите Python (версия 2.x) на свой компьютер, если у вас его нет.
- ВАЖНО: Последняя версия Python — 3.x. Но вам нужна версия 2.x, поскольку скрипт бригадира несовместим с версией 3.x.
- (опция) Установщик по умолчанию не добавляет python.exe в ваш PATH. Если хотите, вам нужно включить эту опцию. (см. скриншот справа)
- Если у вас уже есть другая версия Python, вы, вероятно, не захотите включать эту опцию.
Загрузите brigadier (скрипт Python, который поможет вам загрузить последнюю версию Boot Camp).
Щелкните правой кнопкой мыши следующую ссылку и сохраните файл, используя «Сохранить ссылку как…». [[[ТОК_6]]]
Откройте окно командной строки (также известное как окно DOS) и перейдите в каталог, в который вы загрузили скрипт бригадира.
Предполагая, что сценарий бригадира сохранен как «brigadier.txt», выполните следующую команду:
- Если в вашем PATH находится версия Python 2.x: 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.
Запустите PowerShell администратора и выполните BootCamp.msi, он установит кое-что, но нам нужно обновить драйвер, используя содержимое папки AppleKeyboardMagic2
Запускаем Диспетчер устройств (devmgmt.msc)
Разверните узел Human Interface Devices
Найдите Bluetooth HID Device
Обновите драйвер, используя содержимое папки AppleKeyboardMagic2
Перезагрузите компьютер.

Вы должны увидеть, что клавиатура Bluetooth теперь определяется как клавиатура Apple.

Обновление поведения клавиш FNЕсли вы все установили правильно, вы заметите, что клавиши FN включены по умолчанию. Это означает, что вам нужно нажать `fn` + `F5` для фактического нажатия кнопки `F5`.

Чтобы это исправить, я нашел решение, указанное в разделе документации, которое работает путем изменения некоторой записи в реестре.

Откройте реестр
Перейдите к HKEY_CURRENT_USER\SOFTWARE\Apple Inc.\Apple Keyboard Support
Создайте или обновите OSXFnBehavior и установите для него значение 0
Перезагрузите компьютер.

Обновить сопоставление ключей

Если у вас возникли проблемы с сопоставлениями, вы можете использовать SharpKeys и обновить их.

Его очень просто использовать, но не забудьте выйти из системы или перезагрузить компьютер, чтобы включить обновления, поскольку при этом обновляется реестр.

В моем случае мне пришлось обновить ключи Windows, alt, º и <> ключи.

Добавление скомпилированных библиотек в пакет NuGet

Thu, 01 Oct 2020 00:00:00 +0000

Буквально на днях я обнаружил ошибку, связанную с NullReferenceException в отсутствующей библиотеке, которая должна была там быть, поскольку она взята из загруженного нами пакета nuget.

По сути, я скомпилировал класс библиотеки, который ссылался на несколько проектов. На этапе сборки файлы dll добавляются в папку bin, но когда packaging это пакет nuget и устанавливается в другое решение, файлы dll, на которые я ссылался и которые следует скопировать в папку bin, отсутствуют.

Как это решить

Решить эту проблему довольно просто: вам необходимо обновить файл nuspec и для каждой из библиотек, которые вы хотите скопировать, добавить file в часть files.

[[[ТОК_8]]]

Сделать загрузку терминала bash в домашнем каталоге WSL

Tue, 22 Sep 2020 00:00:00 +0000

Я люблю WSL для разработки и тестирования с того дня, как он вышел, затем приложение Terminal исчезло, и я очень доволен: он хорошо выглядит, отлично работает и имеет отличную производительность.

Было бы глупо не использовать его с дистрибутивом WSL вместо того, чтобы использовать консоль, которая вам его предоставляет.

Эта консоль, очевидно, хороша, но после того, как вы воспользуетесь Терминалом, пути назад уже не будет. Это намного лучше, еще и цвета.

Теперь, если вы запустите терминал и откроете новую вкладку для загрузки дистрибутива WSL, он загрузит смонтированную пользовательскую папку.

На самом деле это не проблема, потому что если вы просто выполните cd ~ он просто загрузит пользовательскую папку дистрибутива.

Дело в том, что я не хочу делать это снова и снова, поэтому давайте обновим файл, чтобы он делал это сам.

.bashrc

Запустите терминал или консоль, зайдите в папку своего профиля, а затем отредактируйте файл .bashrc с помощью вашего любимого текстового редактора.

Добавьте cd ~ в конец файла перед последней инструкцией.

Сохраните, снова откройте консоль WSL с терминалом, и вы должны оказаться в папке профилей.

Имейте в виду, что вам придется сделать это для всех ваших установок WSL, поскольку мы обновляем файл bashrc для одной установки.

Генерация динамических объектов с использованием ExpandoObject

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

Мне нужно было преобразовать файлы Excel с собственными определенными столбцами в новый файл с динамическими столбцами, и я был немного озадачен тем, как это сделать правильно, без каких-либо серьезных проблем с производительностью.

Я подошел к руководству, которое вы можете найти здесь, в котором используется .NET ExpandoObject, который в значительной степени позволяет вам создавать объект и добавлять динамических участников.

РасширяемыйОбъект

Определение Microsoft следующее:

Представляет объект, члены которого можно динамически добавлять и удалять во время выполнения.

И есть несколько замечаний:

Класс ExpandoObject позволяет добавлять и удалять члены его экземпляров во время выполнения, а также устанавливать и получать значения этих членов. Этот класс поддерживает динамическую привязку, что позволяет использовать стандартный синтаксис, например sampleObject.sampleMember, вместо более сложного синтаксиса, такого как sampleObject.GetAttribute(“sampleMember”).

Текущее поведение

У нас есть ExcelExportService, который, передав List<T>, в данном случае ExcelItem, будет использовать Reflection для создания файла xlsx.

Пока что наш код выглядит так:

[[[ТОК_7]]]

ExcelItem — это объект со всеми свойствами, которые используются для создания файла Excel.

[[[ТОК_9]]]

Этот подход работает отлично, файл xlsx генерируется без проблем, причем каждый столбец является каждым свойством, вы можете использовать этот метод GetExcelBytes следующим образом, например, чтобы сохранить его в файл:

[[[ТОК_12]]]

Проблема

Поскольку мы правильно знаем, что используем все свойства объекта ExcelItem , все, что я хочу, это на самом деле не использовать их все, а просто использовать, может быть, 2 или 3 из них.

Также обязательным условием является то, что я не хочу менять код, все должен делать administrator, который будет решать, какие столбцы следует отображать, и он может знать или не знать свойства в коде.

TLDR: все должно быть динамическим, у нас есть объект со свойствами, и мы должны убедиться, что сгенерированный файл имеет свойства N этого объекта, но явно не жестко закодирован.

Динамические столбцы

Изменение будет заключаться в использовании объекта dynamic, поскольку мы хотели бы установить, какие свойства объекта будут использоваться для создания списка столбцов.

Допустим, у нас есть объект с множеством свойств, например, тонной, и мы на самом деле не хотим изменять объект ExcelItem каждый раз, когда мы вносим изменения, мы создаем таблицу ColumnExcelItem, которая будет использоваться для создания этого ExcelItem.

Структура базы данных

Мы сохраняем это определение в нашей базе данных примерно так:

Id PropertyName
---------------------
1 Name
2 Surname
3 Age

Обратите внимание, что у нас меньше значений, чем у существующих свойств объекта ExcelItem: он имеет свойства 6 и в базе данных указан только 3.

Также обратите внимание, что PropertyName должно соответствовать имени свойства объекта, который я буду использовать для динамического назначения.

Построение объекта

Теперь, когда у нас есть таблицы базы данных, нам нужно создать репозиторий, чтобы получить их и иметь возможность использовать их в коде.Я не буду делать руководство по этой части, я пропущу начало новой функции GetExcelBytes().

public static byte[] GetExcelBytes(List<string> columns) {
 List<ExcelItem> excelItems = new List<ExcelItem>();
 List<dynamic> objectsToExcel = new List<dynamic>();
 ExcelExportService exportService = new ExcelExportService();

 foreach (var item in itemsToExcel)
 {
 dynamic newObject = new ExpandoObject();
 foreach (var col in columns)
 {
 this.AddProperty(newObject, col, product.GetType().GetProperty(col).GetValue(item, null));
 }

 objectsToExcel.Add(newObject);
 }

 return exportService.ExportToExcel(objectsToExcel);
}

Теперь нам предстоит создать объект с некоторыми свойствами ExcelItem, но полностью динамический. Вместо использования всех шести свойств мы используем только три из них — то, которое хотим отправить.

Теперь давайте представим, что этот объект ExcelItem имеет 200 свойств, сумасшедший, но такое может случиться.

Единственное, что мне нужно сделать, это вставить те свойства, которые я хочу отобразить, в файл Excel в эту таблицу ColumnExcelItem и все.

Случаев

В данном случае мы использовали только один случай, но предположим, что вы хотите иметь разные отчеты для некоторых пользователей. Допустим, роль admin должна получить все свойства, тогда вы создадите в базе данных что-то вроде этой структуры.

ReportingTemplates

Id PropertyName
---------------------
1 Admin
2 Users

ReportingTemplateItems

Id TemplateId PropertyName
---------------------
1 1 Id
2 1 Name
3 1 Surname
4 1 Age
5 1 CreatedAt
6 1 UpdatedAt
7 2 Name
8 2 Surname
9 2 Age

Затем, получив шаблон, вы сможете иметь разные столбцы, все динамически и без привязки к коду.

Если у нас есть пользователь с ролью Admins, файл будет содержать столбцы Id, Name, Surname, Age, CreatedAt, UpdatedAt.

В случае, если вы генерируете его с использованием роли Users, он будет иметь Name, Age. Surname.

Заключение

Это отличный способ узнать, как dynamic работает в .NET, и это действительно хорошее решение, когда вам нужно иметь разные роли или шаблоны для разных пользователей и вы не особо заинтересованы в том, чтобы тратить время на жесткое программирование.

Непрерывная доставка пакета NuGet с использованием TravisCI

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

Недавно я сделал учебник о том, как использовать Travis CI в качестве инструмента для автоматического тестирования вашего кода, который вы только что отправили или пытаетесь отправить в ветку master. Заставить его скомпилировать и протестировать и, наконец, сообщить вам о статусе этого изменения.

Но мы можем продолжать делать ее лучше, например, основную библиотеку, созданную в последнем уроке. Я хочу сделать ее общедоступной с помощью канала NuGet, чтобы каждый мог упростить работу со своими библиотеками!

Но как? Как мы собираемся скомпилировать, протестировать, а затем опубликовать этот пакет в ленте, чтобы каждый мог загрузить его в свои проекты?

Ну вот этот урок для 😁!

Что нового?

В коде почти нет изменений, нам нужно изменить упаковку, публикацию, а затем то, как мы можем это автоматизировать.

.NET Core CLI

Мы собираемся использовать .NET Core CLI, мы использовали его в предыдущем руководстве с такими командами, как dotnet restore, dotnet build и dotnet test.

Теперь мы собираемся использовать новый набор команд!

[[[ТОК_9]]]

Вы можете посмотреть документацию по этому набору инструментов прямо здесь, но есть краткое объяснение:

dotnet nuget — это набор необходимых инструментов, включающий установку, восстановление, удаление и публикацию пакетов.

NuGet-фид

NuGet — менеджер пакетов для .NET. Клиентские инструменты NuGet предоставляют возможность создавать и использовать пакеты. Галерея NuGet — это центральный репозиторий пакетов, используемый всеми авторами и потребителями пакетов.

NuGet бесплатен, поэтому вы можете зарегистрироваться, получить ключ API и начать загрузку пакетов. Они будут загружены, проверены и затем перечислены для всех.

Получите ключ API

Чтобы загрузить пакет, вам потребуется получить ключ API после регистрации, поэтому перейдите на страницу ключей API и создайте новый.

Имейте в виду, что срок действия ключа API составляет 365 дней.

Затем скопируйте свой ключ и сохраните его где-нибудь, как сказано на странице, вы не сможете увидеть его снова, и если вы не сохранили его, вам придется его восстановить.

Создать пакет NuGet

Теперь, когда у нас есть ключ API, наш следующий шаг — сгенерировать пакет NuGet из решения, поэтому откройте решение, в котором у вас есть библиотека классов.

Я буду использовать решение из моего последнего урока, в котором есть класс библиотеки .NET Core под названием CalculatorCLI.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`

Как и в предыдущем уроке, мы использовали разные команды для создания и тестирования решения. Теперь мы собираемся добавить больше команд для упаковки и публикации пакетов.

Эти команды:

[[[ТОК_32]]]
[[[ТОК_33]]]

Скрипты развертывания

Поскольку мы собираемся изменить способ сборки, я считаю, что лучшей идеей было бы иметь разные файлы, каждый из которых содержит определение сборки в зависимости от среды.

Итак, давайте создадим папку с именем scripts с тремя скриптами bash в корне репозитория.

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 зависит от ветки
Если ваша сборка находится на master, это означает, что пакет необходимо обновить, поэтому мы собираемся отправить наш пакет в каналы NuGet.
Если ваша сборка представляет собой запрос на включение, мы все равно проверим, компилируется ли сборка и протестируем ее, но не будем ее публиковать.

Этапы

Из их документации:

Вы можете отфильтровывать и отклонять сборки, этапы и задания, указав условия в конфигурации сборки (ваш файл .travis.yml).

Дополнительную информацию о TravisCI stages можно найти на странице документации.

Итак, мы собираемся изменить файл и добавить этапы, что в итоге получится следующим образом:

language:
 csharp
sudo: required
mono: none 
dotnet: 3.0

os:
 - linux

jobs:
 include:
 - stage: compile
 script: bash scripts/compile.sh

 - stage: test
 script: bash scripts/test.sh

 - stage: deploy-prod
 if: branch = master AND type = push
 name: "Deploy to NuGet"
 script: bash scripts/push.sh

Как вы можете видеть, у нас есть три разных этапа compile, test и push, последний из которых будет запускаться только тогда, когда branch равен master и это не pull request для него, а только push.

Если вы этого не понимаете, просто загляните в документацию, и все объясняется довольно просто.

Имея это в виду, все pull request не будут ничего отправлять в канал NuGet.

Установка ключа API в качестве переменной среды

Перейдите к настройкам сборки вашего репозитория и добавьте новую переменную среды с именем NUGET_API_KEY со значением, являющимся скопированным ключом API со страницы NuGet.

Создайте `pull request`

Теперь, когда у нас все настроено, пришло время создать pull request и проверить, игнорирует ли компиляция для этого запроса на включение последний stage.

Проверьте сборки

Как только вы сделаете запрос на включение, сборка будет поставлена в очередь на панели управления TravisCI, и, как вы можете видеть, у нас там две разные сборки, а не три.

Теперь давайте примем pull request и снова проверим сборку, чтобы увидеть, что теперь у нас есть три задания вместо двух.

И как только вы увидите, что сборка поставлена в очередь, вы увидите три задания, включая Deploy-prod в конце.

Как только вся сборка завершится, вы увидите в журналах, что пакет был отправлен в исходные коды.

И, очевидно, вы можете увидеть это на странице NuGet.

Вот и все

В этом руководстве мы узнали, как автоматизировать доставку пакетов NuGet. Мы использовали некоторые инструменты, такие как TravisCI, stages и dotnet nuget.

На мой взгляд, даже если это потребует времени для правильной настройки и в некоторых случаях может оказаться слишком сложным. Инвестирование времени в такого рода методы, чтобы все было идеально и автоматизировано, того стоит.

Вы можете найти исходный код вместе с файлом .travis.yml прямо здесь, если у вас есть какие-либо вопросы, не стесняйтесь обращаться ко мне в twitter!

Непрерывная интеграция проекта .NET Core 3.0 с использованием TravisCI

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

В прошлые выходные я решил, что хочу правильно запустить свой проект скрапер-проверки-загрузчика, который я делал в разных репозиториях.

После запуска еще одного проекта это должно было быть круто, на самом деле круто, использование CI/CD, пул-реквест, документация, значки в файле readme, все, что я видел, это круто и действительно является лучшими практиками.

И после хороших выходных я создал Dramarr, набор инструментов для удаления и загрузки шоу из разных источников.

У него есть разные репозитории в организации, и большинство из них представляют собой библиотеки, которые компилируются, тестируются и развертываются самостоятельно в запросе на включение и при слиянии в основной ветке.

Это то, что называется CI/CD или непрерывной интеграцией/непрерывной доставкой.

Но в этом уроке мы просто поговорим о CI.

Непрерывная интеграция

Что это?

Взято из [блога] Мартина Фаулера (https://martinfowler.com/articles/continuousIntegration.html), это лучшее объяснение, которое я читал:

Непрерывная интеграция — это практика разработки программного обеспечения, при которой члены команды часто интегрируют свою работу, обычно каждый человек интегрируется как минимум ежедневно, что приводит к нескольким интеграциям в день. Каждая интеграция проверяется автоматической сборкой (включая тестирование) для максимально быстрого обнаружения ошибок интеграции.

Инструменты

Существует множество инструментов для интеграции вашего рабочего процесса с CI/CD, но в этом руководстве мы будем использовать Github для хранения нашего кода и инструменты TravisCI для настройки CI. Что касается языка и фреймворков, мы будем использовать C# и новый .NET Core 3.0.

Требования

Для того, чтобы сделать эту работу, вам нужны три простые вещи:

Последняя версия Visual Studio 2019.
Аккаунт на Гитхабе
Учетная запись Travis-CI, связанная с вашей учетной записью Github.

Проект

В рамках этого урока мы будем создавать простой калькулятор. Мы будем создавать библиотеку, инструмент командной строки и проект тестирования, чтобы протестировать все.

Этот проект тестирования также будет запущен, когда мы настроим CI, а это означает, что если в будущем мы внесем изменения в код и тесты, которые мы изначально создали, не пройдут, мы получим уведомление или можем просто отклонить запрос на включение.

Создание репозитория Github

Сначала мы создадим репозиторий Github, поэтому зайдите на Github, создайте репозиторий и клонируйте его в локальную среду. Я решил назвать этот новый репозиторий CalculatorCLI-demo.

Создание решения

Теперь создадим пустое решение с именем CalculatorCLI в корневой папке клонированного репозитория.

Основная библиотека

Как и в реальном проекте, мы будем хранить нашу логику в отдельном проекте, который генерирует библиотеку, поэтому давайте создадим ее.

Идите и создайте Class Library (.NET Standard) и назовите его CalculatorCLI.Core

Версия NET CoreКак только вы создадите проект, перейдите к свойствам проекта и измените `Target framework` на `.NET Standard 2.1`, чтобы сделать его совместимым с проектами, встроенными в `.NET Core 3.0`.

Код

В целях обучения давайте создадим простой класс, обрабатывающий операции.

[[[ТОК_12]]]

интерфейс командной строки

Теперь, когда у нас есть основной проект, давайте создадим приложение. В данном случае это будет простое консольное приложение, которое принимает аргументы и отображает результат.

Итак, давайте продолжим и создадим новый 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 в наш недавно созданный тестовый проект.

Код

Мы собираемся разделить тест на два разных файла: 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);
 }
 }
}

После всего созданного мы получим такое решение:

Теперь мы можем запускать тесты, поэтому перейдите в Test Explorer в Visual Studio и запустите их!

Трэвис CI

Если вы еще этого не сделали, TravisCI — это размещенная система непрерывной интеграции и развертывания.

Здесь нам нужно сделать несколько шагов, но сначала мы собираемся связать наш репозиторий Github, чтобы его прослушивали агенты TravisCI, чтобы построить и протестировать наш проект.

Включить репозиторий

Для этого войдите на страницу 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.
Мы не будем использовать mono, потому что .NET Core 3.0 будет работать в Linux.
Устанавливаем версию dotnet на 3.0.
Устанавливаем os, по умолчанию это linux, но я все равно его добавил.
Теперь у нас есть before_script который будет работать перед основной логикой .here, поэтому я поставил задачу запустить dotnet restore для решения, чтобы потом все загружалось идеально.
Теперь в script мы выполним dotnet builld и dotnet test для нашего решения, это проверит его компиляцию, а затем запустит тесты.

Иа, мы закончили!

Загрузить в мастер

Теперь нам просто нужно все подтолкнуть к освоению.

git add --all
git commit -m "Initial files"
git push

Проверьте непрерывную интеграцию

Мы можем проверить статус CI отправки в master, которую мы сделали, как на странице репозитория, так и на панели управления TravisCI.

В процессе

Готово

Давайте сломаем это

Теперь, чтобы увидеть, насколько это мощно, давайте сломаем код и изменим основную библиотеку, чтобы она не работала.

Изменения кода

Итак, перейдите в 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.

Вот и все

Вот и все, как создать решение .NET Core 3.0 с непрерывной интеграцией в каждой сборке с использованием TravisCI и сохранением кода в Github.

Вы можете найти исходный код этого проекта здесь.

Мой взгляд на кэш в памяти

Tue, 03 Sep 2019 00:00:00 +0000

Я работал над некоторыми вещами, которые обрабатывали большой объем данных. Делая это, я понял, что большая часть этого никогда не меняется, или, по крайней мере, в течение определенного времени это не так.

Поэтому я подумал, что было бы полезно создать личный репозиторий кэша, конечно, это не ново, несколько недель назад я прочитал об этом в [посте] StackOverflow (https://nickcraver.com/blog/2019/08/06/stack-overflow-how-we-do-app-caching/#in-memory--redis-cache), написанном Ником Крейвером о том, как они управляют кешем приложений.

Кроме того, я всегда хотел разобраться с кешем, узнать, как он работает, его логику и как заставить его работать, так… почему бы и нет!

Поток

Вот краткий обзор того, как будет вести себя класс, который управляет кешем, когда пользователь запрашивает значение.

Реализация

Прежде чем мы начнем

Я знаю, я знаю. Есть System.Runtime.Caching, который обрабатывает кеш памяти. Но я решил создать его сам. Если вы хотите использовать этот класс, проверьте здесь инструкции.

###Элемент кэша

Первый шаг — создать класс, в котором будет храниться значение объекта и дата истечения срока действия. Вероятно, есть лучший способ сделать это, но я так подумал, так что вот:

[[[ТОК_6]]]

###Репозиторий кэша

Затем нам нужен класс, который обрабатывает объекты и где-то их сохраняет (как CacheItem). Мне нравится обрабатывать все данные/модели в классах, имеющих суфикс Repository, но это не обязательно, поэтому давайте создадим один для кэширования.

[[[ТОК_9]]]

На данный момент у нас есть статический словарь под названием Cache, в котором будут храниться все элементы. Помните, что это будет продолжаться только во время работы приложения, поэтому в этом учебнике есть кэширование в памяти.

Имейте в виду, что элемент Cache будет инициализирован после загрузки класса CacheRepository.

Единственный метод, доступный при вызове класса CacheRepository, — это GetOrSet(string key, Func<T> lookup, TimeSpan durationMinutes) для которого требуется три параметра:

key: идентификатор объекта для сохранения.
lookup: функция обратного вызова в случае, если срок действия кеша истек или он равен нулю.
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, она запрашивает у CacheRepository значение объекта, имеющего ключ users.

Если этот ключ существует, он проверит дату истечения срока действия. Если какое-либо из этих условий ложно, он будет использовать обратный вызов для установки значения (с помощью usersRepo.Get) объекта, сохранения его в кэше с датой истечения срока действия, установленной в DateTime.UtcNow + TimeSpan.FromMinutes(10) и возврата его.

Делайте скриншоты страниц с помощью Devtools

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

Бывали случаи, когда мне нужно было показать клиенту или товарищу по команде полный снимок экрана текущего состояния веб-сайта или даже его части, поэтому я использовал Снимок экрана всей страницы, а для любых других видов снимков экрана — Инструмент Windows Snippet или Snaggit. Если я хочу разместить его в Интернете, как в этом посте Gyazo, в котором также есть создатель GIF.

Недавно я обнаружил, что в Devtools есть инструмент, который делает скриншот всей страницы без расширения!

Это не новая мысль, она была включена в обновление Devtools в апреле 2017 года, но похоже, что я живу под камнем и не узнал об этом до сих пор…

Инструменты разработчика

Как указано на официальной странице Devtools:

Chrome DevTools — это набор инструментов веб-разработчика, встроенных непосредственно в браузер Google Chrome. DevTools может помочь вам оперативно редактировать страницы и быстро диагностировать проблемы, что в конечном итоге поможет вам быстрее создавать более качественные веб-сайты.

Запуск команд в Devtools

Вы уже знаете, как открыть Devtools, но если вы просто забыли и ради этого поста, откройте его с помощью ключа F12 или ярлыка Ctrl + Shift + I. Затем вам нужно открыть Run command в меню Devtools или использовать Ctrl + Shift + P.

Инструмент создания снимков экрана

Если вы наберете screenshot команды будут фильтроваться, вы можете использовать 4 типа методов создания снимков экрана:

Скриншот области
Скриншот в полный размер.
Скриншот узла
Сделать снимок экрана

Прежде чем проверять все методы создания снимков экрана, после того, как devtools завершит обработку изображения, он автоматически загрузит его с именем веб-страницы.

Скриншот области

area screenshot позволит вам выбрать часть сайта и сделать снимок экрана.

Результат:

Скриншот в полном размере

full size screenshot сделает снимок экрана всей веб-страницы, от начала до конца.

Результат:

Скриншот узла

Команда node screenshot позволит вам сделать снимок экрана выбранного узла в элементе проверки.

Результат:

Сделать скриншот

capture screenshot сделает снимок экрана текущей страницы без прокрутки и размера браузера.

Результат:

Пользовательские языки с использованием встроенных и внешних ресурсов в .NET Framework.

Mon, 06 May 2019 00:00:00 +0000

Введение

На работе мы столкнулись с обычной проблемой, с которой, я почти уверен, приходится сталкиваться многим разработчикам, а именно с языками и специальными языками клиентов, которые предоставляют наши услуги своим клиентам.

Например, предположим, что базовый язык использует неформальный язык, а клиент хочет использовать формальный язык, потому что его клиенты — пожилые люди.

Также обратите внимание, что это решение предназначено для нескольких языков, мы будем использовать английский и испанский.

Мой родной язык не английский. Приношу извинения за ошибки в уроке. Если вы обнаружите ошибки и захотите их исправить, вы можете открыть запрос на включение в этот репозиторий, и я с радостью его одобрю!

Ресурсы

Ресурсы — это XML-файлы с расширением .resx со структурой ключ/значение, которые выглядят следующим образом:

[[[ТОК_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.John` вместо `Properties.Doe`.

Кроме того, это упрощает внесение изменений, когда приложение уже развернуто, поскольку вы можете легко изменить файл app.config.

## Доступ к встроенным файлам ресурсов

Использовать .NET Framework довольно просто, поэтому для доступа к встроенным свойствам нам просто нужно использовать объект `Properties` , который будет иметь файлы ресурсов в качестве свойства, а внутри этого объекта будут все ключи/значения, которые есть в файле `resx`.

```csharp
static void Main(string[] args)
{
 var hello = Properties.Resource.Action_greeting;
 var bye = Properties.Resource.Action_cancel;

 Console.WriteLine($"Action_greeting value: {hello}, Action_cancel value: {bye}");

 Console.Read();
}

Запустив это, мы должны показать что-то вроде этого:

Action_greeting value: Hello, Action_cancel value: Cancel

Доступ к файлам внешних ресурсов

Эта часть практически такая же: вы можете получить доступ к файлам ресурсов с помощью объекта Properties.

var hello = Properties.Resource.Action_greeting;
var bye = Properties.Resource.Action_cancel;

var johnhello = Properties.John.Resource.Action_greeting;
var johnbye = Properties.John.Resource.Action_cancel;

var doehello = Properties.Doe.Resource.Action_greeting;
var doebye = Properties.Doe.Resource.Action_cancel;

Проблема

Основная проблема при использовании этого метода заключается в том, что каждый ключ является свойством внутри объекта, поэтому нам приходится вызывать его так, как мы видели раньше. Если вы хотите вызвать ключ Action_greeting файла ресурсов John мы должны использовать следующий Properties.John и затем Resource.Action_greeting.

Вот в чём проблема.

Это потому, что если мы разрабатываем приложение для большого количества клиентов, менять способ вызова файлов ресурсов для каждого из них — плохая идея.

Можете ли вы себе такое представить? Компилируем приложение для каждого клиента и меняем John на Doe, а затем на что-то еще. Это безумие!

Решение

Наш руководитель группы придумал довольно хороший метод, что-то вроде резервной системы: у нас должна быть базовая модель ресурсов, а затем для каждого из клиентов есть файл ресурсов, который будет обновлять файл своими ресурсами, и в итоге мы получаем единый список ресурсов.

Если клиенту не нужны специальные ресурсы, мы используем базовые ресурсы, а если они им нужны, мы используем их.

Чтобы внести это в контрольный список, нам нужно сделать:

Найдите способ сопоставить все ключи/значения со словарем для встроенных ресурсов.
[] Найдите способ сопоставить все ключи/значения со словарем для внешних ресурсов.
Смешайте оба файла и получите один словарь для каждого языка.
[] Создать метод, который обращается к словарю и возвращает значение

Диаграмма

Давайте напишем код

Прежде всего, давайте создадим отдельный класс, в котором будет вся наша логика: от получения файлов ресурсов до их смешивания и возврата значения. Этот класс будет называться CustomResources.

Вот как это выглядит:

 class CustomResources
 {

 private static Dictionary<string, string> _ResourcesEnglish;
 private static Dictionary<string, string> ResourcesEnglish;

 private static Dictionary<string, string> _ResourcesSpanish;
 private static Dictionary<string, string> ResourcesSpanish;


 private static Dictionary<string, string> OverwriteDictionary(Dictionary<string, string> currentDictionary, Dictionary<string, string> newDictionary, bool addIfDoesntExist = false)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
 {
 ...
 }

 private static Dictionary<string, string> GetDictionaryFromFile(string file)
 {
 ...
 }

 public static string GetText(string key)
 {
 ...
 }

 public static string GetText(string key, string language)
 {
 ...
 }
 }

Обратите внимание, что мы реализуем отложенную загрузку свойств, что помогает повысить производительность и позволяет однократно загружать словарь.

GetDictionaryFromEmbedded: возвращает словарь из встроенных ресурсов.
GetDictionaryFromFile: возвращает словарь из внешних ресурсов.
OverwriteDictionary: смешивает два словаря и возвращает один.
GetText: возвращает значение по ключу.

От встроенного ресурса к словарю

Нам нужно получить все свойства из XML-файла и вернуть словарь:

private static Dictionary<string, string> GetDictionaryFromEmbedded(string embedded, string cultureInfoCode)
{
 Dictionary<string, string> res = new Dictionary<string, string>();

 try
 {
 ResourceManager rm = new ResourceManager(embedded, Assembly.GetExecutingAssembly());
 var resourceSet = rm.GetResourceSet(new CultureInfo(cultureInfoCode), true, true);

 var resourceDictionary = resourceSet.Cast<DictionaryEntry>()
 .ToDictionary(r => r.Key.ToString(),
 r => r.Value.ToString());
 res = resourceDictionary;
 }
 catch (Exception e)
 {
 string a = e.Message;
 // Error getting resource file
 }

 return res;
}

Две вещи:- Обратите внимание, что ему нужен параметр с именем embedded, который parementers — это имя файла, который вы можете увидеть в дизайнере, в нашем случае это: resources-demo.Properties.Resource.

Также у нас есть параметрcultreInfoCode, который является кодом выбираемого языка. К счастью для нас, .NET Framework делает всю работу за нас, и нам не нужно ничего делать, просто установите английский или испанский язык, и он выберет между resource.es.resx или resource.resx

Из внешнего ресурса в словарь

Получение файла из файла немного сложное, но несложное: нам нужно получить текущее местоположение исполняемого файла, соединить местоположение файла ресурсов, а затем проанализировать его в словаре.

Но сначала вам нужно добавить ссылку на System.Windows.Forms, чтобы получить доступ к ResXResourceReader.

Теперь перейдем к нашему методу 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".

Смешивание словарей

Мы почти закончили, во-первых, не забудьте добавить System.Configuration к ссылкам, чтобы вы могли получить доступ к app.settings.

 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.
Затем получаем базовые ресурсы, встроенные.
После этого мы получаем пользовательские ресурсы, для этого нам нужно имя папки (которое является идентификатором).
Затем смешиваем их и возвращаем значение.

Все это будет сделано один раз, из-за ленивой загрузки.

Тестирование

Все, что связано с кодом, закончено, теперь давайте его протестируем, чтобы получить значение из словаря нам нужно вызвать метод CustomResources.GetText(string key) который возвращает значение.

Обновление целых файлов ресурсов

Это тестирование представляет собой тот случай, когда мы хотим обновить весь ключ/значение файлов ресурсов, как вы можете видеть на изображениях, у нас одинаковые ключи, но разные значения.

Мы будем тестировать John, и для того, чтобы это установить, нам нужно установить в app.config значение <add key="CustomResources.Folder" value="John" />.

Теперь давайте проверим наш базовый файл ресурсов (Properties/Resource.es.resx):

И затем наш внешний файл ресурсов (Properties/John/Resource.es.resx):

Окей, все настроено, запускаем консольное приложение, остановимся на части свойств get и все проверим

folderIdentifier имеет значение настройки приложения:

baseResources имеет значение базовых ресурсов, встроенных:

customResources содержит значения внешних ресурсов внутри папки John:

И, наконец, _ResourcesSpanish имеет значение, смешанное с базовыми ресурсами и внешними ресурсами.

Обновление только одного

Теперь давайте протестируем то же самое, но по другому сценарию: просто обновим один ключ, а другой оставим таким же.

Как вы можете видеть, файлы имеют одинаковое значение значения для Action_greeting, но другое значение для Action_cancel, поэтому следует обновлять только Action_cancel.

Отсутствует файл ресурсов

Если вы не предоставите внешний файл ресурсов, это вообще не имеет значения, потому что, поскольку мы ожидаем наличие файла, в случае сбоя он вернет пустой словарь, а при смешивании обоих словарей в конечном итоге получится базовый.

Отсутствует пара во встроенном ресурсе

Если у вас есть пара во внешнем файле ресурсов, по умолчанию она не будет добавлена в окончательный словарь. Вы можете изменить это, вызвав метод OverwriteDictionary() при смешивании обоих словарей и установив для параметра addIfDoesntExist значение true.

Разные языки

Как вы можете видеть, мы не указали какой-либо язык, потому что все это делается функцией GetText(string key), которая вызывает GetText(string key, string language), а параметр language заполняется TwoLetterISOLanguageName который возвращает текущий язык нашего потока.

В моем случае испанский язык является языком по умолчанию, поэтому он всегда отображается на испанском, но мы можем попробовать использовать и английский.

Давайте немного напишем код и создадим что-нибудь для проверки испанского и английского языков.

static void Main(string[] args)
{

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("en-US");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("en-US");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 // System.Threading.Thread.CurrentThread.CurrentUICulture = new CultureInfo("es-ES");
 System.Threading.Thread.CurrentThread.CurrentCulture = new CultureInfo("es-ES");
 WriteText("Action_greeting");
 WriteText("Action_cancel");

 Console.Read();
}

private static void WriteText(string key) {
 Console.WriteLine($"[Culture: {System.Threading.Thread.CurrentThread.CurrentCulture}] Key: {key} -> value: {CustomResources.GetText(key)}");
}

Запустив это, результат должен быть примерно таким:

[Culture: en-US] Key: Action_greeting -> value: Hello
[Culture: en-US] Key: Action_cancel -> value: Finish
[Culture: es-ES] Key: Action_greeting -> value: Hola
[Culture: es-ES] Key: Action_cancel -> value: Terminar

Первые два значения взяты из resources.resx на английском языке, а последние оба на испанском, и значения извлекаются из resources.es.resx.

Вот и все

В этом уроке мы нашли способ объединить встроенные и внешние ресурсы для языков. Это было решением проблемы, которая возникла у нас в команде, и с тех пор все работает без каких-либо проблем.

Вы можете проверить исходный код здесь.

Если у вас есть какие-либо вопросы, напишите мне в Твиттере по адресу @emimontesdeocaa, и я свяжусь с вами, когда у меня будет время.

Интеграционный тест с использованием Bot Framework и DirectLine для потоковых случаев.

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

Введение

В предыдущих сообщениях блога мы провели интеграционный тест для отдельных случаев. «Единичные случаи» — это те случаи, что задав что-то боту, он ответит только один раз, а затем мы сравниваем результаты.

В этом руководстве не объясняется, как выполняются аутентификация и вызовы API. Если вы хотите это проверить, ознакомьтесь с руководством для отдельных случаев.

А как насчет плавных разговоров?

Используя текущий способ, у нас нет какого-либо потока в разговоре, например, если вы хотите попросить о помощи, а затем появляется меню с различными опциями, а затем, после выбора одного из них, другое меню. Это составит примерно 2 или более responses. Это означает, что использование решения для интеграционного тестирования, которое мы использовали ранее, не будет работать.

Вот схема того, как работает интеграционный тест для отдельных случаев.

А вот схема того, как мы собираемся адаптировать текущее решение для интеграционного тестирования к потоковым сценариям.

[

Следующее объяснение не охватывает всю основную информацию о том, как работает Bot Framework. Если вы не понимаете, пожалуйста, просмотрите официальную документацию.

Пример случая

В следующем руководстве я буду использовать бота с созданным мной потоковым диалогом, который просит о помощи, а затем выбирает различные варианты.

[

Новая структура JSON

Теперь, когда у нас есть более одного request при разговоре с ботом, нам нужно изменить нашу структуру json, чтобы добавить все request, которые мы будем делать.

[[[ТОК_9]]]

Как видите, произошло важное изменение: request теперь называется requests. Это означает, что теперь у нас есть List<Activity> вместо одного activity.

Новые объекты

Раньше у нас были объекты, настроенные для отдельных случаев: TestEntry и TestEntryCollection. Для случаев потока мы будем создавать новые объекты: TestEntryFlow и TestEntryFlowCollection.

`TestEntryFlow`

Этот объект предназначен для каждой записи, которая есть в коллекции. Обратите внимание, что объект Requests теперь является List<Activity> вместо одного 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`

Этот объект будет содержать соответствующую информацию для DirectLine, такую как secret и конечные точки, а также список Entries, который мы будем тестировать.

Обратите внимание, что Entries теперь представляет собой список TestEntryFlow, а не TestEntry.

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

Теперь нам нужно выполнить цикл для каждого TestEntryFlow из data.entries, при этом мы можем следовать тому же потоку, который мы делали в отдельных случаях, до новой части, где мы зацикливаемся на 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 — это значение, которое API DirectLine возвращает при запросе информации о разговоре.

После этого нам останется только заполнить globals нашими latestReponse и expectedResponse.

/// Arrange with new values
var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

И чтобы закончить дело, мы оцениваем строку assert в entry.

/// 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 должен быть более заполнен.

Чтобы сделать это тестирование лучше, у нас должен быть response для каждого request, и мы должны утверждать каждый раз, когда отправляем сообщение. Сейчас мы делаем это, сохраняя все requests и финальный response .

Я сделал схему, чтобы показать, как это будет выглядеть.

Я твердо убежден, что этот способ в целом намного лучше с точки зрения целостности теста, поскольку вы тестируете практически каждое поведение в потоке, а не просто тестируете окончательный ответ.

Ну, это все, что касается этого руководства. Помните, что это руководство является продолжением руководства для отдельных случаев. Если вы чувствуете себя потерянным, обратитесь к тому руководству, которое длиннее и содержит больше объяснений для всего.

Помните, что весь код хранится у меня на github в репозитории this.

Хорошего дня!

Интеграционный тест с использованием Bot Framework и DirectLine (1)

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

Поскольку я начал работать в компании в течение короткого периода времени, мне поручили работать над интеграционным тестом для Bot Framework.

Моя работа в группе — сделать бота максимально стабильным, но прежде всего, что такое Bot Framework?

Создавайте, подключайте, развертывайте интеллектуальных ботов и управляйте ими, чтобы естественным образом взаимодействовать с вашими пользователями на веб-сайте, в приложении, в Cortana, Microsoft Teams, Skype, Slack, Facebook Messenger и т. д. Быстро начните работу с полноценной средой для создания ботов, платя только за то, что вы используете.

Вы можете найти дополнительную информацию о Bot Framework прямо здесь.

Зачем мне нужен интеграционный тест?

Интеграционный тест необходим, потому что каждый раз, когда один из моих коллег выдвигает исправление, новую функцию или даже новую ошибку, эти тесты будут запускаться перед отправкой кода в производство, и если какой-либо из тестов завершится неудачно, код не пойдет в производство, а это означает, что у конечного пользователя не будет ошибки.

Тест интеграции с ботами?

Я верю, что для ботов интеграционный тест очень важен. У вас не может быть бота, у которого некоторые меню не работают или некоторые функции ничего не возвращают.

Компании используют ботов для своих клиентов, потому что не хотят, чтобы люди были заняты их проблемами. Если бот может помочь пользователю, другие сотрудники смогут использовать свое время для чего-то более важного.

Обзор решения.

Чтобы это работало, я использовал тестовый проект в Visual Studio, который будет использовать WebClient для API Rest и файл Json, где мы будем хранить наши случаи.

JSON-файл

[[[ТОК_1]]]

Как видите, у нас есть:

Секрет Директа -> секрет от опубликованного бота
Конечная точка генерации токена Directline -> конечная точка для получения токена с использованием секрета.
Конечная точка разговора по прямой линии -> конечная точка, чтобы поиграть с разговором.
Вступление -> тестовый пример
- Запрос -> что отправляем в беседу
- Ответ -> то, что мы ожидаем получить
- Assert -> что мы сравниваем

Десериализация

У нас есть идеально отформатированный файл json, теперь нам нужно загрузить его в решение, поэтому мы будем использовать JSON.NET и некоторые классы. Сначала у нас есть коллекция записей, в которой есть все, а затем для каждой коллекции есть список записей.

[[[ТОК_2]]]

И это объект, который имеет имя, запрос, ответ и утверждение для тестового примера.

[[[ТОК_3]]]

Разбор json в объект в тестовом примере

Имея классы для объекта синтаксического анализа, это довольно просто, поскольку нам нужно читать как объект.

[[[ТОК_4]]]

Теперь, имея эту коллекцию, мы сможем просмотреть ее и получить информацию, используя, например, foreach.

 foreach (TestEntry entry in data.Entries)
 {
 ....
 }

И на этом всё, следующая часть будет включать авторизацию для DirectLine, помните, что весь код хранится у меня на github в репозитории this.

Интеграционный тест с использованием Bot Framework и DirectLine (2)

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

В этой части мы проведем авторизацию DirectLine и получим значения из ответа бота.

Теперь, когда мы выполнили десериализацию, пришло время получить информацию из коллекции и всего, что мы будем использовать для получения авторизации, выполнения вызовов API и подтверждения результата.

Выполнение вызовов API с помощью WebClient

Чтобы нам было проще вызывать API, я создал класс utils, в котором мы сохраняем функции, которые будем использовать несколько раз. Этот класс включает в себя uploadString для POST и downloadString для GET.

[[[ТОК_3]]]

Авторизация DirectLine

Если вы прочитаете официальную документацию, то сможете узнать, как это сделать, и это довольно легко, а с нашими функциями еще проще. Прежде всего помните, что мы находимся внутри оператора foreach, поскольку мы выполняем аутентификацию для каждого случая на случай, если у нас закончится время, что означает, что тест завершится неудачей.

[[[ТОК_4]]]

Теперь у нас есть токен, который будет использоваться для всех последующих вызовов конечной точки диалога.

Создание разговора.

Чтобы поговорить с ботом, нам сначала нужно создать разговор. Этот разговор вернет новый токен, который включает идентификатор разговора.

/// 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 мы можем создать конечную конечную точку для отправки Activity, который является request из файла json.

[[[ТОК_12]]]

Получить последнее сообщение

В истории сообщений после того, как мы отправили действие, бот уже должен был ответить, поэтому нам нужно получить все сообщения с водяным знаком, а затем, используя этот водяной знак, отфильтровать последнее сообщение/действие.

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

И это все, что касается этой части, следующая часть будет включать в себя часть, в которой мы получаем текст из assert в json, преобразуем его в код, например, используя eval() в Javascript, но в C#, а затем используя Assert.isTrue() для получения окончательного результата теста.

Помните, что весь код хранится у меня на github в репозитории this.

Интеграционный тест с использованием Bot Framework и DirectLine (3)

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

Это последняя часть руководства, в этой части мы будем оценивать текст из утверждения в json.

Теперь, когда мы использовали request и отправили боту как activity, мы получили response и нам нужно сравнить то, что assert в json (ответ, который мы сохранили в json, это ожидаемый ответ) с ответом, который мы получили от бота.

Добавление Microsoft.CodeAnaанализ в решение

Прежде всего, нам нужно включить CodeAnalysis как пакет NuGet.

[

После установки не забудьте добавить пакет в файл .cs.

[[[ТОК_7]]]

Создание объекта `Globals`

Чтобы оценить, мы должны передать параметры оценщику. Этому оценщику нужен файл конфигурации.

[[[ТОК_9]]]

Эта часть очень важна: в этот файл конфигурации мы будем включать объекты, которые будем сравнивать, поэтому нам нужно передать ему ожидаемый ответ и полученный ответ.

Имея эту информацию, он будет использовать assert в файле json и оценивать то, что он говорит.

[[[ТОК_11]]]

EvaluateAsync<T> оценивает и возвращает T, в нашем случае мы передаем string для оценки и globals, который содержит данные, в которых он будет оценивать.

Я попытаюсь объяснить это на примере, используя запись (которая имеет имя, запрос, ответ и утверждение).

{
 "name": "DecirHola",
 "request": {
 "type": "message",
 "text": "Hola",
 "from": {
 "id": "default-user",
 "name": "User"
 },
 "locale": "es",
 "textFormat": "plain",
 "timestamp": "2018-04-09T08:04:37.195Z",
 "channelData": {
 "clientActivityId": "1523261059363.6264723268323733.0"
 },
 "entities": [
 {
 "type": "ClientCapabilities",
 "requiresBotState": true,
 "supportsTts": true,
 "supportsListening": true
 }
 ],
 "id": "61hacck8j6jg"
 },
 "response": {
 "type": "message",
 "timestamp": "2018-04-09T08:04:37.901Z",
 "localTimestamp": "2018-04-09T09:04:37+01:00",
 "serviceUrl": "http://localhost:50629",
 "channelId": "emulator",
 "from": {
 "id": "j98bbdf097a",
 "name": "Bot"
 },
 "conversation": {
 "id": "eabcie4be8ak"
 },
 "recipient": {
 "id": "default-user"
 },
 "locale": "es",
 "text": "No tengo respuesta para eso.",
 "attachments": [],
 "entities": [],
 "replyToId": "61hacck8j6jg",
 "id": "47me557ikbf7"
 },
 "assert": "Request.Text == Response.Text"
 }

Давайте возьмем самое важное из этой записи: сначала утверждение "assert": "Request.Text == Response.Text", это означает, что оно сравнит Request.Text с Response.Text и вернет значение в виде логического значения.

Но когда мы вызываем функцию await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals) мы передаем 2 параметра:

string строка для оценки -> "Request.Text == Response.Text"
Данные globals для оценщика -> в этом случае мы должны предоставить Request и Response, запрос — это наш ожидаемый ответ, а ответ — это полученный ответ.

Поскольку мы заполняем данные в вычислителе, теперь мы можем использовать строку и оценивать, поэтому она вернет true или false.

Готово

Мы закончили, здесь вы можете увидеть готовый TestMethod

[TestMethod]
public async Task ShouldTestSingleCases()
{
 // Load entries from file
 var path = System.IO.File.ReadAllText(@"C:\data.json");

 // Deserialize to object
 var data = JsonConvert.DeserializeObject<TestEntriesCollection>(path);

 /// Flow: Arrange -> Act -> arrange -> assert

 foreach (TestEntry entry in data.Entries)
 {
 /// Arrange with current requested values
 string token, newToken, conversationId;

 if (entry.Request.Type == ActivityTypes.Message)
 {
 /// Act

 /// 1 - Get token using secret from DirectLine in BotFramework panel
 token = Utils.uploadString<DirectLineAuth>(data.Secret, data.DirectLineGenerateTokenEndpoint, "").token;

 /// 2 -Create a new conversation
 var createdConversation = Utils.uploadString<DirectLineAuth>(token, data.DirectLineConversationEndpoint, "");

 // This returns a new token and a conversationId
 newToken = createdConversation.token;
 conversationId = createdConversation.conversationId;

 /// 3 - Send an activity to the conversation with new token and conversationId
 string directlineConversationActivitiesEndpoint = data.DirectLineConversationEndpoint + conversationId + "/activities";
 Utils.uploadString<DirectLineAuth>(newToken, directlineConversationActivitiesEndpoint, JsonConvert.SerializeObject(entry.Request));

 /// 4 - Get all activities, we get a List<activity> and a watermark
 var getLastActivity = Utils.downloadString<ActivityResponse>(newToken, directlineConversationActivitiesEndpoint);

 /// 5 - Get the latest activity which is the response we should be expecting
 var latestResponse = getLastActivity.activities[Int32.Parse(getLastActivity.watermark)];

 /// Arrange with new values
 var globals = new Objects.Globals { Request = entry.Response, Response = latestResponse };

 /// Assert
 Assert.IsTrue(await CSharpScript.EvaluateAsync<bool>(entry.Assert, globals: globals));
 }
 }
 await Task.CompletedTask;
}

Диаграмма

Вот диаграмма всего процесса, которому мы следовали, чтобы понять этот момент. Надеюсь, если вы чего-то не поняли, это прояснит ситуацию.

И это все, это делается для единичных случаев, когда случай 1 к 1, пользователь отправляет activity и бот возвращает еще один одиночный activity.

Надеюсь, вам понравилось. следующим будут сценарии тестирования с более чем одним ответом.

Помните, что весь код хранится у меня на github в репозитории this.

Выступления

Mon, 01 Jan 0001 00:00:00 +0000

Я регулярно выступаю на международных технологических конференциях, фокусируясь на .NET, Azure, ИИ и облачно-нативной разработке. Я был отмечен как Самый активный докладчик Sessionize в 2023, 2024 и 2025 годах, а также имею сертификат Microsoft MVP в области технологий для разработчиков.

Если вы хотите, чтобы я выступил на вашем мероприятии, давайте поговорим!

2026

Blazor в 2026 году

Взгляд на текущее состояние Blazor в 2026 году и то, как он эволюционировал вместе с .NET 10. Рассматриваем последние изменения и улучшения, их влияние на разработку реальных приложений, и какая модель хостинга Blazor лучше всего подходит для каждого сценария.

Усиление поддержки уровня 3 с помощью ИИ: Azure Functions + OpenAI в действии

Как Azure Functions, оповещения Azure Monitor и Azure OpenAI работают вместе для ускорения поддержки уровня 3. От автоматической сортировки алертов до интеллектуального анализа логов — практический взгляд на добавление ИИ в реальные рабочие процессы поддержки.

От дашборда к агенту: следующий шаг наблюдаемости

Практическая сессия, соединяющая мир ИИ-агентов и наблюдаемости в продакшене. От Semantic Kernel до автономных агентов, запрашивающих данные OpenTelemetry, взаимодействующих с Grafana через MCP и помогающих эксплуатировать и оптимизировать реальные системы.

Ожидается: Global Azure 2026 — Апрель 2026, Мадрид, Испания

2025

Фреймворк агентов Microsoft спасает Рождество

Построение и координация нескольких ИИ-агентов с помощью Microsoft Agent Framework для поиска идеальных рождественских подарков. Каждый агент специализируется — от генерации идей подарков до сравнения цен — работая вместе для более умных праздничных покупок.

Усиление поддержки уровня 3 с ИИ: Azure Functions + Semantic Kernel в действии

Azure Functions, Azure Monitor и Semantic Kernel работают вместе, чтобы сделать поддержку уровня 3 более быстрой и эффективной — от автоматического обнаружения алертов до интеллектуального анализа логов.

Что нового в Blazor с .NET 10?

Изучение ключевых новых возможностей Blazor для .NET 10, включая улучшения производительности, формы, постоянное состояние и более мощную JavaScript-интероперабельность.

Гибридный ИИ с C#, Semantic Kernel и Gemini: Создание умных корпоративных приложений

Оркестрация гибридных ИИ-рабочих процессов на C# — сочетание локальных моделей (Phi-3) с Gemini Pro/Ultra через Vertex AI, построение когнитивных агентов с плагинами Semantic Kernel и проектирование адаптивных архитектур.

.NET Aspire: Создание Cloud-Native приложений без головной боли

Практическая сессия по созданию облачных микросервисов, изначально масштабируемых, отказоустойчивых и наблюдаемых. Изучение того, как .NET Aspire устраняет 70% облачного бойлерплейта.

.NET Aspire: Cloud-Native без хаоса

Реальные примеры проектирования приложений, изначально масштабируемых — с наблюдаемостью и авто-устойчивостью с самого первого коммита.

2024

ИИ встречает SQL: Создание умной пиццерии с .NET и Semantic Kernel

Взаимодействие ИИ на естественном языке, понимающего ваш код и данные — создание интеллектуальной пиццерии на .NET и Semantic Kernel.

.NET Aspire: Cloud-Native приложения без сложностей

Создание облачных микросервисов без головной боли — практическая демо-сессия, показывающая, как .NET Aspire упрощает Cloud-native разработку.

Power Platform: Путешествие от Low-code к Pro-code технологиям

Переход от Low-code Power Apps к продвинутым Pro-code компонентам с использованием TypeScript в рамках той же платформы.

Интеллектуальная автоматизация: Трансформируйте свои корпоративные приложения с интегрированным ИИ

Вывод .NET-приложений на следующий уровень — сочетание традиционной логики с ИИ-рассуждением с помощью Semantic Kernel и .NET Aspire.

От Low-Code к Pro-Code: Подходы к разработке ИИ в корпоративных решениях

Исследование различных подходов для корпоративных решений — от Power Platform с ИИ до традиционной разработки с Semantic Kernel.

Управление командировочными расходами с Azure

Использование Azure AI Vision, Document Intelligence и OpenAI с Semantic Kernel для автоматизации управления командировочными расходами.

Значки и Признание

🏆 Sessionize Most Active Speaker 2025
🏆 Sessionize Most Active Speaker 2024
🏆 Sessionize Most Active Speaker 2023
🏅 Microsoft MVP в области технологий для разработчиков

Посмотреть все сессии на Sessionize →

Обо мне

Mon, 01 Jan 0001 00:00:00 +0000

Обо мне

Я Эмилиано Монтесдеока (Emiliano Montesdeoca) — уругвайско-испанский разработчик программного обеспечения, Microsoft MVP в области технологий для разработчиков, и счастливый отец, живущий в Тенерифе, Канарские острова.

Я люблю решать сложные технические задачи и создавать масштабируемые облачные решения с технологиями Microsoft. Мой ежедневный набор инструментов вращается вокруг .NET, Azure, ИИ с Semantic Kernel и современных архитектур, таких как .NET Aspire.

Чем я занимаюсь

В качестве тимлида по облачным решениям в Intelequia Technologies я руковожу проектированием и разработкой облачно-нативных приложений — сочетая стратегическое видение с практическим исполнением. Я процветаю на стыке архитектуры и кода, обеспечивая создание командой решений, которые одновременно элегантны и готовы к производственной среде.

Сообщество

Я регулярно выступаю на международных конференциях и был признан Самым активным докладчиком Sessionize в 2023, 2024 и 2025 годах. Делюсь практическими знаниями из реального мира через выступления на конференциях по всему миру и через свои блоги.

Я также создатель The .NET Blog — ресурса для сообщества .NET — и регулярно пишу в этом блоге о том, что учу и создаю.

Наставничество и построение сообщества — это неотъемлемая часть того, кто я есть. Отдача экосистеме, которая сформировала мою карьеру, — это то, к чему я отношусь серьёзно.

Давайте свяжемся

Я всегда открыт для выступлений на мероприятиях, сотрудничества в проектах или разговоров об облачной архитектуре и ИИ. Не стесняйтесь обращаться!

Email: emimontesdeoca@outlook.es
GitHub: @emimontesdeoca
X / Twitter: @emimontesdeocaa
LinkedIn: emimontesdeoca
Instagram: @emimontesdeoca
Sessionize: emimontesdeoca

Emiliano Montesdeoca

Blazor с нуля: Глава 3 — Компоненты, которые масштабируются

Что такое компонент Blazor на практике

Шаг 1: Начните с узко сфокусированного компонента

Шаг 2: Делайте поведение явным через параметры

Шаг 3: Используйте RenderFragment для композиции

Шаг 4: Композиция вместо гигантских страниц

Шаг 5: Баланс между разметкой и логикой

Шаг 6: Практичная структура папок

Частые ошибки в ранних Blazor-проектах

Что дальше

Blazor с нуля: Глава 2 — Ваше первое приложение Blazor

Шаг 1: Создайте проект

Шаг 2: Запустите локально

Шаг 3: Разберитесь со структурой проекта

Шаг 4: Сделайте первое изменение

Шаг 5: Один раз прочитайте Program.cs

Частые проблемы

Что дальше

Blazor с нуля: Глава 1 — Что такое Blazor?

Краткая история

Что такое Blazor на самом деле

Модели рендеринга

Статический SSR

Интерактивный сервер

Интерактивный WebAssembly

Режим Auto

Смешивание режимов в одном приложении

Как Blazor соотносится с JavaScript-фреймворками

Что нужно для дальнейшего изучения

Что дальше

Blazor с нуля: Новая серия

Для кого эта серия

Что мы рассмотрим

Почему серия, почему сейчас

Как следить за серией

Типы объединений C#: наконец-то появляются размеченные объединения

Что такое дискриминируемые профсоюзы?

Как мы моделируем профсоюзы сегодня

Абстрактные записи с наследованием

Библиотека OneOf

Ручное перечисление + шаблон данных

Предложение C#: ключевое слово union

Члены, имеющие только значение

Общие союзы

Объединения с методами

Сопоставление вложенных шаблонов

Охранные положения

Практические примеры

Шаблон результата: замена исключений на ожидаемые ошибки

Моделирование домена: типы платежей

Государственные машины

Как попробовать

Сравнение с существующими подходами

Что это значит для экосистемы .NET

Заключение

Создание системы RAG на C# с семантическим ядром

Введение

Как работает RAG

Предварительные условия

Настройка ядра

Определение модели данных

Разбиение документов на части

Загрузка документов

Поиск соответствующих фрагментов

Генерация ответов с учетом контекста

Использование этого

Переезд в производство

Советы по созданию RAG-систем

Заключение

Ресурсы

Создание рабочих процессов агента с помощью Microsoft Agent Framework

Введение

Что такое рабочие процессы агента?

Предварительные условия

Построение последовательного рабочего процесса

Определение агентов

Выполнение последовательно

Параллельное выполнение

Условное ветвление

Шаг 3: Используйте `RenderFragment` для композиции

Предложение C#: ключевое слово `union`