Разработать пользовательский веб-сервис с анонимной аутентификацией и нестандартной кодировкой

Средний

Пример реализован для Creatio версии 8.0.2 и выше.

Пример. Создать пользовательский веб-сервис с анонимной аутентификацией, который получает произвольный текст в кодировке ISO-8859-1. Веб-сервис возвращает аналогичный текст в той же кодировке.

1. Создать схему Исходный код 

  1. Перейдите в раздел Конфигурация (Configuration) и выберите пользовательский пакет, в который будет добавлена схема.

  2. На панели инструментов реестра раздела нажмите Добавить —> Исходный код (Add —> Source code).

  3. В дизайнере исходного кода заполните свойства схемы:

    • Код (Code) — "UsrEncodingService".
    • Заголовок (Title) — "Сервис с нестандартной кодировкой" ("Service with custom encoding").

    Для применения заданных свойств нажмите Применить (Apply).

2. Создать класс веб-сервиса 

  1. В дизайнере схем добавьте пространство имен, которое вложено в Terrasoft.Configuration. Например, UsrEncodingServiceNamespace.
  2. C помощью директивы using добавьте пространства имен, типы данных которых задействованы в классе.
  3. Добавьте название класса, которое соответствует названию схемы (свойство Код (Code)).
  4. В качестве родительского класса укажите класс Terrasoft.Nui.ServiceModel.WebService.BaseService.
  5. Для класса добавьте атрибуты [ServiceContract] и [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)].
  6. Для анонимного доступа к пользовательскому веб-сервису добавьте системное подключение SystemUserConnection.

3. Реализовать метод класса веб-сервиса 

  1. Реализуйте конечную точку пользовательского веб-сервиса. Для этого в дизайнере исходного кода добавьте в класс метод public string Test(string Name). В зависимости от значения параметра Name, которое указано в текстовой кодировке ISO-8859-1 и отправляется в строке запроса, тело ответа на запрос содержит значение этого же параметра в той же кодировке.

  2. Укажите пользователя, от имени которого выполняется обработка текущего http-запроса. Для этого после получения SystemUserConnection вызовите метод SessionHelper.SpecifyWebOperationIdentity пространства имен Terrasoft.Web.Common. Этот метод обеспечивает работоспособность бизнес-процессов при работе с сущностью (Entity) базы данных из пользовательского веб-сервиса с анонимной аутентификацией.

    Terrasoft.Web.Common.SessionHelper.SpecifyWebOperationIdentity(HttpContextAccessor.GetInstance(), SystemUserConnection.CurrentUser);

Исходный код пользовательского веб-сервиса UsrEncodingService представлен ниже.

UsrEncodingService
/* Пользовательское пространство имен. */
namespace Terrasoft.Configuration.UsrEncodingServiceNamespace
{
    using System;
    using System.ServiceModel;
    using System.ServiceModel.Web;
    using System.ServiceModel.Activation;
    using Terrasoft.Core;
    using Terrasoft.Web.Common;
    using Terrasoft.Core.Entities;

    [ServiceContract]
    [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)]
    public class UsrEncodingService: BaseService
    {
        /* Ссылка на экземпляр UserConnection, который требует для обращения к базе данных. */
        private SystemUserConnection _systemUserConnection;
        private SystemUserConnection SystemUserConnection {
            get {
                return _systemUserConnection ?? (_systemUserConnection = (SystemUserConnection)AppConnection.SystemUserConnection);
            }
        }
        
        /* Метод, который возвращает значение переданного параметра в указанной кодировке. */
        [OperationContract]
        [WebInvoke(Method = "POST", RequestFormat = WebMessageFormat.Xml, BodyStyle = WebMessageBodyStyle.Wrapped, ResponseFormat = WebMessageFormat.Xml)]
        public string Test(string Name){
            /* Указывает пользователя, от имени которого выполняется обработка данного http-запроса. */
            SessionHelper.SpecifyWebOperationIdentity(HttpContextAccessor.GetInstance(), SystemUserConnection.CurrentUser);
            /* Возвращает результат. */
            return Name;
        }
    }
}

На панели инструментов дизайнера исходного кода нажмите Опубликовать (Publish) для выполнения изменений на уровне базы данных.

4. Зарегистрировать веб-сервис 

  1. В каталоге ..\Terrasoft.WebApp\ServiceModel создайте файл UsrEncodingService.svc.

  2. В файл UsrEncodingService.svc добавьте запись.

    <% @ServiceHost
    Service = "Terrasoft.Configuration.UsrEncodingServiceNamespace.UsrEncodingService"
    Debug = "true"
    Language = "C#"
%>

    Атрибут Service содержит полное имя класса веб-сервиса с указанием пространства имен.

  3. Сохраните файл.

