Реализация интеграций IRIS с .NET или Java с помощью PEX

Введение {#Вебинар:ImplementingIntegrationswith.NetorJava-Introduction}

InterSystems IRIS 2020.1 включает PEX (Production EXtension Framework) для облегчения разработки производств IRIS Interoperability с компонентами, написанными на Java или .NET.

Благодаря PEX разработчик интеграции, владеющий Java или .NET, может воспользоваться мощью, масштабируемостью и надежностью фреймворка InterSystems IRIS Interoperability и в кратчайшие сроки начать продуктивную работу.

Для специалиста по IRIS Interoperability framework, PEX позволяет легко обогатить интеграцию уже существующими внешними компонентами на языке Java или .NET.

В этом учебнике мы рассмотрим PEX и подскажем разработчикам .NET их первые шаги в работе с PEX. Код доступен по адресу https://github.com/es-comunidad-intersystems/webinar-PE.

Учебник дополняет документацию по PEX, доступную в Интернете по адресу https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=EPEX.

 

Архитектура интероперабельности InterSystems IRIS {#Вебинар:ImplementarIntegracionescon.NetoJava-ArquitecturadeInteroperabilidadInterSystemsIRIS}

PEX позволяет вам выбрать язык программирования (в настоящее время Java или .NET, а позже Python) для реализации любого из компонентов (бизнес-сервис, бизнес-процесс, бизнес-операция, InboundAdapter, OutboundAdapter, Messages), которые формируют производство IRIS Interoperability.

Существует 3 основных компонента интероперабельности IRIS:

• Бизнес-сервисы: Компоненты, которые предлагают услуги, могут быть использованы извне. Примерами бизнес-сервисов являются REST-сервис и SOAP Web-сервис, а также сервис, который читает и обрабатывает новые файлы, записанные в каталог, сервис, который читает и обрабатывает строки таблицы базы данных, и/или сервис, который читает файлы через FTP, и т.д. Бизнес-служба может иметь ассоциированный входящий адаптер, который заботится о деталях реализации конкретного протокола (SQLInboundAdapter для чтения таблиц SQL, FileInboundAdapter для чтения файлов и т.д.). Бизнес-сервис отвечает за обработку информации, копирование ее в сообщение IRIS Interoperability, отправку сообщения в бизнес-процесс или бизнес-операцию и, возможно, ожидание ответа, если таковой имеется.  
• Бизнес-операция: Компонент, который получает сообщение IRIS Interoperability и работает с внешней системой, возможно, с помощью OutboundAdapter, который заботится о деталях реализации протокола (TCP, REST, SOAP, Files, SQL и т.д.). Бизнес-операция может возвращать или не возвращать ответ вызывающей стороне.  
• Бизнес-процесс: Процесс оркестровки, который, получая сообщение IRS Interoperability, может выполнять процессы и вызовы одного или нескольких других бизнес-процессов или операций для выполнения сложных операций и/или возврата сообщения с информацией, добавленной отправившей его Бизнес-службой.

Конфигурация компонентов сгруппирована в «Production», класс InterSystems IRIS, который содержит определение всех интеграций, которые запускаются вместе при инициации IRIS, и конфигурацию для каждого компонента этих интеграций. Он может быть отредактирован как класс IRIS или изменен с портала управления.

 

Архитектура PEX {#Вебинар:ImplementarIntegracionescon.NetoJava-ArquitecturadePEX}

Для выполнения .NET или Java кода InterSystems IRIS использует соответствующий объектный шлюз. Этот шлюз может быть инстанцирован локально или на удаленном сервере.

Шлюзы Java и .Net {#Вебинар:ImplementarIntegracionescon.NetoJava-LosJavay.NetGateways}

Шлюз — это собственный компонент .NET или Java, который прослушивает определенный порт TCP/IP, получает запросы от процесса IRIS, выполняет их и возвращает результаты.

 

Готовые компоненты PEX {#Webinar:ImplementarIntegracionescon.NetoJava-LosComponentesPEXpre-construidos}

Чтобы использовать PEX в производстве IRIS, необходимо добавить в производство предварительно созданный компонент для каждого компонента, разработанного на Java или .NET. Предварительно созданный компонент служит оберткой для внешнего элемента, на который он ссылается, и позволяет определить его свойства и конфигурацию в рамках производства.

Компоненты Java или .NET, запускаемые из соответствующего шлюза, должны наследоваться (быть подклассами) от уже существующего компонента PEX. Ниже приведен обзор этих элементов:

Компоненты IRIS {#Webinar:ImplementarIntegracionescon.NetoJava-ComponentesdeIRIS}

Для .NET и Java

 

Компоненты Java или .NET

Эти компоненты доступны в библиотеках, которые должны быть добавлены в проект Java или .NET. Минимальная библиотека для ссылки в проекте PEX — та же, что и у шлюза. Кроме того, если вы хотите использовать сообщения IRISObject для вызова компонентов IRIS из PEX, вы должны ссылаться на библиотеку IRISClient:

 

Суперкласс для использования в компонентах .NET

 

Суперкласс для использования в Java-компонентах

 

Функции утилиты {#Вебинар:ImplementarIntegracionescon.NetoJava-FuncionesdeUtilidades}

В компонентах, реализованных на ObjectScript, InterSystems IRIS предлагает некоторые команды в форме MACRO для заполнения информацией журнала событий IRIS. Эти методы доступны в Java и .NET следующим образом:

 

Взаимодействие между родными и PEX компонентами {#Вебинар:ImplementarIntegracionescon.NetoJava-InteroperabilidadentrecomponentesnativosycomponentesPEX}

Можно комбинировать компоненты на родном языке ObjectScript компании InterSystems IRIS с компонентами PEX, разработанными на Java или .NET.

• Если оба компонента имеют тип BusinessService — InboundAdapter или BusinessOperation — OutboundAdapter, разработчик может выбрать тип данных/объекта для использования в вызовах: Вызовы осуществляются между IRIS и шлюзом Java/.NET в соответствии с правилами преобразования данных, которые определяет шлюз.
• Когда оба компонента, обменивающиеся информацией, являются Business Hosts (BS, BP, BO), компонент, который должен получить сообщение (запрос или ответ), навязывает тип объектов, используемых для сообщения:
  • Компонент PEX всегда получает сообщение EnsLib.PEX.Message
  • Компонент IRIS получает сообщение IRISObject

 

EnsLib.PEX.Message {#Вебинар:ImplementarIntegracionescon.NetoJava-EnsLib.PEX.Message}

EnsLib.PEX.Message позволяет представить сообщение, структура которого была определена в .NET или Java, в объектном сценарии IRIS. IRIS использует функцию DynamicObject для манипулирования свойствами. Внутри IRIS использует JSON в качестве транспортной среды между IRIS и .NET/Java. При создании сообщения PEX в IRIS имя класса NET/Java, который должен быть инстанцирован для использования сообщения, должно быть задано как %classname.

IRISObject {#Вебинар:ImplementarIntegracionescon.NetoJava-IRISObject}

Чтобы вызвать предварительно созданный компонент InterSystems IRIS из компонента PEX, необходимо определить сообщение типа IRISObject (в .NET полный класс — InterSystems.Data.IRISClient.ADO.IRISObject).

 

Первые шаги с PEX и .NET {#Вебинар:ImplementarIntegracionescon.NetoJava-PrimerosPasosconPEXy.NET}

В этих первых шагах мы:

• Создадим проект .NET с необходимыми библиотеками PEX, версия 4.5 фреймворка .NET
• Добавим BusinessOperation и Simple сообщение в проект .NET
• Настроим шлюз .NET компании Intersystems IRIS
• Создайте производство интероперабельности
• Добавьте предварительно созданный BO

Создание проекта .NET с помощью Visual Studio 2019 {#Webinar:ImplementingIntegrationswith.NetorJava-Creatinga.NETProjectwithVisualStudio2019}

Создадим новый проект типа «Class Library .Net Standard in C #» в Visual Studio. Назовем его «PEX.Webinar.FirstDemo»:

 

 

Для работы с PEX добавляем необходимые зависимости из «Solution Explorer» и контекстного меню «Add Reference»:

 

, и добавляем две библиотеки (совместимые с .NET Framework 4.5! ), расположенные в подкаталоге инсталляции InterSystems IRIS с помощью кнопки «Browse»:

 

Затем из проводника решения Class1.cs переименовывается в «FirstOperation.cs», а класс модифицируется для наследования от класса PEX BusinessOperation (InterSystems.EnsLib.PEX.BusinessOperation). Все 3 метода PEX.BusinessOperation перезаписываются:

 

На данный момент не определены ни сообщения, ни задачи для выполнения. По этой причине в 3 метода добавлены функции LOGINFO. С другой стороны, метод суперкласса не нужно вызывать, поэтому мы можем исключить вызовы базового класса (base.OnInit (), base.OnTearDown(), base.OnMessage). Мы оставляем реализацию следующим образом:

 

Это позволяет скомпилировать начальную версию проекта .NET с помощью меню «Build Solution». Затем IRIS генерирует следующий файл, который используется далее:

InterSystems IRIS Interoperability Production Creation {#Вебинар:ImplementingIntegrationswith.NetorJava-InterSystemsIRISInteroperabilityProductionCreation}

Портал управления IRIS теперь позволяет выбрать меню «Interoperability», пространство имен «Ensemble», а также меню «Configure» и «Production». Вкладка «Действия» и кнопка «Новый» позволяют определить новое производство IRIS Integration.

Чтобы активировать службу тестирования, выберите вкладку «Settings», включите опцию «Testing Enabled» в последнем разделе списка («Development and Debugging») и нажмите кнопку Apply:

 

Добавление .NET-шлюза в производство {#Вебинар:ImplementingIntegrationswith.NetorJava-Addingthe.NETGatewaytotheProducción}

Для работы с PEX необходимо запустить соответствующий Java или .NET шлюз. InterSystems рекомендует конфигурировать и запускать эти шлюзы из меню «System Administration/Configuration/Connectivity/Object Gateways» для производственных сред (live). Для среды разработки компонент для запуска шлюза может быть добавлен непосредственно в production. Это позволяет запускать и останавливать шлюз одновременно с продакшеном одним щелчком мыши, тем самым освобождая доступ к .NET DLL проекта, когда вы хотите перекомпилировать его (Visual Studio не может перекомпилировать его, если .NET шлюз был запущен).

 

Чтобы добавить компонент «.Net Gateway», добавьте Business Service в производство, используя кнопку «+» рядом с «Services». «EnsLib.DotNetGateway.Service» — это имя класса компонента (Service Class), который нужно добавить, а для включения компонента выберите «Enable now».

 

Параметры конфигурации добавленного компонента можно отредактировать, щелкнув его, заполнив значения на вкладке «Settings» (Параметры) и нажав кнопку «Apply» (Применить):

 

Добавление бизнес-операции, созданной в .NET {#Вебинар:ImplementingIntegrationswith.NetorJava-AddingtheBusinessOperationcreatedin.NET}

Теперь мы добавим бизнес-операцию PEX, используя кнопку «+» рядом с «Operations», чтобы сослаться на ранее созданный в .NET код. «EnsLib.PEX.BusinessOperation» — это тип класса, (необязательный) компонент называется «PEX.Webinar.FirstOperation», и он включен с помощью «Enable Now».

 

Далее компонент настраивается (щелчком по добавленному компоненту) и выбором вкладки «Settings» справа:

Чтобы применить изменения, нажмите кнопку «Применить»:

 

Добавление и тестирование производства {#Webinar:ImplementingIntegrationswith.NetorJava-AddingandStartingtheProduction}

Кнопка «Start» запускает производство и все его компоненты:

InterSystems IRIS позволяет провести простое, изолированное тестирование компонента. Выберите «Бизнес-операцию» под названием «PEX.Webinar.FirstOperation» и выберите кнопку «Test» на вкладке Actions:

 

На следующем экране заполняются следующие данные:

 

При нажатии на кнопку «Invoke Testing Service», система IRIS Interoperability framework отправляет сообщение компоненту, и выполняется код .NET.

Нажав «Visual Trace», можно просмотреть детали. Белая точка (#3) отображает трассировку «LOGINFO», реализованную в .NET.

Журнал событий IRIS содержит компиляцию всех сгенерированных сообщений LOGINFO(), в том числе в OnInit() и OnTearDown().

 

Следующие шаги с PEX: завершение производства {#Вебинар:ImplementingIntegrationswith.NetorJava-NextStepswithPEX:CompletingtheProduction}

Ниже приведены другие типы компонентов, созданные в .NET:

• .NET Messages
• .NET Бизнес-сервисы
• .NET Бизнес-процесс

Создание и использование PEX-сообщения с данными {#Вебинар:ImplementingIntegrationswith.NetorJava-CreatingandUsingaPEXMessagewithData}

Чтобы передать информацию из Ensemble в компоненты PEX, определите класс в .NET как подкласс InterSystems.EnsLib.PEX.Message со свойствами для передаваемой информации. Продолжая упрощенный пример, добавим к сообщению строковое свойство «value». Бизнес-операция PEX станет сообщением того же типа с содержимым, преобразованным в заглавные буквы.

Класс Message в .NET {#Вебинар:ImplementarIntegracionescon.NetoJava-Clasedemensajeen.NET}

В проект .NET добавляется новый файл «FirstMessage.cs» со следующим определением:

FirstMessage

 

Использование сообщения из .NET {#Вебинар:ImplementarIntegracionescon.NetoJava-Usodelmensajedesde.NET}

В бизнес-операции FirstOperation тип данных для OnMessage определен как Object. Для его использования необходимо привести его к классу «FirstMessage»:

 

OnMessageV2

Производство IRIS должно быть остановлено (кнопкой «Stop»), или .NET Gateway должен быть, по крайней мере, отключен (двойной щелчок на компоненте) и скомпилировать .NET проект.

Использование класса из InterSystems IRIS {#Webinar:ImplementarIntegracionescon.NetoJava-UsodelaclasedesdeInterSystemsIRIS}

Кнопка «Тест» (Служба тестирования) не позволяет заполнить динамические свойства класса EnsLib.PEX.Message. Однако, Служба тестирования может быть использована с IRIS-нативным типом сообщения «Ens.StringRequest» и может быть преобразована (через преобразование данных) в сообщение PEX. Преобразование вызывается из предварительно созданного бизнес-процесса типа Router.

Трансформация данных {#Вебинар:ImplementingIntegrationswith.NetorJava-DataTransformation}

Преобразование данных создается для копирования данных из собственного сообщения ансамбля:

 

Трансформация данных может быть создана на портале управления «Interoperability»/»Build»/»Data Transformations» с помощью кнопки «New»:

 

После этого задаются параметры преобразования из «исходного» в «целевое» сообщение, как описано в предыдущей таблице, используя графический инструмент и заполняя текст на вкладке «Action» справа, чтобы получить две строки текста, отображаемые внизу. Затем на вкладке «Инструменты» можно сохранить, скомпилировать и протестировать.

 

Теперь, открыв вкладку «Инструменты», вы можете протестировать это преобразование данных:

 

Откроется окно Test, где вы можете указать значения для исходного сообщения (в StringValue) и проверить результат:

Как вы можете видеть, сообщение PEX использует внутреннее представление JSON для передачи значений между IRIS и Java или .NET.

 

Создание бизнес-процесса типа Router {#Вебинар:ImplementingIntegrationswith.NetorJava-CreatingaRoutertypeBusinessProcess}

Теперь можно добавить бизнес-процесс типа Router в Production и определить правило маршрутизации, которое вызывает созданную трансформацию данных и отправляет сообщение существующей бизнес-операции.

На портале управления вернитесь на экран конфигурации производства («Interoperability» / «Configure» / «Production») и добавьте бизнес-процесс типа «EnsLib.Message.Router», нажав на «+» рядом с «Processes», и заполните следующим образом:

 

Осталось отредактировать правило маршрутизации для этого компонента. Для этого выберите компонент «MessageRouter» в производстве и нажмите на увеличительное стекло рядом с именем бизнес-правила:

 

Редактор правил позволяет отредактировать правило для отправки всех сообщений «Ens.StringRequest» в бизнес-операцию «PEX.Webinar.FirstOperation» после применения к ним трансформации. Кнопка «+» позволяет добавлять элементы в правила и редактировать элемент при его предварительном выборе. Правило должно выглядеть следующим образом:

По умолчанию этот компонент не ожидает ответа. Измените настройки на вкладке «Настройки» компонента, чтобы получать ответ от Бизнес-операции:

 

Тестирование маршрутизатора с помощью службы тестирования {#Webinar:ImplementarIntegracionescon.NetoJava-PruebadelEnrutadorconelServiciodePruebas}

Вернувшись на страницу производства, вы можете использовать кнопку «Start» для запуска производства, выбрать компонент «MessageRouter» и на вкладке «Actions» нажать кнопку «Test», чтобы отправить сообщение типа «Ens.StringRequest»:

 

Сообщение «Test Response» можно просмотреть в разделе «Test Results», а полный журнал сообщений показывает все детали выполнения на различных компонентах производства IRIS Interoperability:

Response:

  {#Webinar:ImplementarIntegracionescon.NetoJava-}

Трассировка сообщений:

 

.NET Business Services {#Вебинар:ImplementarIntegracionescon.NetoJava-BusinessServiceen.NET}

.NET Implementation {#Вебинар:ImplementingIntegrationswith.NetorJava-Implementationin.NET}

Вернитесь в Visual Studio, чтобы создать бизнес-сервис .NET. В этом начальном примере эта бизнес-служба не связана с конкретным «Входящим адаптером»; она использует «EnsLib.InboundAdapter», компонент, который запускается через регулярные промежутки времени (в соответствии с установленным значением CallInterval) и делает вызов бизнес-службы каждый CallInterval. 

В Visual Studio для класса «FirstService» создается новый файл «FirstService.cs». Обработка каждого события, обнаруженного входящим адаптером, производится с помощью метода «OnProcessInput». Объект, задаваемый в параметре, зависит от реализации InboundAdapter; в данном случае он не используется:

FirstService:OnProcessInput

FirstService:OnProcessInput

 

Чтобы отправить сообщение любому компоненту продакшена без его перекомпиляции, можно использовать параметр, настраиваемый с портала управления; значения указываются в виде JSON-строки в параметре конфигурации «RemoteSettings».

Параметры

 

Если значение, указанное для «TargetConfigName», равно null, бизнес-сервис не отправит сообщение ни в одно место назначения. Чтобы обнаружить эту проблему как можно раньше, можно проверить значение TargetConfigName при запуске компонента в вызове OnInit():

FirstService:OnInit

Теперь вы можете изменить OnProcessInput, чтобы использовать значение TargetConfigName:

OnProcessInput

 

PEX Business Service в InterSystems IRIS {#Вебинар:ImplementarIntegracionescon.NetoJava-BusinessServicePEXenInterSystemsIRIS}

На портале управления добавьте компонент типа Business Service к определению Production, нажав на «+» рядом с надписью 

 

Затем настройте компонент (щелкнув на добавленном компоненте) и выберите вкладку «Настройки» справа: 

 

Когда эта бизнес-служба активирована, выполняется каждый CallIntervall связанного с ней адаптера OnTask() (Ens.InboundAdapter). Здесь OnTask просто вызывает FirstService.OnProcessInput(). То есть, каждый callInterval и FirstService.OnProcessInput() генерирует сообщение, которое отправляется компоненту, определенному в «TargetConfigName». Это можно проверить в Message Viewer:

 

С деталями вызова:

 

 

.NET Business Process {#Вебинар:ImplementarIntegracionescon.NetoJava-BusinessProcess.NET}

.NET Implementation {#Вебинар:ImplementingIntegrationswith.NetorJava-.NETImplementation}

Как и каждый бизнес-хост, бизнес-процесс имеет методы CallBack OnInit() и OnTearDown(). Конкретные методы Бизнес-процесса следующие:

Важно отметить, что бизнес-процесс может иметь длительное время выполнения (часы или дни, ожидая асинхронного ответа). Для этого IRIS Framework может прерывать и возобновлять выполнение процесса. Все значения, которые вы хотите сохранить во время выполнения процесса, должны быть помещены в свойства класса, которые IRIS сохраняет персистентно. Это необходимо указать с помощью обозначения «[persistent]».

В данном примере реализована минимальная реализация, в которой бизнес-процесс направляет полученное им PEX-сообщение в пункт назначения:

Используются две переменные, которые могут быть изменены с портала управления:

FirstProcess

 

Когда вы получаете сообщение, оно асинхронно отправляется в TargetConfigName:

FirstProces:OnRequest

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

FirstProcess:OnResponse

В конце процесса возвращается ответ:

FirstProcess:OnComplete

 

Бизнес-процесс PEX в InterSystems IRIS {#Вебинар:ImplementarIntegracionescon.NetoJava-BusinessProcessPEXenIntersystemsIRIS}

Мы добавляем бизнес-процесс EnsLib.PEX.BusinessProcess, настраиваем его по необходимости и изменяем TargetConfigName для бизнес-сервиса «PEX.Webinar.FirstProcess», чтобы отправлять сообщения новому процессу вместо того, чтобы отправлять их непосредственно в BO. 

 

«Настройки» компонента определяются следующим образом:

Результат в трассировке выглядит следующим образом:

 

Заключение

PEX позволяет реализовать интеграцию на .NET или Java очень легко и предлагает всю мощь и надежность уровня интероперабельности InterSystems IRIS для разработчиков, владеющих этими языками.