[Abp 源码分析]五、系统设置

0.简要介绍

Abp 本身有两种设置，一种就是 上一篇文章 所介绍的模块配置 Configuration，该配置主要用于一些复杂的数据类型设置，不仅仅是字符串，也有可能是一些 C# 运行时的一些变量。另外一种则是本篇文章所讲的 Setting，Setting 主要用于配置一些简单的参数，比如 SMTP 地址，数据库连接字符串等一些基本的配置类型可以使用 Setting 来进行处理。

1.代码分析

1.1 启动流程

我们先来看一下设置是怎样被加入到 Abp 框架当中，并且是如何来使用它的。

在 Abp 框架内部开发人员可以通过 ISettingsConfiguration 的 Providers 属性来添加自己实现的 SettingProvider ，而 ISettingsConfiguration 的初始化是在上一篇文章所写的 AbpBootstrapper.Initialize() 里面进行初始化的。

开发人员通过继承 SettingProvider 来提供这些设置信息，并且在模块的 PreInitialize() 方法当中通过 Configuration 来添加书写好的配置提供者。

在模块进行初始化之后(也就是在 PostInitiailze() 方法内部)，所有开发人员定义的 SettingProvider 通过 ISettingDefinitionManager 的 Initialize() 方法存储到一个 Dictionary 里面。

public sealed class AbpKernelModule : AbpModule
{
    // 其他代码
    public override void PostInitialize()
    {
        // 其他代码
        IocManager.Resolve<SettingDefinitionManager>().Initialize();
        // 其他代码
    }
}

Initialize() 方法内部：

private readonly IDictionary<string, SettingDefinition> _settings;

public void Initialize()
{
    var context = new SettingDefinitionProviderContext(this);

    foreach (var providerType in _settingsConfiguration.Providers)
    {
        using (var provider = CreateProvider(providerType))
        {
            foreach (var settings in provider.Object.GetSettingDefinitions(context))
            {
                _settings[settings.Name] = settings;
            }
        }
    }
}

对外则是通过 ISettingManager 来进行管理的。

所有的设置项是通过 ServiceProvider 来提供的。

设置的持久化配置则是通过 ISettingStore 来实现的，开发者可以通过替换 ISettingStore 的实现达到持久化到数据库或者是其他位置。

1.2 典型用法

1.2.1 设置提供者定义

internal class EmailSettingProvider : SettingProvider
{
    public override IEnumerable<SettingDefinition> GetSettingDefinitions(SettingDefinitionProviderContext context)
    {
        return new[]
               {
                   new SettingDefinition(EmailSettingNames.Smtp.Host, "127.0.0.1", L("SmtpHost"), scopes: SettingScopes.Application | SettingScopes.Tenant),
                   new SettingDefinition(EmailSettingNames.Smtp.Port, "25", L("SmtpPort"), scopes: SettingScopes.Application | SettingScopes.Tenant),
                   new SettingDefinition(EmailSettingNames.Smtp.UserName, "", L("Username"), scopes: SettingScopes.Application | SettingScopes.Tenant),
                   new SettingDefinition(EmailSettingNames.Smtp.Password, "", L("Password"), scopes: SettingScopes.Application | SettingScopes.Tenant),
                   new SettingDefinition(EmailSettingNames.Smtp.Domain, "", L("DomainName"), scopes: SettingScopes.Application | SettingScopes.Tenant),
                   new SettingDefinition(EmailSettingNames.Smtp.EnableSsl, "false", L("UseSSL"), scopes: SettingScopes.Application | SettingScopes.Tenant),
                   new SettingDefinition(EmailSettingNames.Smtp.UseDefaultCredentials, "true", L("UseDefaultCredentials"), scopes: SettingScopes.Application | SettingScopes.Tenant),
                   new SettingDefinition(EmailSettingNames.DefaultFromAddress, "", L("DefaultFromSenderEmailAddress"), scopes: SettingScopes.Application | SettingScopes.Tenant),
                   new SettingDefinition(EmailSettingNames.DefaultFromDisplayName, "", L("DefaultFromSenderDisplayName"), scopes: SettingScopes.Application | SettingScopes.Tenant)
               };
    }

