update zh docs for v3.0

docs/content/user-guide/zh/cap/messaging.md

@@ -2,6 +2,10 @@
 
 使用 `ICapPublisher` 接口发送出去的数据称之为 Message (`消息`)。
 
+## 发送 & 处理消息
+
+你可以阅读 [quick-start](../getting-started/quick-start.md#_3) 来学习如何发送和处理消息。
+
 ## 消息调度
 
 CAP 接收到消息之后会将消息发送到 Transport, 由 Transport 进行运输。

docs/content/user-guide/zh/cap/serialization.md

 # 序列化
 
-CAP 目前还不支持消息本身的序列化，在将消息发送到消息队列之前 CAP 使用 json 对消息对象进行序列化。
+CAP 提供了 `ISerializer` 接口来支持对消息进行序列化，默认情况下我们使用 json 来对消息进行序列化处理并存储到数据库中。
 
-## 内容序列化
+## 自定义序列化
 
-CAP 支持对消息的 Content 字段进行序列化，你可以自定义 `IContentSerializer` 接口来做到这一点。
-
-目前由于消息对象需要进行数据库存储，所以只支持 string 的序列化和反序例化。
-
-```csharp
-
-class MyContentSerializer : IContentSerializer 
+```C#
+public class YourSerializer: ISerializer
 {
-    public T DeSerialize<T>(string messageObjStr)
+    Task<TransportMessage> SerializeAsync(Message message)
     {
-    }
 
-    public object DeSerialize(string content, Type type)
-    {
     }
-
-    public string Serialize<T>(T messageObj)
+ 
+    Task<Message> DeserializeAsync(TransportMessage transportMessage, Type valueType)
     {
+
     }
 }
 ```
 
-## 消息适配器
+然后将你的实现注册到容器中:
+
+```
+
+//注册你的自定义实现
+services.AddSingleton<ISerializer, YourSerializer>();
+
+// ---
+services.AddCap 
+
+```
+
+
+## 消息适配器 (v3.0移除 )
 
 在异构系统中，有时候需要和其他系统进行通讯，但是其他系统使用的消息对象可能和 CAP 的[**包装器对象**](../persistent/general.md#_7)不一样，这个时候就需要对消息进行自定义适配。
 

docs/content/user-guide/zh/getting-started/contributing.md

 # 贡献
 
-One of the easiest ways to contribute is to participate in discussions and discuss issues. 
+贡献最简单的方式之一就是参与讨论和issue讨论。
 
-If you have any question or problems, please report them on the CAP repository:
+如果您有任何疑问或问题，请在CAP仓库中报告：
 
 <a href="https://github.com/dotnetcore/cap/issues/new"><button data-md-color-primary="purple"><i class="fa fa-github fa-2x"></i> Report Issue</button></a>
 <a href="https://github.com/dotnetcore/cap/issues"><button data-md-color-primary="purple" type="submit"> Active Issues <i class="fa fa-github fa-2x"></i></button></a>
 
-## Submitting Changes
+## 提交更改
 
-You can also contribute by submitting pull requests with code changes.
+您还可以通过提交代码更改PR来做出贡献。
 
 >
-Pull requests let you tell others about changes you've pushed to a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before the changes are merged into the repository.
+Pull requests 可让您告诉其他人已推送到GitHub上存储库的更改。 打开 Pull requests 后，您可以与协作者讨论和审查做出的更改，并在更改合并到存储库之前添加后续提交。
 
-## Additional Resources
+## 其他资源
 
-* [Filtering issues and pull requests](https://help.github.com/articles/filtering-issues-and-pull-requests/)
+* [issue 和 pull requests](https://help.github.com/articles/filtering-issues-and-pull-requests/)
 
-* [Using search to filter issues and pull requests](https://help.github.com/articles/using-search-to-filter-issues-and-pull-requests/)
+* [使用搜索过滤 issue 和 pull requests](https://help.github.com/articles/using-search-to-filter-issues-and-pull-requests/)
\ No newline at end of file

docs/content/user-guide/zh/getting-started/introduction.md

@@ -6,7 +6,7 @@ CAP 是一个EventBus，同时也是一个在微服务或者SOA系统中解决
 
 !!! question "什么是 EventBus？"
 
-    An Eventbus is a mechanism that allows different components to communicate with each other without knowing about each other. A component can send an Event to the Eventbus without knowing who will pick it up or how many others will pick it up. Components can also listen to Events on an Eventbus, without knowing who sent the Events. That way, components can communicate without depending on each other. Also, it is very easy to substitute a component. As long as the new component understands the Events that are being sent and received, the other components will never know.
+    事件总线是一种机制，它允许不同的组件彼此通信而不彼此了解。 组件可以将事件发送到Eventbus，而无需知道是谁来接听或有多少其他人来接听。 组件也可以侦听Eventbus上的事件，而无需知道谁发送了事件。 这样，组件可以相互通信而无需相互依赖。 同样，很容易替换一个组件。 只要新组件了解正在发送和接收的事件，其他组件就永远不会知道.
 
 相对于其他的 Service Bus 或者 Event Bus， CAP 拥有自己的特色，它不要求使用者发送消息或者处理消息的时候实现或者继承任何接口，拥有非常高的灵活性。我们一直坚信约定大于配置，所以CAP使用起来非常简单，对于新手非常友好，并且拥有轻量级。
 

docs/content/user-guide/zh/getting-started/quick-start.md

@@ -59,6 +59,35 @@ public class ConsumerController : Controller
 }
 ```
 
+## 带有头信息的消息
+
+### 发送包含头信息的消息
+
+```c#
+var header = new Dictionary<string, string>()
+{
+    ["my.header.first"] = "first",
+    ["my.header.second"] = "second"
+};
+
+capBus.Publish("test.show.time", DateTime.Now, header);
+
+```
+
+### 处理包含头信息的消息
+
+```c#
+[CapSubscribe("test.show.time")]
+public void ReceiveMessage(DateTime time, [FromCap]CapHeader header)
+{
+    Console.WriteLine("message time is:" + time);
+    Console.WriteLine("message firset header :" + header["my.header.first"]);
+    Console.WriteLine("message second header :" + header["my.header.second"]);
+}
+
+```
+
+
 ## 摘要
 
 相对于直接集成消息队列，异步消息传递最强大的优势之一是可靠性，系统的一个部分中的故障不会传播，也不会导致整个系统崩溃。 在 CAP 内部会将消息进行存储，以保证消息的可靠性，并配合重试等策略以达到各个服务之间的数据最终一致性。
\ No newline at end of file

docs/content/user-guide/zh/monitoring/dashboard.md

@@ -4,7 +4,13 @@ CAP 原生提供了 Dashboard 供查看消息，利用 Dashboard 提供的功能
 
 ## 启用 Dashboard
 
-默认情况下，不会启动Dashboard中间件，要开启Dashboard功能你需要在配置中添加如下代码：
+首先，你需要安装Dashboard的 NuGet 包。
+
+```powershell
+PM> Install-Package DotNetCore.CAP.Dashboard
+```
+
+然后，在配置中添加如下代码：
 
 ```C#
 services.AddCap(x =>

docs/content/user-guide/zh/monitoring/diagnostics.md

@@ -7,6 +7,8 @@ Diagnostics 提供一组功能使我们能够很方便的可以记录在应用
 
 在 CAP 中，对 `DiagnosticSource` 提供了支持，监听器名称为 `CapDiagnosticListener`。
 
+你可以在 `DotNetCore.CAP.Diagnostics.CapDiagnosticListenerNames` 类下面找到CAP已经定义的事件名称。
+
 Diagnostics 提供对外提供的事件信息有：
 
 * 消息持久化之前
@@ -21,4 +23,20 @@ Diagnostics 提供对外提供的事件信息有：
 * 订阅者方法执行之后
 * 订阅者方法执行异常
 
-相关涉及到的对象，你可以在 `DotNetCore.CAP.Diagnostics` 命名空间下看到。
+
\ No newline at end of file
+## 在 Skywalking 中追踪 CAP 事件
+
+Skywalking 的 C# 客户端提供了对 CAP Diagnostics 的支持，你可以利用 [SkyAPM-dotnet](https://github.com/SkyAPM/SkyAPM-dotnet) 来实现在 Skywalking 中追踪事件。
+
+尝试阅读Readme文档来在你的项目中集成它。
+
+![](https://user-images.githubusercontent.com/8205994/71006463-51025980-2120-11ea-82dc-bffa5530d515.png)
+
+
+![](https://user-images.githubusercontent.com/8205994/71006589-7b541700-2120-11ea-910b-7e0f2dfddce8.png)
+
+## 其他 APM 的支持
+
+目前还没有实现对除了Skywalking的其他APM的支持，如果你想在其他 APM 中实现对 CAP 诊断事件的支持，你可以参考这里的代码来实现它：
+
+https://github.com/SkyAPM/SkyAPM-dotnet/tree/master/src/SkyApm.Diagnostics.CAP
\ No newline at end of file

docs/content/user-guide/zh/persistent/general.md

@@ -62,4 +62,10 @@ Timestamp |	消息创建时间 |	string
 Content |	内容 |	string
 CallbackName |	回调的订阅者名称 | string
 
-其中 Id 字段，CAP 采用的 MongoDB 中的 ObjectId 分布式Id生成算法生成。
+其中 Id 字段，CAP 采用的 MongoDB 中的 ObjectId 分布式Id生成算法生成。
\ No newline at end of file
+
+## 社区支持的持久化
+
+感谢社区对CAP的支持，以下是社区支持的持久化的实现
+
+* SQLite ([@colinin](https://github.com/colinin)) ： https://github.com/colinin/DotNetCore.CAP.Sqlite   

docs/content/user-guide/zh/persistent/mongodb.md

@@ -35,7 +35,7 @@ public void ConfigureServices(IServiceCollection services)
 
 ```
 
-#### MongoDBOptions
+#### 配置项
 
 NAME | DESCRIPTION | TYPE | DEFAULT
 :---|:---|---|:---
@@ -44,7 +44,7 @@ DatabaseConnection | 数据库连接字符串 | string | mongodb://localhost:270
 ReceivedCollection | 接收消息集合名称 | string | cap.received
 PublishedCollection | 发送消息集合名称 | string | cap.published
 
-## Publish with transaction
+## 使用事务发布消息
 
 下面的示例展示了如何利用 CAP 和 MongoDB 进行本地事务集成。
 

docs/content/user-guide/zh/persistent/mysql.md

@@ -29,16 +29,43 @@ public void ConfigureServices(IServiceCollection services)
 
 ```
 
-#### MySqlOptions
+### 配置项
 
 NAME | DESCRIPTION | TYPE | DEFAULT
 :---|:---|---|:---
 TableNamePrefix | Cap表名前缀 | string | cap 
 ConnectionString | 数据库连接字符串 | string | null
 
-## Publish with transaction
+### 自定义表名称
 
-### ADO.NET with transaction
+你可以通过重写 `IStorageInitializer` 接口获取表名称的方法来做到这一点
+
+示例代码：
+
+```C#
+
+public class MyTableInitializer : MySqlStorageInitializer
+{
+    public override string GetPublishedTableName()
+    {
+        //你的 发送消息表 名称
+    }
+
+    public override string GetReceivedTableName()
+    {
+        //你的 接收消息表 名称
+    }
+}
+```
+然后将你的实现注册到容器中
+
+```
+services.AddSingleton<IStorageInitializer, MyTableInitializer>();
+```
+
+## 使用事务发布消息
+
+### ADO.NET 
 
 ```csharp
 
@@ -59,7 +86,7 @@ using (var connection = new MySqlConnection(AppDbContext.ConnectionString))
 }
 ```
 
-### EntityFramework with transaction
+### EntityFramework 
 
 ```csharp
 

