Tisa.XrmCore 2025.9.10.1120

Tisa.XrmCore

Библиотека для .NET, предоставляющая клиент, совместимый с WS-Trust, для подключения к локальным экземплярам IFD Dynamics 365 из .NET Core. Библиотека создана на основе Microsoft.PowerPlatform.Dataverse.Client и предлагает альтернативную реализацию IOrganizationService с использованием WS-Trust.

Возможности

• Поддержка .NET 8.0, .NET 9.0 и .NET 10.0
• Подключение к Dynamics 365 по URL-адресу службы организации
• Поддержка различных типов аутентификации: AD, IFD, OAuth, ClientSecret
• WS-Trust протокол для локальных подключений
• Асинхронные операции с IOrganizationServiceAsync2
• Расширения для работы с Entity, Money, Query
• Типовые операции с данными через XrmDataService
• Unit of Work для транзакций
• Валидация токенов безопасности
• Интеграция с Tisa.Common

Установка

dotnet add package Tisa.XrmCore

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

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

Библиотека предоставляет несколько клиентов для различных сценариев аутентификации.

OnPremiseClient - Локальное подключение

Клиент для подключения к локальным экземплярам Dynamics 365 с использованием WS-Trust.

using Tisa.XrmCore;
using Microsoft.Xrm.Sdk;

// Создание клиента
var client = new OnPremiseClient(
    organizationUrl: "https://your-org.crm.dynamics.com",
    username: "your-username",
    password: "your-password"
);

// Асинхронные операции
var whoAmIResponse = await client.ExecuteAsync(new WhoAmIRequest());
var userId = ((WhoAmIResponse)whoAmIResponse).UserId;

// Создание записи
var account = new Entity("account");
account["name"] = "Test Account";
var accountId = await client.CreateAsync(account);

// Получение записи
var retrievedAccount = await client.RetrieveAsync("account", accountId, new ColumnSet(true));

// Обновление записи
account["name"] = "Updated Account";
await client.UpdateAsync(account);

// Удаление записи
await client.DeleteAsync("account", accountId);

ADAuthClient - Active Directory аутентификация

Клиент для аутентификации с использованием Active Directory.

using Tisa.XrmCore;

// Создание клиента с доменом
var client = new ADAuthClient(
    url: "https://your-org.crm.dynamics.com",
    username: "domain\\username", // или "username@domain.com"
    password: "your-password",
    upn: "service@domain.com"
);

// Использование аналогично OnPremiseClient
var response = await client.ExecuteAsync(new WhoAmIRequest());

ClaimsBasedAuthClient - Claims-Based аутентификация

Клиент для аутентификации на основе утверждений.

using Tisa.XrmCore;

var client = new ClaimsBasedAuthClient(
    url: "https://your-org.crm.dynamics.com",
    issuerEndpoint: "https://sts.your-domain.com/adfs/services/trust/13/usernamemixed"
);

var response = await client.ExecuteAsync(new WhoAmIRequest());

XCoreService - Сервис для работы с токенами

Сервис для валидации токенов и получения IOrganizationService на основе конфигурации.

Настройка конфигурации

{
  "Tokens": {
    "token-1": "Auth:Token1"
  },
  "Auth": {
    "Token1": {
      "AuthType": "IFD",
      "Url": "https://your-org.crm.dynamics.com",
      "User": "username",
      "Password": "password"
    }
  }
}

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

using Tisa.XrmCore.Abstractions;
using Tisa.XrmCore.Infrastructure;
using Microsoft.Extensions.Configuration;

// Регистрация в DI
services.AddScoped<IXCoreService, XCoreService>();

// Использование
public class ContactService
{
    private readonly IXCoreService _xCoreService;

    public ContactService(IXCoreService xCoreService)
    {
        _xCoreService = xCoreService;
    }

    public bool ValidateToken(string token)
    {
        return _xCoreService.ValidateToken($"Tokens:{token}");
    }

    public void CreateContact(string firstName, string lastName)
    {
        var service = _xCoreService.GetOrganizationService();
        
        var contact = new Entity("contact");
        contact["firstname"] = firstName;
        contact["lastname"] = lastName;
        
        service.Create(contact);
    }
}

Типы аутентификации

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

• AD - Active Directory аутентификация
• IFD - Internet-Facing Deployment
• OAuth - OAuth 2.0 аутентификация
• ClientSecret - Аутентификация с использованием Client Secret

Конфигурация для различных типов

{
  "Auth": {
    "ADAuth": {
      "AuthType": "AD",
      "Url": "https://your-org.crm.dynamics.com",
      "User": "domain\\username",
      "Password": "password"
    },
    "IFDAuth": {
      "AuthType": "IFD",
      "Url": "https://your-org.crm.dynamics.com",
      "User": "username",
      "Password": "password"
    },
    "OAuthAuth": {
      "AuthType": "OAuth",
      "ConnectionString": "AuthType=OAuth;Url=https://your-org.crm.dynamics.com;Username=username;Password=password;AppId=app-id;RedirectUri=redirect-uri;LoginPrompt=Auto"
    },
    "ClientSecretAuth": {
      "AuthType": "ClientSecret",
      "ConnectionString": "AuthType=ClientSecret;Url=https://your-org.crm.dynamics.com;ClientId=client-id;ClientSecret=client-secret"
    }
  }
}