    private static LocalizableString L(string name)
    {
        return new LocalizableString(name, AbpConsts.LocalizationSourceName);
    }
}

1.2.2 注入设置提供者

public sealed class AbpKernelModule : AbpModule
{
    public override void PreInitialize()
    {
        // 其他代码
        Configuration.Settings.Providers.Add<EmailSettingProvider>();
        // 其他代码
    }
}

注入之后，那么相应的模块如何得到已经注入的配置项呢？

我们拿一个最直观的例子来展示一下，这里我们来到 Abp 项目的 Email 模块，来看看它是如何使用的。

public class DefaultMailKitSmtpBuilder : IMailKitSmtpBuilder, ITransientDependency
{
    private readonly ISmtpEmailSenderConfiguration _smtpEmailSenderConfiguration;

    public DefaultMailKitSmtpBuilder(ISmtpEmailSenderConfiguration smtpEmailSenderConfiguration)
    {
        _smtpEmailSenderConfiguration = smtpEmailSenderConfiguration;
    }

    public virtual SmtpClient Build()
    {
        var client = new SmtpClient();

        try
        {
            ConfigureClient(client);
            return client;
        }
        catch
        {
            client.Dispose();
            throw;
        }
    }

    protected virtual void ConfigureClient(SmtpClient client)
    {
        client.Connect(
            _smtpEmailSenderConfiguration.Host,
            _smtpEmailSenderConfiguration.Port,
            _smtpEmailSenderConfiguration.EnableSsl
        );

        if (_smtpEmailSenderConfiguration.UseDefaultCredentials)
        {
            return;
        }

        client.Authenticate(
            _smtpEmailSenderConfiguration.UserName,
            _smtpEmailSenderConfiguration.Password
        );
    }
}

可以看到以上代码通过 ISmtpEmailSenderConfiguration 来拿到 SMTP 对应的主机名与端口号，那这与我们的 ISettingManager 又有何关系呢？

其实我们转到 ISmtpEmailSenderConfiguration 的实现 SmtpEmailSenderConfiguration 就清楚了。

public class SmtpEmailSenderConfiguration : EmailSenderConfiguration, ISmtpEmailSenderConfiguration, ITransientDependency
{
    /// <summary>
    /// SMTP Host name/IP.
    /// </summary>
    public virtual string Host
    {
        get { return GetNotEmptySettingValue(EmailSettingNames.Smtp.Host); }
    }

    /// <summary>
    /// SMTP Port.
    /// </summary>
    public virtual int Port
    {
        get { return SettingManager.GetSettingValue<int>(EmailSettingNames.Smtp.Port); }
    }

    /// <summary>
    /// User name to login to SMTP server.
    /// </summary>
    public virtual string UserName
    {
        get { return GetNotEmptySettingValue(EmailSettingNames.Smtp.UserName); }
    }

    /// <summary>
    /// Password to login to SMTP server.
    /// </summary>
    public virtual string Password
    {
        get { return GetNotEmptySettingValue(EmailSettingNames.Smtp.Password); }
    }

    /// <summary>
    /// Domain name to login to SMTP server.
    /// </summary>
    public virtual string Domain
    {
        get { return SettingManager.GetSettingValue(EmailSettingNames.Smtp.Domain); }
    }

    /// <summary>
    /// Is SSL enabled?
    /// </summary>
    public virtual bool EnableSsl
    {
        get { return SettingManager.GetSettingValue<bool>(EmailSettingNames.Smtp.EnableSsl); }
    }

    /// <summary>
    /// Use default credentials?
    /// </summary>
    public virtual bool UseDefaultCredentials
    {
        get { return SettingManager.GetSettingValue<bool>(EmailSettingNames.Smtp.UseDefaultCredentials); }
    }

    /// <summary>
    /// Creates a new <see cref="SmtpEmailSenderConfiguration"/>.
    /// </summary>
    /// <param name="settingManager">Setting manager</param>
    public SmtpEmailSenderConfiguration(ISettingManager settingManager)
        : base(settingManager)
    {

    }
}

