Богдан Стефанюк: дописи з тегом asp.net core

Push Notification via ASP.NET Core

Thu, 08 Jun 2023 20:43:17 -0400

Недавно запустили на роботі новий функціонал інбоксів. Якщо коротко, то це універсальний месенджер з підтримкою різних платформ та каналів що дозволяє вести комунікацію з кінцевими клієнтами в одному місці.

Для кращого UX треба було добавити пуш нотифікації. На цей момент у нас уже були підключені веб сокети по яким ганяли різні дані, в тому числі і про нові повідомлення. Але такі сповіщення можна відобразити тільки коли відкрита сторінка в браузері.

Тому вирішили добавити підтримку браузерних пушів. Саме про те як їх підключити та використовувати в звʼязці з ASP.NET Core я хочу розказати.

Як це працює?

Процес роботи технології пуш нотифікацій у браузері досить простий. Спочатку ми запрошуємо права на отримання сповіщень у користувача. Браузер покаже йому модалку із запитанням «Do you want to receive push notifications?».

Після того як він підтвердить вибір нам потрібно підписати користувача на отримання нотифікацій використовуючи Push API браузера. Під капотом браузер робить запит на спеціальний push service та повертає нам обʼєкт PushSubscription в якому є вся необхідна інформація для відправки пушів:

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/c1KrmpTuRm…",
  "expirationTime": null,
  "keys": {
    "p256dh": "BGyyVt9FFV…",
    "auth": "R9sidzkcdf…"
  }
}

Далі ми берем цей обʼєкт і відправляємо на наш сервер, де кладемо його у базу даних або зберігаємо іншим способом щоб використовувати його в подальшому.

Якщо придивитися до структури PushSubscription, можна помітити адрес ендпоінта. Суть в тому, що наш сервер не відправляє сповіщення напряму в браузер. Для цього використовується спеціальний push service, який у кожного розробника браузера свій.

Нам повезло, що браузери змогли домовитись і стандартизувати протокол push сервіса, тому нам можна не паритись за формат даних для кожного вендора. Усі вони приймають один формат даних, який містить:

Контент повідомлення
Кому його відправити
Як саме його відправити, з яким пріорітетом, в який топік та з яким таймаутом.

Кожне повідомлення шифрується за допомогою ключів, що були створені при генерації підписки. Крім цього, потрібно також підписувати повідомлення за допомогою приватного ключа, щоб підтвердити, що це саме наш сервер відправляє повідомлення. Виглядає це ось так:

Генеруємо пару публічного та приватного ключа, які ще називають VAPID ключами. Цей крок треба зробити всього один раз. В інтернеті купа онлайн сервісів де можна згенерувати ключі.
Публічний ключ використовуємо при створенні підписки на стороні браузера. Дальше цей ключ асоціюється з ендпоінтом для конкретної підписки.
Приватний ключ використовуємо для підписки повідомлення на стороні нашого сервера.
Дальше за допомогою публічного ключа ми можемо перевірити що повідомлення було відправлено саме нашим сервером а не кимось іншим.

Структура VAPID ключа:

{
    "sub": "mailto:bohdan@stefaniuk.io",
    "public_key": "sdgdklsnvi2f0m-12dgsg...",
    "private_key": "1fn0ASFfnaksf..."
 }

Але, як в тому жарті, є нюанс. Subject в VAPID ключі є опціональним і його не обовʼязково відправляти разом з запитом на push сервіс. Проте Сафарі так не вважає, ще й вимагає специфічний формат. Коли я генерував ключі, то мав ось такий sub mailto: <bohdan@stefaniuk.io>.

В хромі все працювало чудово, а сафарі кидав помилку, що запит невалідний. Виявилось, що вони не підтримують пробіли та кутові лапки, замінив sub на mailto:bohdan@stefaniuk.io і все запрацювало.

Реалізація бекенду

Якщо у вас macOS, то ви не зможете локально протестувати сповіщення. Проблема в тому що .NET не підтримує шифрування AesGcm на маках, тому при відправці вилетить ексепшен. Поки я не знайшов як це обійти.

На стороні сервера будемо використовувати бібліотеку Lib.Net.Http.WebPush яка під капотом буде шифрувати, підписувати та відправляти наші сповіщення. Для цього вона дає декілька базових модельок та один клас для відправки пушів.

Почнемо з реалізації створення та видалення підписок та зберігання їх в БД. Для цього добавимо клас ApplicationPushSubscription, який описує структуру таблиці та підключимо його в Entity Framework контекст:

