docs: update documentation

BryanLiu2019 · Sep 5, 2021 · 833d78d · 833d78d
1 parent 3b0cf8b
commit 833d78d
Show file tree

Hide file tree

Showing 8 changed files with 316 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -330,4 +330,9 @@ ASALocalRun/
 .mfractor/
 
 # Mac OS
-.DS_Store
+.DS_Store
+
+# Read the docstates
+_build/
+_static/
+_templates/
diff --git a/README.md b/README.md
@@ -28,6 +28,10 @@ dotnet add package nacos-sdk-csharp.IniParser
 - Integrate With Aliyun ACM
 - ...
 
+Find more information on the documents pages:
+
+https://nacos-sdk-csharp.readthedocs.io/en/latest/
+
 ## Basic Usage
 
 ### Simple Configuration Usage

diff --git a/README.zh-cn.md b/README.zh-cn.md
@@ -29,6 +29,10 @@ dotnet add package nacos-sdk-csharp.IniParser
 - 和阿里云应用配置管理(Application Configuration Management，简称 ACM)集成使用
 - ...
 
+更多信息请查阅文档:
+
+https://nacos-sdk-csharp.readthedocs.io/en/latest/
+
 ## 简易用法
 
 ### 配置

diff --git a/docs/features/cfg-encrypt.rst b/docs/features/cfg-encrypt.rst
@@ -0,0 +1,69 @@
+配置加解密
+===============
+
+配置加解密这个功能是衍生功能，目前和 nacos 服务端联系还不大，是 SDK 对配置加密后再传输，解密后再使用。
+
+如果需要使用这个功能，需要做下面两件事。
+
+1. 自定义 ConfigFilter
+2. 配置 ConfigFilter 
+
+
+自定义 ConfigFilter
+^^^^^^^^^^^^^^^^^^^^^^
+
+把配置加解密的逻辑放到自定义的 ConfigFilter 里面。 ConfigFilter 可以有多个，不同 ConfigFilter 的执行顺序是按他们的 Order 属性来决定的。
+
+.. code-block:: csharp
+
+    public class MyNacosConfigFilter : IConfigFilter
+    {
+        public void DoFilter(IConfigRequest request, IConfigResponse response, IConfigFilterChain filterChain)
+        {
+            if (request != null)
+            {
+                // 这里是请求的过滤，也就是在这里进行加密操作
+
+                
+                // 不要忘了在这里覆盖请求的内容！！！！！
+                request.PutParameter(Nacos.V2.Config.ConfigConstants.ENCRYPTED_DATA_KEY, encryptedDataKey);
+                request.PutParameter(Nacos.V2.Config.ConfigConstants.CONTENT, content);
+            }
+
+            if (response != null)
+            {
+                // 这里是响应的过滤，也就是在这里进行解密操作
+
+                
+                // 不要忘了在这里覆盖响应的内容！！！！！
+                response.PutParameter(Nacos.V2.Config.ConfigConstants.CONTENT, content);
+            }
+        }
+
+        public string GetFilterName() => nameof(MyNacosConfigFilter);
+
+        public int GetOrder() => 1;
+
+        public void Init(NacosSdkOptions options)
+        {
+            // 做一些初始化操作
+        }        
+    }
+
+
+配置 ConfigFilter 
+^^^^^^^^^^^^^^^^^^^^^^
+
+这一步主要是告诉 nacos-sdk-csharp 去那个程序集找 ConfigFilter 的实现，以及它的实现需要什么参数。
+
+.. code-block:: JSON
+
+    {
+        "NacosConfig": {           
+            "ConfigFilterAssemblies": [ "XXXX.CusLib" ],
+            "ConfigFilterExtInfo": "{\"JsonPaths\":[\"ConnectionStrings.Default\"],\"Other\":\"xxxxxx\"}"
+        }
+    }
+
+
+这里主要是两个配置，一个是 `ConfigFilterAssemblies` 指定实现类所在的程序集，一个是 `ConfigFilterExtInfo` 指定实现类可能需要的参数。
diff --git a/docs/features/configuration.rst b/docs/features/configuration.rst
@@ -1,2 +1,86 @@
 配置中心
 ===============
