diff --git a/ReleaseNotes.md b/ReleaseNotes.md
index 06d1ab38a..422d18621 100644
--- a/ReleaseNotes.md
+++ b/ReleaseNotes.md
@@ -1,54 +1,4 @@
-## February 2024 (version {0}) aka [Lunar Eclipse](https://www.timeanddate.com/eclipse/lunar/2024-march-25) release
-> Codenamed: **[Lunar Eclipse](https://www.bing.com/search?q=Lunar+Eclipse+2024)**
-> Read the Docs: [Ocelot 23.2](https://ocelot.readthedocs.io/en/23.2.0/)
+## Documentation patch (version {0}) for [{1}](https://github.com/ThreeMammals/Ocelot/releases/tag/{1}) release
+> Read the Docs: [Ocelot 23.2](https://ocelot.readthedocs.io/en/{0}/)
-### What's new?
-
-- **[Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html)**: A brand new [Merging files to memory](https://ocelot.readthedocs.io/en/23.2.0/features/configuration.html#merging-files-to-memory) by @ebjornset as a part of the [Merging Configuration Files](https://ocelot.readthedocs.io/en/23.2.0/features/configuration.html#merging-configuration-files) feature.
- The `AddOcelot` method merges the **ocelot.*.json** files into a single **ocelot.json** file as the primary configuration file, which is written back to disk and then added to the `IConfigurationBuilder` for the well-known `IConfiguration`. You can now call another `AddOcelot` method that adds the merged JSON directly from memory to the `IConfigurationBuilder`, using `AddJsonStream` instead.
- See more details in [Configuration Overview](https://ocelot.readthedocs.io/en/23.2.0/features/dependencyinjection.html#configuration-overview) of [Dependency Injection](https://ocelot.readthedocs.io/en/23.2.0/features/dependencyinjection.html).
-- **[Service Fabric](https://ocelot.readthedocs.io/en/latest/features/servicefabric.html)**: Published old undocumented "[Placeholders in Service Name](https://ocelot.readthedocs.io/en/23.2.0/features/servicefabric.html#placeholders-in-service-name)" feature of [Service Fabric](https://ocelot.readthedocs.io/en/23.2.0/features/servicefabric.html) [service discovery provider](https://ocelot.readthedocs.io/en/23.2.0/search.html?q=ServiceDiscoveryProvider).
- This feature by @FelixBoers is available starting from version [13.0.0](https://github.com/ThreeMammals/Ocelot/releases/tag/13.0.0).
-- **[Quality of Service](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html)**: A brand new [Polly](https://github.com/App-vNext/Polly) v8 pipelines [Extensibility](https://ocelot.readthedocs.io/en/23.2.0/features/qualityofservice.html#extensibility) feature by @RaynaldM
-
-### Focus On
-
-
- Updates of the features: Configuration, Dependency Injection and QoS
-
- - [Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html): New [Merging files to memory](https://ocelot.readthedocs.io/en/23.2.0/features/configuration.html#merging-files-to-memory) feature by @ebjornset
- - [Dependency Injection](https://ocelot.readthedocs.io/en/latest/features/dependencyinjection.html): Added new overloaded [AddOcelot methods](https://ocelot.readthedocs.io/en/23.2.0/features/dependencyinjection.html#addocelot-method) by @ebjornset
- - [Quality of Service](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html): Support of new [Polly](https://github.com/App-vNext/Polly) v8 syntax and new [Extensibility](https://ocelot.readthedocs.io/en/23.2.0/features/qualityofservice.html#extensibility) feature by @RaynaldM
-
-
-
- Ocelot extra packages
-
- - [Ocelot.Provider.Polly](https://www.nuget.org/packages/Ocelot.Provider.Polly): Support of new [Polly](https://github.com/App-vNext/Polly) v8 syntax.
- *Polly* [8.0+](https://github.com/App-vNext/Polly/releases) versions introduced the concept of [resilience pipelines](https://www.pollydocs.org/pipelines/).
- All [AddPolly extensions](https://github.com/ThreeMammals/Ocelot/blob/develop/src/Ocelot.Provider.Polly/OcelotBuilderExtensions.cs) have been automatically migrated from **v7** to **v8**.
- Please note that older **v7** extensions are marked with the `[Obsolete]` attribute and renamed using the `V7` suffix. And the old **v7** implementation has been moved to the [v7 namespace](https://github.com/ThreeMammals/Ocelot/tree/develop/src/Ocelot.Provider.Polly/v7).
- See more details in [Polly v7 vs v8](https://ocelot.readthedocs.io/en/23.2.0/features/qualityofservice.html#polly-v7-vs-v8) section of [Quality of Service](https://ocelot.readthedocs.io/en/23.2.0/features/qualityofservice.html) chapter.
-
-
-
- Stabilization aka bug fixing
-
- - [683](https://github.com/ThreeMammals/Ocelot/issues/683) by PR [1927](https://github.com/ThreeMammals/Ocelot/pull/1927)
- [New rules](https://github.com/search?q=repo%3AThreeMammals%2FOcelot+IsPlaceholderNotDuplicatedIn+IsUpstreamPlaceholderDefinedInDownstream+IsDownstreamPlaceholderDefinedInUpstream&type=code) have been added to Ocelot's configuration validation logic to find duplicate placeholders in path templates.
- See more in the [FileConfigurationFluentValidator](https://github.com/search?q=repo%3AThreeMammals%2FOcelot%20FileConfigurationFluentValidator&type=code) class. Thanks to @AlyHKafoury!
- - [1518](https://github.com/ThreeMammals/Ocelot/issues/1518) hotfix by PR [1986](https://github.com/ThreeMammals/Ocelot/pull/1986)
- Using the default `IServiceCollection` [DI extensions](https://github.com/ThreeMammals/Ocelot/blob/develop/src/Ocelot/DependencyInjection/ServiceCollectionExtensions.cs) to register Ocelot services resulted in the `ServiceCollection` provider being forced to be created by calling `BuildServiceProvider()`.
- This resulted in problems with dependency injection libraries, or worse, causing the Ocelot app to crash!
- See more in the [ServiceCollectionExtensions](https://github.com/search?q=repo%3AThreeMammals%2FOcelot+ServiceCollectionExtensions&type=code) class. Thanks to @ArwynFr!
- - See [all bugs](https://github.com/ThreeMammals/Ocelot/issues?q=is%3Aissue+is%3Aclosed+label%3Abug+milestone%3AFebruary%2724) of the [February'24](https://github.com/ThreeMammals/Ocelot/milestone/5) milestone
-
-
-
- Documentation for version 23.2
-
- - [Configuration](https://ocelot.readthedocs.io/en/23.2.0/features/configuration.html)
- - [Dependency Injection](https://ocelot.readthedocs.io/en/23.2.0/features/dependencyinjection.html)
- - [Quality of Service](https://ocelot.readthedocs.io/en/23.2.0/features/qualityofservice.html)
- - [Service Fabric](https://ocelot.readthedocs.io/en/23.2.0/features/servicefabric.html)
-
+This is a technical release: no other information.
diff --git a/build.cake b/build.cake
index 2b1c99828..680d2c0bf 100644
--- a/build.cake
+++ b/build.cake
@@ -56,6 +56,7 @@ var nugetFeedStableSymbolsUploadUrl = "https://www.nuget.org/api/v2/package";
string committedVersion = "0.0.0-dev";
GitVersion versioning = null;
int releaseId = 0;
+bool IsTechnicalRelease = true;
string gitHubUsername = "TomPallister";
string gitHubPassword = Environment.GetEnvironmentVariable("OCELOT_GITHUB_API_KEY");
@@ -83,7 +84,7 @@ Task("RunTests")
.IsDependentOn("RunIntegrationTests");
Task("Release")
- .IsDependentOn("Build")
+ //.IsDependentOn("Build")
.IsDependentOn("CreateReleaseNotes")
.IsDependentOn("CreateArtifacts")
.IsDependentOn("PublishGitHubRelease")
@@ -154,12 +155,18 @@ Task("CreateReleaseNotes")
var lastReleaseTags = GitHelper("describe --tags --abbrev=0 --exclude net*");
var lastRelease = lastReleaseTags.First(t => !t.StartsWith("net")); // skip 'net*-vX.Y.Z' tag and take 'major.minor.build'
- Information("Last release tag is " + lastRelease);
-
var releaseVersion = versioning.NuGetVersion;
+
// Read main header from Git file, substitute version in header, and add content further...
+ Information("{0} New release tag is " + releaseVersion);
+ Information("{1} Last release tag is " + lastRelease);
var releaseHeader = string.Format(System.IO.File.ReadAllText("./ReleaseNotes.md"), releaseVersion, lastRelease);
releaseNotes = new List { releaseHeader };
+ if (IsTechnicalRelease)
+ {
+ WriteReleaseNotes();
+ return;
+ }
var shortlogSummary = GitHelper($"shortlog --no-merges --numbered --summary {lastRelease}..HEAD")
.ToList();
@@ -298,6 +305,7 @@ Task("CreateReleaseNotes")
}
}
} // END of Top 3
+
releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:");
releaseNotes.AddRange(topContributors);
releaseNotes.Add("");
@@ -415,20 +423,23 @@ Task("RunIntegrationTests")
Task("CreateArtifacts")
.IsDependentOn("CreateReleaseNotes")
- .IsDependentOn("Compile")
- .Does(() =>
+ //.IsDependentOn("Compile")
+ .Does(() =>
{
WriteReleaseNotes();
System.IO.File.AppendAllLines(artifactsFile, new[] { "ReleaseNotes.md" });
- CopyFiles("./src/**/Release/Ocelot.*.nupkg", packagesDir);
- var projectFiles = GetFiles("./src/**/Release/Ocelot.*.nupkg");
- foreach(var projectFile in projectFiles)
+ if (!IsTechnicalRelease)
{
- System.IO.File.AppendAllLines(
- artifactsFile,
- new[] { projectFile.GetFilename().FullPath }
- );
+ CopyFiles("./src/**/Release/Ocelot.*.nupkg", packagesDir);
+ var projectFiles = GetFiles("./src/**/Release/Ocelot.*.nupkg");
+ foreach(var projectFile in projectFiles)
+ {
+ System.IO.File.AppendAllLines(
+ artifactsFile,
+ new[] { projectFile.GetFilename().FullPath }
+ );
+ }
}
var artifacts = System.IO.File.ReadAllLines(artifactsFile)
@@ -511,13 +522,21 @@ Task("PublishToNuget")
.IsDependentOn("DownloadGitHubReleaseArtifacts")
.Does(() =>
{
- Information("Skipping of publishing to NuGet...");
+ if (IsTechnicalRelease)
+ {
+ Information("Skipping of publishing to NuGet because of technical release...");
+ return;
+ }
+
if (IsRunningOnCircleCI())
{
+ Information("Publish to NuGet...");
PublishPackages(packagesDir, artifactsFile, nugetFeedStableKey, nugetFeedStableUploadUrl, nugetFeedStableSymbolsUploadUrl);
}
});
+Task("Void").Does(() => {});
+
RunTarget(target);
private void GenerateReport(Cake.Core.IO.FilePath coverageSummaryFile)
diff --git a/docs/features/configuration.rst b/docs/features/configuration.rst
index 7ae03bb93..b6e6bd2ef 100644
--- a/docs/features/configuration.rst
+++ b/docs/features/configuration.rst
@@ -75,19 +75,19 @@ More information on how to use these options is below.
Multiple Environments
---------------------
-Like any other ASP.NET Core project Ocelot supports configuration file names such as **appsettings.dev.json**, **appsettings.test.json** etc.
+Like any other ASP.NET Core project Ocelot supports configuration file names such as ``appsettings.dev.json``, ``appsettings.test.json`` etc.
In order to implement this add the following to you:
.. code-block:: csharp
- ConfigureAppConfiguration((hostingContext, config) =>
+ ConfigureAppConfiguration((context, config) =>
{
- var env = hostingContext.HostingEnvironment;
+ var env = context.HostingEnvironment;
config.SetBasePath(env.ContentRootPath)
.AddJsonFile("appsettings.json", true, true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", true, true)
- .AddJsonFile("ocelot.json")
- .AddJsonFile($"ocelot.{env.EnvironmentName}.json")
+ .AddJsonFile("ocelot.json") // primary config file
+ .AddJsonFile($"ocelot.{env.EnvironmentName}.json") // environment file
.AddEnvironmentVariables();
})
@@ -98,18 +98,18 @@ More info on this can be found in the ASP.NET Core docs: `Use multiple environme
.. _config-merging-files:
-Merging Configuration Files [#f1]_
-----------------------------------
+Merging Configuration Files
+---------------------------
-This feature allows users to have multiple configuration files to make managing large configurations easier [#f1]_.
+This feature allows users to have multiple configuration files to make managing large configurations easier. [#f1]_
-Instead of adding the configuration directly e.g. ``AddJsonFile("ocelot.json")`` you can call ``AddOcelot()`` like below:
+Rather than directly adding the configuration e.g., using ``AddJsonFile("ocelot.json")``, you can achieve the same result by invoking ``AddOcelot()`` as shown below:
.. code-block:: csharp
- ConfigureAppConfiguration((hostingContext, config) =>
+ ConfigureAppConfiguration((context, config) =>
{
- var env = hostingContext.HostingEnvironment;
+ var env = context.HostingEnvironment;
config.SetBasePath(env.ContentRootPath)
.AddJsonFile("appsettings.json", true, true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", true, true)
@@ -118,9 +118,9 @@ Instead of adding the configuration directly e.g. ``AddJsonFile("ocelot.json")``
})
In this scenario Ocelot will look for any files that match the pattern ``^ocelot\.(.*?)\.json$`` and then merge these together.
-If you want to set the **GlobalConfiguration** property, you must have a file called **ocelot.global.json**.
+If you want to set the **GlobalConfiguration** property, you must have a file called ``ocelot.global.json``.
-The way Ocelot merges the files is basically load them, loop over them, add any Routes, add any **AggregateRoutes** and if the file is called **ocelot.global.json** add the **GlobalConfiguration** aswell as any Routes or **AggregateRoutes**.
+The way Ocelot merges the files is basically load them, loop over them, add any **Routes**, add any **AggregateRoutes** and if the file is called ``ocelot.global.json`` add the **GlobalConfiguration** aswell as any **Routes** or **AggregateRoutes**.
Ocelot will then save the merged configuration to a file called `ocelot.json`_ and this will be used as the source of truth while Ocelot is running.
At the moment there is no validation at this stage it only happens when Ocelot validates the final merged configuration.
@@ -134,9 +134,9 @@ You can also give Ocelot a specific path to look in for the configuration files
.. code-block:: csharp
- ConfigureAppConfiguration((hostingContext, config) =>
+ ConfigureAppConfiguration((context, config) =>
{
- var env = hostingContext.HostingEnvironment;
+ var env = context.HostingEnvironment;
config.SetBasePath(env.ContentRootPath)
.AddJsonFile("appsettings.json", true, true)
.AddJsonFile($"appsettings.{env.EnvironmentName}.json", true, true)
@@ -151,38 +151,41 @@ Ocelot needs the ``HostingEnvironment`` so it knows to exclude anything environm
Merging files to memory [#f2]_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By default Ocelot writes the merged configuration back to disk as `ocelot.json`_ (primary configuration file) with adding the file to config.
+By default, Ocelot writes the merged configuration to disk as `ocelot.json`_ (the primary configuration file) by adding the file to the ASP.NET configuration provider.
-If your server don't have write permissions to your configuration folder, you can instruct Ocelot to use the merged configuration directly from memory instead, like this:
+If your web server lacks write permissions for the configuration folder, you can instruct Ocelot to use the merged configuration directly from memory.
+Here's how:
.. code-block:: csharp
// It implicitly calls ASP.NET AddJsonStream extension method for IConfigurationBuilder
// config.AddJsonStream(new MemoryStream(Encoding.UTF8.GetBytes(json)));
- config.AddOcelot(hostingContext.HostingEnvironment, MergeOcelotJson.ToMemory);
+ config.AddOcelot(context.HostingEnvironment, MergeOcelotJson.ToMemory);
-This feature is extremely useful in a cloud environment such as Azure, AWS, GCP where the application may not have enough write permissions to save files.
-Additionally, the Docker container environment may lack permissions and would require significant DevOps effort to implement file write operation.
-So don't waste your time: use the feature! [#f2]_
+This feature proves exceptionally valuable in cloud environments like Azure, AWS, and GCP, especially when the app lacks sufficient write permissions to save files.
+Furthermore, within Docker container environments, permissions can be scarce, necessitating substantial DevOps efforts to enable file write operations.
+Therefore, save time by leveraging this feature! [#f2]_
Reload JSON Config On Change
----------------------------
-Ocelot supports reloading the JSON configuration file on change. For instance, the following will recreate Ocelot internal configuration when the `ocelot.json`_ file is updated manually:
+Ocelot supports reloading the JSON configuration file on change.
+For instance, the following will recreate Ocelot internal configuration when the `ocelot.json`_ file is updated manually:
.. code-block:: csharp
config.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true); // ASP.NET framework version
-Please note: as of version `23.2`_, most ``AddOcelot`` methods have optional ``bool?`` arguments aka ``optional`` and ``reloadOnChange``.
-So, you can supply these arguments to the internal ``AddJsonFile`` call in the last step of configuring (see `AddOcelotJsonFile `_) e.g.
+Important Note: Starting from version `23.2`_, most :ref:`di-configuration-addocelot` include optional ``bool?`` arguments, specifically ``optional`` and ``reloadOnChange``.
+Therefore, you have the flexibility to provide these arguments when invoking the internal ``AddJsonFile`` method during the final configuration step (see `AddOcelotJsonFile `_ implementation):
.. code-block:: csharp
config.AddJsonFile(ConfigurationBuilderExtensions.PrimaryConfigFile, optional ?? false, reloadOnChange ?? false);
-As you see, in previous versions less than `23.2`_ ``AddOcelot`` extension methods didn't apply the ``reloadOnChange`` arg because it was ``false``.
-Finally, we recommend to control reloading by ``AddOcelot`` extension methods instead of usage of the framework ``AddJsonFile`` one e.g.
+As you can see, in versions prior to `23.2`_, the `AddOcelot extension methods `_ did not apply the ``reloadOnChange`` argument because it was set to ``false``.
+We recommend using the ``AddOcelot`` extension methods to control reloading, rather than relying on the framework's ``AddJsonFile`` method.
+For example:
.. code-block:: csharp
@@ -199,7 +202,7 @@ Finally, we recommend to control reloading by ``AddOcelot`` extension methods in
config.AddOcelot(configuration, env, mergeTo, optional: false, reloadOnChange: true); // with configuration object, environment and merging type
})
-It would be useful to look into `the ConfigurationBuilderExtensions class `_ code and note something to better understand the signatures of the overloaded methods [#f2]_.
+Examining the code within the `ConfigurationBuilderExtensions class `_ would be helpful for gaining a better understanding of the signatures of the overloaded methods [#f2]_.
Store Configuration in Consul
-----------------------------
@@ -215,8 +218,7 @@ In order to register Consul services we must call the ``AddConsul()`` and ``AddC
.. code-block:: csharp
- services
- .AddOcelot()
+ services.AddOcelot()
.AddConsul()
.AddConfigStoredInConsul();
@@ -398,10 +400,10 @@ Ocelot allows you to choose the HTTP version it will use to make the proxy reque
Dependency Injection
--------------------
-*Dependency Injection* for this **Configuration** feature in Ocelot is designed to extend and/or control **configuring** of Ocelot core before the stage of building ASP.NET MVC pipeline services.
-The main method is :ref:`di-configuration-addocelot` of the `ConfigurationBuilderExtensions`_ class which has a bunch of overloaded versions with corresponding signatures.
+*Dependency Injection* for this **Configuration** feature in Ocelot is designed to extend and/or control **the configuration** of the Ocelot kernel before the stage of building ASP.NET MVC pipeline services.
+The primary methods are :ref:`di-configuration-addocelot` within the `ConfigurationBuilderExtensions`_ class, which offers several overloaded versions with corresponding signatures.
-Use them in the following ``ConfigureAppConfiguration`` method (**Program.cs** and **Startup.cs**) of your ASP.NET MVC gateway app (minimal web app) to configure Ocelot pipeline and services:
+You can utilize these methods in the ``ConfigureAppConfiguration`` method (located in both **Program.cs** and **Startup.cs**) of your ASP.NET MVC gateway app (minimal web app) to configure the Ocelot pipeline and services.
.. code-block:: csharp
@@ -412,11 +414,11 @@ Use them in the following ``ConfigureAppConfiguration`` method (**Program.cs** a
IWebHostBuilder ConfigureAppConfiguration(Action configureDelegate);
}
-More details you could find in the special ":ref:`di-configuration-overview`" section and in subsequent sections of the :doc:`../features/dependencyinjection` feature.
+You can find additional details in the dedicated :ref:`di-configuration-overview` section and in subsequent sections related to the :doc:`../features/dependencyinjection` chapter.
""""
-.. [#f1] ":ref:`config-merging-files`" feature was requested in `issue 296 `_, since then we extended it in `issue 1216 `_ (PR `1227 `_) as ":ref:`config-merging-tomemory`" subfeature which was released as a part of the version `23.2`_.
+.. [#f1] ":ref:`config-merging-files`" feature was requested in `issue 296 `_, since then we extended it in `issue 1216 `_ (PR `1227 `_) as ":ref:`config-merging-tomemory`" subfeature which was released as a part of version `23.2`_.
.. [#f2] ":ref:`config-merging-tomemory`" subfeature is based on the ``MergeOcelotJson`` enumeration type with values: ``ToFile`` and ``ToMemory``. The 1st one is implicit by default, and the second one is exactly what you need when merging to memory. See more details on implementations in the `ConfigurationBuilderExtensions`_ class.
.. [#f3] :ref:`di-the-addocelot-method` adds default ASP.NET services to DI container. You could call another extended :ref:`di-addocelotusingbuilder-method` while configuring services to develop your own :ref:`di-custom-builder`. See more instructions in the ":ref:`di-addocelotusingbuilder-method`" section of :doc:`../features/dependencyinjection` feature.
.. [#f4] ":ref:`config-consul-key`" feature was requested in `issue 346 `_ as a part of version `7.0.0 `_.
diff --git a/docs/features/dependencyinjection.rst b/docs/features/dependencyinjection.rst
index c8e8030ea..dbd3437f6 100644
--- a/docs/features/dependencyinjection.rst
+++ b/docs/features/dependencyinjection.rst
@@ -230,9 +230,9 @@ This is just one common use case, and you can add additional services to the bui
Configuration Overview
----------------------
-*Dependency Injection* for the :doc:`../features/configuration` feature in Ocelot is designed to extend and/or control **configuring** of Ocelot core before the stage of building ASP.NET MVC pipeline services.
+*Dependency Injection* for the :doc:`../features/configuration` feature in Ocelot is designed to extend and/or control **the configuration** of Ocelot kernel before the stage of building ASP.NET MVC pipeline services.
-Use :ref:`di-configuration-extensions` in the following ``ConfigureAppConfiguration`` method (**Program.cs** and **Startup.cs**) of your app (minimal web app) to configure Ocelot pipeline and services:
+To configure the Ocelot pipeline and services, use the :ref:`di-configuration-extensions` in the following ``ConfigureAppConfiguration`` method (located in *Program.cs* and *Startup.cs*) of your minimal web app:
.. code-block:: csharp
@@ -250,14 +250,17 @@ Use :ref:`di-configuration-extensions` in the following ``ConfigureAppConfigurat
| **Namespace**: ``Ocelot.DependencyInjection``
| **Class**: `ConfigurationBuilderExtensions`_
-The main one is the :ref:`di-configuration-addocelot` of the `ConfigurationBuilderExtensions`_ class, which has a list of overloaded versions with corresponding signatures.
+The main methods are the :ref:`di-configuration-addocelot` within the `ConfigurationBuilderExtensions`_ class.
+This method has a list of overloaded versions with corresponding signatures.
-The purpose of the method is to prepare everything before actually configuring with native extensions:
-merge partial JSON files, select a merge type to save the merged JSON configuration data ``ToFile`` or ``ToMemory``,
-and finally call the following native ``IConfigurationBuilder`` framework extensions:
+The purpose of this method is to prepare everything before actually configuring with native extensions. It involves the following steps:
-* ``AddJsonFile`` finally adds primary configuration file (aka `ocelot.json`_) after the merge stage writing the file back **to the file system** using the ``ToFile`` merge type option, which is implicitly the default.
-* ``AddJsonStream`` finally adds the JSON data of the primary configuration file as a UTF-8 stream after the merge stage **into memory** using the ``ToMemory`` merge type option.
+1. **Merging Partial JSON Files**: The ``GetMergedOcelotJson`` method merges partial JSON files.
+2. **Selecting Merge Type**: It allows you to choose a merge type to save the merged JSON configuration data either ``ToFile`` or ``ToMemory``.
+3. **Framework Extensions**: Finally, the method calls the following native ``IConfigurationBuilder`` framework extensions:
+
+ * The ``AddJsonFile`` method adds the primary configuration file (commonly known as `ocelot.json`_) after the merge stage. It writes the file back **to the file system** using the ``ToFile`` merge type option, which is implicitly the default.
+ * The ``AddJsonStream`` method adds the JSON data of the primary configuration file as a UTF-8 stream **into memory** after the merge stage. It uses the ``ToMemory`` merge type option.
.. _di-configuration-addocelot:
@@ -271,7 +274,7 @@ and finally call the following native ``IConfigurationBuilder`` framework extens
IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, IWebHostEnvironment env);
IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, string folder, IWebHostEnvironment env);
-**Note!** These versions use implicit ``ToFile`` merge type to write `ocelot.json`_ back to a disk and finally they call the ``AddJsonFile`` extension.
+**Note**: These versions use the implicit ``ToFile`` merge type to write `ocelot.json`_ back to disk. Finally, they call the ``AddJsonFile`` extension.
**Signatures** of the versions to specify a ``MergeOcelotJson`` option:
@@ -282,8 +285,8 @@ and finally call the following native ``IConfigurationBuilder`` framework extens
IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, string folder, IWebHostEnvironment env, MergeOcelotJson mergeTo,
string primaryConfigFile = null, string globalConfigFile = null, string environmentConfigFile = null, bool? optional = null, bool? reloadOnChange = null);
-**Note!** These versions have optional arguments to specify the location of 3 main files that are involved in the merge operation.
-In theory, these files can be located anywhere, but in practice it is better to keep the files in one folder.
+**Note**: These versions include optional arguments to specify the location of the three main files involved in the merge operation.
+In theory, these files can be located anywhere, but in practice, it is better to keep them in one folder.
**Signatures** of the versions to indicate the ``FileConfiguration`` object of a self-created out-of-the-box configuration: [#f1]_
@@ -294,13 +297,13 @@ In theory, these files can be located anywhere, but in practice it is better to
IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, FileConfiguration fileConfiguration, IWebHostEnvironment env, MergeOcelotJson mergeTo,
string primaryConfigFile = null, string globalConfigFile = null, string environmentConfigFile = null, bool? optional = null, bool? reloadOnChange = null);
-| **Note 1**. These versions have optional arguments to specify the location of 3 main files that are involved in the merge operation.
-| **Note 2**. Your ``FileConfiguration`` object can be serialized/deserialized to/from anywhere: local or remote storages, Consul KV storage and even a database.
- Please, read more about this super useful feature in PR `1569`_ [#f1]_.
+| **Note 1**: These versions include optional arguments to specify the location of the three main files involved in the merge operation.
+| **Note 2**: Your ``FileConfiguration`` object can be serialized/deserialized from anywhere: local or remote storage, Consul KV storage, and even a database.
+ For more information about this super useful feature, please read PR `1569`_ [#f1]_.
""""
-.. [#f1] Dynamic :doc:`../features/configuration` feature was requested in issues `1228`_, `1235`_, and delivered by PR `1569`_ as a part of the version `20.0`_. Since then we extended it in PR `1227`_ and released it as a part of the version `23.2`_.
+.. [#f1] The Dynamic :doc:`../features/configuration` feature was requested in issues `1228`_ and `1235`_. It was delivered by PR `1569`_ as part of version `20.0`_. Since then, we have extended it in PR `1227`_ and released it as part of version `23.2`_.
.. _ServiceCollectionExtensions: https://github.com/ThreeMammals/Ocelot/blob/develop/src/Ocelot/DependencyInjection/ServiceCollectionExtensions.cs#L7
.. _ConfigurationBuilderExtensions: https://github.com/ThreeMammals/Ocelot/blob/develop/src/Ocelot/DependencyInjection/ConfigurationBuilderExtensions.cs
diff --git a/docs/features/qualityofservice.rst b/docs/features/qualityofservice.rst
index e4c8216dc..799efdc08 100644
--- a/docs/features/qualityofservice.rst
+++ b/docs/features/qualityofservice.rst
@@ -54,18 +54,19 @@ If someone needs this to be configurable, open an issue. [#f2]_
`Polly`_ v7 vs v8
-----------------
-**Important changes** of the version `23.2`_: [#f3]_
- - with `Polly`_ version 8, ``ExceptionsAllowedBeforeBreaking`` must be equal to or greater than ``2``!
- - the ``AddPolly`` method has been migrated from v7 policy wrappers to v8 resilience pipelines, so it has different behaviour now based on v8 pipelines!
+Important changes in version `23.2`_: [#f3]_
-If you don't want to change your settings, you must use `Polly`_ v7 like this:
+ - With `Polly`_ version 8+, the ``ExceptionsAllowedBeforeBreaking`` value must be equal to or greater than **2**!
+ - The ``AddPolly`` method has been migrated from v7 policy wrappers to v8 resilience pipelines. Consequently, it now exhibits different behavior based on v8 pipelines.
+
+If you prefer not to modify your settings, you can continue using `Polly`_ v7 as follows:
.. code-block:: csharp
services.AddOcelot()
.AddPollyV7();
-**Please note!** Support for `Polly`_ v7 will be removed in a future version, so we advise you not to use this method (tagged as ``Obsolete``) unless you really have to.
+**Note**: Support for `Polly`_ v7 will be removed in a future version. We recommend avoiding this method (which is tagged as ``Obsolete``) unless absolutely necessary.
.. _qos-extensibility:
@@ -114,7 +115,7 @@ And finally, if you want to define your own set of exceptions to map, you can us
.. [#f1] :ref:`di-the-addocelot-method` adds default ASP.NET services to DI container. You could call another extended :ref:`di-addocelotusingbuilder-method` while configuring services to develop your own :ref:`di-custom-builder`. See more instructions in the ":ref:`di-addocelotusingbuilder-method`" section of :doc:`../features/dependencyinjection` feature.
.. [#f2] If something doesn't work or you get stuck, please review current `QoS issues `_ filtering by |QoS_label| label.
-.. [#f3] We upgraded `Polly`_ version from v7.x to v8.x! The :ref:`qos-extensibility` feature was requested in issue `1875`_ and delivered by PR `1914`_ as a part of the version `23.2`_.
+.. [#f3] We upgraded `Polly`_ version from v7.x to v8.x! The :ref:`qos-extensibility` feature was requested in issue `1875`_ and delivered by PR `1914`_ as a part of version `23.2`_.
.. _Polly: https://www.thepollyproject.org
.. _1875: https://github.com/ThreeMammals/Ocelot/issues/1875
diff --git a/docs/features/servicefabric.rst b/docs/features/servicefabric.rst
index a9fe7595e..9e4206afb 100644
--- a/docs/features/servicefabric.rst
+++ b/docs/features/servicefabric.rst
@@ -48,18 +48,17 @@ Placeholders in Service Name [#f1]_
In Ocelot, you can insert placeholders for variables into your ``UpstreamPathTemplate`` and ``ServiceName`` using the format ``{something}``.
-It's important to note that the placeholder variable must exist in both the (**DownstreamPathTemplate** vs **ServiceName**) and the **UpstreamPathTemplate**.
-The **UpstreamPathTemplate** should include all placeholders from the **DownstreamPathTemplate** and **ServiceName**;
-otherwise, Ocelot will not start due to validation errors, which are logged.
-
-Once the validation stage is cleared, Ocelot will replace the placeholder values in the **UpstreamPathTemplate** with those in the **DownstreamPathTemplate** and/or **ServiceName** for each processed request.
-Thus, the :ref:`sf-placeholders` behave similarly to the :ref:`routing-placeholders` feature, but with the **ServiceName** property considered during the processing.
+Important Note: The placeholder variable must exist in both the ``DownstreamPathTemplate`` (or ``ServiceName``) and the ``UpstreamPathTemplate``.
+Specifically, the ``UpstreamPathTemplate`` should include all placeholders from the ``DownstreamPathTemplate`` and ``ServiceName``.
+Failure to do so will result in Ocelot not starting due to validation errors, which are logged.
+Once the validation stage is cleared, Ocelot will replace the placeholder values in the ``UpstreamPathTemplate`` with those from the ``DownstreamPathTemplate`` and/or ``ServiceName`` for each processed request.
+Thus, the :ref:`sf-placeholders` behave similarly to the :ref:`routing-placeholders` feature, but with the ``ServiceName`` property considered during processing.
Placeholders example
^^^^^^^^^^^^^^^^^^^^
-Here is the example of variable ``version`` in *Service Fabric* service name.
+Here is the example of the ``version`` variable in *Service Fabric* service name.
**Given** you have the following `ocelot.json`_:
@@ -89,7 +88,7 @@ Here is the example of variable ``version`` in *Service Fabric* service name.
""""
-.. [#f1] ":ref:`sf-placeholders`" feature was requested in issue `721`_ and delivered by PR `722`_ as a part of the version `13.0.0`_.
+.. [#f1] ":ref:`sf-placeholders`" feature was requested in issue `721`_ and delivered by PR `722`_ as a part of version `13.0.0`_.
.. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/test/Ocelot.ManualTest/ocelot.json
.. _721: https://github.com/ThreeMammals/Ocelot/issues/721