Tisa.Common 2026.9.10.321

Tisa.Common

👁 NuGet Version

Библиотека общих компонентов и утилит для .NET приложений, разработанная компанией ТИСА. Предоставляет набор базовых абстракций, расширений и примитивов для ускорения разработки приложений с использованием функциональных подходов и DDD паттернов.

Возможности

• Поддержка .NET Standard 2.0, .NET 8.0, .NET 9.0 и .NET 10.0
• Система Result для обработки результатов операций без исключений
• Тип Maybe<T> для работы с опциональными значениями
• Базовые классы для DDD: ValueObject, AbstractEntity
• Расширенные перечисления EnumEnumeration<T>
• Система обработки ошибок Error
• Богатый набор методов расширения для коллекций, строк, дат и XML
• Маркеры жизненного цикла сервисов для DI

Установка

dotnet add package Tisa.Common

Основные компоненты

Result - Результаты операций

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

Базовое использование

using Tisa.Common.Primitives;

// Создание успешного результата
var success = Result.Success();

// Создание результата с данными
var dataResult = Result.Success(new { Name = "Test", Id = 1 });

// Создание результата с ошибкой
var errorResult = Result.Failure("Произошла ошибка");

// Проверка результата
if (dataResult.IsSuccess)
{
 var value = dataResult.Value; // Получение значения
}
else
{
 var error = dataResult.Error; // Получение ошибки
}

Работа с методами

public Result<User> GetUser(int id)
{
 if (id <= 0)
 {
 return Result.Failure<User>("Неверный идентификатор пользователя");
 }
 
 var user = _repository.FindById(id);
 if (user == null)
 {
 return Result.Failure<User>("Пользователь не найден");
 }
 
 return Result.Success(user);
}

// Использование
var result = GetUser(1);
result.Match(
 onSuccess: user => Console.WriteLine($"Пользователь: {user.Name}"),
 onFailure: error => Console.WriteLine($"Ошибка: {error.Detail}")
);

Цепочка операций

var result = GetUser(1)
 .Map(user => user.Name)
 .Map(name => name.ToUpper())
 .Bind(name => ValidateName(name));

// Комбинирование результатов
var combinedResult = Result.Combine(
 GetUser(1),
 GetUser(2)
);

Maybe - Опциональные значения

Тип Maybe<T> представляет опциональное значение, которое может присутствовать или отсутствовать.

Базовое использование

using Tisa.Common.Primitives;

// Создание Maybe со значением
var maybeValue = Maybe.Some(42);

// Создание Maybe без значения
var maybeNone = Maybe.None<int>();

// Проверка наличия значения
if (maybeValue.HasValue)
{
 var value = maybeValue.Value; // Получение значения
}

// Безопасное получение значения
var value = maybeValue.GetValueOrDefault(0); // Вернет 0, если значения нет
var valueOrThrow = maybeValue.GetValueOrThrow("Значение отсутствует");

Работа с коллекциями

var numbers = new List<int> { 1, 2, 3, 4, 5 };

// Поиск первого элемента
var first = numbers.TryFirst(x => x > 3); // Maybe<int>

// Поиск последнего элемента
var last = numbers.TryLast(x => x < 3); // Maybe<int>

// Поиск элемента
var found = numbers.TryFind(x => x == 3); // Maybe<int>

Преобразования

var maybe = Maybe.Some(10);

// Map - преобразование значения
var doubled = maybe.Map(x => x * 2); // Maybe<int> со значением 20

// Bind - цепочка операций
var result = maybe
 .Bind(x => x > 0 ? Maybe.Some(x * 2) : Maybe.None<int>())
 .Map(x => x.ToString());

// Преобразование в Result
var result = maybe.ToResult("Значение отсутствует");

EnumEnumeration - Расширенные перечисления

Класс EnumEnumeration<T> предоставляет типобезопасные перечисления с дополнительными возможностями.

Определение перечисления

using Tisa.Common.Primitives;

public sealed class UserRole : EnumEnumeration<UserRole>
{
 public static readonly UserRole Admin = new(1, nameof(Admin));
 public static readonly UserRole User = new(2, nameof(User));
 public static readonly UserRole Guest = new(3, nameof(Guest));

