Plugins development ru RU

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

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

Эта страница описывает плагины ASF с точки зрения разработчиков - создание, сопровождение, публикация и аналогичное обслуживание. Если вы хотите просмотреть ракурс пользователя, переместите here вместо этого.

---

Основные настройки

Плагины являются стандартными библиотеками .NET, которые определяют класс, унаследованный от обычного интерфейса IPlugin, объявленного в ASF. Вы можете разрабатывать плагины независимо от основной ветки ASF и повторно использовать их в текущей и будущей версиях ASF, до тех пор, пока внутренний ASF API остается совместимым. Плагин, используемый в ASF, основан на «Системе». 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.</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <! - Поскольку вы загружаете плагин в процесс ASF, который уже включает эту зависимость, IncludeAssets="compile" позволяет исключить его из финального вывода -->
    <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" />

    <! - Если сборка с загруженным DLL двоичным файлом, используйте это вместо <ProjectReference> выше -->
    <! - <Reference Include="ArchiSteamFarm" HintPath="C:\\Path\To\Downloaded\ArchiSteamFarm.dll" /> -->
  </ItemGroup>
</Project>

Со стороны кода класс вашего плагина должен унаследоваться от интерфейса IPlugin (явно, или имплицитно унаследовав от более специализированного интерфейса, например IASF) и [Export(typeof(IPlugin))] для распознавания ASF во время выполнения. Самый простой пример реализации всего этого будет следующим:

использование системы;
с использованием System.Composition;
с использованием System.Threading.Tasks;
с использованием ArchiSteamFarm;
с использованием ArchiSteamFarm.Plugins;

пространства имен YourNamespace. ourPluginName;

[Export(typeof(IPlugin))]
публичные опечатанные класс YourPluginName : IPlugin {
	public string Name => nameof(YourPluginName);
	public Version => typeof(YourPluginName). ssembly.GetName().Version;

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

		return Task.CompletedTask;
	}
}

Чтобы воспользоваться вашим плагином, его надо сначала скомпилировать. Вы можете сделать это либо из своей IDE, или из корневой папки вашего проекта с помощью команды:

# Если у вас самостоятельный проект (нет нужды указывать имя, поскольку оно только одно)
dotnet publish -c "Release" -o "out"

# Если ваш проект часть дерева ASF (чтобы избежать компиляции необязательных частей)
dotnet publish YourPluginName -c "Release" -o "out"

После этого, ваш плагин готов к развертыванию. Именно вы, как именно вы хотите распространять и публиковать свой плагин, но мы рекомендуем создать zip-архив, где вы поместите ваш скомпилированный плагин вместе с его dependencies. Таким образом, пользователю просто нужно распаковать ваш zip-архив в отдельный подкаталог внутри папки plugins и ничего другого.

Это самый простой сценарий, просто чтобы помочь вам начать. У нас есть проект ExamplePlugin, который показывает примеры интерфейсов и действий, которые вы можете сделать в вашем собственном плагине, включая полезные комментарии. Не стесняйтесь посмотреть, если вы хотите учиться на рабочем коде, или найдите ArchiSteamFarm. lugins namace самостоятельно и обратитесь к включенной документации по всем доступным опциям. Мы также продолжим разработку некоторых базовых понятий ниже, чтобы объяснить их лучше.

Если вместо плагина вы хотите учиться на реальных проектах, то есть несколько официальных плагинов, разработанных нами, напр. ItemsMatcher, MobileAuthenticator или SteamTokenDumper. Кроме того, в нашем third-party разделе также есть плагины, разработанные другими разработчиками.

---

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

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

У нас очень открытая политика с точки зрения доступности API, так что если вы хотите использовать то, что уже включено в код ASF, просто открыть вопрос и объяснить в этом примере ваш планируемый вариант использования нашего внутреннего API ASF. Мы скорее всего не будем иметь ничего против, если предполагаемое вами использование имеет смысл. Это также включает в себя все предложения относительно новых интерфейсов IPlugin, которые могут быть добавлены для расширения существующей функциональности.

Однако, независимо от доступности ASF API ничего не мешает вам, например, включая Discord. et библиотека в вашем приложении и создание моста между вашим ботом Discord и командами ASF, так как ваш плагин может также иметь зависимости от самостоятельно. Возможности безграничны и мы постарались дать вам максимальную возможную свободу и гибкость используя вашим плагинам, поэтому никаких искусственных ограничений нет — плагин загружается в основной процесс ASF и может делать всё, что возможно сделать в C# коде.

---

Совместимость API