在这里我们可以看到这些配置项其实是通过一个名字叫做 GetNotEmptySettingValue() 的方法来得到的，该方法定义在 SmtpEmailSenderConfiguration 的基类 EmailSenderConfiguration 当中。

public abstract class EmailSenderConfiguration : IEmailSenderConfiguration
{
    // 其他代码，已经省略

    /// <summary>
    /// Creates a new <see cref="EmailSenderConfiguration"/>.
    /// </summary>
    protected EmailSenderConfiguration(ISettingManager settingManager)
    {
        SettingManager = settingManager;
    }

    /// <summary>
    /// Gets a setting value by checking. Throws <see cref="AbpException"/> if it's null or empty.
    /// </summary>
    /// <param name="name">Name of the setting</param>
    /// <returns>Value of the setting</returns>
    protected string GetNotEmptySettingValue(string name)
    {
        var value = SettingManager.GetSettingValue(name);

        if (value.IsNullOrEmpty())
        {
            throw new AbpException($"Setting value for '{name}' is null or empty!");
        }

        return value;
    }
}

总而言之，如果你想要获取已经添加好的设置项，直接注入 ISettingManager 通过其 GetSettingValue() 就可以拿到这些设置项。

1.3 具体代码分析

Abp 系统设置相关的最核心的部分就是 ISettingManager、ISettingDefinitionManager、ISettingStore，SettingProvider、SettingDefinition 下面就这几个类进行一些细致的解析。

1.3.1 SettingDefinition

在 Abp 当中，一个设置项就是一个 SettingDefinition，每个 SettingDefinition 的 Name 与 Value 是必填的，其中 Scopes 字段对应一个 SettingScopes 枚举，该属性用于确定这个设置项的使用应用范围。

public class SettingDefinition
{
    /// <summary>
    /// Unique name of the setting.
    /// </summary>
    public string Name { get; private set; }

    /// <summary>
    /// Display name of the setting.
    /// This can be used to show setting to the user.
    /// </summary>
    public ILocalizableString DisplayName { get; set; }

    /// <summary>
    /// A brief description for this setting.
    /// </summary>
    public ILocalizableString Description { get; set; }

    /// <summary>
    /// Scopes of this setting.
    /// Default value: <see cref="SettingScopes.Application"/>.
    /// </summary>
    public SettingScopes Scopes { get; set; }

    /// <summary>
    /// Is this setting inherited from parent scopes.
    /// Default: True.
    /// </summary>
    public bool IsInherited { get; set; }

    /// <summary>
    /// Gets/sets group for this setting.
    /// </summary>
    public SettingDefinitionGroup Group { get; set; }

    /// <summary>
    /// Default value of the setting.
    /// </summary>
    public string DefaultValue { get; set; }

    /// <summary>
    /// Can clients see this setting and it's value.
    /// It maybe dangerous for some settings to be visible to clients (such as email server password).
    /// Default: false.
    /// </summary>
    [Obsolete("Use ClientVisibilityProvider instead.")]
    public bool IsVisibleToClients { get; set; }

    /// <summary>
    /// Client visibility definition for the setting.
    /// </summary>
    public ISettingClientVisibilityProvider ClientVisibilityProvider { get; set; }

    /// <summary>
    /// Can be used to store a custom object related to this setting.
    /// </summary>
    public object CustomData { get; set; }
    
    public SettingDefinition(
            string name,
            string defaultValue,
            ILocalizableString displayName = null,
            SettingDefinitionGroup group = null,
            ILocalizableString description = null,
            SettingScopes scopes = SettingScopes.Application,
            bool isVisibleToClients = false,
            bool isInherited = true,
            object customData = null,
            ISettingClientVisibilityProvider clientVisibilityProvider = null)
    {
        if (string.IsNullOrEmpty(name))
        {
            throw new ArgumentNullException(nameof(name));
        }

        Name = name;
        DefaultValue = defaultValue;
        DisplayName = displayName;
        Group = @group;
        Description = description;
        Scopes = scopes;
        IsVisibleToClients = isVisibleToClients;
        IsInherited = isInherited;
        CustomData = customData;

        ClientVisibilityProvider = new HiddenSettingClientVisibilityProvider();

        if (isVisibleToClients)
        {
            ClientVisibilityProvider = new VisibleSettingClientVisibilityProvider();
        }
        else if (clientVisibilityProvider != null)
        {
            ClientVisibilityProvider = clientVisibilityProvider;
        }
    }
}