docs/content/user-guide/zh/persistent/postgresql.md

@@ -31,16 +31,43 @@ public void ConfigureServices(IServiceCollection services)
 
 ```
 
-#### PostgreSqlOptions
+### 配置项
 
 NAME | DESCRIPTION | TYPE | DEFAULT
 :---|:---|---|:---
 Schema | 数据库架构 | string | cap 
 ConnectionString | 数据库连接字符串 | string | 
 
-## Publish with transaction
+### 自定义表名称
 
-### ADO.NET with transaction
+你可以通过重写 `IStorageInitializer` 接口获取表名称的方法来做到这一点
+
+示例代码：
+
+```C#
+
+public class MyTableInitializer : PostgreSqlStorageInitializer
+{
+    public override string GetPublishedTableName()
+    {
+        //你的 发送消息表 名称
+    }
+
+    public override string GetReceivedTableName()
+    {
+        //你的 接收消息表 名称
+    }
+}
+```
+然后将你的实现注册到容器中
+
+```
+services.AddSingleton<IStorageInitializer, MyTableInitializer>();
+```
+
+## 使用事务发布消息
+
+### ADO.NET 
 
 ```csharp
 
@@ -61,7 +88,7 @@ using (var connection = new NpgsqlConnection("ConnectionString"))
 }
 ```
 
-### EntityFramework with transaction
+### EntityFramework
 
 ```csharp
 

