ABP框架 - 设置管理

时间:2023-03-08 17:25:09
ABP框架 - 设置管理

文档目录

本节内容:

简介

每个应用必需存储一些设置,并在应用里的某处使用它。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(和同步版)方法,分别为一个应用,一个租户和一个用户修改设置。

关于缓存

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