Разработка плагинов для веб-сервера (пример)

В этой статье разобран пример плагина для WEB-версии ПОЛИНОМ:MDM. Плагин добавляет метод GetStatistics, который возвращает статистику наполнения хранилища данных.

Общие правила создания плагина приведены в статье Создание плагина для веб-сервера. Ниже показан полный код примера из SDK.

Расположение и состав проекта

Полный код проекта плагина расположен по пути SDK/Web/Samples/Server/Samples.WebApi.Plugin и подключён к решению Samples.WebApi.sln.

Samples.WebApi.Plugin/
├── Samples.WebApi.Plugin.csproj
├── ServiceRegistrar.cs
├── Controllers/
│   └── SampleController.cs
├── Interfaces/
│   ├── Requests/IGetStatisticsRequest.cs
│   └── Responses/IGetStatisticsResponse.cs
├── Models/
│   └── Requests/GetStatisticsRequest.cs
├── Data/
│   └── CountInfo.cs
├── Services/
│   └── StatisticsService.cs
└── Validation/
    └── Requests/GetStatisticsRequestValidator.cs

SDK подключается одной ссылкой на метапакет Ascon.Polynom.Web.Api.Plugins. Сборка выполняется в файл Sample.Web.Api.Plugin.dll с суффиксом .Plugin, поэтому хост обнаруживает её автоматически. Сборка размещается в каталоге Bin/WebServer рядом с хостом.

Samples.WebApi.Plugin.csproj — файл настроек проекта:

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

    <PropertyGroup>
        <OutputType>Library</OutputType>
    </PropertyGroup>

    <PropertyGroup>
        <RootNamespace>Sample.Web.Api.Plugin</RootNamespace>
        <AssemblyName>Sample.Web.Api.Plugin</AssemblyName>
        <Title>Пример дополнения к WEB API ПОЛИНОМ:MDM</Title>
        <DocumentationFile>$(AssemblyName).xml</DocumentationFile>
    </PropertyGroup>

    <Import Project="$(ProjectDir)..\Sdk.props"/>

    <PropertyGroup>
        <OutputPath>..\..\..\..\..\Bin\WebServer</OutputPath>
    </PropertyGroup>

    <ItemGroup>
        <PackageReference Include="Ascon.Polynom.Web.Api.Plugins" Version="24.1.*" />
        <PackageReference Include="Asp.Versioning.Mvc" Version="8.*" />
        <PackageReference Include="FluentValidation" Version="12.*" />
        <PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="12.*" />
    </ItemGroup>

</Project>

Контракты запроса и ответа

Interfaces/Requests/IGetStatisticsRequest.cs — интерфейс запроса:

using System.Text.Json.Serialization;

using Ascon.Polynom.Web.Api.Plugins.Contracts.Interfaces.Requests.Base;

using Sample.Web.Api.Plugin.Models.Requests;

namespace Sample.Web.Api.Plugin.Interfaces.Requests;

[JsonPolymorphic(
    UnknownDerivedTypeHandling = JsonUnknownDerivedTypeHandling.FallBackToBaseType),
 JsonDerivedType(typeof(GetStatisticsRequest))]
public interface IGetStatisticsRequest : IWebApiRequest
{
    string? ReferenceName { get; set; }
}

Models/Requests/GetStatisticsRequest.cs — класс запроса:

using System.Text.Json.Serialization;

using Ascon.Polynom.Web.Api.Plugins.Contracts.Requests.Base;

using Sample.Web.Api.Plugin.Interfaces.Requests;

namespace Sample.Web.Api.Plugin.Models.Requests;

[JsonUnmappedMemberHandling(JsonUnmappedMemberHandling.Disallow)]
public class GetStatisticsRequest : WebApiRequest, IGetStatisticsRequest
{
    public string? ReferenceName { get; set; }
}

Interfaces/Responses/IGetStatisticsResponse.cs — интерфейс ответа, Data/CountInfo.cs — реализующий его класс статистики.

Контроллер

Controllers/SampleController.cs — контроллер дополнения. Он наследует WebApiPluginController, задаёт [Authorize], [ApiVersion("1")], [RequestValidation] и объявляет действие GetStatistics:

using Ascon.Polynom.Web.Api.AspNetCore;
using Ascon.Polynom.Web.Api.Plugins.AspNetCore;
using Ascon.Polynom.Web.Api.Plugins.Core;
using Asp.Versioning;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace Sample.Web.Api.Plugin.Controllers;

[ApiVersion("1")]
[Authorize]
[RequestValidation]
public class SampleController : WebApiPluginController
{
    private readonly StatisticsService _statisticsService;

    public SampleController(
        IPluginAuthorizationService authorizationService,
        StatisticsService statisticsService,
        IServiceProvider services) : base(authorizationService, services)
    {
        _statisticsService = statisticsService;
    }

    [HttpPost(nameof(GetStatistics))]
    public async Task<ActionResult<IGetStatisticsResponse>> GetStatistics(
        IGetStatisticsRequest request,
        CancellationToken cancellationToken)
    {
        CheckAuthorization();

        var session = await GetPolynomApiSession(cancellationToken);
        if (session is null)
            return Unauthorized();

        var result = await _statisticsService.GetStatisticsAsync(session, request, cancellationToken);

        return new JsonResult(result);
    }
}

Статистика собирается сервисом Services/StatisticsService.cs через объекты сессии Polynom.Api.ISession: session.Objects.AllReferences, session.Objects.RootConcepts, session.Objects.PropDefCatalog.PropDefGroups.

Регистрация сервисов и валидация

ServiceRegistrar.cs регистрирует сервис и валидаторы:

using Ascon.Polynom.Web.Api.Plugins.Core;
using FluentValidation;
using Microsoft.Extensions.DependencyInjection;

namespace Sample.Web.Api.Plugin;

public class ServiceRegistrar : IPluginServiceRegistrar
{
    public void RegisterServices(IServiceCollection services)
    {
        services.AddValidatorsFromAssembly(typeof(ServiceRegistrar).Assembly);
        services.AddScoped<StatisticsService>();
    }
}

Validation/Requests/GetStatisticsRequestValidator.cs проверяет длину имени справочника:

using FluentValidation;

using Sample.Web.Api.Plugin.Interfaces.Requests;

namespace Sample.Web.Api.Plugin.Validation.Requests;

public class GetStatisticsRequestValidator : AbstractValidator<IGetStatisticsRequest>
{
    public GetStatisticsRequestValidator()
    {
        RuleFor(x => x.ReferenceName).MaximumLength(200);
    }
}

Запуск и проверка

1. Соберите проект:

   dotnet build .\SDK\Web\Samples\Server\Samples.WebApi.Plugin\Samples.WebApi.Plugin.csproj -c Release
   

2. Результат сборки — файлы Sample.Web.Api.Plugin.dll, Sample.Web.Api.Plugin.xml и сопутствующие файлы в каталоге Bin/WebServer.

3. Запустите веб-сервер из каталога Bin/WebServer. В Swagger появится раздел Sample с методом GetStatistics.

Запрос метода:

POST /api/v1/Sample/GetStatistics
Authorization: Bearer %access-token%
Content-Type: application/json

{ "referenceName": "Справочник" }

Поле referenceName необязательно: если оно не задано, статистика собирается по всему хранилищу.

См. также

• Создание плагина для веб-сервера
• Авторизация в C# .NET