public class ApplicationPushSubscription
{
    [Key]
    public string P256Dh { get; set; }
    public string Endpoint { get; set; }
    public string Auth { get; set; }
    public Guid UserId { get; set } // Id користувача в нашій системі
}

public class DatabaseContext : DbContext
{
    public DbSet<ApplicationPushSubscription> PushSubscriptions { get; set; }
}

Тепер створимо клас PushNotificationsService в який добавимо методи для створення та видалення підписок. Метод створення буде приймати екземпляр класу PushSubscription з бібліотеки Lib.Net.Http.WebPush.

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

public class PushNotificationsService
{
    private readonly DatabaseContext _context;
    private readonly PushServiceClient _pushClient;
    
    public PushNotificationsService (DatabaseContext context, PushServiceClient pushClient)
    {
        _context = context;
        _pushClient = pushClient;
    }
    
    public async Task CreateSubscription(Guid userId, PushSubscription pushSubscription)
    {
        var subscription = new ApplicationPushSubscription()
        {
            UserId = userId,
            AccountId = currentUser.AccountId,
            Endpoint = subscription.Endpoint,
            P256Dh = subscription.GetKey(PushEncryptionKeyName.P256DH),
            Auth = subscription.GetKey(PushEncryptionKeyName.Auth)
        };
        
        if (await _context.PushSubscriptions.AnyAsync(x => x.P256Dh == subscription.P256Dh))
        {
            return;
        }
        
        _context.PushSubscriptions.Add(subscription);
    
        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateException)
        {
            var alreadyExists = await _context.PushSubscriptions.AnyAsync(x => x.P256Dh == subscription.P256Dh);
            if (!alreadyExists)
            {
                throw;
            }
        }
    }
    
    public async Task DeleteSubscription(Guid userId, string endpoint)
    {
        var subscription = await _context.PushSubscriptions
            .FirstOrDefaultAsync(x => x.UserId == userId && x.Endpoint == endpoint);
        
        if (subscription == null)
        {
            return;
        }
        
        _context.PushSubscriptions.Remove(subscription);
        await _context.SaveChangesAsync();
    }
}

Реалізовуємо метод для відправки сповіщень нашим користувачам. Він буде приймати Id користувача якому ми відправляємо повідомлення і модель з даними.

Нам залишається отримати підписку з БД, серіалізувати повідомлення в JSON і скормити це все бібліотеці.

public async Task SendNotificationAsync(Guid userId, PushNotificationModel model)
{
    try
    {
        var applicationPushSubscriptions = await _context.PushNotifications
            .Where(x => x.UserId == userId)
            .ToList();
            
        foreach(var applicationPushSubscription in applicationPushSubscriptions)
        {
            var pushSubscription = new PushSubscription();
            pushSubscription.Endpoint = applicationPushSubscription.Endpoint;
            pushSubscription.SetKey(PushEncryptionKeyName.P256DH, applicationPushSubscription.P256Dh);
            pushSubscription.SetKey(PushEncryptionKeyName.Auth, applicationPushSubscription.Auth);
            
            var settings = new JsonSerializerSettings { ContractResolver = new CamelCasePropertyNamesContractResolver() };
            var payload = JsonConvert.SerializeObject(model, settings);
    
            var pushMessage = new PushMessage(payload);
            await _pushClient.RequestPushMessageDeliveryAsync(
                pushSubscription,
                pushMessage,
                _pushClient.DefaultAuthentication,
                VapidAuthenticationScheme.WebPush);
        }
    }
    catch (PushServiceClientException exception)
    {
        if (exception.StatusCode is HttpStatusCode.NotFound or HttpStatusCode.Gone)
        {
            _context.PushSubscriptions.Remove(subscription);
            await _context.SaveChangesAsync();
        }
        else
        {
            // Re-Throw exception or log
        }
    }
    catch (Exception exception)
    {
        // Re-Throw exception or log
    }
}

Структура класу PushNotificationModel досить проста та універсальна. Я передаю заголовок сповіщення, текст та додаткові дані:

public class PushNotificationModel
{
    public string Title { get; set; }
    public string Body { get; set; }
    public object AdditionalData { get; set; }
}

Підключаємо наш сервіс в ендопінт:

[Route("api/push-notifications")]
[Authorize]
[ApiController]
public class PushNotificationsController : ControllerBase
{
    private readonly PushNotificationService _pushNotificationService;

    public PushNotificationsController(PushNotificationService pushNotificationService)
    {
        _pushNotificationService = pushNotificationService;
    }
    
