[OpenMod]插件的配置

搬运自OpenMod官网，经过翻译，可能有些不足，欢迎指正！原文链接

配置

配置文件允许用户配置和自定义插件行为。

假设你的插件在杀死玩家时提供XP。通过使用configs，用户可以动态地设置XP的数量。

OpenMod配置基于Microsoft.Extensions.Configuration也用于ASP.NET Core。

plugins.csproj文件中的<RootNamespace>和<AssemblyName>属性必须相等，否则IConfiguration服务将无法工作。

添加config.yaml

创建名为“config.yaml”的新文件在项目的根目录中。

之后，将以下内容添加到.csproj文件中：

<ItemGroup>
  <EmbeddedResource Include="config.yaml" />
</ItemGroup>

如果您使用其中一个模板创建插件项目，comfig.yaml文件将已被创建。

从配置文件读取

您可以使用IConfiguration服务读取config.yaml文件。你可以这样注入：

public class MyPlugin : OpenModUniversalPlugin
{
    private readonly IConfiguration m_Configuration; 
 
     public MyPlugin(IConfiguration configuration, IServiceProvider serviceProvider) : base(serviceProvider)
    {
        m_Configuration = configuration;
    }
    public async Task OnLoadAsync()
    {
       // ...
    }
}

假设您的配置如下所示：

plugin_load_delay: 500

那么这就是如何读取值：

public async Task OnLoadAsync(){
  var delay = m_Configuration.GetSection("plugin_load_delay").Get<int>();
  await Task.Delay(delay);
}

也可以有嵌套值：

plugin_load:
  actions:
    wait_delay: 500

——————————————————————————————————————————

public async Task OnLoadAsync(){  // 注意如何使用":"来访问嵌套值
  var delay = m_Configuration.GetSection("plugin_load:actions:wait_delay").Get<int>();
  await Task.Delay(delay);
}

如果要访问字符串，还可以使用索引器：

players:
  owner: "Trojaner"

——————————————————————————————————————————

public async Task OnLoadAsync(){  // 读字符串更容易
  string owner = m_Configuration["players:owner"];
}

配置文件并不意味着存储数据，这就是为什么没有setter或save方法。如果需要存储和加载数据，请参阅持久性。

不要缓存从配置中读取的数据。这将中断配置文件的动态重新加载。

将配置转换为C#类

public async Task OnLoadAsync()
{
  var config = new MyConfigClass();  
  m_Configuration.Bind(config);
  // 或者只想绑定一个子集:
  // m_Configuration.GetSection("某物").Bind(config);
}

您可以在这里缓存config变量，如果配置重新加载，bind将自动更新这些值。

监听配置更改

要监听更改，可以使用更改令牌。

获取配置的重新加载令牌：

var changeToken = m_Configuration.GetReloadToken();

添加新的事件侦听器：

var listener = ChangeToken.OnChange(() => reloadToken, () =>
{
    m_Logger.LogInformation("配置文件已重新加载！");
})

你可以用listener.Dispose()停止侦听。

不要使用配置更改侦听器获取最新的配置值。OpenMod会自动执行此操作。IConfiguration.Get将始终返回当前配置值。

添加您自己的配置源

您可以通过实现IConfigurationConfigurator接口来添加其他配置源。

此接口允许您向构建OpenMod config时使用的IConfigurationBuilder添加其他源。

目前尚不支持插件的自定义配置源。

最佳例子

不要硬编码重要值。如果你正在制作一个插件，让玩家在杀死其他玩家时获得XP值，那么请确保XP值是可配置的，因为这是许多用户可能想要调整的。

不要使配置过于复杂。只添加用户可能会更改的值。简单的配置比复杂的配置更可取。

不要对可自定义的消息使用配置，请改用本地化。与配置不同，本地化支持格式化和传递参数。