1.3.2 ISettingManager

首先我们看一下 ISettingManager 的默认实现 SettingManager。

public class SettingManager : ISettingManager, ISingletonDependency
{
    public const string ApplicationSettingsCacheKey = "ApplicationSettings";

    /// <summary>
    /// Reference to the current Session.
    /// </summary>
    public IAbpSession AbpSession { get; set; }

    /// <summary>
    /// Reference to the setting store.
    /// </summary>
    public ISettingStore SettingStore { get; set; }

    private readonly ISettingDefinitionManager _settingDefinitionManager;
    private readonly ITypedCache<string, Dictionary<string, SettingInfo>> _applicationSettingCache;
    private readonly ITypedCache<int, Dictionary<string, SettingInfo>> _tenantSettingCache;
    private readonly ITypedCache<string, Dictionary<string, SettingInfo>> _userSettingCache;

    /// <inheritdoc/>
    public SettingManager(ISettingDefinitionManager settingDefinitionManager, ICacheManager cacheManager)
    {
        _settingDefinitionManager = settingDefinitionManager;

        AbpSession = NullAbpSession.Instance;
        SettingStore = DefaultConfigSettingStore.Instance;

        _applicationSettingCache = cacheManager.GetApplicationSettingsCache();
        _tenantSettingCache = cacheManager.GetTenantSettingsCache();
        _userSettingCache = cacheManager.GetUserSettingsCache();
    }
}

可以看到在这里面，他注入了 ISetingStore 与 ISettingDefinitionManager ，并且使用了三个 ITypedCache 来为这些设置进行一个缓存。

下面这个 GetSettingValueAsync() 方法则是获取一个指定名称的设置值。

public Task<string> GetSettingValueAsync(string name)
{
    return GetSettingValueInternalAsync(name, AbpSession.TenantId, AbpSession.UserId);
}

private async Task<string> GetSettingValueInternalAsync(string name, int? tenantId = null, long? userId = null, bool fallbackToDefault = true)
{
    // 获取指定 Name 的 SettingDefine
    var settingDefinition = _settingDefinitionManager.GetSettingDefinition(name);

    // 判断该设置项的使用范围是否为 User
    if (settingDefinition.Scopes.HasFlag(SettingScopes.User) && userId.HasValue)
    {
        var settingValue = await GetSettingValueForUserOrNullAsync(new UserIdentifier(tenantId, userId.Value), name);
        if (settingValue != null)
        {
            return settingValue.Value;
        }

        if (!fallbackToDefault)
        {
            return null;
        }

        if (!settingDefinition.IsInherited)
        {
            return settingDefinition.DefaultValue;
        }
    }

    // 判断该设置项的使用范围是否为 Tenant
    if (settingDefinition.Scopes.HasFlag(SettingScopes.Tenant) && tenantId.HasValue)
    {
        var settingValue = await GetSettingValueForTenantOrNullAsync(tenantId.Value, name);
        if (settingValue != null)
        {
            return settingValue.Value;
        }

        if (!fallbackToDefault)
        {
            return null;
        }

        if (!settingDefinition.IsInherited)
        {
            return settingDefinition.DefaultValue;
        }
    }

    // 判断该设置项的使用范围是否为 Application
    if (settingDefinition.Scopes.HasFlag(SettingScopes.Application))
    {
        var settingValue = await GetSettingValueForApplicationOrNullAsync(name);
        if (settingValue != null)
        {
            return settingValue.Value;
        }

        if (!fallbackToDefault)
        {
            return null;
        }
    }

    // 如果都没有定义，则返回默认的设置值
    return settingDefinition.DefaultValue;
}