Важно подчеркнуть, что ASF это пользовательское приложение, а не обычная библиотека с фиксированными API, на которых можно безусловно основываться. Это означает, что вы не можете предполагать, что ваш плагин после компиляции будет работать со всеми будущими ASF релизами, это просто невозможно, если мы хотим продолжать разрабатывать программу дальше, и будучи не в состоянии адаптироваться к постоянным изменениям Steam в интересах обратной совместимости, это просто не подходит для нашего случая. Это должно быть для вас логичным, но важно подчеркнуть этот факт.

Мы сделаем все возможное, чтобы общественные части ASF работали и работали стабильно, но мы не будем бояться нарушить совместимость при наличии достаточных причин, следуя нашей deprecation политике в процессе. Это особенно важно в отношении внутренних структур ASF, которые подвержены вам как части инфраструктуры ASF (напр. ArchiWebHandler), который может быть улучшен (и, следовательно, переписан) в рамках улучшений ASF в одной из будущих версий. Мы будем стараться информировать об устаревшем функционале в списке изменений, и выдавать соответствующие предупреждения в процессе работы. У нас нет цели переписывать всё подряд только ради того чтобы переписать, так что вы можете быть относительно уверены в том, что следующая минорная версия не сломает полностью ваш плагин только потому, что увеличился номер версии, но вам стоит следить за списками изменений и периодически проверять, что всё работает.

---

Зависимости плагинов

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

Вывод вашей сборки будет включать ядро библиотеки YourPluginName.dll, а также все зависимости, которые вы указали. Так как вы разрабатываете плагин для уже работающей программы, вам не нужно, и даже должен включать в себя зависимости, которые уже включены ASF, например ArchiSteamFarm, SteamKit2 или AngleSharp. Удаление из вашей сборки всех зависимостей, общих с ASF, не является обязательным требованием для работы плагина, но это существенно уменьшит потребляемую память и размер вашего плагина, а также увеличит быстродействие, благодаря тому что ASF будет разделять свои зависимости с вами, и будет загружать только те библиотеки, о которых ему неизвестно.

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

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

Если вы запутались с вышеприведенным выражением и не знаете лучше, проверьте, какие библиотеки dll включены в ASF-generic. ip пакет и убедитесь, что в ваш плагин включены только те, которые еще не являются его частью. Для самых простых плагинов это будет только YourPluginName.dll. Если у вас при выполнении возникнут проблемы с какими-то библиотеками, включите в пакет также эти библиотеки. Если ничего не работает - вы всегда можете решить добавить в пакет вообще все зависимости.

---

Платформо-специфичные зависимости

Платформо-специфичные зависимости создаются как часть сборок для конкретных ОС, поскольку на целевой машине отсутствует .NET runtime, и ASF работает через свой собственный .NET runtime, включенный в состав сборки под данную ОС. С целью минимизировать размер сборки, ASF урезает все платформо-специфичные зависимости, чтобы они включали в себя только тот код, которому может реально быть передано управление в процессе работы программы, что по сути отрезает все неиспользуемые части среды исполнения. Это может создать потенциальную проблему для вас в отношении вашего плагина, если вдруг вы обнаружили себя в ситуации, где ваш плагин зависит от некоторых . Функция ET, которая не используется в ASF, и поэтому сборки, специфичные для OS, не могут ее запустить, обычно бросая в процесс System.MissingMethodException или System.Reflection.ReflectionTypeLoadException. По мере роста вашего плагина и становится все сложнее, Рано или поздно вы попали в поверхность, не покрытую нашей сборкой ОС.

Вы никогда не столкнётесь с этой проблемой в универсальной сборкой, потому что они никогда не имеют платформо-специфичных зависимостей (поскольку в этом случае для запуска ASF на целевой машине должна быть работоспособная среда исполнения). Поэтому рекомендуется использовать ваш плагин исключительно в общих сборках, но очевидно, что имеет свою собственную сторону вырезать плагин от пользователей, которые запускают сборки ASF, специфичные для ОС. Если вы сомневаетесь, что ваша проблема связана с платформо-специфичными зависимостями - вы можете также использовать этот метод для проверки, загрузив ваш плагин в универсальную сборку ASF и посмотрев, решит ли это проблему. Если проблема пропала, то с зависимостями плагина всё в порядке, и проблема вызвана только платформо-специфичными зависимостями.