    [HttpPost("subscriptions")]
    public async Task<IActionResult> CreateSubscription([FromBody] PushSubscription subscription)
    {
        var user = HttpContext.GetCurrentUser(); // Our custom method to get current logged-in user
        await _pushNotificationService.CreateSubscription(user.Id, subscription);
        return Ok();
    }

    [HttpDelete("subscriptions")]
    public async Task<IActionResult> DeleteSubscription([FromQuery] string endpoint)
    {
        var user = HttpContext.GetCurrentUser();
        await _pushNotificationService.DeleteSubscription(user.Id, endpoint);
        return Ok();
    }
}

Все що залишається — підключити наші класи в DI і все готово. Для простоти підключення можемо добавити ще один пакет Lib.AspNetCore.WebPush.

services.AddTransient<PushNotificationService>();
services.AddMemoryVapidTokenCache();
services.AddPushServiceClient(options =>
{
    var clientOptions = configuration.GetSection(nameof(PushServiceClient));
    options.Subject = clientOptions.GetValue<string>(nameof(options.Subject));
    options.PublicKey = clientOptions.GetValue<string>(nameof(options.PublicKey));
    options.PrivateKey = clientOptions.GetValue<string>(nameof(options.PrivateKey));
});

Реалізація фронтенда

Підтримка технології Web Push була додана в Сафарі тільки в версії MacOS 13 та вище.

Перше, що потрібно реалізувати на стороні клієнта — це запит прав на отримання сповіщень. Для цього використовуємо обʼєкт Notification:

// Запит у браузера прав на підключення пушей
async function askPermission() {
    const permissionPromiseResult = await new Promise(function (resolve, reject) {
        const permissionResult = Notification.requestPermission(function (result) {
            resolve(result);
        });

        if (permissionResult) {
            permissionResult.then(resolve, reject);
        }
    });
    
    if (permissionPromiseResult !== 'granted') {
        alert("We weren't granted permission.");
    } else {
        await subscribeUserToPush();
    }
}

Після того, як отримали права, нам потрібно зареєструвати service worker в якому буде логіка відображення сповіщень, створити підписку та відправити її на наш сервер.

При створенні підписки необхідно передати наш публічний ключ. Але він повинен бути в форматі масиву байтів, тому треба спочатку його декодувати і вже тоді передавати.

В результаті отримуємо обʼєкт pushSubscription, який ми відправляємо на створений раніше ендпоінт. Крім цього, ще відправляємо Bearer токен, щоб розуміти до якого користувача привʼязати підписку.

const publicKey = "vapid-public-key";

async function subscribeUserToPush() {
    const registration = await navigator.serviceWorker.register('/service-worker.js');
    const subscribeOptions = {
        userVisibleOnly: true,
        applicationServerKey: urlBase64ToUint8Array(publicKey),
    };

    var pushSubscription = await registration.pushManager.subscribe(subscribeOptions);
   
    fetch('http://localhost:5000/api/push-notifications/subscriptions', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer 1245'
        },
        body: JSON.stringify(pushSubscription)
    }).then(function (response) {
        if (response.ok) {
            alert('Successfully subscribed for Push Notifications');
        } else {
            alert('Failed to store the Push Notifications subscription on server');
        }
    }).catch(function (error) {
        console.log('Failed to store the Push Notifications subscription on server: ' + error);
    });
    
    return pushSubscription;
}

function urlBase64ToUint8Array(base64String) {
    var padding = '='.repeat((4 - (base64String.length % 4)) % 4);
    var base64 = (base64String + padding).replace(/\-/g, '+').replace(/_/g, '/');

    var rawData = window.atob(base64);
    var outputArray = new Uint8Array(rawData.length);

    for (var i = 0; i < rawData.length; ++i) {
        outputArray[i] = rawData.charCodeAt(i);
    }
    return outputArray;
};

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

Також необхідно додати логіку обробки кліку по сповіщенню. Ми будемо перевіряти чи відкритий сайт в браузері. Якщо ні, то відкривати його в новій вкладці. А якщо у нас вже є вкладка з сайтом, то переключаємось на неї і робимо редірект на потрібну сторінку.

self.addEventListener('push', function (event) {
    var data = event.data.json();
    // {
    //     "title": "New Notification",
    //     "body": "This is the body of the notification"
    //     "additionalData": {
    //         "pageId": "12512515"
    //     }
    // }

    event.waitUntil(self.registration.showNotification(data.title, {
        body: data.body,
        icon: '/logo.png',
        data: {
            pageId: data.additionalData?.pageId,
        },
    }));
});

