ThreeMammals#1351 ThreeMammals#1510 New AddOcelot extensions to suppo…

…rt custom ASP.NET MVC pipeline building via the IMvcCoreBuilder interface (ThreeMammals#1655)

* AddOcelot support custom mvc builder.

* Fix SA1503 : The opening and closing braces for a C# statement have been omitted.

* Fix SA1135 : A using directive is not qualified.

* Add AddDefaultAspNetServices method. Remove anonymous delegate.

* Make method names shorter

* add unit test for AddOcelotUsingBuilder

* Sort Usings

* Refactor integration test for the case with AddOcelotUsingBuilder

* Update OcelotBuilder.cs

* Update gettingstarted.rst

Fix target framework as net7.0

* Add "The AddOcelot method" paragraph

* Use correct heading levels for subsections

* Update configuration.rst

Use correct heading levels for (sub)sections

* Update configuration.rst

Readability improvements

* Incapsulate all system services to the AddDefaultAspNetServices method

* Add developer's XML-docs for OcelotBuilder and related extensions

* Create dependencyinjection.rst

* Update dependencyinjection.rst

Overview paragraph

* Update dependencyinjection.rst

"IServiceCollection extensions" paragraph.
"The OcelotBuilder class" paragraph.

* Update dependencyinjection.rst: Custom Builder paragraph

* Add Dependency Injection feature to the index of docs

* Update gettingstarted.rst: Add footnotes

* Correction of typo in English grammar

* Unit tests for AddOcelotUsingBuilder extension

* Improve readability of BDDfy scenarios in logs

* Update requestaggregation.rst. Add footnotes 

Mark down corrections

* Update tracing.rst: Add footnotes. Markdown text corrections

* Update qualityofservice.rst: Add footnotes

* Update administration.rst: Add footnotes. Markdown text corrections

* Update configuration.rst: Add footnotes. Text corrections

* IDE1006 Naming rule violation: These words must begin with upper case characters: should_*

---------

Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

docs/features/administration.rst

@@ -3,16 +3,19 @@ Administration
 
 Ocelot supports changing configuration during runtime via an authenticated HTTP API. This can be authenticated in two ways either using Ocelot's internal IdentityServer (for authenticating requests to the administration API only) or hooking the administration API authentication into your own IdentityServer.
 
-The first thing you need to do if you want to use the administration API is bring in the relavent NuGet package..
+The first thing you need to do if you want to use the administration API is bring in the relavent NuGet package:
 
-``Install-Package Ocelot.Administration``
+.. code-block:: powershell
 
-This will bring down everything needed by the admin API.
+    Install-Package Ocelot.Administration
+
+This will bring down everything needed by the administration API.
 
 Providing your own IdentityServer
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------------
 
-All you need to do to hook into your own IdentityServer is add the following to your ConfigureServices method.
+All you need to do to hook into your own IdentityServer is add the following configuration options with authentication to your ``ConfigureServices`` method.
+After that we must pass these options to ``AddAdministration()`` extension of the ``OcelotBuilder`` being returned by ``AddOcelot()`` [#f1]_ like below:
 
 .. code-block:: csharp
 
@@ -26,7 +29,7 @@ All you need to do to hook into your own IdentityServer is add the following to
             {
                 ValidateAudience = false,
             };
-            // etc....
+            // etc...
         };
 
         services
@@ -36,18 +39,21 @@ All you need to do to hook into your own IdentityServer is add the following to
 
 You now need to get a token from your IdentityServer and use in subsequent requests to Ocelot's administration API.
 
-This feature was implemented for `issue 228 <https://github.com/ThreeMammals/Ocelot/issues/228>`_. It is useful because the IdentityServer authentication middleware needs the URL of the IdentityServer. If you are using the internal IdentityServer it might not alaways be possible to have the Ocelot URL.  
+This feature was implemented for `Issue 228 <https://github.com/ThreeMammals/Ocelot/issues/228>`_. It is useful because the IdentityServer authentication middleware needs the URL of the IdentityServer. 
+If you are using the internal IdentityServer it might not always be possible to have the Ocelot URL.  
 
 Internal IdentityServer
-^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------
 
-The API is authenticated using bearer tokens that you request from Ocelot iteself. This is provided by the amazing `Identity Server <https://github.com/IdentityServer/IdentityServer4>`_ project that I have been using for a few years now. Check them out.
+The API is authenticated using Bearer tokens that you request from Ocelot itself. This is provided by the amazing `Identity Server <https://github.com/IdentityServer/IdentityServer4>`_ project that I have been using for a few years now. Check them out.
 
-In order to enable the administration section you need to do a few things. First of all add this to yourinitial Startup.cs. 
+In order to enable the administration section you need to do a few things. First of all add this to your initial **Startup.cs**. 
 
-The path can be anything you want and it is obviously reccomended don't usea url you would like to route through with Ocelot as this will not work. The administration uses theMapWhen functionality of asp.net core and all requests to {root}/administration will be sent there not to the Ocelot middleware.
+The path can be anything you want and it is obviously recommended don't use a URL you would like to route through with Ocelot as this will not work.
+The administration uses the ``MapWhen`` functionality of ASP.NET Core and all requests to "**{root}/administration**" will be sent there not to the Ocelot middleware.
 
 The secret is the client secret that Ocelot's internal IdentityServer will use to authenticate requests to the administration API. This can be whatever you want it to be!
+In order to pass this secret string as parameter we must call the ``AddAdministration()`` extension of the ``OcelotBuilder`` being returned by ``AddOcelot()`` [#f1]_ like below:
 
 .. code-block:: csharp
 
@@ -58,30 +64,33 @@ The secret is the client secret that Ocelot's internal IdentityServer will use t
             .AddAdministration("/administration", "secret");
     }
 
-In order for the administration API to work, Ocelot / IdentityServer must be able to call itself for validation. This means that you need to add the base url of Ocelot to global configuration if it is not default (http://localhost:5000). Please note if you are using something like docker to host Ocelot it might not be able to call back to localhost etc and you need to know what you are doing with docker networking in this scenario. Anyway this can be done as follows..
+In order for the administration API to work, Ocelot / IdentityServer must be able to call itself for validation. 
+This means that you need to add the base URL of Ocelot to global configuration if it is not default (http://localhost:5000). 
+Please note, if you are using something like Docker to host Ocelot it might not be able to call back to **localhost** etc and you need to know what you are doing with Docker networking in this scenario. 
+Anyway, this can be done as follows.
 
-If you want to run on a different host and port locally..
+If you want to run on a different host and port locally:
 
 .. code-block:: json
 
  "GlobalConfiguration": {
     "BaseUrl": "http://localhost:55580"
   }
 
-or if Ocelot is exposed via dns
+or if Ocelot is exposed via DNS:
 
 .. code-block:: json
 
  "GlobalConfiguration": {
     "BaseUrl": "http://mydns.com"
   }
 
-Now if you went with the configuration options above and want to access the API you can use the postman scriptscalled ocelot.postman_collection.json in the solution to change the Ocelot configuration. Obviously these will need to be changed if you are running Ocelot on a different url to http://localhost:5000.
-
+Now if you went with the configuration options above and want to access the API you can use the Postman scripts called **ocelot.postman_collection.json** in the solution to change the Ocelot configuration. 
+Obviously these will need to be changed if you are running Ocelot on a different URL to http://localhost:5000.
 
-The scripts show you how to request a bearer token from ocelot and then use it to GET the existing configuration and POST a configuration.
+The scripts show you how to request a Bearer token from Ocelot and then use it to GET the existing configuration and POST a configuration.
 
-If you are running multiple Ocelot instances in a cluster then you need to use a certificate to sign the bearer tokens used to access the administration API.
+If you are running multiple Ocelot instances in a cluster then you need to use a certificate to sign the Bearer tokens used to access the administration API.
 
 In order to do this you need to add two more environmental variables for each Ocelot in the cluster.
 
@@ -90,11 +99,11 @@ In order to do this you need to add two more environmental variables for each Oc
 ``OCELOT_CERTIFICATE_PASSWORD``
     The password for the certificate.
 
-Normally Ocelot just uses temporary signing credentials but if you set these environmental variables then it will use the certificate. If all the other Ocelot instances in thecluster have the same certificate then you are good!
-
+Normally Ocelot just uses temporary signing credentials but if you set these environmental variables then it will use the certificate. 
+If all the other Ocelot instances in the cluster have the same certificate then you are good!
 
 Administration API
-^^^^^^^^^^^^^^^^^^
+------------------
 
 **POST {adminPath}/connect/token**
 
@@ -117,15 +126,19 @@ This gets the current Ocelot configuration. It is exactly the same JSON we use t
 
 **POST {adminPath}/configuration**
 
-This overrwrites the existing configuration (should probably be a put!). I reccomend getting your config from the GET endpoint, making any changes and posting it back...simples.
+This overwrites the existing configuration (should probably be a put!). I recommend getting your config from the GET endpoint, making any changes and posting it back...simples.
 
-The body of the request is JSON and it is the same format as the FileConfiguration.cs that we use to set up 
-Ocelot on a file system. 
+The body of the request is JSON and it is the same format as the FileConfiguration.cs that we use to set up Ocelot on a file system. 
 
-Please note that if you want to use this API then the process running Ocelot must have permission to write to the disk where your ocelot.json or ocelot.{environment}.json is located. This is because Ocelot will overwrite them on save. 
+Please note that if you want to use this API then the process running Ocelot must have permission to write to the disk where your **ocelot.json** or **ocelot.{environment}.json** is located.
+This is because Ocelot will overwrite them on save. 
 
 **DELETE {adminPath}/outputcache/{region}**
 
 This clears a region of the cache. If you are using a backplane it will clear all instances of the cache! Giving your the ability to run a cluster of Ocelots and cache over all of them in memory and clear them all at the same time / just use a distributed cache.
 
 The region is whatever you set against the Region field in the FileCacheOptions section of the Ocelot configuration.
+
+""""
+
+.. [#f1] The ``AddOcelot`` method adds default ASP.NET services to DI-container. You could call another more extended ``AddOcelotUsingBuilder`` method while configuring services to build and use custom builder via an ``IMvcCoreBuilder`` interface object. See more instructions in :doc:`../features/dependencyinjection`, "**The AddOcelotUsingBuilder method**" section.