ABP框架 - 设置管理

文档目录

本节内容：

• 简介
  • 关于ISettingStore
• 定义设置
  • setting scope（设置范围）
  • 重写设置定义
• 获取设置值
  • 服务端
  • 客户端
• 修改设置
• 关于缓存

简介

每个应用必需存储一些设置，并在应用里的某处使用它。ABP提供一个强大的基础来存储/获取应用、租户和用户级别的设置，服务端与客户端都可以。

一个设置是一对name-value字符串，通常存储在数据库（或其它源）。我们可以把不是字符串类的值，转换成字符串后存储。

关于 ISettingStore

为使用设置系统,必须实现ISettingStore接口。虽然你能用自己的方式实现它，不过在module-zero项目里已经完全实现。如果不实现它，会从配置文件（web.config或app.config）中读取设置，但不能修改设置。同样，scope不能工作。

定义设置

设置在用前需要先定义，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（必需）：一个设置必须有一个系统范围内唯一的名称，最好定义成一个常量，而不是可变的字符串。
• Default value：有一个默认值，可以是null或“”。
• Scope：一个设置应该有它的Scope（见下方）。
• Display name:一个显示在UI上的本地化名称字符串。
• Description：一个显示在UI上的本地化描述字符串
• Group：只用在UI上，不在设置管理里使用，用来群组设置。
• IsVisibleToClients：设为true使客户端上的设置可用。
• isInherited：这个设置是否被租户和用户继承（见“设置 scope”）。
• customData：为这个定义设置一个用户数据。

在创建一个设置供应器后，我们应该为我们的模块，在预初始化方法里注册它。

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

设置供应器会自动被依赖注入所注册，所以一个设置供应器可以注入任何依赖（如一个仓储），以用途其它源建立设置定义。

setting scope（设置范围）

在SettingScopes枚举里，有三个设置范围（或级别）：

• Application:一个应用范围的设置，用在用户/租户的独立设置。例如，我们可以定义一个名为“SmtpServerAddress”，在发送邮件时，获取服务器Ip地址。如果这个设置有个单一值（不是基于用户而变），我们就可以把它定义为应用范围。
• Tenant：如果应用多租户，我们可以定义指定租户的设置。
• User：我们可以使用一个用户范围的设置来存储/获取每个用户指定设置的值。

SettingScopes枚举有Flags（标志）特性，所以我们可以用多个范围（级别）定义一个设置。

设置范围在默认情况下是有继承关系的（除非你设置了isInherited为false）。例如，我们定义一个设置范围为“Application | Tenant | user” 然后尝试获取设置的当前值：

• 如果它定义（重写）为user，我们就获取特定User的值。
• 如果不是，如果它定义（重写）为tanant，我们就获取特定Tenant的值。
• 如果不是，如果已定义，我们获取Application值。
• 如果不是，我们获取默认值。

默认值可能是null或“”。建议为设置尽可能地提供默认值。

重写设置定义

context.Manager可获取一个设置定义，并修改它的值，这种方式，可以操作依赖模块的设置定义。

获取设置值

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

服务端

ISettingManager用来执行设置操作，我们可在应用的任何地方注入并使用它。ISettingManager定义了许多获取一个设置的值的方法。

常用的方法是GetSettingValue（或异常GetSettingValueAsync），获取设置基于范围级别（Application，Tenant，User）的当前值（如前面所述），例如：

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

//Getting a string value (sync call)
var value2 = SettingManager.GetSettingValue("SmtpServerAddress");

GetSetrtingValue有泛型和异常版本，如上所述。当然也有方法能获取一个指定租户或用户的设置值或所有值列表。

由于广泛地使用了ISettingManager，一些特殊的基类（如ApplicationService，DomainService和AppController）有一个SettingManager属性。如果你从这些类继承，就不再需要显式注入ISettingManager。

客户端

如果你在定义一个设置时，把IsVisibleToClicents设为true，那么你可以在客户端使用Javascript获取它的当前值。abp.setting命名空间定义了所需的函数和对象，例如：

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

同样还有getInt和getBoolean方法，你可以使用abp.setting.values对象获取所有值。注意：如果你在服务端修改一个设置，除非刷新页面、以某种方式重新载入设置和用手工代码更新，否则客户端不会知道这个修改。

修改设置

ISetingManager定义了ChangeSettingForApplicationAsync，ChangeSettingForTenantAsync和ChangeSettingForUserAsync（和同步版）方法，分别为一个应用，一个租户和一个用户修改设置。

关于缓存

设置管理的缓存在服务端设置，所以我们不应该直接用仓储或数据库更新查询来修改一个设置。