XrmDataService - Типовые операции с данными

Базовый класс для работы с данными Dynamics 365 с типовыми методами.

Создание сервиса данных

using Tisa.XrmCore.Data;
using Tisa.XrmCore.Abstractions;
using Microsoft.Xrm.Sdk;
using Tisa.Common.Primitives;

public class ContactDataService : XrmDataService
{
    public ContactDataService(IXCoreService xCoreService)
        : base(xCoreService)
    {
    }

    public Result<Entity> GetContactById(Guid contactId)
    {
        var entityReference = new EntityReference("contact", contactId);
        return Retrieve(entityReference, "firstname", "lastname", "emailaddress1");
    }

    public Result<EntityCollection> GetContactsByEmail(string email)
    {
        var query = new QueryExpression("contact");
        query.ColumnSet = new ColumnSet("firstname", "lastname", "emailaddress1");
        query.Criteria.AddCondition("emailaddress1", ConditionOperator.Equal, email);
        
        return RetrieveMultiple(query);
    }

    public Result<Guid> CreateContact(string firstName, string lastName, string email)
    {
        var contact = new Entity("contact");
        contact["firstname"] = firstName;
        contact["lastname"] = lastName;
        contact["emailaddress1"] = email;
        
        return Create(contact);
    }
}

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

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

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

using Tisa.XrmCore.Extensions;
using Microsoft.Xrm.Sdk;

var entity = new Entity("account");
entity["name"] = "Test Account";

// Безопасное получение значений
var name = entity.GetAttributeValue<string>("name");
var revenue = entity.GetAttributeValue<Money>("revenue");

// Установка значений с проверкой
entity.SetAttributeValue("name", "Updated Account");

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

using Tisa.XrmCore.Extensions;
using Microsoft.Xrm.Sdk;

var money = new Money(123.456m);

// Округление
var rounded = money.Round(2); // 123.46
var roundedUp = money.RoundUp(2); // 123.46
var roundedDown = money.RoundDown(2); // 123.45

// Операции
var sum = money.Sum(new Money(10m), new Money(20m));
var difference = money.Subtraction(new Money(10m));
var min = money.Min(new Money(100m));
var max = money.Max(new Money(100m));

// Получение значения с значением по умолчанию
var value = money.Value(0m);

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

using Tisa.XrmCore.Extensions;
using Microsoft.Xrm.Sdk.Query;

var query = new QueryExpression("account");
query.ColumnSet = new ColumnSet("name", "revenue");

// Добавление условий
query.Criteria.AddCondition("statecode", ConditionOperator.Equal, 0);
query.Criteria.AddCondition("revenue", ConditionOperator.GreaterThan, 1000000);

// Добавление связей
var link = query.AddLink("contact", "accountid", "parentcustomerid");
link.Columns = new ColumnSet("firstname", "lastname");

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

using Tisa.XrmCore.Extensions;
using Microsoft.Xrm.Sdk;

// Выполнение FetchXML
var fetchXml = @"
    <fetch>
        <entity name='account'>
            <attribute name='name'/>
            <filter>
                <condition attribute='statecode' operator='eq' value='0'/>
            </filter>
        </entity>
    </fetch>";

var results = service.FetchXml(fetchXml);

// Получение всех страниц результатов
var allResults = service.RetrieveMultiple(query, shouldRetrieveAllPages: true);

// Получение с ограничением количества
var limitedResults = service.RetrieveMultiple(query, maxResultCount: 100);

Unit of Work - Транзакции

Класс для работы с транзакциями в Dynamics 365.

using Tisa.XrmCore.Data;
using Microsoft.Xrm.Sdk;

public class TransactionService
{
    private readonly IOrganizationService _service;

    public TransactionService(IOrganizationService service)
    {
        _service = service;
    }

    public void CreateMultipleEntities()
    {
        using var unitOfWork = new UnitOfWork(_service);
        
        try
        {
            // Создание нескольких сущностей в одной транзакции
            var account = new Entity("account");
            account["name"] = "Test Account";
            var accountId = unitOfWork.Create(account);

            var contact = new Entity("contact");
            contact["firstname"] = "John";
            contact["lastname"] = "Doe";
            contact["parentcustomerid"] = new EntityReference("account", accountId);
            unitOfWork.Create(contact);

            // Подтверждение транзакции
            unitOfWork.Commit();
        }
        catch
        {
            // Откат транзакции при ошибке
            unitOfWork.Rollback();
            throw;
        }
    }
}

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

Все клиенты поддерживают асинхронные операции через интерфейс IOrganizationServiceAsync2.

