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

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("xxxxxx@qq.com","无主题","测试正文",false);
        return Task.FromResult(0);
    }
}

3.点此跳转到总目录