 private UserRole(int value, string name)
 : base(value, name)
 {
 }
}

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

// Получение по значению
var role = UserRole.FromValue(1); // Maybe<UserRole>

if (role.HasValue)
{
 Console.WriteLine(role.Value.Name); // "Admin"
}

// Получение по имени
var adminRole = UserRole.FromName("Admin"); // Maybe<UserRole>

// Получение всех значений
var allRoles = UserRole.ToList();

// Проверка существования
if (UserRole.ContainsValue(1))
{
 // Роль существует
}

ValueObject - Объекты-значения

Базовый класс для создания объектов-значений в DDD.

Определение ValueObject

using Tisa.Common.Primitives;

public sealed class Money : ValueObject
{
 public decimal Amount { get; }
 public string Currency { get; }

 public Money(decimal amount, string currency)
 {
 Amount = amount;
 Currency = currency;
 }

 protected override IEnumerable<object> GetEqualityComponents()
 {
 yield return Amount;
 yield return Currency;
 }
}

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

var money1 = new Money(100, "USD");
var money2 = new Money(100, "USD");

// Сравнение по значению
if (money1 == money2) // true
{
 Console.WriteLine("Суммы равны");
}

AbstractEntity - Базовые сущности

Базовый класс для создания сущностей в DDD.

Определение Entity

using Tisa.Common.Primitives;

public sealed class User : AbstractEntity<Guid>
{
 public string Name { get; private set; }
 public string Email { get; private set; }

 private User() { } // Для EF Core

 public User(Guid id, string name, string email)
 : base(id)
 {
 Name = name;
 Email = email;
 }
}

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

var user1 = new User(Guid.NewGuid(), "John", "john@example.com");
var user2 = new User(user1.Id, "John", "john@example.com");

// Сравнение по идентификатору
if (user1 == user2) // true, если Id совпадают
{
 Console.WriteLine("Один и тот же пользователь");
}

Error - Обработка ошибок

Класс Error предоставляет структурированную обработку ошибок.

Создание ошибок

using Tisa.Common.Errors;

// Различные типы ошибок
var notFound = Error.NotFound("User.NotFound", "Пользователь не найден");
var badRequest = Error.BadRequest("User.InvalidEmail", "Неверный формат email");
var conflict = Error.Conflict("User.EmailExists", "Email уже используется");
var unauthorized = Error.Unauthorized("Auth.InvalidToken", "Недействительный токен");
var forbidden = Error.Forbidden("Auth.AccessDenied", "Доступ запрещен");
var failure = Error.Failure("System.Error", "Внутренняя ошибка системы");

// Ошибка из исключения
try
{
 // код
}
catch (Exception ex)
{
 var error = Error.Failure(ex);
 // или
 var handledError = Error.HandleException(ex, ex => 
 ex is ArgumentException 
 ? Error.BadRequest("InvalidArgument", ex.Message)
 : Error.Failure(ex));
}

Использование с параметрами

var error = Error.NotFound("User.NotFound", "Пользователь с ID {0} не найден")
 .WithParams(userId);

Расширения (Extensions)

Библиотека предоставляет множество методов расширения для упрощения работы с базовыми типами.

Расширения для коллекций

using Tisa.Common.Extensions;

var list = new List<int> { 1, 2, 3 };

// Добавление диапазона
list.AddRange(new[] { 4, 5, 6 });

// Проверка наличия элементов
if (list.HasItems())
{
 // Коллекция не пуста
}

Расширения для строк

using Tisa.Common.Extensions;

string text = "Hello {0}";

// Заполнение параметров
var result = text.Fill("World"); // "Hello World"

// Повторение строки
var repeated = "abc".Repeat(3); // "abcabcabc"

// Проверки
if (text.IsEmpty())
{
 // Строка пуста
}

// Работа с Base64
var base64 = "Hello".ToBase64();
var decoded = base64.FromBase64();

// Извлечение подстрок
var left = "Hello World".Left(5); // "Hello"
var right = "Hello World".Right(5); // "World"

// Удаление нецифровых символов
var digits = "abc123def".RemoveNonDigits(); // "123"

Расширения для дат

using Tisa.Common.Extensions;