5. Зарегистрировать нестандартную текстовую кодировку 

  1. В файл ..\Terrasoft.WebApp\ServiceModel\http\bindings.config добавьте секцию <customBinding>.

  2. В секцию <customBinding> добавьте атрибуты:

    • name элемента <binding> — "ISO88591Encoding".
    • encoding элемента <customTextMessageEncoding> — "ISO-8859-1".
    • manualAddressing элемента <httpTransport> — "true".
    Файл ..\Terrasoft.WebApp\ServiceModel\http\bindings.config
    <bindings>
    ...
    <customBinding>
        <binding name="ISO88591Encoding">
            <customTextMessageEncoding encoding="ISO-8859-1" />
            <httpTransport manualAddressing="true"/>
        </binding>
        ...
    </customBinding>
</bindings>
  3. Сохраните файл.
  4. В файл ..\Terrasoft.WebApp\ServiceModel\https\bindings.config добавьте аналогичную запись.

6. Настроить веб-сервис для работы по протоколам http и https 

  1. В файл ..\Terrasoft.WebApp\ServiceModel\http\services.config добавьте запись.

    Файл ..\Terrasoft.WebApp\ServiceModel\http\services.config
    <services>
    ...
    <service name="Terrasoft.Configuration.UsrEncodingServiceNamespace.UsrEncodingService">
        <endpoint name="UsrEncodingServiceEndPoint"
            address=""
            binding="customBinding"
            bindingConfiguration="ISO88591Encoding"
            behaviorConfiguration="RestServiceBehavior"
            bindingNamespace="http://Terrasoft.WebApp.ServiceModel"
            contract="Terrasoft.Configuration.UsrEncodingServiceNamespace.UsrEncodingService" />
    </service>
</services>

    Атрибут binding содержит значение "<customBinding>", которое соответствует названию секции <customBinding> с регистрацией текстовой кодировки.

    Атрибут bindingConfiguration содержит название зарегистрированной текстовой кодировки. Совпадает со значением атрибута name элемента <binding>, который задан на предыдущем шаге.

  2. Сохраните файл.
  3. В файл ..\Terrasoft.WebApp\ServiceModel\https\services.config добавьте аналогичную запись.

7. Настроить доступ к веб-сервису для всех пользователей 

  1. В файл ..\Terrasoft.WebApp\Web.config добавьте элемент <location>, который определяет относительный путь и права доступа к веб-сервису.

    Файл ..\Terrasoft.WebApp\Web.config
    <configuration>
    ...
    <location path="ServiceModel/UsrEncodingService.svc">
        <system.web>
            <authorization>
                <allow users="*" />
            </authorization>
        </system.web>
    </location>
    ...
</configuration>

  2. В файле ..\Terrasoft.WebApp\Web.config в атрибут value ключа AllowedLocations элемента <appSettings> добавьте относительный путь к веб-сервису.

    Файл ..\Terrasoft.WebApp\Web.config
    <configuration>
    ...
    <appSettings>
    ...
        <add key="AllowedLocations" value="[Предыдущие значения];ServiceModel/UsrEncodingService.svc"  />
    ...
    </appSettings>
    ...
</configuration>
  3. Сохраните файл.

8. Перезапустить приложение в IIS 

Для применения изменений перезапустите приложение в IIS.

Результат выполнения примера 

Для демонстрации результата выполнения примера используем инструмент тестирования запросов Postman. Работа с Postman описана в официальной документации Postman. Инструкция по использованию Postman для выполнения запросов к Creatio содержится в статье Выполнить запрос к Creatio в Postman. Инструкция по использованию Postman для вызова веб-сервиса содержится в статье Вызвать пользовательский веб-сервис с помощью Postman.

Чтобы посмотреть результат выполнения примера, выполните запрос к веб-сервису UsrEncodingService.

Настройки запроса, которые необходимо установить в Postman:

  • Метод запроса: POST.

  • Строка запроса к методу Test пользовательского веб-сервиса UsrEncodingService.

    Строка запроса к веб-сервису UsrEncodingService
    http://myсreatio.com/0/ServiceModel/UsrEncodingService.svc/Test

  • Формат данных запроса (настраивается на вкладке Body).

    1. Установите опцию "raw".
    2. Выберите тип "XML".
    3. Заполните тело POST запроса. В теле запроса передайте символы в текстовой кодировке ISO-8859-1. О символах, которые используются в текстовой кодировке ISO-8859-1, читайте в Википедии.

В результате выполнения примера получен ответ на POST запрос. Формат ответа — XML, код — 200 OK. Тело ответа отображается на вкладке Body и содержит значение параметра Name тела запроса в текстовой кодировке ISO-8859-1.

Ресурсы
Пакет с реализацией примера
Коллекция запросов в Postman с результатом выполнения примера