docs/content/user-guide/zh/persistent/sqlserver.md

@@ -31,16 +31,43 @@ public void ConfigureServices(IServiceCollection services)
 
 ```
 
-#### SqlServerOptions
+### 配置项
 
 NAME | DESCRIPTION | TYPE | DEFAULT
 :---|:---|---|:---
 Schema | 数据库架构 | string | Cap
 ConnectionString | 数据库连接字符串 | string | 
 
-## Publish with transaction
+### 自定义表名称
 
-### ADO.NET with transaction
+你可以通过重写 `IStorageInitializer` 接口获取表名称的方法来做到这一点
+
+示例代码：
+
+```C#
+
+public class MyTableInitializer : SqlServerStorageInitializer
+{
+    public override string GetPublishedTableName()
+    {
+        //你的 发送消息表 名称
+    }
+
+    public override string GetReceivedTableName()
+    {
+        //你的 接收消息表 名称
+    }
+}
+```
+然后将你的实现注册到容器中
+
+```
+services.AddSingleton<IStorageInitializer, MyTableInitializer>();
+```
+
+## 使用事务发布消息
+
+### ADO.NET 
 
 ```csharp
 
@@ -61,7 +88,7 @@ using (var connection = new SqlConnection("ConnectionString"))
 }
 ```
 
-### EntityFramework with transaction
+### EntityFramework
 
 ```csharp
 

