From 24e12207f04a40354493e90b1563260a3c895a6e Mon Sep 17 00:00:00 2001 From: liangshiwei Date: Wed, 13 Nov 2019 22:47:24 +0800 Subject: [PATCH] Translate Settings document --- docs/en/Settings.md | 2 +- docs/zh-Hans/Configuration.md | 3 + docs/zh-Hans/CurrentUser.md | 3 + docs/zh-Hans/Modules/Setting-Management.md | 3 + docs/zh-Hans/Options.md | 3 + docs/zh-Hans/Settings.md | 180 +++++++++++++++++++++ docs/zh-Hans/docs-nav.json | 13 +- 7 files changed, 204 insertions(+), 3 deletions(-) create mode 100644 docs/zh-Hans/Configuration.md create mode 100644 docs/zh-Hans/CurrentUser.md create mode 100644 docs/zh-Hans/Modules/Setting-Management.md create mode 100644 docs/zh-Hans/Options.md create mode 100644 docs/zh-Hans/Settings.md diff --git a/docs/en/Settings.md b/docs/en/Settings.md index 5a5616a71a..35c5e2112f 100644 --- a/docs/en/Settings.md +++ b/docs/en/Settings.md @@ -171,7 +171,7 @@ While a setting value provider is free to use any source to get the setting valu `ISettingEncryptionService` is used to encrypt/decrypt setting values when `IsEncrypted` property of a setting definition was set to `true`. -You can replace this service in the dependency injection system to customize the encryption/decryption process. Default implementation uses the `IStringEncryptionService` which is implemented with the AES algorithm by default (see string [encryption document](String-Encryption.md) for more). +You can replace this service in the dependency injection system to customize the encryption/decryption process. Default implementation uses the `StringEncryptionService` which is implemented with the AES algorithm by default (see string [encryption document](String-Encryption.md) for more). ## Setting Management Module diff --git a/docs/zh-Hans/Configuration.md b/docs/zh-Hans/Configuration.md new file mode 100644 index 0000000000..9d40af46c0 --- /dev/null +++ b/docs/zh-Hans/Configuration.md @@ -0,0 +1,3 @@ +# 配置 + +ASP.NET Core 提供了一个灵活可扩展,基于键值的配置系统. 但是配置系统独立于ASP.NET Core是`Microsoft.Extensions` 类库的部分. 它可以用于任何类型的应用程序 . 参见 [微软文档](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/) 学习配置的更多内容. ABP 框架与配置系统百分百兼容. \ No newline at end of file diff --git a/docs/zh-Hans/CurrentUser.md b/docs/zh-Hans/CurrentUser.md new file mode 100644 index 0000000000..b240a4421d --- /dev/null +++ b/docs/zh-Hans/CurrentUser.md @@ -0,0 +1,3 @@ +# Current User + +TODO! \ No newline at end of file diff --git a/docs/zh-Hans/Modules/Setting-Management.md b/docs/zh-Hans/Modules/Setting-Management.md new file mode 100644 index 0000000000..97e8c2f3e1 --- /dev/null +++ b/docs/zh-Hans/Modules/Setting-Management.md @@ -0,0 +1,3 @@ +# Setting Management Module + +TODO \ No newline at end of file diff --git a/docs/zh-Hans/Options.md b/docs/zh-Hans/Options.md new file mode 100644 index 0000000000..a5206bce91 --- /dev/null +++ b/docs/zh-Hans/Options.md @@ -0,0 +1,3 @@ +# Options + +TODO! diff --git a/docs/zh-Hans/Settings.md b/docs/zh-Hans/Settings.md new file mode 100644 index 0000000000..7b5d7fbd35 --- /dev/null +++ b/docs/zh-Hans/Settings.md @@ -0,0 +1,180 @@ +# Settings + +[配置系统](Configuration.md) 是在启动时配置应用程序很好的方式. 除了配置之外, ABP提供了另外一种设置和获取应用程序设置的方式. + +设置存储在动态数据源(通常是数据库)中的键值对. 设置系统预构建了用户,租户,全局和默认设置方法并且可以进行扩展. + +## 定义设置 + +使用设置之前需要定义它. ABP是 [模块化](Module-Development-Basics.md)的, 不同的模块可以拥有不同的设置. 模块中派生 `SettingDefinitionProvider` 类定义模块内的配置. 示例如下: + +````csharp +public class EmailSettingProvider : SettingDefinitionProvider +{ + public override void Define(ISettingDefinitionContext context) + { + context.Add( + new SettingDefinition("Smtp.Host", "127.0.0.1"), + new SettingDefinition("Smtp.Port", "25"), + new SettingDefinition("Smtp.UserName"), + new SettingDefinition("Smtp.Password", isEncrypted: true), + new SettingDefinition("Smtp.EnableSsl", "false") + ); + } +} +```` + +ABP会自动发现并注册设置的定义. + +### SettingDefinition + +`SettingDefinition` 类具有以下属性: + +* **Name**: 应用程序中设置的唯一名称. 是**具有约束的唯一属性**, 在应用程序获取/设置此设置的值 (设置名称定义为常量而不是`magic`字符串是个好主意). +* **DefaultValue**: 设置的默认值. +* **DisplayName**: 本地化的字符串,用于在UI上显示名称. +* **Description**: 本地化的字符串,用于在UI上显示描述. +* **IsVisibleToClients**: 布尔值,表示此设置是否在客户端可用. 默认为false,避免意外暴漏内部关键设置. +* **IsInherited**: 布尔值,此设置值是否从其他提供程序继承. 如果没有为请求的提供程序设置设定值,那么默认值是true并回退到下一个提供程序 (参阅设置值提供程序部分了解更多). +* **IsEncrypted**: 布尔值,表示是否在保存值是加密,读取时解密. 在数据库中存储加密的值. +* **Providers**: 限制可用于特定的设置值提供程序(参阅设置值提供程序部分了解更多). +* **Properties**: 设置此值的自定义属性 名称/值 集合,可以在之后的应用程序代码中使用. + +## 读取设置值 + +### ISettingProvider + +`ISettingProvider` 用于获取指定设置的值或所有设置的值. 示例用法: + +````csharp +public class MyService +{ + private readonly ISettingProvider _settingProvider; + + //Inject ISettingProvider in the constructor + public MyService(ISettingProvider settingProvider) + { + _settingProvider = settingProvider; + } + + public async Task FooAsync() + { + //Get a value as string. + string userName = await _settingProvider.GetOrNullAsync("Smtp.UserName"); + + //Get a bool value and fallback to the default value (false) if not set. + bool enableSsl = await _settingProvider.GetAsync("Smtp.EnableSsl"); + + //Get a bool value and fallback to the provided default value (true) if not set. + bool enableSsl = await _settingProvider.GetAsync( + "Smtp.EnableSsl", defaultValue: true); + + //Get a bool value with the IsTrueAsync shortcut extension method + bool enableSsl = await _settingProvider.IsTrueAsync("Smtp.EnableSsl"); + + //Get an int value or the default value (0) if not set + int port = (await _settingProvider.GetAsync("Smtp.Port")); + + //Get an int value or null if not provided + int? port = (await _settingProvider.GetOrNullAsync("Smtp.Port"))?.To(); + } +} +```` + +> `ISettingProvider` 是非常常用的服务,一些基类中(如`IApplicationService`)已经将其属性注入. 这种情况下可以直接使用`SettingProvider`. + +### 在客户端读取设置值 + +如果允许在客户端显示某个设置,可以使用 JavaScript 代码读取设置值. 示例: + +````js +//Gets a value as string. +var language = abp.setting.get('Abp.Localization.DefaultLanguage'); + +//Gets an integer value. +var requiredLength = abp.setting.getInt('Abp.Identity.Password.RequiredLength'); + +//Gets a boolean value. +var requireDigit = abp.setting.getBoolean('Abp.Identity.Password.RequireDigit'); +```` + +使用 `abp.setting.values` 可以读取所有设置值的字典. + +## 设置值提供程序 + +设置系统是可扩展的, 你可以定义设置值提供程序扩展它,根据任何条件从任何来源获取设置值. + +`ISettingProvider` 使用设置值提供程序来获取设置值. 如果值提供程序无法获取设置值,则会回退到下一个值提供程序. + +有五个预构建设置值提供程序按以下顺序注册: + +* `DefaultValueSettingValueProvider`: 从设置定义的默认值中获取值(参见上面的SettingDefinition部分). +* `ConfigurationSettingValueProvider`: 从[IConfiguration服务](Configuration.md)中获取值. +* `GlobalSettingValueProvider`: 获取设置的全局(系统范围)值. +* `TenantSettingValueProvider`: 获取当前租户的设置值(参阅 [多租户](Multi-Tenancy.md)文档). +* `UserSettingValueProvider`: 获取当前用户的设置值(参阅 [当前用户](CurrentUser.md) 文档). + +> 设置回退系统从底部 (用户) 到 (默认) 方向起用用. + +全局,租户和用户设置值提供程序使用 `ISettingStore` 从数据源读取值(参见下面的小节). + +### 自定义设置值提供程序 + +扩展设置系统的方式是定义一个派生自 `SettingValueProvider` 的类. 示例: + +````csharp +public class CustomSettingValueProvider : SettingValueProvider +{ + public override string Name => "Custom"; + + public CustomSettingValueProvider(ISettingStore settingStore) + : base(settingStore) + { + } + + public override Task GetOrNullAsync(SettingDefinition setting) + { + /* Return the setting value or null + Use the SettingStore or another data source */ + } +} +```` + +> 或者你直接可以实现 `ISettingValueProvider` 接口. 这时需要记得将其注册到 [依赖注入](Dependency-Injection.md). + +每一个提供程序都应该具有唯一的名称 (这里的名称是 "Custom" ). 内置提供程序使用给定的名称: + +* `DefaultValueSettingValueProvider`: "**D**". +* `ConfigurationSettingValueProvider`: "**C**". +* `GlobalSettingValueProvider`: "**G**". +* `TenantSettingValueProvider`: "**T**". +* `UserSettingValueProvider`: "**U**". + +最好使用一个字母的名称来减少数据库中的数据大小(提供者名称在每行中重复). + +定义自定义设置值提供程序后,需要将其显式注册到 `AbpSettingOptions`: + +````csharp +Configure(options => +{ + options.ValueProviders.Add(); +}); +```` + +本示例将其添加到最后一项,因此它将成为`ISettingProvider`使用的第一个值提供程序. 你也可以将其添加到`options.ValueProviders`列表的另一个位置. + +### ISettingStore + +尽管设置值提供程序可以自由使用任何来源来获取设置值,但 `ISettingStore` 服务是设置值的默认来源. 全局,租户和用户设置值提供者都使用它. + +## ISettingEncryptionService + +`ISettingEncryptionService` 用于在设置定义的 `isencryption` 属性设置为 `true` 时加密/解密设置值. + +你可以在依赖项入系统中替换此服务,自定义实现加密/解密过程. 默认实现 `StringEncryptionService` 使用AES算法(参见字符串[加密文档](String-Encryption.md)学习更多). + +## 设置管理模块 + +设置系统核心是相当独立的,不做任何关于如何管理(更改)设置值的假设. 默认的`ISettingStore`实现也是`NullSettingStore`，它为所有设置值返回null. + +设置管理模块通过管理数据库中的设置值来完成逻辑(实现`ISettingStore`).有关更多信息参阅[设置管理模块](Modules/Setting-Management.md)学习更多. diff --git a/docs/zh-Hans/docs-nav.json b/docs/zh-Hans/docs-nav.json index 185d45ac68..f50edace6a 100644 --- a/docs/zh-Hans/docs-nav.json +++ b/docs/zh-Hans/docs-nav.json @@ -48,6 +48,10 @@ { "text": "基础知识", "items": [ + { + "text": "配置", + "path": "Configuration.md" + }, { "text": "依赖注入", "path": "Dependency-Injection.md", @@ -82,9 +86,10 @@ }, { "text": "审计" - }, + }, { - "text": "设置管理" + "text": "设置管理", + "path": "Settings.md" } ] }, @@ -107,6 +112,10 @@ { "text": "服务", "items": [ + { + "text": "当前用户", + "path": "CurrentUser.md" + }, { "text": "对象序列化" },