2.5 ABP公共结构 - 设置管理

2.5.1 简介

每个应用程序需要存储一些设置并在应用程序的某个地方使用这些设置。ABP框架提供强大的基础架构，我们可以在服务端或者客户端设置，来存储/获取应用程序、 租户和用户级别的配置。

设置通常是存储在数据库（或另一个来源）中，用名称-值（name-value）字符串对应的结构来表示。我们可以把非字符串值转换成字符串值来存储。

注意：关于ISettingStore接口:为了使用设置管理必须实现 ISettingStore 接口。你可以用自己的方式实现它，在module-zero项目中有完整的实现可以参考。

关于ISettingStore

该ISettingStore接口必须以使用设置系统来实现。 虽然您可以以自己的方式实现它，但它完全在Module Zero项目中实现。如果未实现，则从应用程序的配置文件（web.config或app.config）中读取设置，但不能更改这些设置。范围界定也不起作用。

2.5.2 定义设置

使用设置之前必须要先定义。ABP框架是模块化设计，所以不同的模块可以有不同的设置。为了定义模块自己的设置，每个模块都应该创建继承自 SettingProvider 的派生类。设置提供程序示例如下所示：

public class MySettingProvider : SettingProvider
{
    public override IEnumerable<SettingDefinition> GetSettingDefinitions(SettingDefinitionProviderContext context)
    {
        return new[]
                {
                    new SettingDefinition(
                        "SmtpServerAddress",
                        "127.0.0.1"
                        ),

                    new SettingDefinition(
                        "PassiveUsersCanNotLogin",
                        "true",
                        scopes: SettingScopes.Application | SettingScopes.Tenant
                        ),

                    new SettingDefinition(
                        "SiteColorPreference",
                        "red",
                        scopes: SettingScopes.User,
                        isVisibleToClients: true
                        )

                };
    }
}

GetSettingDefinitions 方法返回 SettingDefinition 对象。SettingDefinition 类的构造函数中有如下参数：

  • Name (必填):必须具有全系统唯一的名称。比较好的办法是定义字符串常量来设置Name。

  • Default value: 设置一个默认值。此值可以是null 或空字符串。

  • Scopes: 定义设置的范围 (见下文)。

  • Display name: 一个可本地化的字符串，用于以后在UI中显示设置的名称。

  • Description: 一个可本地化的字符串，用于以后在UI中显示设置的描述。

  • Group: 可用于设置组。这仅仅是UI使用，不用于设置管理。

  • IsVisibleToClients: 设置为 true 将使设置在客户端可用。

  • isInherited: 用于设置，如果该设置继承了tenant或者用户(参照设置范围章节)。

  • customData: 可以用来设置自定义数据对于该定义的设置。

在创建设置提供程序(SettingProvider)之后，我们应该在预初始化(PreIntialize)方法中注册我们的模块:

Configuration.Settings.Providers.Add<MySettingProvider>();

设置提供程序会自动注册依赖注入。所以，设置提供程序可以注入任何依赖项 (如存储库) 来生成设置定义的一些其它来源。

2.5.3 设置范围

有三个设置范围 (或级别) 在 SettingScopes 枚举中定义:

  • Application：应用程序范围设置用于用户/租户独立的设置。例如，我们可以定义一个名为"SmtpServerAddress"的设置，当发送电子邮件时，获取服务器的 IP 地址。如果此设置有一个单一的值 (不基于用户改变)，那么我们可以定义它为应用程序范围。

  • Tenant：如果应用程序是多租户的，我们可以定义特定于租户的设置。

  • User：我们可以使用的用户范围的设置来为每个用户存储/获取设置的值。

SettingScopes 枚举具有Flags属性，所以我们可以定义一个具有多个作用域的设置。

设置范围是分层的。例如，如果我们定义设置范围为"Application | Tenant | User"并尝试获取当前设置的值;

我们获取特定用户的值，如果它定义了 (重写) User;如果没有定义User，我们获取特定的租户值，如果它定义了 (重写) Tenant。如果也没有，我们获取应用的值，如果它定义了Application。如果还是没有，我们得到的默认值。

默认值可以是 null 或空字符串。如果可以，建议为设置提供一个默认值。

2.5.4 重写定义的设置

context.Manager 可以用来取得某个定义的设置并更改它的值。你可以使用这种方式来操控依赖模块的定义的设置。

2.5.5 获取设置值

定义设置后，我们可以在服务器和客户端获取到它的当前值。

1. 服务器端(Server side)

ISettingManager 用于执行设置操作。我们可以在应用程序中任何地方注入和使用它。ISettingManager 定义了很多获取设置值方法。

最常用的方法是 GetSettingValue (或GetSettingValueAsync 为异步调用)。它将返回当前设置的基于默认值、 应用程序、 租户和用户设置范围的值(如设置范围之前的一段中所述)。例子:

//Getting a boolean value (async call)
var value1 = await SettingManager.GetSettingValueAsync<bool>("PassiveUsersCanNotLogin");
//Getting a string value (sync call)
var value2 = SettingManager.GetSettingValue("SmtpServerAddress");

GetSettingValue 有泛型和异步版本，如上所示。也有方法来获取特定的租户或用户的设置值或所有设置值的列表。

由于ISettingManager使用广泛，一些特定的基类 (如 ApplicationService、 DomainService 和 AbpController) 有一个名为 SettingManager的属性。如果我们从这些类继承，就无需显式地注入它。

ISettingDefinitionManager

也ISettingDefinitionManager可用于获取定义的设置定义AppSettingProvider。我们也可以在应用程序的任何地方注入和使用它。您可以使用获取定义名称，默认值，显示名称等ISettingDefinitionManager。

2. 客户端(Client side)

  • VisibleSettingClientVisibilityProvider：使设置定义对客户端可见。
  • HiddenSettingClientVisibilityProvider：使设置定义对客户端可见。
  • RequiresAuthenticationSettingClientVisibilityProvider：如果用户已登录，则使设置定义对客户端可见。
  • RequiresPermissionSettingClientVisibilityProvider：如果登录用户具有特定权限，则使设置定义对客户端可见。

如果定义设置时将 IsVisibleToClients 设置为 true，就可以在客户端使用 javascript得到它的当前值。abp.setting 命名空间定义所需的函数和对象。示例:

var currentColor = abp.setting.get("SiteColorPreference");

也有 getInt 和 getBoolean 这样的方法。你可以使用 abp.setting.values 对象获取所有值。请注意，如果你在服务器端更改设置，客户端不会知道这种变化，除非刷新页面或者以某种方式重新加载页面或者通过代码手动更新。

3. 更改设置

ISettingManager定义了ChangeSettingForApplicationAsync，ChangeSettingForTenantAsync 和 ChangeSettingForUserAsync 方法（以及同步版本）来更改应用程序，租户和用户分别的设置。

4. 关于缓存

Setting Manager会在服务器端缓存设置，所以，我们不应直接使用存储库或数据库更新语句改变设置的值。

（2.1、2.2由半冷翻译，2.3由天道翻译，2.4由李伟翻译）