+
+`nacos-sdk-csharp` 操作 nacos 的配置提供了两个 nuget 包，一个是原生的 sdk 版本， 一个是集成了 ASP.NET Core 配置体系的版本，大家可以根据自己的需要选择不同的版本。
+
+::
+
+    注: 请还在使用 nuget 包的名称里面还带有 `unofficial` 的朋友尽快升级到
+    不带 `unofficial` 的版本，新版本同时支持 nacos server 1.x 和 2.x
+
+
+原生的 sdk 版本
+^^^^^^^^^^^^^^^^^^^
+
+原生 sdk 暴露出了下面几个方法
+
+.. code-block:: csharp
+
+    Task<string> GetConfig(string dataId, string group, long timeoutMs);
+
+    Task<string> GetConfigAndSignListener(string dataId, string group, long timeoutMs, IListener listener);
+
+    Task AddListener(string dataId, string group, IListener listener);
+
+    Task<bool> PublishConfig(string dataId, string group, string content);
+
+    Task<bool> PublishConfig(string dataId, string group, string content, string type);
+
+    Task<bool> RemoveConfig(string dataId, string group);
+
+    Task RemoveListener(string dataId, string group, IListener listener);
+
+    Task<string> GetServerStatus();
+
+    Task ShutDown();
+
+主要就是配置的 CURD 和监听。
+
+监听可以让客户端实时获取 nacos 上面的最新配置，这个对实现配置的热加载/热更新是一个很重要的基石。
+
+实现监听，需要自定义一个实现 `IListener` 的监听者。
+
+.. code-block:: csharp
+
+        public class CusConfigListen : Nacos.V2.IListener
+        {
+            public void ReceiveConfigInfo(string configInfo)
+            {
+                // 这里会有配置变更的回调，在这里处理配置变更之后的逻辑。
+                System.Console.WriteLine("config cb cb cb " + configInfo);
+            }
+        }
+
+添加监听和移除监听，要保证是同一个监听者对象，不然会造成监听一直存在，移除不了的情况。
+
+对于重要配置被修改需要通知到部门群或者其他地方时，通过监听就可以实现一个 webhook 的功能了。
+
+
+集成 ASP.NET Core 版本
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+推出这样一个版本很大程度是为了简化操作，只加几个配置，代码层级的用法几乎零改动，类似于 spring cloud 那样。
+
+SDK 这一块通过实现了自定义的 **ConfigurationProvider** 和 **IConfigurationSource** 来达到了这个效果。
+
+对于配置的热加载/热更新， SDK 则是实现了一个默认的监听者，在配置变更之后进行了 `OnReload` 的操作。
+
+使用上需要在 `Program` 里面进行 **ConfigureAppConfiguration** 的设置。
+
+.. code-block:: csharp
+
+        Host.CreateDefaultBuilder(args)
+            .ConfigureAppConfiguration((context, builder) =>
+            {
+                var c = builder.Build();
+                builder.AddNacosV2Configuration(c.GetSection("NacosConfig"));
+            })
+            .ConfigureWebHostDefaults(webBuilder =>
+            {
+                webBuilder.UseStartup<Startup>();
+            })
+
+::
+
+    注: 请注意 `IOptions<T>`、`IOptionsSnapshot<T>` 和 `IOptionsMonitor<T>` 的区别
+    避免出现配置变更了，应用读取不到最新配置的情况！！！
diff --git a/docs/features/servicediscovery.rst b/docs/features/servicediscovery.rst
@@ -1,2 +1,134 @@
 服务发现
 ===============
