Mds.Libraries.CSharp.DisplaySchema

Пакет для удобной работы с выходными сущностями для Api.

Основные задачи пакета:

• Уйти от формирования DTO для формаирования ответа сервера
• Дать фронту возможность заказывать для получения только те сущности, которые ему сейчас нужны.

Пример работы с DisplaySchema

// Пример Action для получения **сущности**
[HttpGet("offers/{offerId}")]
public async Task<JToken> FindAsync(long offerId, [FromQuery] IncludePropertiesParameters parameters)
{
    var result = await Query.CheckAndFindAsync(offerId);

    // Формируем схему
    var schema = new DisplaySchema<ComplexOffer>()
    {
        { "id", o => o.Id, Visibility.Always },
        // Формат вывода для Datetime
        { "created_at", o => o.CreatedAt, DateTimeFormat.Timestamp },
        { "updated_at", o => o.UpdatedAt, DateTimeFormat.Timestamp },
        { "partner_id", o => o.PartnerId },
        // Вложенные сущности
        { "harmonization_link", o => o.Link, new DisplaySchema<HarmonizationLink>()
        {
            { "id", l => l.Id, Visibility.Always },
            { "created_at", l => l.CreatedAt, DateTimeFormat.Timestamp },
            { "updated_at", l => l.UpdatedAt, DateTimeFormat.Timestamp },
            { "good", l => l.Good, new DisplaySchema<Good>()
            {
                // Указание уровня видимости
                { "id", l => l.Id, Visibility.Always },
                { "name", l => l.Name }
            }
            },
            // Формат вывода для Enum
            { "catalog", l => l.Catalog, EnumFormat.Description },
            { "quality", l => l.Quality }
        }
        }
    };

    // Формируем JToken с поомощью схемы и найденной сущности
    return schema.JsonBuild(result, parameters.Properties);
}

// Класс для передачи свойств, которые необходимо отобразить.
// Ожидается формат свойст через точку. Для массивов тоже.
// Например: [ "id", "harmonization_link.good.id", "harmonization_link.good.name" ]
// Если свойства не будут указаны, тогда будут отображены все.
public class IncludePropertiesParameters
{
    [FromQuery(Name = "include_property")]
    public IEnumerable<string> Properties { get; set; }
}

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

Если вы хотите, чтобы определенное свойство отображалось всегда, когда отображается родительское свойство, тогда его надо пометить как Visibility.Always. Поведение по умолчанию Visibility.OnDemand.

Из примера выше, это будет работать так:

• Если было запрошено harmonization_link.created_at, тогда harmonization_link.id будет отображено.
• Если из harmonization_link не было запррошено ни одного свйоства, и не было запрошено harmonization_link, тогда harmonization_link.id НЕ будет отображено

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

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

var formatter = new CustomDateTimeFormatter()
var schema = new DisplaySchema<ComplexOffer>()
{
    { "created_at", o => o.CreatedAt, formatter },
};

// Реализация собственного форматтера для отображения свойства
internal class CustomDateTimeFormatter : IDisplayValueFormatter<DateTime>
{

    internal CustomDateTimeFormatter() {}


    #region IDisplayValueFormatter


    object IDisplayValueFormatter<DateTime?>.Prepare(DateTime value)
    {
       // Тут нужно описать реализацию форматтера
    }

    #endregion IDisplayValueFormatter
}

Специальное расширение для работы с вложенной сущностями

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

var schema = new DisplaySchema<UtekaPosition>()
{
    { "id", c => c.Id, Visibility.Always },
    { "created_at", c => c.CreatedAt, DateTimeFormat.Timestamp },
    { "updated_at", c => c.UpdatedAt, DateTimeFormat.Timestamp },
    // Мы не передаем expression, потому что он будет вида p => p, а сразу передаем схему новую.
    { "raw", new DisplaySchema<UtekaPosition>()
    {
        { "id", c => c.ExternalId, Visibility.Always },
        { "name", c => c.Name },
    }
    },
};

Расширение для работы с DateTime

Для форматирования DateTime и DateTimeOffset написано специальное расширение и есть встроенный форматтер.

var schema = new DisplaySchema<ComplexOffer>()
{
    // Работа с DateTime с указанием необходимого формата вывода
    { "created_at", o => o.CreatedAt, DateTimeFormat.Timestamp },
};

Возможные форматы

• Timestamp - выводим в unix timestamp

Расширение для работы с Enum

Для форматирования Enum написано специальное расширение и есть встроенный форматтер.

var schema = new DisplaySchema<ComplexOffer>()
{
    // Работа с Enum с указанием необходимого формата вывода
    { "catalog", l => l.Catalog, EnumFormat.Description },
};

Возможные форматы

• Value - берем значение Enum
• Name - берем имя значения Enum
• Description - берем значение из аттрибута Description
• EnumMember - берем значение из аттрибута EnumMember