Tisa.XrmCore 2026.9.10.316

Tisa.XrmCore

👁 NuGet Version

Библиотека для .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

Лицензия

MIT License

Поддержка

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