+
+`nacos-sdk-csharp` 操作 nacos 的配置提供了两个 nuget 包，一个是原生的 sdk 版本， 一个是集成了 ASP.NET Core 配置体系的版本，大家可以根据自己的需要选择不同的版本。
+
+::
+
+    注: 请还在使用 nuget 包的名称里面还带有 `unofficial` 的朋友尽快升级到
+    不带 `unofficial` 的版本，新版本同时支持 nacos server 1.x 和 2.x
+
+
+原生的 sdk 版本
+^^^^^^^^^^^^^^^^^^^
+
+原生 sdk 暴露出了下面几个方法
+
+.. code-block:: csharp
+
+    Task RegisterInstance(string serviceName, string ip, int port);
+
+    Task RegisterInstance(string serviceName, string groupName, string ip, int port);
+
+    Task RegisterInstance(string serviceName, string ip, int port, string clusterName);
+
+    Task RegisterInstance(string serviceName, string groupName, string ip, int port, string clusterName);
+
+    Task RegisterInstance(string serviceName, Instance instance);
+
+    Task RegisterInstance(string serviceName, string groupName, Instance instance);
+
+    Task DeregisterInstance(string serviceName, string ip, int port);
+
+    Task DeregisterInstance(string serviceName, string groupName, string ip, int port);
+
+    Task DeregisterInstance(string serviceName, string ip, int port, string clusterName);
+
+    Task DeregisterInstance(string serviceName, string groupName, string ip, int port, string clusterName);
+
+    Task DeregisterInstance(string serviceName, Instance instance);
+
+    Task DeregisterInstance(string serviceName, string groupName, Instance instance);
+
+    Task<List<Instance>> GetAllInstances(string serviceName);
+
+    Task<List<Instance>> GetAllInstances(string serviceName, string groupName);
+
+    Task<List<Instance>> GetAllInstances(string serviceName, bool subscribe);
+
+    Task<List<Instance>> GetAllInstances(string serviceName, string groupName, bool subscribe);
+
+    Task<List<Instance>> GetAllInstances(string serviceName, List<string> clusters);
+
+    Task<List<Instance>> GetAllInstances(string serviceName, string groupName, List<string> clusters);
+
+    Task<List<Instance>> GetAllInstances(string serviceName, List<string> clusters, bool subscribe);
+
+    Task<List<Instance>> GetAllInstances(string serviceName, string groupName, List<string> clusters, bool subscribe);
+
+    Task<List<Instance>> SelectInstances(string serviceName, bool healthy);
+
+    Task<List<Instance>> SelectInstances(string serviceName, string groupName, bool healthy);
+
+    Task<List<Instance>> SelectInstances(string serviceName, bool healthy, bool subscribe);
+
+    Task<List<Instance>> SelectInstances(string serviceName, string groupName, bool healthy, bool subscribe);
+
+    Task<List<Instance>> SelectInstances(string serviceName, List<string> clusters, bool healthy);
+
+    Task<List<Instance>> SelectInstances(string serviceName, string groupName, List<string> clusters, bool healthy);
+
+    Task<List<Instance>> SelectInstances(string serviceName, List<string> clusters, bool healthy, bool subscribe);
+
+    Task<List<Instance>> SelectInstances(string serviceName, string groupName, List<string> clusters, bool healthy, bool subscribe);
+
+    Task<Instance> SelectOneHealthyInstance(string serviceName);
+
+    Task<Instance> SelectOneHealthyInstance(string serviceName, string groupName);
+
+    Task<Instance> SelectOneHealthyInstance(string serviceName, bool subscribe);
+
+    Task<Instance> SelectOneHealthyInstance(string serviceName, string groupName, bool subscribe);
+
+    Task<Instance> SelectOneHealthyInstance(string serviceName, List<string> clusters);
+
+    Task<Instance> SelectOneHealthyInstance(string serviceName, string groupName, List<string> clusters);
+
+    Task<Instance> SelectOneHealthyInstance(string serviceName, List<string> clusters, bool subscribe);
+
+    Task<Instance> SelectOneHealthyInstance(string serviceName, string groupName, List<string> clusters, bool subscribe);
+
+    Task Subscribe(string serviceName, IEventListener listener);
+
+    Task Subscribe(string serviceName, string groupName, IEventListener listener);
+
+    Task Subscribe(string serviceName, List<string> clusters, IEventListener listener);
+
+    Task Subscribe(string serviceName, string groupName, List<string> clusters, IEventListener listener);
+
+    Task Unsubscribe(string serviceName, IEventListener listener);
+
+    Task Unsubscribe(string serviceName, string groupName, IEventListener listener);
+
+    Task Unsubscribe(string serviceName, List<string> clusters, IEventListener listener);
+
+    Task Unsubscribe(string serviceName, string groupName, List<string> clusters, IEventListener listener);
+
+    Task<ListView<string>> GetServicesOfServer(int pageNo, int pageSize);
+
+    Task<ListView<string>> GetServicesOfServer(int pageNo, int pageSize, string groupName);
+
+    Task<ListView<string>> GetServicesOfServer(int pageNo, int pageSize, AbstractSelector selector);
+
+    Task<ListView<string>> GetServicesOfServer(int pageNo, int pageSize, string groupName, AbstractSelector selector);
+
+    Task<List<ServiceInfo>> GetSubscribeServices();
+
+    Task<string> GetServerStatus();
+
+    Task ShutDown();
+
+
+可以看到有很多重载的方法，主要也是离不开服务的 CURD 和监听。
+
+
+集成 ASP.NET Core 版本
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+推出这样一个版本很大程度是为了简化操作，可以在应用启动的时候注册到 nacos 的注册中心，应用停止的时候可以注销。
+
+SDK 内部是通过实现了一个后台服务 (IHostedService) 来达到这个效果的。
+
+无论是注册还是注销，都会有重试的机制，目前最多重试 3 次。
+
+查询服务实例则需要通过上面 **INacosNamingService** 提供的方法来实现。
diff --git a/docs/index.rst b/docs/index.rst
@@ -22,6 +22,7 @@
    :caption: Features
 
    features/configuration
+   features/cfg-encrypt
    features/servicediscovery
 
 .. toctree::
@@ -42,6 +43,7 @@
    releasenote/v1.0.3
    releasenote/v1.1.0
    releasenote/v1.1.1
+   releasenote/v1.2.0
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/releasenote/v1.2.0.rst b/docs/releasenote/v1.2.0.rst
@@ -0,0 +1,15 @@
+v1.2.0 (Sept 5th, 2021) 发布记录
+=============================================
+
+
+1. [NAMING] Fixed not pass section for AddNacosV2Naming (#131)
+#. [AUTH] Fixed request login interface too frequently (#137)
+#. [CORE] improve: make rpcstatus error message readable
+#. [DOCS] improve: host documentation website on `readthedocs <https://nacos-sdk-csharp.readthedocs.io/en/latest/>`_
+
+------------
+
+1. [NAMING] 修复 AddNacosV2Naming 没有传递 section 的 bug (#131)
+#. [AUTH] 修复请求登录接口过于频繁的 bug (#137)
+#. [CORE] 优化 rpc 状态错误的提示语
+#. [DOCS] 托管文档网站到 `readthedocs <https://nacos-sdk-csharp.readthedocs.io/en/latest/>`_