self.addEventListener('notificationclick', function (event) {
    var notification = event.notification;

    event.waitUntil(
        self.clients.matchAll().then(function (allClients) {
            if (allClients.length === 0) {
                self.clients.openWindow(
                    `${self.location.origin}/page/${notification?.data?.pageId}`,
                );
                notification.close();
                return;
            }

            allClients[0]?.navigate(`/page/${notification?.data?.pageId}`);
            allClients[0]?.focus();
            notification.close();
        }),
    );
});

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

Окремо ще можна поговорити про топіки та пріоритети сповіщень, але це виходить за рамки цієї статті. Можливо, розкажу про це пізніше :)

Ресурси

Жизненный цикл запросов в ASP.NET Core

Fri, 12 Jun 2020 16:38:19 -0400

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

Общий вид на жизненный цикл ASP.NET Core MVC приложений:

Он содержит в себе несколько этапов:

Middlewares
Routing
Controller Initialization
Controller action execution
Result Execution
View Rendering

Middlewares

Middlewares представляют из себя базовые блоки, с помощью которых строится HTTP пайплайн. Такой пайплайн представляет из себя конвейер, который обрабатывает каждый запрос. Каждый блок получает запрос и смотрит на него, если может предоставить ответ — возвращает его, если нет, передаёт запрос следующему блоку.

В ASP.NET Core у нас есть 4 метода, с помощью которых мы можем создавать свои middlewares.

Use
Run
Map
MapWhen

Официальная документация

Routing

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

UseRouting
UseEndpoints

Как все это работает?

UseRouting встраивает класс EndpointRoutingMiddleware, он смотрит на конечные точки, которые есть в приложении и выбирает подходящую. Выбор происходит на основании URL и заголовков. После того как нужный обработчик найден (Request delegate) его присваивают свойству Endpoint(IEndpointFeature) внутри текущего HttpContext. В дальнейшем мы можем получить его значения с помощью метода GetEndpoint.

UseEndpoints встраивает EndpointMiddleware. Он отвечает за выполнение установленной ранее конечной точки.

Официальная документация

Controller initialization

Для обеспечения работы контроллеров у есть два класса: ResourceInvoker, ControllerActionInvoker.

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

ControllerActionInvoker наследует ResourceInvoker и добавляет в него логику работы с контроллерами и их методами.

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

Исходники классов можно посмотреть на github (ResourceInvoker, ControllerActionInvoker).

Action workflow

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

Общий вид этого жизненного цикла:

Фильтры авторизации
Фильтры ресурсов
Привязки моделей
Фильтры действий
Выполнение метода контроллера
Фильтры исключений
Фильтры результатов
Выполнение результата
Фильтры результатов

Детальнее про фильтры можно почитать на метаните.

Result execution

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

Общий вид того как происходит рендеринг представлений:

Источники

Как я делал бота для Facebook workplace

Tue, 26 Nov 2019 10:22:26 -0400

Дали мне задачу: написать бота для мессенджера workplace, с помощью которого можно получать уведомления из нашей CRM и управлять разными вещами. Расскажу о разных интересных вещах с которыми я столкнулся. Бота писал с помощью ASP.NET Core Web API.

Вебхуки

Для того чтобы бот мог обрабатывать запросы и сообщения от Facebook нам надо настроить вебхуки. Webhook — механизм оповещения системы о событиях. Для того чтобы Facebook принял наш хук, он должен обрабатывать как GET так и POST запросы.

Подробнее о Webhook в официальной документации

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

Показать код метода-обработчика GET запроса

public IActionResult Receive( [FromQuery(Name = "hub.mode")] string mode, 
    [FromQuery(Name = "hub.challenge")] string challenge, 
    [FromQuery(Name = "hub.verify_token")] string verifyToken)
{ 
   if (string.IsNullOrEmpty(verifyToken)) { 
       return Unauthorized(); 
    }  
    if (verifyToken.Equals(FacebookEnvironment.FacebookVToken)) { 
        return Ok(challenge); 
    } 
    return Unauthorized(); 
}

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

Показать код метода-обработчика POST запроса

public async Task<IActionResult> Receive([FromBody]FbResponse response = null)
{
    if (response is null) {
        return BadRequest();
    }

    if (response.Object != "page") {
        return Ok();
    }

    foreach (var entry in response.Entries) {
        foreach (var message in entry.Messaging) {
            await PrepareMessageAsync(message);
        }
    }
    return Ok("EVENT_RECEIVED");
}

Авторизация запросов Facebook