К сожалению, нам пришлось сделать трудный выбор между публикацией всей среды исполнения в составе сборок под конкретную ОС и урезанием ненужных функций, что делает сборку на более чем 80 МБ меньше по сравнению с полной. Мы выбрали второй вариант, и к сожалению невозможно включить в ваш плагин недостающие в среде исполнения функции. Если ваш проект требует доступа к оставшимся функциям во время выполнения, вы должны включить полную информацию . ET runtime вы зависите, и это значит, что ваш плагин запускается в generic ASF вкус. Вы не сможете запускать свой плагин со сборками под конкретную ОС, поскольку эти сборки просто не включают в себя необходимые вам функции среды исполнения, а среда исполнения .NET Core на данный момент не умеет "объединять" такие зависимости. Возможно в будущем такая возможность появится, но сейчас это невозможно.

Сборки ASF под конкретную ОС включают в себя только самый минимум дополнительных функций, который требуется для запуска официальных плагинов. Кроме того, это слегка расширяет объём дополнительных зависимостей, которые могут потребоваться для самых простых плагинов. Следовательно, не всем плагинам нужно беспокоиться о платформо-специфичных зависимостях - только тем, которым требуется что-то, что не используется в ASF или наших официальных плагинах. Это сделано дополнительно, поскольку если нам самим нужно включать дополнительные зависимости для наших целей - мы можем просто поставлять их непосредственно в ASF, делая их доступными и для вас тоже. К сожалению, этого не всегда достаточно, и по мере того, как ваш плагин становится больше и более сложным, вероятность работы в обрезанной функциональности увеличивается. Поэтому мы обычно рекомендуем вам запускать пользовательские плагины в generic ASF эксклюзивно. Вы всё ещё можете вручную убедиться, что в платформо-специфичной сборке ASF есть все зависимости, что требуется плагину для его функциональности, но поскольку это меняется как на ваших обновлениях, так и на наших, это может быть сложно поддержать.

Иногда можно "обход" недостающих функций, либо используя альтернативные опции, либо перереализовывать их в вашем плагине. Однако это не всегда возможно или жизнеспособно, особенно если отсутствует функция приходит из зависимостей сторонних разработчиков, которые вы включаете в качестве части вашего плагина. Вы всегда можете попробовать запустить плагин в сборке для конкретных ОС и попытаться сделать его работой, но это может стать слишком много трудностей в долгосрочной перспективе, особенно если вы хотите от вашего кода к просто работать, а не сражаться с ASF поверхностью.

---

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

ASF предлагает вам два интерфейса для реализации автоматических обновлений в вашем плагине:

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

---

IGithubPluginUpdates

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

• Вам нужно объявить RepositoryName, который определяет, откуда будут доставлены обновления.
• Вам необходимо использовать теги и релизы, предоставленные GitHub. Тег должен быть в формате для версии плагина, например 1.0.0.0.
• Свойство Version плагина должно совпадать со свойством тега. Это означает, что двоичный файл с тегом 1.2.3.4 должен присутствовать как 1.2.3.4.
• Каждый тег должен иметь соответствующий релиз на GitHub с zip-файлом, который включает в себя ваши бинарные файлы плагина. Двоичные файлы, содержащие классы IPlugin, должны быть доступны в корневом каталоге в zip-файле.

Это позволит механизму в ASF:

• Определить текущую версию вашего плагина, например 1.0.1.
• Используйте GitHub API для получения последних tag доступных в репозитории 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, чтобы выбрать первую, в то время как во всех остальных версиях ASF будет использоваться второй.
• Если выше вам не хватает и вам требуется пользовательская логика для выбора правильной . файл ip, вы можете переопределить функцию GetTargetReleaseAsset() и предоставить артефакт для использования ASF.
• Если требуется выполнить некоторые дополнительные работы до/после обновления, вы можете переопределить методы OnPluginUpdateProceeding() и/или OnPluginUpdateFinished().

---

IPluginUpdates

Этот интерфейс позволяет вам реализовать пользовательскую логику для обновлений, если по какой-либо причине IGithubPluginUpdates вам не достаточно, например, потому что у вас есть теги, которые не разбираются с версиями, или потому, что вы вообще не используете платформу GitHub.

Существует одна функция GetTargetReleaseURL() для переопределения, которая ожидает от вас Uri? места обновления целевого плагина. ASF предоставляет некоторые ключевые переменные, связанные с контекстом вызываемой функции, но кроме того, вы несете ответственность за реализацию всего, что вам нужно в этой функции, и предоставляете ASF URL, который должен быть использован, или null, если обновление недоступно.

Кроме того, он похож на обновления GitHub, где URL-адрес должен указывать на . ip-файл с бинарными файлами, доступными в корневом каталоге. У вас также доступны методы OnPluginUpdateProceeding()иOnPluginUpdateFinished()`.