Plugins zh TW
從ASF V4版本開始，程式支援可在執行期間載入的自訂外掛程式。 外掛程式使您能夠自訂ASF的行為，例如加入自訂指令、自訂交易邏輯，或與第三方服務或是API進行整體整合。
ASF會從您的ASF資料夾中的plugins資料夾載入外掛程式。 建議為您使用的每個外掛程式提供一個專屬資料夾，該資料夾可以依據外掛程式的名稱命名，例如我的外掛程式。 最終會產生plugins/我的外掛程式的樹狀結構。 最後，外掛程式的所有二進制檔案都應該放在那個專屬資料夾中，ASF會在重新啟動後成功偵測並使用您的外掛程式。
通常外掛程式的開發人員會以zip檔的形式來發布他們的外掛程式，該檔案會具有已經為您準備好的檔案結構，因此只需將該.zip檔解壓縮至plugins資料夾中，就能自動建立適當的資料夾。
若外掛程式被成功載入，您將會在紀錄中看到它的名稱及版本。 若遇到與您使用的外掛程式相關的問題、或對程式內容或使用方式有疑問時，您應諮詢相應的外掛程式開發人員。
您可以在我們的第三方工具章節中找到一些精選的外掛程式。
請注意，ASF外掛程式可能包含惡意功能。 您應始終確保您所使用的外掛程式來自您可以信任的開發人員。 若您決定使用任何自訂外掛程式，ASF開發人員將不再保證您正常的ASF權益（例如無惡意程式或不被VAC）。 我們亦無法支援使用自訂外掛程式的設定，因為您不再執行原版的ASF程式碼。
外掛程式是標準的.NET程式庫，繼承了ASF的通用IPlugin介面。 只要API保持相容，您就可以完全獨立於主線ASF來開發外掛程式，並可以在現在及未來的ASF版本中重複使用它們。 ASF使用的外掛程式系統基於System.Composition，前稱Managed Extensibility Framework，可以使ASF在執行期間偵測並載入您的程式庫。
我們為您準備了ASF外掛程式模板，您可以把它當作您外掛程式專案的基礎。 使用模板並非強制性（因為您可以從頭開始建立），但我們強烈建議使用，因為它能夠極大加速您的開發過程，節省各種事情所需的時間。 參閱模板的README，來進一步了解詳細資訊。 不論如何，若您仍想從頭開始，或希望更理解外掛程式模板裡面所使用的概念，我們也會在接下來介紹相關基礎。
您的專案應該是一個標準.NET程式庫，以您想要的ASF版本為目標來選取適合的Framework，如編譯中所述。 我們建議您以.NET (Core)作為目標，但.NET Framework外掛程式也是可以使用的。
專案必須引用ArchiSteamFarm主程式集，或您先前下載的發布中所包含的預建置ArchiSteamFarm.dll程式庫，或原始專案（例如您決定將ASF Tree作為子模組）。 這將使您可以存取與檢查ASF的結構、方法及屬性，特別是您接下來將需要繼承的IPlugin核心介面。 專案也必須至少引用System.Composition.AttributedModel，使您能夠[Export]您的IPlugin給ASF使用。 除此之外，您可能還希望／需要引用其他公開程式庫，來解譯在某些介面中提供給您的資料結構，但除非您確實需要它們，否則現在這樣就夠了。
若您所做一切正確，您的csproj應類似於下面：
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net7.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="System.Composition.AttributedModel" IncludeAssets="compile" Version="7.0.0" />
</ItemGroup>
<ItemGroup>
<Reference Include="ArchiSteamFarm" HintPath="C:\\Path\To\Downloaded\ArchiSteamFarm.dll" />
<!-- 若要作為ASF的Source Tree建置的一部份，使用這個來取代上面的<Reference> -->
<!-- <ProjectReference Include="C:\\Path\To\ArchiSteamFarm\ArchiSteamFarm.csproj" ExcludeAssets="all" Private="false" /> -->
</ItemGroup>
</Project>從程式碼方面來說，您的外掛程式類別必須繼承自IPlugin介面（顯式，或透過例如IASF等更專門的介面來進行隱式繼承）與[Export(typeof(IPlugin))]，使ASF能在執行期間進行辨識。 達成這一點最簡單的範例如下：
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("Meow");
return Task.CompletedTask;
}
}為了使用您的外掛程式，您必須先編譯它。 您可以使用您的IDE，或在您的專案的根目錄下執行此命令來編譯：
# 若您的專案是獨立的（不需要定義它的名稱，因為它是唯一的）
dotnet publish -c "Release" -o "out"
# 若您的專案屬於ASF的Source Tree的一部份（用以防止編譯不需要的部分）
dotnet publish 您外掛程式的名稱 -c "Release" -o "out"在這之後，您的外掛程式就已準備好部署。 如何轉發及發布外掛程式完全取決於您自己，但我們建議建立一個.zip壓縮檔，其中只含有一個名為您的命名空間.您的外掛程式名稱的資料夾，並在裡面放入您已編譯好的外掛程式及它的相依程式。 這樣，使用者只需要將您的.zip解壓縮至他的plugins資料夾中即可，而不需要進行其他動作。
這只是讓您入門的最基礎情境。 我們提供外掛程式範例專案，來向您展示您在自己的外掛程式中可以實作的介面與操作的範例，及實用的註解。 若您想從工作碼中學習，或自行探索ArchiSteamFarm.Plugins命名空間，可以隨意閱覽並參考所包含的文件，以了解所有可用的選項。
若您想從真實的專案而不是從範例外掛程式中學習，可以使用我們開發的SteamTokenDumper外掛程式，該外掛程式附隨在ASF中。 除此之外，還有其他開發者開發的外掛程式，列在我們的第三方工具章節中。
除了您可以在介面中存取的內容之外，ASF還向您公開了許多您可以使用的內部API，以便擴展功能。 舉例來說，若您想向Steam網站傳送某種新請求，您不需從頭開始實作所有內容，特別是處理我們先前已處理過的所有問題。 只需使用我們的Bot.ArchiWebHandler，它已經公開了許多UrlWithSession()方法以供您使用，並已為您完成了所有的底層工作，例如身分驗證、連線階段重新整理或處理網路限制等。 同樣地，若要向Steam平台以外傳送Web請求，您可以使用標準的.NET HttpClient類別，但最好還是使用我們提供給您的Bot.ArchiWebHandler.WebBrowser，它能為您提供許多幫助，例如重試失敗的請求。
我們在API可用性的方面採取非常開放的政策，所以若您想使用ASF程式碼中已有的功能，請提出一個Issue，在裡面說明您需要使用的ASF內部API，並解釋您計劃使用的範例情境。 只要您的範例情境有意義，我們不太可能會反對。 我們根本不可能開放全部可以使用的東西，所以我們只能開放對我們來說最有意義的地方，然後等待著您的請求，來防止您需要存取尚未public的部分。 這也包含關於新的IPlugin介面的所有建議，只要用來擴展現有功能時加入它是有意義的。
實際上，ASF的內部API是您外掛程式功能的唯一限制。 因為您的外掛程式也可以擁有自己的相依程式，所以沒有什麼能夠阻止您。例如您可以在您的應用程式中加入Discord.Net程式庫，並在您的Discord Bot及ASF指令間搭起一座橋梁。 外掛程式的可能性是無限的，我們會盡最大努力為您的外掛程式提供盡可能多的自由及靈活性，因此沒有給予任何人為限制。只是我們不能完全確定哪些ASF的部分是在您外掛程式開發中所必需的（您可以經由告訴我們來解決此問題，或無須通知，您也隨時可以自行實作所需的功能）。
需要特別為您強調，ASF是一個使用者應用程式，而非一個您能無條件依賴、具有穩定API介面的程式庫。 這代表您無法假定您的外掛程式一經編譯，就能夠在未來所有的ASF版本中持續運作。若您想進一步開發程式，這將是不可能的，我們無法只為了反向相容性，就放棄去適應不斷變化的Steam。 對您來說這應該合乎邏輯，但強調這一點事實很重要。
我們會盡最大努力，保持ASF公開的部分能夠正常且穩定運作。但如果有足夠的理由，我們不會害怕去破壞相容性，並且在這個過程中，會遵循我們的棄用政策。 這對於作為ASF基礎架構的一部份公開給您的內部ASF結構來說特別重要，如上文所述（例如ArchiWebHandler），在未來某個版本中，它們可能會作為ASF增強的一部份而被改進（或因此而被重寫）。 我們將會盡最大努力在更新日誌中適當通知您，並在執行期間適時顯示與過時功能相關的警告。 我們不會故意為了重寫而重寫，因此您可以相信，下一個ASF次版更新不會只因為版本號碼增加，而讓您的外掛程式完全失效。但仍最好留意更新日誌，並偶爾驗證一切是否正常運作。
預設情形下，您的外掛程式會至少含有兩個相依套件，ArchiSteamFarm用於內部API，以及System.Composition.AttributedModel的PackageReference，這是被辨識成ASF外掛程式所必需的。 除此之外，依據您的外掛程式功能，它可能還需要更多的相依套件（例如若您決定與Discord整合，就需要Discord.Net程式庫）。
建置的輸出將包含您的您的外掛程式名稱.dll核心程式庫，及所有您引用的相依套件。 因為您是為已在運作的程式開發外掛程式，所以您不必，也不應該包含ASF已含有的相依套件，例如ArchiSteamFarm、SteamKit2或Newtonsoft.Json。 精簡與ASF共用的相依套件並不是外掛程式運作的必要措施，但這樣能使記憶體使用及外掛程式大小顯著減少，同時使效能增加，因為ASF會與您共用它自己的相依套件，並只載入那些它所不知道的程式庫。
一般而言，建議是只封裝ASF不包含的，或與ASF包含版本不同／不相容的程式庫。 明顯的範例有您的外掛程式名稱.dll；另一個範例是Discord.Net.dll，若您決定整合Discord，因ASF並不含有它，故您也需要將它封裝在內。 若您想確保API相容性，那麼與ASF共用的附隨程式庫依然有意義（例如確保您外掛程式中相依的Newtonsoft.Json永遠處於X版本，而不是ASF所提供的版本）。但顯然這樣做的代價是增加了記憶體／檔案大小，並使效能更差，因此應該要仔細評估。
若您已知您所需的相依套件已經包含在ASF中，您可以使用IncludeAssets="compile"標示它，就如上述範例csproj所示。 這將會告訴編譯器不發布被引用的程式庫，因為ASF已經將它包含在內。 同樣地，請注意我們使用了ExcludeAssets="all" Private="false"來引用ASF專案，其運作原理非常相似⸺告訴編譯器不要產生任何ASF檔案（因為使用者已經擁有它們了）。 這只在引用ASF專案時適用，因為如果您是引用dll程式庫，您不會將ASF檔案作為您外掛程式的一部份而產生出來。
若您對上述陳述感到困惑，且您無法理解，請查閱ASF-generic.zip套件中含有哪些dll程式庫，並確保您的外掛程式只包含那些尚未被包含在內的部分。 對於最簡單的外掛程式來說，這唯一一個會是您的外掛程式名稱.dll。 若您在執行期間遇到有關某些程式庫的問題，請將那些受影響的程式庫也包含在內。 若一切嘗試都失敗了，您仍可以選擇附隨所有東西。
原生相依套件是作為特定作業系統建置的一部份生成的，因為主機上沒有可用的.NET執行環境，ASF就需要經由自己的.NET執行環境來執行，該環境附隨於特定作業系統建置的一部份。 為了最小化建置的大小，ASF會修整自己的原生相依套件，只包含程式中可能用到的程式碼，這樣就會有效減少執行期間未使用到的部分。 這可能會給您的外掛程式帶來問題，若您突然發現您的外掛程式相依於ASF中未使用的某些.NET功能，特定作業系統的建置會無法正確執行它，程序通常會擲回System.MissingMethodException或System.Reflection.ReflectionTypeLoadException。
這對於Generic建置版本而言從來都不是問題，因為它們一開始就不會處理原生相依程式（因為它們在主機上擁有完整的執行環境來執行ASF）。 這也自動成為該問題的一種解決方案，將您的外掛程式只供Generic建置版本使用，但顯然這具有本身的缺點，特定作業系統建置的ASF使用者就無法使用您的外掛程式。 若您想知道您遇到的問題是否與原生相依套件有關，您也可以使用這個方法來驗證，在ASF Generic建置版本中載入您的外掛程式，並看它是否能夠運作。 如果可以，則說明您的外掛程式已有相依套件，而問題在於原生相依套件。
不幸的是，我們不得不做出一個艱難的決定：是將整個執行環境發布成適用於特定作業系統建置的一部分，或是決定刪除其未使用的功能，使得建置檔案比完整版的建置小50 MB以上。 我們選擇了後者，所以您無法讓您的外掛程式直接使用缺少的執行環境功能。 若您的專案需要存取被省略的執行環境功能，您就必須包含要相依的完整.NET執行環境，這代表您的外掛程式需要與Generic ASF版本一同執行。 You can't run your plugin in OS-specific builds, as those builds are simply missing a runtime feature that you need, and .NET runtime as of now is unable to "merge" native dependency that you could've provided with our own. Perhaps it'll improve one day in the future, but as of now it's simply not possible.
ASF's OS-specific builds include the bare minimum of additional functionality which is required to run our official plugins. Apart of that being possible, this also slightly extends the surface to extra dependencies required for the most basic plugins. Therefore not all plugins will need to worry about native dependencies to begin with - only those that go beyond what ASF and our official plugins directly need. This is done as an extra, since if we need to include additional native dependencies ourselves for our own use cases anyway, we can as well ship them directly with ASF, making them available, and therefore easier to cover, also for you. Unfortunately, this is not always enough, and as your plugin gets bigger and more complex, the likelihood of running into trimmed functionality increases. Therefore, we usually recommend you to run your custom plugins in generic ASF flavour exclusively. You can still manually verify that OS-specific build of ASF has everything that your plugin requires for its functionality - but since that changes on your updates as well as ours, it might be tricky to maintain.