docs/content/user-guide/zh/transports/general.md

-# Transports
+# 运输器
 
-Transports move data from one place to another – between acquisition programs and pipelines, between pipelines and the entity database, and even between pipelines and external systems.
+通过运输将数据从一个地方移动到另一个地方-在采集程序和管道之间，管道与实体数据库之间，甚至在管道与外部系统之间。
 
-## Supported transports
+## 支持的运输器
 
-CAP supports several transport methods:
+CAP 支持以下几种运输方式：
 
 * [RabbitMQ](rabbitmq.md)
 * [Kafka](kafka.md)
 * [Azure Service Bus](azure-service-bus.md)
 * [In-Memory Queue](in-memory-queue.md)
 
-## How to select a transport
+## 怎么选择运输器
 
  🏳‍🌈  | RabbitMQ | Kafka | Azure Service Bus | In-Memory
 :--   |   :--:    | :--: | :--:               | :--  :
@@ -25,8 +25,4 @@ CAP supports several transport methods:
 > http://geekswithblogs.net/michaelstephenson/archive/2012/08/12/150399.aspx
 
 >`Kafka` vs `RabbitMQ` :   
-> https://stackoverflow.com/questions/42151544/is-there-any-reason-to-use-rabbitmq-over-kafka
-
+> https://stackoverflow.com/questions/42151544/is-there-any-reason-to-use-rabbitmq-over-kafka
\ No newline at end of file
-## Community Supported transports
-
-* SQLite ([@colinin](https://github.com/colinin)) ： https://github.com/colinin/DotNetCore.CAP.Sqlite   

docs/content/user-guide/zh/transports/kafka.md

@@ -41,7 +41,37 @@ NAME | DESCRIPTION | TYPE | DEFAULT
 :---|:---|---|:---
 Servers | Broker 地址 | string | 
 ConnectionPoolSize | 用户名 | int | 10
+CustomHeaders | 设置自定义头 | Function | 
 
+有关 `CustomHeaders` 的说明：
+
+如果你想在消费消息的时候，通过从 `CapHeader` 获取 Kafka 中例如 Offset 或者 Partition 等信息，你可以通过自定义此函数来实现这一点。
+
+例如以下代码为你展示了如何进行设置额外的参数到 `CapHeader` 中:
+
+```C#
+x.UseKafka(opt =>
+{
+    //...
+
+    opt.CustomHeaders = kafkaResult => new List<KeyValuePair<string, string>>
+    {
+        new KeyValuePair<string, string>("my.kafka.offset", kafkaResult.Offset.ToString()),
+        new KeyValuePair<string, string>("my.kafka.partition", kafkaResult.Partition.ToString())
+    };
+});
+```
+
+然后你可以通过这个方式来获取你添加的头信息:
+
+```C#
+[CapSubscribe("sample.kafka.postgrsql")]
+public void HeadersTest(DateTime value, [FromCap]CapHeader header)
+{
+    var offset = header["my.kafka.offset"];
+    var partition = header["my.kafka.partition"];
+}
+```
 
 #### Kafka MainConfig Options
 

docs/mkdocs.yml

@@ -115,7 +115,7 @@ nav:
           - 消息: user-guide/zh/cap/messaging.md
           - Sagas: user-guide/zh/cap/sagas.md
           - 序列化: user-guide/zh/cap/serialization.md
-          - 传输: user-guide/zh/cap/transactions.md
+          - 运输: user-guide/zh/cap/transactions.md
           - 幂等性: user-guide/zh/cap/idempotence.md          
       - 传输:
           - 简介: user-guide/zh/transports/general.md