var date = DateTime.Now;

// Округление даты
var rounded = date.Round(TimeSpan.FromMinutes(15));

// Работа с TimeSpan
var span = TimeSpan.FromMinutes(90);
var formatted = span.ToHumanReadableString();

Расширения для XML

using Tisa.Common.Extensions;
using System.Xml.Linq;

var xElement = XElement.Parse("<root><item>value</item></root>");

// Удаление пространств имен
var withoutNamespaces = xElement.RemoveAllNamespaces();

// Преобразование в XmlDocument
var xmlDoc = xElement.ToXmlDocument();

// Условное добавление
xElement.Append(condition, new XElement("new", "value"));

ServiceLifetimes - Маркеры жизненного цикла

Интерфейсы для маркировки жизненного цикла сервисов в DI контейнере.

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

using Tisa.Common.ServiceLifetimes;

// Маркировка сервиса как Transient
public class MyService : IMyService, ITransient
{
 // Реализация
}

// Маркировка сервиса как Scoped
public class MyRepository : IMyRepository, IScoped
{
 // Реализация
}

Затем можно использовать автоматическую регистрацию через Scrutor или другие библиотеки:

services.Scan(scan => scan
 .FromAssemblyOf<MyService>()
 .AddClasses(classes => classes.AssignableTo<ITransient>())
 .AsImplementedInterfaces()
 .WithTransientLifetime()
 .AddClasses(classes => classes.AssignableTo<IScoped>())
 .AsImplementedInterfaces()
 .WithScopedLifetime());

Структура проекта

• Abstractions/ - Базовые интерфейсы (IResult, IMaybe, IEntity, IValue, IError, ICombine)
• Primitives/ - Базовые примитивы
  • Results/ - Система результатов операций
  • Maybe/ - Опциональные значения
  • ValueObject/ - Объекты-значения
  • EnumEnumeration.cs - Расширенные перечисления
  • AbstractEntity.cs - Базовые сущности
  • Request.cs, RequestT.cs - Базовые классы запросов
• Extensions/ - Методы расширения для стандартных типов
• ServiceLifetimes/ - Маркеры жизненного цикла сервисов (IScoped, ITransient)
• Errors/ - Система обработки ошибок

Требования

• .NET Standard 2.0 или .NET 8.0 / 9.0 / 10.0 (в зависимости от целевого TFM проекта)

Дополнительные возможности

Функциональное программирование

Библиотека поддерживает функциональные подходы:

// Композиция функций
var result = GetUser(1)
 .Map(user => user.Email)
 .Bind(email => ValidateEmail(email))
 .Map(email => SendWelcomeEmail(email))
 .Match(
 onSuccess: () => Console.WriteLine("Email отправлен"),
 onFailure: error => Console.WriteLine($"Ошибка: {error.Detail}")
 );

Асинхронные операции

Поддержка асинхронных операций с Result и Maybe:

public async Task<Result<User>> GetUserAsync(int id)
{
 var user = await _repository.FindByIdAsync(id);
 return user != null 
 ? Result.Success(user) 
 : Result.Failure<User>("Пользователь не найден");
}

// Использование
var result = await GetUserAsync(1)
 .MapAsync(async user => await ProcessUserAsync(user));

Публикация в NuGet

Сборка пакета (Release, все целевые платформы):

dotnet pack "Tisa.Common/Source/Tisa.Common.csproj" -c Release --no-restore

Артефакты: Tisa.Common/Source/bin/Release/Tisa.Common.<версия>.nupkg и .snupkg (символы для отладки).

Публикация (замените ключ и источник при необходимости):

dotnet nuget push "Tisa.Common/Source/bin/Release/Tisa.Common.*.nupkg" -k <API_KEY> -s https://api.nuget.org/v3/index.json
dotnet nuget push "Tisa.Common/Source/bin/Release/Tisa.Common.*.snupkg" -k <API_KEY> -s https://api.nuget.org/v3/index.json

Перед публикацией обновите <Version> в Tisa.Common.csproj. Для приватного feed укажите свой URL источника.

Лицензия

MIT License

Поддержка

По вопросам поддержки и сообщений об ошибках: support@tisn.ru