Для авторизации Facebook использует специальный http заголовок (X-Hub-Signature), в нем он передает некую сигнатуру с помощью которой мы можем авторизовать запрос. Для того чтобы добавить такую функциональность в наш контроллер, добавим фильтр.

Пример кода, для проверки подписи

private const string Sha1Prefix = "sha1=";

public static bool Validate(string signature, string contentString) {
    if (!signature.StartsWith(Sha1Prefix, StringComparison.OrdinalIgnoreCase)) {
        return false;
    }
    var secret = Encoding.ASCII.GetBytes(FacebookEnvironment.AppSecret);
    var signatureWithoutPrefix = signature.Substring(Sha1Prefix.Length);
    var content = Encoding.ASCII.GetBytes(contentString);
    return GetIsHashValid(secret, signatureWithoutPrefix, content);
}

private static bool GetIsHashValid(byte[] secret, string signature, byte[] content) {
    using var hmac = new HMACSHA1(secret);
    var hash = hmac.ComputeHash(content);
    var hashString = ToHexString(hash);
    return hashString.Equals(signature);
}

private static string ToHexString(IReadOnlyCollection<byte> bytes)
{
    var builder = new StringBuilder(bytes.Count * 2);
    foreach (var b in bytes)
    {
        builder.AppendFormat("{0:x2}", b);
    }

    return builder.ToString();
}

Тестирование бота

Как установить letsencrypt сертификат для IIS. Если же вы используете связку в виде ubuntu и nginx вам подойдет эта инструкция.

Для тестирования нужно развернуть бот на сервере, который смотрит в мир. Также необходимо чтобы у сервера было доменное имя и валидный SSL сертификат. В моем случае, в качестве сервера выступала машина на винде, так как другой внутри нашей сети не было. Как мне показалось захостить приложение написанное на .NET Core намного проще под Ubuntu + nginx нежели под Windows + IIS. В качестве поставщика сертификатов выбрал letsencrypt, так как они предоставляют бесплатный сертификат на 3 месяца, с возможностью дальнейшего обновления.

CancellationToken в C#

Mon, 27 May 2019 06:26:41 -0400

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

Чтобы решить эту проблему нужно использовать механизм отмены задач. Состоит он из двух компонентов:

CancellationTokenSource — позволяет создавать специальные токены, который содержат информацию про состояние текущей отмены.
CancellationToken — собственно сам токен, у него есть свойство IsCancellationRequested, которое показывает состояние отмены, а также есть метод, который выбрасывает исключение (OperationCanceledException) в случае отмены операции.

Как это работает?

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

Чтобы отменить задачу нужно вызвать метод Cancel у экземпляра CancellationTokenSource. Он переведет все выпущенные токены в отмененное состояние. Внутри асинхронного метода сработает проверка токена и работа будет завершена.

Также CancellationTokenSource позволяет установить таймаут по истечению которого автоматически отменяться все токены.

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

public static void Main() 
{
    CancellationTokenSource cancelTokenSource = new CancellationTokenSource();
    CancellationToken token = cancelTokenSource.Token;
    
    var task = Task.Run(() => Task(cancelTokenSource.Token), cancelTokenSource.Token);

    cancelTokenSource.Cancel();
}

public static void Task(CancellationToken cancellationToken) 
{
    while (true) 
    {
        // делает полезную работу.

        cancellationToken.ThrowIfCancellationRequested();
    }
    
}

Советы

В ASP.NET Core приложениях стоит использовать токены отмены для эндпоинтов, которые долго выполняются или сильно нагружают систему. Это позволит отменять такие операции в случае тайм-аутов или когда закрылось подключение.
Если операция может быть отменена сразу же без дополнительных действий то для проверки отмены стоит использовать ThrowIfCancellationRequested. Если же нам нужно после вызова отмены сделать некую дополнительную работу (очистить ресурсы), то стоит проверять состояние с помощью свойства IsCancellationRequested и если оно равно true — выполнить дополнительную логику очистки.
Если метод уже выполнил свою работу и была вызвана отмена, то не нужно бросать исключение OperationCanceledException. Нужно просто вернуть результат работы и пускай вызывающий код решать что делать с этим результатом.
Можно вообще обойтись без использования механизма отмены если код отрабатывает очень быстро.

Полезные ссылки по теме:

Best Practices for Building Async APIs with ASP.NET Core

Fri, 25 Jan 2019 06:41:54 -0400

На днях был вебинар от JetBrains на тему: «Лучшие практики по построению асинхронных API в ASP.NET Core».
В скором времени опубликую заметку на эту тему.