Creation of Backend package from template

Для розробки знадобиться IDE з підтримкою написання коду на мові програмування C#. Для написання даної інструкції використовувалась VisualStudio.

Також необхідна наявність dotnet CLI

Repository cloning

Розробку першого плагіна розпочнемо з клонування GIT репозиторію tutorial-backend-plugin.

git clone https://github.com/mef-dev/tutorial-backend-plugin/tree/ibackend-plugin

Content overview

Після завантаження, та відкриття проекту можемо оглянути вміст.

вміст проекту

Унікальним ідентифікатором на платформі є назва проекту, а також назва сутності (entity). При створенні власного проекту перейменовуємо проект і модифікуємо назву сутності.

Implementation

Платформа MEF.DEV підтримує архітектурний стиль розробки REST задля того, щоб використовувати методи HTTP для операцій замість написання різних імен сервісів для кожної операції. Нижче наведено список методів, які використовуються у платформі, і їхні властивості відображено по відношенню до кожної сутності:

  • GET: Цей метод є безпечним та ідемпотентним. Зазвичай використовується для отримання інформації та не має побічних ефектів
  • POST: цей метод не є безпечним, але він ідемпотентний у реалізації REST API - це зроблено для підтримки змінності в застарілих системах, які не підтримують метод PUT. Цей метод найчастіше використовується для створення сутностей
  • PUT: цей метод є ідемпотентним, тому для оновлення ресурсів краще використовувати цей метод замість POST. Уникайте використання POST для оновлення ресурсів, за винятком тих сутностей, для змін яких потрібні історичні зміни, наприклад адрес або профілів

Більш детально розглянемо методи:

  • BaseEntity Post(string lang, BaseEntity entity, string parent = null);
  • BaseEntity Put(string id, string lang, BaseEntity entity);

Цы методи приймають модель даних наслюдувача класу BaseEntity. Для того щоб платформа MEF.DEV знала який саме конкретний клас має використовуватись для десералізації тіла запиту використовується такий саме атрібут, який використовується для позначення сутності як експортованої (для прикладу entityName на скріншоті вище), а саме ExportAttribute. Ключовий момент в тому щоб значення цього атрібуту співпадали!

Наприклад, якщо є експортований клас 

[Export("accounts", typeof(IBackendPlugin))]
public sealed class AccountsEntity : IBackendPlugin
{
}

то ОБОВ'ЯЗКОВО треба описувати і модель для методів POST і PUT

[Export("accounts", typeof(BaseEntity))]
public sealed class AccountsRequest : BaseEntity
{
}

Build

Для збірки плагіна можна скористатися командою

dotnet publish -o bin\Deploy --force

Та заархівувати вміст теки bin\Deploy.

Registration package

Для початку перейдемо на сторінку створення плагіну.

Cторінкa створення

Вона знаходиться в пункті меню Плагіни

Після чого ми попадаємо на сторінку створення плагінів.

Аліас- назва предметної області плагіну. Ім'я- назва плагіну. Вооодимо ці данні, і переходимо до типу. У платформі існує 4 основних типи плагінів. Про відмінності між ними написано в блоці допомоги. Зараз нас цікавить тип Service- плагін, що містить лише API складову, без користувацької конфінурації. Вибираємо його.

Після вибору у нас активувався Backend блок. Він містить лише одне поле PluginMefName. Це є назва нашого проекту. Вводимо назву з репозиторію, після чого нажимаємо кнопку Зберегти.

Uploading version of package

Для завантаження готового ZIP-архіву плагіну на платформу mef.dev technical preview, необхідно, на сторінці конфігурації в блоці Backend натиснути кнопку Завантажити нову версію.

Cторінкa створення

Після завантаження, в дропдауні необхідно вибрати необхідну версію та натиснути кнопку Зберегти

Package Dry run

Провіряти роботу API плагінів можна любою програмою-сніфером. В данному випадку використовуватиметься Postman.

Для відправлення запитів потрібно авторизуватися – зазвичай використовується схема авторизації із токеном користувача в платформі, алє для тестування ми застосуємо Basic Auth. Необхідну пару логін-пароль доступу до API можна створити в розділі SETTINGS \ CREDENTIALS свого профілю, куди можна потрапити натиснувши на іконку користувача у верхньому правому кутку і вибравши пункт меню SETTINGS. Після натискання на кнопку ADD Ви зможете задати логін користувача і пароль для авторизації Basic Auth

Базова перевірка працездатності

В межах платформи існує endpoint для перевірки працездатності плагіна:

https://preview.mef.dev/api/v1/<alias>/plugins/<PluginMefName>/version.json?detaillevel=detailed
detaillevel=detailed

У випадку схожого результату, важ плагін успішно завантажений на платформу, та готовий до роботи.

Запити до плагіна

Надсилання запитів до плагіна продемонструємо на прикладі GET запитів.

Для надсилання запитів використовується шаблон:

https://preview.mef.dev/api/v1/<alias>/<EntityName>

При цьому в тіло запиту можна добавляти будь-які параметри\хедери\поля, проте варто відобразити їх у вхідній моделі плагіна.

detaillevel=detailed

Запити до Action

Action можуть сприймати лише POST запити, Які формуються за формулою:

https://preview.mef.dev/api/v1/<alias>/<EntityName>/<ActionName>.json
detaillevel=detailed

Реалізацію цих запитів також можна побачити в Ангуляр-аплікаці tutorial-ui-plugin.