Plugins development uk UA

Розробка плагинів

ASF має підтримку для користувацьких плагінів, які можуть бути завантажені протягом роботи. Плагіни дозволяють вам налаштувати поведінку ASF, наприклад, додавши власні команди, власну торговельну логіку або всю інтеграцію із сторонніми сервісами та API.

Ця сторінка описує плагіни ASF з погляду розробників. Створення твору, супроводження, публікацію і т.п. Якщо ви хочете побачити перспективу користувача, перемістіть here натомість.

---

Основні настройки

Плагіни - це стандартні стандартні бібліотеки .NET, що визначають клас, успадкований від загального інтерфейсу IPlugin, оголошеного в ASF. Ви можете розробляти плагіни цілком незалежно від мейнлайн ASF і повторно використовувати їх у поточних і майбутніх версіях ASF, поки внутрішній ASF API залишається сумісним. Плагін, що використовується у ASF на основі System. omposition, раніше відомий, як Managed Extensibility Framework що дозволяє ASF знаходити та завантажити ваші бібліотеки протягом роботи.

---

Приступаючи до роботи

Ми підготували ASF-PluginTemplate для вас, який ви можете (і повинний) використовувати в якості основи вашого проекту плагінів. Використання шаблону не є обов'язковим (як ви можете робити все з нуля), але ми рекомендуємо підібрати його, оскільки він може кардинально копіювати ваш проект і скоротити час, необхідний для всього що підходить. Просто перевірте README у шаблоні і він покаже вам далі. Незалежно від того, ми розглянемо основи нижче, якщо ви хочете почати з нуля, або щоб краще зрозуміти поняття, що використовуються в шаблоні плагінів. Зазвичай, не потрібно робити нічого з цього, якщо ви вирішили використовувати наш шаблон плагінів.

Ваш проект має бути стандартним. Ціль ET бібліотеки підтримує відповідну структуру вашої цільової версії ASF, як зазначено в compilation розділ.

Проект повинен посилатися на головну збірку ArchiSteamFarm або на попередньо побудований ArchiSteamFarm. ll бібліотека, яку ви завантажили в якості частини релізу, або вихідний проект (наприклад, якщо ви вирішили додати дерево ASF як підмодуль). Це дозволить вам отримувати доступ та знаходити структури ASF, методи та властивості, особливо основний інтерфейс IPlugin, який вам потрібно успадкувати з наступного кроку. Проект має також посилатись на System.Composition.AttributedModel мінімальну, що дозволяє вам використовувати [Export] ваш IPlugin для ASF. На додаток до цього, ви можете захотіти/захотіти ознайомитися з іншими загальними бібліотеками для того, щоб інтерпретувати структури даних у деяких інтерфейсах, але якщо ви не потребуєте їх явно - цього буде достатньо.

Якщо ви зробили все вірно, ваш csproj буде схожий на нижче:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <!-- Since you're loading plugin into the ASF process, which already includes this dependency, IncludeAssets="compile" allows you to omit it from the final output -->
    <PackageReference Include="System.Composition.AttributedModel" IncludeAssets="compile" Version="9.0.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="C:\\Path\To\ArchiSteamFarm\ArchiSteamFarm.csproj" ExcludeAssets="all" Private="false" />

    <!-- If building with downloaded DLL binary, use this instead of <ProjectReference> above -->
    <!-- <Reference Include="ArchiSteamFarm" HintPath="C:\\Path\To\Downloaded\ArchiSteamFarm.dll" /> -->
  </ItemGroup>
</Project>

