更新说明文档

AterDev · Dec 11, 2023 · a13d105 · a13d105
1 parent 8d77dce
commit a13d105
Show file tree

Hide file tree

Showing 11 changed files with 165 additions and 23 deletions.
diff --git a/zh/ater.dry/.order b/zh/ater.dry/.order
@@ -1,5 +1,6 @@
 概述
 安装
-作为智能助手
+创建并运行项目
 Studio
+代码生成说明
 命令行
diff --git a/zh/ater.dry/代码生成说明/DTO生成.md b/zh/ater.dry/代码生成说明/DTO生成.md
@@ -0,0 +1,60 @@
+# DTO生成说明
+
+使用工具可以解析实体，并生成相应的DTO，以下说明具体生成的规则。
+
+## 生成内容
+
+一个实体通常会生成以下几个模型类:
+
+- `ItemDto`: 用于列表元素的模型
+- `ShortDto`: 用于获取模型主要信息的模型
+- `FilterDto`: 用于请求的筛选模型
+- `AddDto`: 用于实体添加时的模型
+- `UpdateDto`：用于更新的模型
+
+## 生成说明
+
+如果实体属性含有[JsonIgnore]属性，那么生成的DTO都会忽略该属性。
+
+### ItemDto
+
+列表元素不会包括以下属性：
+
+- IsDeleted与UpdatedTime字段，但会包含CreatedTime
+- 数组或列表
+- 长度大于1000的字符串
+- 导航属性及对应Id
+
+### ShortDto
+
+在ItemDto的基础上，忽略 CreatedTime以及"Content"字段。
+
+### FilterDto
+
+FilterDto生成内容如下：
+
+- 忽略 "Id", "CreatedTime", "UpdatedTime", "IsDeleted"等基础属性
+- 忽略列表及导航属性
+- 忽略最大长度在于1000的字符串属性
+- 保留必需属性(但不为导航属性)
+- 包括枚举属性
+
+### AddDto
+
+添加模型生成内容如下：
+
+- 忽略 "Id", "CreatedTime", "UpdatedTime", "IsDeleted"等基础属性
+- 必须是可赋值的属性，即有`set`方法。
+- 对于导航属性，会进行以下处理：
+  - 忽略非必需的导航属性
+  - 忽略列表导航属性
+  - 对于必需的导航属性，会生成`属性名`+`Id`的形式来表示
+
+### UpdateDto
+
+更新模型生成内容同添加模型，但是更新模型所有属性默认都为可空属性。
+
+可空属性，意味着，如果该字段为空，更新时，会忽略该字段，以此来实现部分更新。
+
+> [!TIP]
+> 如果你习惯进行全量更新，可直接复用`AddDto`模型。
diff --git a/zh/ater.dry/代码生成说明/Manager生成.md b/zh/ater.dry/代码生成说明/Manager生成.md
@@ -0,0 +1,2 @@
+# Manager代码生成说明
+
diff --git a/zh/ater.dry/作为智能助手.md b/zh/ater.dry/作为智能助手.md
diff --git a/zh/ater.dry/创建并运行项目.md b/zh/ater.dry/创建并运行项目.md
@@ -0,0 +1,82 @@
+# 创建并运行项目
+
+## 创建解决方案
+
+点击创建按钮，进入到解决方案创建页面。
+
+:::image type="content" source="../images/createSolution.jpg" alt-text="create solution":::
+
+你会看到以下页面，请填写解决方案名称和本地路径，然后点击创建。
+
+:::image type="content" source="../images/createSolutionPage.jpg" alt-text="create solution page":::
+
+## 运行解决方案
+
+现在使用你喜欢的IDE打开解决方案，或者直接在Studio 点击打开按钮。
+
+### 配置文件
+
+请先检查配置文件内容，包括：
+
+- 配置数据库连接字符串。请在`Http.API`项目下，`appsettings.json`中的`ConnectionStrings`中配置相关的连接字符串。
+- 在配置文件中`Components`的`Cache`配置，可选"Redis"或"Memory"。
+
+你可参考以下配置说明:
+
+```json
+  "ConnectionStrings": {
+    // 可写数据库
+    "CommandDb": "Server=localhost;Port=5432;Database=MyProjectName;User Id=postgres;Password=root;",
+    // 只读数据库
+    "QueryDb": "Server=localhost;Port=5432;Database=MyProjectName;User Id=postgres;Password=root;",
+    // 缓存连接
+    "Cache": "localhost:6379",
+    // 缓存前缀
+    "CacheInstanceName": "Dev",
+    // 日志接收地址
+    "Logging": "http://localhost:4317"
+  },
+
+  "Components": {
+    //Memory/Redis
+    "Cache": "Memory"
+  },
+  // 邮件发送服务
+  "Smtp": {
+    // smtp服务地址
+    "Host": "",
+    "Port": 25,
+    // 发件人名称
+    "DisplayName": "",
+    // 发件人地址
+    "From": "",
+    // 验证用户名
+    "Username": "",
+    // 验证密码
+    "Password": "",
+    "EnableSsl": true
+  },
+  "Key": {
+    // 默认用户密码
+    "DefaultPassword": "Hello.Net"
+  },
+```
+
+### 数据库迁移
+
+模板默认使用了PostgreSQL。如果你使用其他数据库提供程序，你可以在`Application`项目`AppServiceCollectionExtensions.cs`中找到注入数d据库服务的方法。
+
+请在`Http.API`项目下，使用`dotnet ef`命令生成迁移代码。或者直接运行`EFMigrations.ps1`脚本来执行，如：
+
+```powershell
+.\EFMigrations.ps1 Init
+```
+
+### 运行项目
+
+由于8.0添加了对`.NET Aspire`的支持，现在你有两种方式运行程序。
+
+1. 运行AppHost项目，这是使用 Aspire 提供的方式运行，它将打开`Dashboard`。
+2. 直接运行`Http.API`项目，这将在浏览器中打开接口的`Swagger UI`。
+
+你可以选择合适的方式运行程序。
diff --git a/zh/ater.dry/安装.md b/zh/ater.dry/安装.md
@@ -38,7 +38,7 @@ dry studio
 ```
 
 > [!NOTE]
-> 图形界面更适合使用`Ater.Web`模板创建的项目，有一定的约定配置才能正常使用。
+> 如果安装了新版本，请先执行`dry studio update`更新后再启动 Studio.
 
 ### 使用命令行
 
@@ -48,3 +48,9 @@ dry studio
 
 > [!TIP]
 > 使用命令行工具，可以不依赖项目结构去生成相关的代码！因为你可以指定具体的实体路径和代码输出的路径。
+
+## 接下来
+
+恭喜你已经成功安装并运行了工具。
+
+现在，你可以使用该工具[创建](创建并运行项目.md)新的解决方案项目。
diff --git a/zh/ater.dry/概述.md b/zh/ater.dry/概述.md
@@ -36,6 +36,10 @@ dry 命令工具可以帮助开发者根据实体模型(.cs文件)生成常用
 - 请求服务,`xxx.service.ts`
 - 接口模型,`xxx.ts`
 
+## 作为智能助手
+
+**dry**并不是简单的代码生成器，它通过分析和理解您的实体模型类，更具智慧的理解您的业务逻辑和实现意图，并基于此来生成相关基础代码，您无需从0开始。你所需要做的就是关注业务本身的模型设计。
+
 ## 项目模板支持
 
-可使用[ater.web.templates](https://www.nuget.org/packages/ater.web.templates)项目模板，建议配合使用！
+工具集成了[ater.web.templates](https://www.nuget.org/packages/ater.web.templates)项目模板，你可以使用图形化界面直接创建解决方案！
diff --git a/zh/ater.web/.order b/zh/ater.web/.order
@@ -1,6 +1,6 @@
 概述
-快速入门
 教程
+快速入门
 约定和规范
 示例
 自定义

diff --git a/zh/ater.web/概述.md b/zh/ater.web/概述.md
@@ -48,12 +48,17 @@ dotnet new install ater.web.templates
 
 ## 使用
 
-安装完成后，可使用命令创建项目，也可通过VS的图形界面选择创建。
+安装完成后，可使用命令创建项目，也可通过VS的图形界面选择创建(建议)。
 
 ```pwsh
 dotnet new atapi -n my-project
 ```
 
+转到`Http.API`项目中，在`appsetings.json`中配置数据库连接字符串。
+
+> [!TIP]
+> 模板默认使用`PostgreSQL`，请根据自己实际需求进行变更。
+
 ## 安装ater.dry (推荐)
 
 `ater.dry` 是一个智能代码辅助工具，主要提供代码生成功能，它可以分析您的实体，智能的帮助您生成相关的数据传输对象、数据库读写操作以及API接口。它以`dotnet`命令行工具提供，同时提供Web UI操作界面，能够节省大量的开发时间，强烈建议安装使用！

diff --git a/zh/images/createSolution.jpg b/zh/images/createSolution.jpg
diff --git a/zh/images/createSolutionPage.jpg b/zh/images/createSolutionPage.jpg