这里又为每个判断内部封装了一个方法，这里以 GetSettingValueForApplicationOrNullAsync() 为例，转到其定义：

private async Task<SettingInfo> GetSettingValueForApplicationOrNullAsync(string name)
{
    return (await GetApplicationSettingsAsync()).GetOrDefault(name);
}

private async Task<Dictionary<string, SettingInfo>> GetApplicationSettingsAsync()
{
    // 从缓存当中获取设置信息，如果不存在，则执行其工厂方法
    return await _applicationSettingCache.GetAsync(ApplicationSettingsCacheKey, async () =>
    {
        var dictionary = new Dictionary<string, SettingInfo>();
        
        // 从 ISettingStore 当中获取对应的 Value 值
        var settingValues = await SettingStore.GetAllListAsync(null, null);
        foreach (var settingValue in settingValues)
        {
            dictionary[settingValue.Name] = settingValue;
        }

        return dictionary;
    });
}

1.3.3 ISettingDefinitionManager

这个管理器作用最开始已经说明了，就是单纯的获取到用户注册到 Providers 里面的 SettingDefinition。

1.3.4 SettingProvider

SettingProvider 用于开发人员配置自己的配置项，所有的设置提供者只需要继承自本类，实现其 GetSettingDefinitions 方法即可。

1.3.5 ISettingStore

本类用于设置项值的存储，其本身并不做设置项的新增，仅仅是相同的名称的设置项，优先从 ISettingStore 当中进行获取，如果不存在的话，才会使用开发人员在 SettingProvider 定义的值。

Abp 项目默认的 DefaultConfigSettingStore 实现并不会进行任何实质性的操作，只有 Zero.Common 项目当中重新实现的 SettingStore 类才是针对这些设置的值进行了持久化操作。

2.扩展：Abp.MailKit 模块配置

如果要在 .NetCore 环境下面使用邮件发送的话，首先推荐的就是 MailKit 这个库，而 Abp 针对 MailKit 库封装了一个新的模块，叫做 Abp.MailKit ，只需要进行简单的设置就可以发送邮件了。

在需要使用的模块上面添加：

[DependsOn(typeof(AbpMailKitModule))]
public class TestModule : AbpModule
{
    // 其他代码
}

之后需要自己定义一个 SettingProvider 并且在里面做好 SMTP 发件服务器配置：

public class DevEmailSettings : SettingProvider
{
    public override IEnumerable<SettingDefinition> GetSettingDefinitions(SettingDefinitionProviderContext context)
    {
            return new[]
            {
                // smtp 服务器地址
                new SettingDefiniion(EmailSettingNames.Smtp.Host, "smtpserver"),
                // smtp 用户名称
                new SettingDefinition(EmailSettingNames.Smtp.UserName, "yourusername"),
                // smtp 服务端口
                new SettingDefinition(EmailSettingNames.Smtp.Port, "25"),
                // smtp 用户密码
                new SettingDefinition(EmailSettingNames.Smtp.Password, "yourpassword"),
                // 发件人邮箱地址
                new SettingDefinition(EmailSettingNames.DefaultFromAddress, "youremailaddress"),
                // 是否启用默认验证
                new SettingDefinition(EmailSettingNames.Smtp.UseDefaultCredentials,"false")
        };
    }
}

然后在之前的模块预加载当中添加这个 Provider 到全局设置当中：

[DependsOn(typeof(AbpMailKitModule))]
public class TestModule : AbpModule
{
    public override void PreInitialize()
    {
        Configuration.Settings.Providers.Add<DevEmailSettings>();
    }
}

发送邮件十分简单，直接在需要使用的地方注入 IEmailSender 调用其 Send 或者 SendAsync 方法即可，下面是一个例子：

public class TestApplicationService : ApplicationService
{
    private readonly IEmailSender _emailSender;
    
    public TestApplicationService(IEmailSender emailSender)
    {
        _emailSender = emailSender;
    }
    
    public Task TestMethod()
    {
        _emailSender.Send("[email protected]","无主题","测试正文",false);
        return Task.FromResult(0);
    }
}