using Tisa.XrmCore;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;

var client = new OnPremiseClient(url, username, password);

// Асинхронное создание
var entity = new Entity("account");
entity["name"] = "Test Account";
var id = await client.CreateAsync(entity);

// Асинхронное получение
var retrieved = await client.RetrieveAsync("account", id, new ColumnSet(true));

// Асинхронное обновление
entity["name"] = "Updated Account";
await client.UpdateAsync(entity);

// Асинхронное удаление
await client.DeleteAsync("account", id);

// Асинхронное выполнение запроса
var query = new QueryExpression("account");
query.ColumnSet = new ColumnSet("name");
var results = await client.RetrieveMultipleAsync(query);

// Асинхронное выполнение запроса
var request = new WhoAmIRequest();
var response = await client.ExecuteAsync(request);

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

Библиотека предоставляет специализированные исключения для обработки ошибок.

using Tisa.XrmCore.Exceptions;

try
{
    var client = new OnPremiseClient(url, username, password);
    var response = await client.ExecuteAsync(new WhoAmIRequest());
}
catch (XrmCoreException ex)
{
    // Обработка ошибок XRM
    Console.WriteLine($"Ошибка XRM: {ex.Message}");
}
catch (Exception ex)
{
    // Обработка других ошибок
    Console.WriteLine($"Общая ошибка: {ex.Message}");
}

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

• Abstractions/ - Интерфейсы (IXCoreService, IInnerOrganizationService)
• AuthHelpers/ - Вспомогательные классы для аутентификации WS-Trust
• Data/ - Классы для работы с данными (XrmDataService, UnitOfWork)
• Exceptions/ - Исключения (XrmCoreException)
• Extensions/ - Методы расширения для Entity, Money, Query и т.д.
• Infrastructure/ - Инфраструктурные классы (XCoreService, XrmFactory)
• Resources/ - Ресурсы (FetchXML шаблоны)
• Wsdl/ - WSDL определения

Полный пример использования

using Tisa.XrmCore;
using Tisa.XrmCore.Data;
using Tisa.XrmCore.Abstractions;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;

public class ContactService
{
    private readonly IXCoreService _xCoreService;

    public ContactService(IXCoreService xCoreService)
    {
        _xCoreService = xCoreService;
    }

    public async Task<Guid> CreateContactAsync(
        string firstName, 
        string lastName, 
        string email)
    {
        var service = _xCoreService.GetOrganizationService();
        
        var contact = new Entity("contact");
        contact["firstname"] = firstName;
        contact["lastname"] = lastName;
        contact["emailaddress1"] = email;
        
        return service.Create(contact);
    }

    public async Task<Entity> GetContactAsync(Guid contactId)
    {
        var service = _xCoreService.GetOrganizationService();
        return await service.RetrieveAsync(
            "contact", 
            contactId, 
            new ColumnSet("firstname", "lastname", "emailaddress1"));
    }

    public async Task<List<Entity>> SearchContactsByEmailAsync(string email)
    {
        var service = _xCoreService.GetOrganizationService();
        
        var query = new QueryExpression("contact");
        query.ColumnSet = new ColumnSet("firstname", "lastname", "emailaddress1");
        query.Criteria.AddCondition("emailaddress1", ConditionOperator.Equal, email);
        
        var results = await service.RetrieveMultipleAsync(query);
        return results.Entities.ToList();
    }
}

Требования

• .NET 8.0, .NET 9.0 или .NET 10.0
• Microsoft.PowerPlatform.Dataverse.Client 1.2.10
• Microsoft.IdentityModel.Protocols.WsTrust 6.8.0
• System.ServiceModel.Primitives (версия зависит от целевой платформы)
• System.ServiceModel.Federation (версия зависит от целевой платформы)
• Tisa.Common

Безопасность

При использовании библиотеки убедитесь, что:

• Используются безопасные методы хранения учетных данных (не храните пароли в коде)
• Применяются последние обновления безопасности
• Соблюдаются рекомендации по безопасности Dynamics 365
• Используется HTTPS для всех подключений
• Токены безопасности хранятся в защищенном хранилище

Рекомендации по использованию

1. Всегда используйте асинхронные методы для операций с CRM
2. Реализуйте правильную обработку ошибок с использованием специализированных исключений
3. Используйте Unit of Work для группировки операций в транзакции
4. Кэшируйте подключения где это возможно для оптимизации производительности
5. Используйте расширения для упрощения работы с данными
6. Следите за обновлениями библиотеки и зависимостей

Известные ограничения

• Поддерживается только WS-Trust аутентификация для локальных подключений
• Требуется доступ к URL организации
• Для OAuth и ClientSecret используется Microsoft.PowerPlatform.Dataverse.Client

Авторы

Команда разработчиков TISA

Лицензия

MIT License

Поддержка

Для получения поддержки или сообщения об ошибках, пожалуйста, напишите нам на support@tisn.ru