З сторони коду, клас ваших плагінів повинен успадковуватися від інтерфейсу IPlugin (або явно або неявно успадковуючи від більш спеціалізованого інтерфейсу, наприклад IASF) і [Export(typeof(IPlugin)], щоб його упізнали під час виконання. Найгостріший приклад, що досягнув би наступне:

using System;
using System.Composition;
using System.Threading.Tasks;
using ArchiSteamFarm;
using ArchiSteamFarm.Plugins;

namespace YourNamespace.YourPluginName;

[Export(typeof(IPlugin))]
public sealed class YourPluginName : IPlugin {
	public string Name => nameof(YourPluginName);
	public Version Version => typeof(YourPluginName).Assembly.GetName().Version;

	public Task OnLoaded() {
		ASF.ArchiLogger.LogGenericInfo("Hello World!");

		return Task.CompletedTask;
	}
}

Для того, щоб використовувати свій плагін, ви повинні спочатку скомпілювати його. Ви можете зробити це або з вашого IDE, або з кореневого каталогу вашого проекту за допомогою команди:

# If your project is standalone (no need to define its name since it's the only one)
dotnet publish -c "Release" -o "out"

# If your project is part of ASF source tree (to avoid compiling unnecessary parts)
dotnet publish YourPluginName -c "Release" -o "out"

Після цього Ваш плагін готовий до розгортання. It's up to you how exactly you want to distribute and publish your plugin, but we recommend creating a zip archive where you'll put your compiled plugin together with its dependencies. Таким чином, користувачу потрібно буде просто розпакувати ZIP-архів у окремий підкаталог всередині їх каталогу "plugins", і нічого більше не робити.

Це лише найбільш базовий сценарій, який ви почнете. Ми маємо Наприклад: Plugin проект, який показує вам приклади інтерфейсів та дій, які ви можете зробити в своєму власному плагіні, включаючи корисні коментарі. Ви можете вільно одягати свій вигляд, якщо хочете чомусь навчитись у робочому коді, або ознайомитись з ArchiSteamFarm. lugins namespes себе і зверніться до включеної документації для всіх доступних параметрів. Ми також розглянемо деякі основні концепції нижче, щоб пояснити їх краще.

Якщо замість прикладного плагіна ви б хотіли дізнатись з реальних проектів, ми розроблено декілька офіційних плагінів, наприклад, ItemsMatcher, MobileAuthenticator або SteamTokenDumper. На додаток до цього, існують також розроблені плагінами інших розробників, в нашому third-party розділ.

---

Доступність API

ASF, крім того, що ви маєте доступ до самих себе, нав'язує велику кількість внутрішніх API, які ви можете використовувати, щоб розширити функціонал. Наприклад, якщо ви хочете надіслати який-небудь новий запит до версії Steam, то вам не потрібно реалізувати все з нуля, особливо стосовно усіх проблем, з якими ми мали стикатися до вас. Просто користуйтесь нашим Ботом. rchiWebHandler, який вже розкриває безліч методів "UrlWithSession()", які для вас використовують, обробка всіх речей нижчого рівня, таких як автентифікація, оновлення сесії або веб-обмеження для вас. Так само для надсилання веб-запитів за межами платформи Steam, ви можете використовувати стандартний .NET HttpClient, але краще використовувати Bot. rchiWebHandler.WebBrowser, який доступний для вас, який ще раз пропонує вам корисну руку, наприклад, для регулярного повторного спроби невдалих запитів.

У нас є дуже відкрита політика з точки зору наявності API, так що, якщо ви бажаєте використовувати щось, що вже містить код ASF, просто відкрийте питання і пояснити в ньому ваш планований випадок використання внутрішнього API нашого ASF. Нас, швидше за все, не буде нічого проти, доки у вас є сенс. Це також включає в себе всі пропозиції з огляду на нові інтерфейси IPlugin, які можуть мати сенс бути додані для розширення вже існуючих функцій.

Однак, при відсутності доступності ASF API нічого не зупиняє вас ізвідси, у тому числі Discord. et бібліотека у вашому застосунку і створення мосту між командами Discord з ASF, Оскільки ваш плагін також може мати залежності самі по собі. Можливості нескінченні, і ми зробили все можливе, щоб дати вам якомога більше свободи й гнучкості в межах вашого плагіну, так що немає штучних обмежень - ваш плагін завантажується в основний процес ASF і може зробити що-небудь, що є реальним для порівняння з кодом C# .

---

API compatibility

Бажано підкреслювати, що ASF це споживчий додаток, а не типова бібліотека з фіксованою поверхнею API, на яку ви можете залежати безумовно. Це означає, що ви не можете припустити що ваш плагін після скомпіляції буде працювати з усіма майбутніми релізами ASF з бажанням, просто неможливо, якщо ми хочемо продовжити розвивати програму, і не в змозі адаптуватися до постійних змін Steam задля забезпечення зворотної сумісності просто не підходить для нашого випадку. Це має бути логічно для вас, але важливо виділити цей факт.

We'll do our best to keep public parts of ASF working and stable, but we'll not be afraid to break the compatibility if good enough reasons arise, following our deprecation policy in the process. Це особливо важливо у відношенні до внутрішніх структур ASF, які викриті вам як частина інфраструктури ASF (наприклад, ArchiWebHandler), який може бути покращений (і тому переписував) у якості частини розширень ASF у одній з майбутніх версій. Ми зробимо все можливе, щоб повідомити вам про зміни та включити відповідні попередження під час виконання про застарілі функції. Ми не маємо наміру переписати все заради цього і переписати, так що ви можете бути досить впевнені, що наступна мінорна версія ASF не просто знищить ваш плагін лише тому, що він має вищу версію, але слідкувати за змінами та випадковими перевірками, якщо все працює добре, то це дуже гарна ідея.

---

Залежності плагінів

Ваш плагін включатиме принаймні два залежності по замовчуванню, за посиланням ArchiSteamFarm для внутрішнього API (IPlugin в мінімальному мінімумі) та PackageReference System. метод omposition.AttributedModel, необхідний для розпізнавання плагіна ASF, з якого починається ([Export]. Крім цього, включно з більшою кількістю залежностей стосовно того, що ви вирішили зробити у вашому плагіні (а. . Discord.Net, якщо ви вирішили інтегрувати з Discord).

Вивід вашої збірки включатиме ядро YourPluginName.dll бібліотека, а також всі залежності, на які ви посилаєтесь. Оскільки Ви розробляєте плагін для вже працюючої програми, у Вас не є, і навіть повинний включити залежності, які вже включає ASF, наприклад ArchiSteamFarm, SteamKit2 чи AngleSharp. Вилучення ваших залежностей, спільних у ASF, це не абсолютна потреба вашого плагіна на працювати, але це різко скоротить споживання пам'яті і розмір плагіну, разом із збільшенням продуктивності через те, що ASF буде ділитися своїми залежностями з вами, і буде завантажувати тільки ті бібліотеки, про які вона не знає.

Загалом, рекомендована практика повинна включати лише ті бібліотеки, яких ASF або не включає, або в себе неправильна/несумісна версія. Приклади з них вочевидь "YourPluginName.dll", але наприклад "Discord.Net.dll", якщо ви вирішили залежати від цього, бо ASF не включає це саме собою. Збірки бібліотек, які є спільними у ASF все ще можуть мати сенс, якщо ви бажаєте забезпечити сумісність API (наприклад, щоб переконатися, що AngleSharp, який ви залежали від вашого плагіна, буде завжди в версії X, а не в якому ASF кораблів), але, очевидно, це приходить за рахунок збільшення обсягу пам'яті / розміру і гіршої продуктивності, і тому слід ретельно оцінити.

Якщо ви знаєте, що залежність, яка вам потрібна включена до ASF, ви можете позначити це як "IncludeAssets="compile"як ми показали в прикладі "csproj" вище. Це скаже компілятор, щоб уникнути самої публікації посилань на бібліотеку, бо ASF вже включає в себе це. Так само зверніть увагу, що ми посилаємось на проект ASF за допомогоюExcludeAssets="all" Private="false", який працює дуже подібним чином - вказувати компілятору не створювати будь-які файли ASF (як у користувача вже їх є). Це застосовується лише тоді, коли ви посилаєтеся на проект ASF, бо якщо ви посилаєтеся на бібліотеку dll`, то ви не створюєте файли ASF як частину вашого плагіна.

Якщо ви плутаєте з наведеним вище твердженням і не знаєте краще, перевірте, які бібліотеки dll включені в ASF-generic. пакунок ip і гарантує, що ваш плагін включає лише тих, які ще не є його частиною. Це буде тільки YourPluginName.dll для найпростіших плагінів. Якщо у вас виникнуть будь-які проблеми як бігун, до деяких бібліотек, до них також містяться і ці постраждалі бібліотеки. Якщо все інше зазнає невдачі, ви можете завжди вирішити зібратися з усім.

---

Нативні залежності

Рідні залежності створюються у вигляді структури для конкретної ОС, оскільки їх немає. Доступний час роботи ET на хості і ASF працює на власному .NET runtime який є вбудованим як частина збірки для конкретної ОС. Для того, щоб мінімізувати розмір збірки, ASF спрощує нативні залежності, щоб включити лише той код, який може бути досягнутий у програмі, що ефективно скорочує невикористані частини часу виконання. Це може створити потенційну проблему для вас в відношенні до вашого плагіну, якщо раптом ви дізнаєтесь себе в ситуації, де ваш плагін залежить від деяких проблем. Функція ET, яка не використовується в ASF, і тому збірки для конкретної ОС не можуть її виконувати належним чином, зазвичай кинувши "System.MissingMethodException" або "System.Reflection.ReflectionTypeException" в процесі. Зі збільшенням розмірів ваш плагін стає все більш складним, Рано чи пізно ви б отримали поверхню, яка не покрита нашою побудовою для конкретної ОС.

Ця проблема ніколи не пов'язана з загальними будівлями, оскільки вони ніколи не мають справу з рідними залежностями в першу чергу (як вони завершили роботу над господарем, виконавчим ASF). Ось чому рекомендована практика **використовувати плагін в загальних конструкціях винятково **, але очевидно, що це має власний недолік скоротити плаґін від користувачів, які працюють на ОС збірки ASF. Якщо вам цікаво, чи ваша проблема пов'язана з нативними залежностями, ви також можете використовувати цей метод для перевірки, завантажити свій плагін у універсальній збірці ASF і подивитися, чи він працює. Якщо це станеться, тоді у вас прикрито залежність від плагіна, і це природні залежності від цієї проблеми.

На жаль, нам довелося складати важкий вибір між публікацією цілого середовища як частиною наших будівель для конкретної ОС, і рішення вирізати його з невикористаних функцій, зробити збірку більш ніж на 80 Мб меншою в порівнянні з повним. Ми обрали другу опцію, і, на жаль, неможливо включити відсутні функції під час виконання програми. Якщо ваш проект потребує доступу до функцій, які не залишилися, вам потрібно додати повну версію. ET runtime залежить від вашого та це означає, що ви запускаєте свій плагін в універсальному ASF, який вам сподобається. Ви не можете запустити свій плагін в збірках для конкретної ОС, оскільки ті збірки просто пропускають необхідну функцію виконання і . Час роботи так і не може бути «злиття» рідної залежності, яку можна було б забезпечити нашим власним. Можливо, це покращить один день у майбутньому, але на даний момент це неможливо.

Збірки, специфічні для ОС ASF, включають мінімальний мінімум додаткових функцій, які необхідні для роботи наших офіційних плагінів. Крім цього, це також трохи розширює поверхню на додаткові залежності, необхідні для основних плагінів. Тому не всі плагіни будуть змушені турбуватися про нативні залежності, починаючи з них - тільки ті, що виходять безпосередньо під рамки ASF та офіційних плагінів. Це робиться як додаткові, тому що, якщо нам потрібно включити додаткові нативні залежності самі для нашого використання справи в будь-якому разі, ми можемо також доставити їх напряму за допомогою ASF, зробити їх доступними, і тому легше покрити, також для вас. На жаль, цього не завжди достатньо, і через те, що Ваш плагін стає все більшим і складнішим, ймовірність того, що він використовує цю функцію збільшення. Тому ми рекомендуємо вам запустити користувацькі плагіни у generic ASF відступив. Ви можете вручну перевірити, що ASF має все, що вимагає ваша функціональність - але після змін у оновленні, а також наш, може бути важко утримувати.

Іноді можливо «workaround» відсутні функції або використовуючи альтернативні варіанти або реалізацію їх у вашому плагіні. Це проте не завжди можливо або життєздатно, особливо якщо пропущена функція походить від залежностей сторонніх розробників, до яких ви включаєте в частину вашого плагіна. Ви завжди можете запустити ваш плагін у збірці для конкретної ОС, і спробувати виконати її роботу, але це може стати занадто багато клопоту в довгостроковій перспективі, особливо якщо ви бажаєте з вашого коду просто працювати, а не боротися з інтерфейсом ASF.

---

Автоматичне оновлення

ASF пропонує вам два інтерфейси для автоматичного оновлення у вашому плагіні:

• IGitHubPluginUpdates забезпечує простий спосіб впровадження оновлень на GitHub, схожих на загальний механізм оновлення ASF
• IPluginUpdates, що надає вам функцію більш низького рівня, яка дозволяє використовувати спеціальний механізм оновлення, якщо вам потрібно щось більш складне

---

IGithubPluginUpdates

Мінімальний контрольний список речей, які необхідні для роботи над оновленнями:

• Ви маєте оголосити RepositoryName, яке визначає, звідки вилучаються оновлення.
• Вам потрібно використовувати теги та релізи, надані GitHub. Тег повинен бути в форматі синтаксичної версії плагіна, наприклад 1.0.0.0.
• властивість Versionплагіна повинна відповідати тегу, від якої вона походить. Це означає, що двійковий файл під тегом1.2.3.4повинен представлятись як1.2.3.4`.
• Кожен тег повинен мати відповідний випуск на GitHub з архівним випуском файлів що включає в себе двійковий файл плагіну. Бінарні файли включають у себе класи IPlugin повинні бути доступні в кореневому каталозі в zip-файлі.

Це дозволить механізму у ASF на:

• Вирішіть поточну Версію вашого плагіна, наприклад 1.0.1.
• Використовувати GitHub API для отримання останніх тегів доступних в RepositoryName, наприклад, 1.0.2.
• Визначте що 1.0.2 > 1.0.1, перевірте випуск тега 1.0.2, щоб знайти файл .zip за допомогою оновлення плагінів.
• Завантажте файл .zip, розпакуйте його та помістіть його вміст у каталог, що містить YourPlugin.dll раніше.
• Перезапустіть ASF, щоб завантажити ваш плагін за версією 1.0.2.

Додаткові примітки:

• Оновлення плагінів можуть вимагати відповідних значень конфігурації ASF, а саме PluginsUpdateMode та/або PluginsUpdateList.
• Наш шаблон плагіна вже містить все, що вам потрібно, просто rename плагін для правильних значень і працює з коробки.
• Ви можете використовувати комбінацію останнього релізу та пре-релізу, вони будуть використовуватися як „UpdateChannel“, який визначив користувач.
• Існує логічна властивість CanUpdate, яку можна змінити для вимкнення/увімкнення оновлення плагінів на вашій стороні, наприклад, якщо ви хочете тимчасово пропустити оновлення або з будь-якої іншої причини.
• Є можливість мати кілька zip-файлів у випуску, якщо ви бажаєте призначати різні версії ASF. Дивіться GetTargetReleaseAsset() remarks. Наприклад, ви можете мати "MyPlugin-V6-0.zip", а також "MyPlugin.zip", що призведе до ASF у версії V6. .x.x.x щоб вибрати перший з них, в той час як всі інші версії ASF використовуватимуть другий.
• Якщо вищезгаданий не достатньо для вас, і вам потрібна спеціальна логіка для вибору правильного . файл ip, ви можете змінити функцію GetTargetReleaseAsset() та надати артефакт для користування ASF.
• Якщо ваш плагін повинен виконувати деякі додаткові роботи перед оновленням/після оновлення, ви можете перевизначити методи OnPluginUpdateProceeding() та/або OnPluginUpdateFinished().

---

IPluginUpdates

Цей інтерфейс дозволяє реалізувати користувацьку логіку для оновлень, якщо будь-якої причини GithubPluginUpdates недостатньо для вас, наприклад, коли у вас є теги, які не аналізуються до версій, або тому, що ви взагалі не використовуєте платформу GitHub.

Існує одна функція GetTargetReleaseURL() для вас, яка очікує від вас "Uri?" цільового оновлення розташування. ASF надає деякі базові змінні, які стосуються контексту, з якою була викликана функція, але крім цього, Ви відповідальні за реалізацію всього потрібної вам функції та надання URL, який слід використовувати, або null, якщо оновлення недоступне.

Інша причина, подібна оновлення на GitHub, де URL повинен вказувати на . ip файл з двійковими файлами в кореневій директорії. Ви також маєте методи OnPluginUpdateProceeding() і OnPluginUpdateFinished().