From 7d936233b3ac68122076665061c15721d3b7bcb9 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Mon, 20 Nov 2023 23:02:15 +0300 Subject: [PATCH] .NET8 Release artifacts (#1792) * Update .gitignore * Update README.md * Update docs as .NET SDK agnostic. With .NET 8 * ...and gotchas * Update release notes * Update build.cake --- .gitignore | 230 ++++++++++++++++++++++---- LICENSE.md | 4 +- README.md | 8 +- ReleaseNotes.md | 19 ++- build.cake | 75 +++++---- docs/building/building.rst | 2 +- docs/building/releaseprocess.rst | 2 +- docs/conf.py | 6 +- docs/features/configuration.rst | 2 +- docs/features/dependencyinjection.rst | 8 +- docs/features/logging.rst | 6 +- docs/features/middlewareinjection.rst | 2 +- docs/features/ratelimiting.rst | 4 +- docs/features/websockets.rst | 8 +- docs/index.rst | 2 +- docs/introduction/gettingstarted.rst | 6 +- docs/introduction/gotchas.rst | 4 +- 17 files changed, 288 insertions(+), 100 deletions(-) diff --git a/.gitignore b/.gitignore index 220172830..1c30928ce 100644 --- a/.gitignore +++ b/.gitignore @@ -1,15 +1,21 @@ ## Ignore Visual Studio temporary files, build results, and ## files generated by popular Visual Studio add-ons. +## +## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore # User-specific files +*.rsuser *.suo *.user *.userosscache *.sln.docstates -*.DS_Store + # User-specific files (MonoDevelop/Xamarin Studio) *.userprefs +# Mono auto generated files +mono_crash.* + # Build results [Dd]ebug/ [Dd]ebugPublic/ @@ -17,44 +23,62 @@ [Rr]eleases/ x64/ x86/ -build/ +[Ww][Ii][Nn]32/ +[Aa][Rr][Mm]/ +[Aa][Rr][Mm]64/ bld/ [Bb]in/ [Oo]bj/ -results/ +[Ll]og/ +[Ll]ogs/ -# Visual Studio 2015 cache/options directory +# Visual Studio 2015/2017 cache/options directory .vs/ -.vscode/ # Uncomment if you have tasks that create the project's static files in wwwroot #wwwroot/ -site/wwwroot/ + +# Visual Studio 2017 auto generated files +Generated\ Files/ # MSTest test Results [Tt]est[Rr]esult*/ [Bb]uild[Ll]og.* -# NUNIT +# NUnit *.VisualState.xml TestResult.xml +nunit-*.xml # Build Results of an ATL Project [Dd]ebugPS/ [Rr]eleasePS/ dlldata.c -# DNX +# Benchmark Results +BenchmarkDotNet.Artifacts/ + +# .NET Core project.lock.json +project.fragment.lock.json artifacts/ +# ASP.NET Scaffolding +ScaffoldingReadMe.txt + +# StyleCop +StyleCopReport.xml + +# Files built by Visual Studio *_i.c *_p.c -*_i.h +*_h.h *.ilk *.meta *.obj +*.iobj *.pch *.pdb +*.ipdb *.pgc *.pgd *.rsp @@ -64,7 +88,9 @@ artifacts/ *.tlh *.tmp *.tmp_proj +*_wpftmp.csproj *.log +*.tlog *.vspscc *.vssscc .builds @@ -83,6 +109,8 @@ ipch/ *.opensdf *.sdf *.cachefile +*.VC.db +*.VC.VC.opendb # Visual Studio profiler *.psess @@ -90,6 +118,9 @@ ipch/ *.vspx *.sap +# Visual Studio Trace Files +*.e2e + # TFS 2012 Local Workspace $tf/ @@ -101,15 +132,25 @@ _ReSharper*/ *.[Rr]e[Ss]harper *.DotSettings.user -# JustCode is a .NET coding add-in -.JustCode - # TeamCity is a build add-in _TeamCity* # DotCover is a Code Coverage Tool *.dotCover +# AxoCover is a Code Coverage Tool +.axoCover/* +!.axoCover/settings.json + +# Coverlet is a free, cross platform Code Coverage Tool +coverage*.json +coverage*.xml +coverage*.info + +# Visual Studio code coverage results +*.coverage +*.coveragexml + # NCrunch _NCrunch_* .*crunch*.local.xml @@ -141,19 +182,29 @@ publish/ # Publish Web Output *.[Pp]ublish.xml *.azurePubxml -# TODO: Comment the next line if you want to checkin your web deploy settings +# Note: Comment the next line if you want to checkin your web deploy settings, # but database connection strings (with potential passwords) will be unencrypted *.pubxml *.publishproj +# Microsoft Azure Web App publish settings. Comment the next line if you want to +# checkin your Azure Web App publish settings, but sensitive information contained +# in these scripts will be unencrypted +PublishScripts/ + # NuGet Packages *.nupkg +# NuGet Symbol Packages +*.snupkg # The packages folder can be ignored because of Package Restore -**/packages/* +**/[Pp]ackages/* # except build/, which is used as an MSBuild target. -!**/packages/build/ +!**/[Pp]ackages/build/ # Uncomment if necessary however generally it will be regenerated when needed -#!**/packages/repositories.config +#!**/[Pp]ackages/repositories.config +# NuGet v3's project.json files produces more ignorable files +*.nuget.props +*.nuget.targets # Microsoft Azure Build Output csx/ @@ -163,18 +214,20 @@ csx/ ecf/ rcf/ -# Microsoft Azure ApplicationInsights config file -ApplicationInsights.config - -# Windows Store app package directory +# Windows Store app package directories and files AppPackages/ BundleArtifacts/ +Package.StoreAssociation.xml +_pkginfo.txt +*.appx +*.appxbundle +*.appxupload # Visual Studio cache files # files ending in .cache can be ignored *.[Cc]ache # but keep track of directories ending in .cache -!*.[Cc]ache/ +!?*.[Cc]ache/ # Others ClientBin/ @@ -182,12 +235,19 @@ ClientBin/ *~ *.dbmdl *.dbproj.schemaview +*.jfm *.pfx -!mycert.pfx *.publishsettings -node_modules/ orleans.codegen.cs +# Including strong name files can present a security risk +# (https://github.com/github/gitignore/pull/2483#issue-259490424) +#*.snk + +# Since there are multiple workflows, uncomment next line to ignore bower_components +# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) +#bower_components/ + # RIA/Silverlight projects Generated_Code/ @@ -198,15 +258,22 @@ _UpgradeReport_Files/ Backup*/ UpgradeLog*.XML UpgradeLog*.htm +ServiceFabricBackup/ +*.rptproj.bak # SQL Server files *.mdf *.ldf +*.ndf # Business Intelligence projects *.rdl.data *.bim.layout *.bim_*.settings +*.rptproj.rsuser +*- [Bb]ackup.rdl +*- [Bb]ackup ([0-9]).rdl +*- [Bb]ackup ([0-9][0-9]).rdl # Microsoft Fakes FakesAssemblies/ @@ -216,6 +283,7 @@ FakesAssemblies/ # Node.js Tools for Visual Studio .ntvs_analysis.dat +node_modules/ # Visual Studio 6 build log *.plg @@ -223,6 +291,20 @@ FakesAssemblies/ # Visual Studio 6 workspace options file *.opt +# Visual Studio 6 auto-generated workspace file (contains which files were open etc.) +*.vbw + +# Visual Studio 6 auto-generated project file (contains which files were open etc.) +*.vbp + +# Visual Studio 6 workspace and project file (working project files containing files to include in project) +*.dsw +*.dsp + +# Visual Studio 6 technical files +*.ncb +*.aps + # Visual Studio LightSwitch build output **/*.HTMLClient/GeneratedArtifacts **/*.DesktopClient/GeneratedArtifacts @@ -233,25 +315,107 @@ _Pvt_Extensions # Paket dependency manager .paket/paket.exe +paket-files/ + +# FAKE - F# Make +.fake/ + +# CodeRush personal settings +.cr/personal + +# Python Tools for Visual Studio (PTVS) +__pycache__/ +*.pyc + +# Cake - Uncomment if you are using it +# tools/** +# !tools/packages.config + +# Tabs Studio +*.tss + +# Telerik's JustMock configuration file +*.jmconfig + +# BizTalk build output +*.btp.cs +*.btm.cs +*.odx.cs +*.xsd.cs + +# OpenCover UI analysis results +OpenCover/ + +# Azure Stream Analytics local run output +ASALocalRun/ + +# MSBuild Binary and Structured Log +*.binlog + +# NVidia Nsight GPU debugger configuration file +*.nvuser + +# MFractors (Xamarin productivity tool) working folder +.mfractor/ + +# Local History for Visual Studio +.localhistory/ + +# Visual Studio History (VSHistory) files +.vshistory/ + +# BeatPulse healthcheck temp database +healthchecksdb + +# Backup folder for Package Reference Convert tool in Visual Studio 2017 +MigrationBackup/ + +# Ionide (cross platform F# VS Code tools) working folder +.ionide/ + +# Fody - auto-generated XML schema +FodyWeavers.xsd + +# VS Code files for those working on multiple tools +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +*.code-workspace + +# Local History for Visual Studio Code +.history/ + +# Windows Installer files from build outputs +*.cab +*.msi +*.msix +*.msm +*.msp + +# JetBrains Rider +*.sln.iml +.idea/ + +# Visual Studio Test Results +# Quick Facts: https://file.org/extension/trx#visualstudiotestresults +# Running automated tests from the command line: https://learn.microsoft.com/en-us/previous-versions/ms182486(v=vs.140) +# Run unit tests with Test Explorer: https://learn.microsoft.com/en-us/visualstudio/test/run-unit-tests-with-test-explorer +*.trx + +# OCELOT # FAKE - F# Make .fake/ !tools/packages.config tools/ -# MacOS -.DS_Store - # Ocelot acceptance test config test/Ocelot.AcceptanceTests/ocelot.json -# Read the docstates +# Read the Docs +# https://ocelot.readthedocs.io _build/ _static/ _templates/ - -# JetBrains Rider -.idea/ - -# Test Results -*.trx diff --git a/LICENSE.md b/LICENSE.md index d47ecafdf..f81511d45 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,8 +1,8 @@ The MIT License (MIT) -Copyright (c) 2016 Tom Pallister +Copyright (c) 2023 Tom Pallister, Ocelot Core team at ThreeMammals, and GitHub Ocelot community. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index 02385e021..c4d879464 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,8 @@ A quick list of Ocelot's capabilities, for more information see the [Documentati ## Install -Ocelot is designed to work with ASP.NET Core and it targets `net7.0` framework. +Ocelot is designed to work with ASP.NET Core and it targets `net6.0`, `net7.0` and `net8.0` frameworks. [^4] + Install [Ocelot package](https://www.nuget.org/packages/Ocelot) and its dependencies using NuGet Package Manager: ```powershell Install-Package Ocelot @@ -78,7 +79,7 @@ We can also give advice on the easiest way to do things :octocat: Finally, we mark all existing issues as [![label: help wanted][~helpwanted]](https://github.com/ThreeMammals/Ocelot/labels/help%20wanted) [![label: small effort][~smalleffort]](https://github.com/ThreeMammals/Ocelot/labels/small%20effort) [![label: medium effort][~mediumeffort]](https://github.com/ThreeMammals/Ocelot/labels/medium%20effort) -[![label: large effort][~largeeffort]](https://github.com/ThreeMammals/Ocelot/labels/large%20effort) [^4]. +[![label: large effort][~largeeffort]](https://github.com/ThreeMammals/Ocelot/labels/large%20effort). [^5]
If you want to contribute for the first time, we suggest looking at a [![label: help wanted][~helpwanted]](https://github.com/ThreeMammals/Ocelot/labels/help%20wanted) [![label: small effort][~smalleffort]](https://github.com/ThreeMammals/Ocelot/labels/small%20effort) [![label: good first issue][~goodfirstissue]](https://github.com/ThreeMammals/Ocelot/labels/good%20first%20issue) :octocat: @@ -93,4 +94,5 @@ Finally, we mark all existing issues as [![label: help wanted][~helpwanted]](htt [^1]: Ocelot doesn’t directly support [GraphQL](https://graphql.org/). Developers can easily integrate the [GraphQL for .NET](/graphql-dotnet/graphql-dotnet) library. [^2]: Ocelot does support [Consul](https://www.consul.io/), [Netflix Eureka](https://www.nuget.org/packages/Steeltoe.Discovery.Eureka), [Service Fabric](https://azure.microsoft.com/en-us/products/service-fabric/) service discovery providers, and special modes like [Dynamic Routing](/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst#dynamic-routing) and [Custom Providers](/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst#custom-providers). [^3]: Retry policies only via [Polly](/App-vNext/Polly) library. -[^4]: See all [labels](https://github.com/ThreeMammals/Ocelot/issues/labels) of the repository. +[^4]: Starting with [v21.0](https://github.com/ThreeMammals/Ocelot/releases/tag/21.0.0), the solution's code base supports [Multitargeting](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-multitargeting-overview) as SDK-style projects. It should be easier for teams to move between (migrate to) .NET 6, 7 and 8 frameworks. Also, new features will be available for all .NET SDKs which we support via multitargeting. Find out more here: [Target frameworks in SDK-style projects](https://learn.microsoft.com/en-us/dotnet/standard/frameworks) +[^5]: See all [labels](https://github.com/ThreeMammals/Ocelot/issues/labels) of the repository. diff --git a/ReleaseNotes.md b/ReleaseNotes.md index af4e302ad..1193d5db1 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -1,2 +1,17 @@ -## Documentation release {0} for [Polish Apple](https://www.google.com/search?q=Polish+Apple), v{1} -Special thanks to @ggnaegi! +## Upgrade to .NET 8 (version {0}) aka [.NET 8](https://dotnet.microsoft.com/en-us/download/dotnet/8.0) release +> Read article: [Announcing .NET 8](https://devblogs.microsoft.com/dotnet/announcing-dotnet-8/) by Gaurav Seth, on November 14th, 2023 + +### About +We are pleased to announce to you that we can now offer the support of [.NET 8](https://dotnet.microsoft.com/en-us/download). +But that is not all, in this release, we are adopting support of several versions of the .NET framework through [multitargeting](https://learn.microsoft.com/en-us/dotnet/standard/frameworks). +The Ocelot distribution is now compatible with .NET **6**, **7** and **8**. :tada: + +In the future, we will try to ensure the support of the [.NET SDKs](https://dotnet.microsoft.com/en-us/download/dotnet) that are still actively maintained by the .NET team and community. +Current .NET versions in support are the following: [6, 7, 8](https://dotnet.microsoft.com/en-us/download/dotnet). + +### Technical info +As an ASP.NET Core app, now Ocelot targets `net6.0`, `net7.0` and `net8.0` frameworks. + +Starting with **v{0}**, the solution's code base supports [Multitargeting](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-multitargeting-overview) as SDK-style projects. +It should be easier for teams to move between (migrate to) .NET 6, 7 and 8 frameworks. Also, new features will be available for all .NET SDKs which we support via multitargeting. +Find out more here: [Target frameworks in SDK-style projects](https://learn.microsoft.com/en-us/dotnet/standard/frameworks) diff --git a/build.cake b/build.cake index ad510b0ac..dda6b1b80 100644 --- a/build.cake +++ b/build.cake @@ -2,7 +2,7 @@ #tool "dotnet:?package=coveralls.net&version=4.0.1" #addin nuget:?package=Newtonsoft.Json #addin nuget:?package=System.Text.Encodings.Web&version=4.7.1 -#tool "nuget:?package=ReportGenerator&version=5.1.19" +#tool "nuget:?package=ReportGenerator&version=5.2.0" #addin Cake.Coveralls&version=1.1.0 #r "Spectre.Console" @@ -42,8 +42,9 @@ var benchmarkTestAssemblies = @"./test/Ocelot.Benchmarks"; // packaging var packagesDir = artifactsDir + Directory("Packages"); -var releaseNotesFile = packagesDir + File("ReleaseNotes.md"); var artifactsFile = packagesDir + File("artifacts.txt"); +var releaseNotesFile = packagesDir + File("ReleaseNotes.md"); +var releaseNotes = new List(); // stable releases var tagsUrl = "https://api.github.com/repos/ThreeMammals/ocelot/releases/tags/"; @@ -85,8 +86,8 @@ Task("Release") .IsDependentOn("Build") .IsDependentOn("CreateReleaseNotes") .IsDependentOn("CreateArtifacts") - .IsDependentOn("PublishGitHubRelease"); - // .IsDependentOn("PublishToNuget"); + .IsDependentOn("PublishGitHubRelease") + .IsDependentOn("PublishToNuget"); Task("Compile") .IsDependentOn("Clean") @@ -135,7 +136,7 @@ Task("Version") Task("CreateReleaseNotes") .IsDependentOn("Version") .Does(() => - { + { Information($"Generating release notes at {releaseNotesFile}"); // local helper function @@ -158,7 +159,7 @@ Task("CreateReleaseNotes") var releaseVersion = versioning.NuGetVersion; // Read main header from Git file, substitute version in header, and add content further... var releaseHeader = string.Format(System.IO.File.ReadAllText("./ReleaseNotes.md"), releaseVersion, lastRelease); - var releaseNotes = new List { releaseHeader }; + releaseNotes = new List { releaseHeader }; var shortlogSummary = GitHelper($"shortlog --no-merges --numbered --summary {lastRelease}..HEAD"); var re = new Regex(@"^[\s\t]*(?'commits'\d+)[\s\t]+(?'author'.*)$"); @@ -296,9 +297,9 @@ Task("CreateReleaseNotes") } } } // END of Top 3 - //releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:"); - //releaseNotes.AddRange(topContributors); - //releaseNotes.Add(""); + releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:"); + releaseNotes.AddRange(topContributors); + releaseNotes.Add(""); releaseNotes.Add("### Starring :star: aka Release Influencers :bowtie:"); releaseNotes.AddRange(starring); releaseNotes.Add(""); @@ -306,17 +307,26 @@ Task("CreateReleaseNotes") var commitsHistory = GitHelper($"log --no-merges --date=format:\"%A, %B %d at %H:%M\" --pretty=format:\"%h by **%aN** on %ad →%n%s\" {lastRelease}..HEAD"); releaseNotes.AddRange(commitsHistory); - EnsureDirectoryExists(packagesDir); - System.IO.File.WriteAllLines(releaseNotesFile, releaseNotes); + WriteReleaseNotes(); + }); + +private void WriteReleaseNotes() +{ + Information($"RUNNING {nameof(WriteReleaseNotes)} ..."); - if (string.IsNullOrEmpty(System.IO.File.ReadAllText(releaseNotesFile))) - { - System.IO.File.WriteAllText(releaseNotesFile, "No commits since last release"); - } + EnsureDirectoryExists(packagesDir); + System.IO.File.WriteAllLines(releaseNotesFile, releaseNotes); + + var content = System.IO.File.ReadAllText(releaseNotesFile); + if (string.IsNullOrEmpty(content)) + { + System.IO.File.WriteAllText(releaseNotesFile, "No commits since last release"); + } + + Information($"Release notes are >>>\n{content}<<<"); + Information($"EXITED {nameof(WriteReleaseNotes)}"); +} - Information("Release notes are >>>" + Environment.NewLine + System.IO.File.ReadAllText(releaseNotesFile) + "<<<"); - }); - Task("RunUnitTests") .IsDependentOn("Compile") .Does(() => @@ -407,25 +417,24 @@ Task("CreateArtifacts") .IsDependentOn("Compile") .Does(() => { - EnsureDirectoryExists(packagesDir); - + WriteReleaseNotes(); System.IO.File.AppendAllLines(artifactsFile, new[] { "ReleaseNotes.md" }); - CopyFiles("./ReleaseNotes.md", packagesDir); - - // 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 } - // ); - // } + + 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) .Distinct(); - - foreach(var artifact in artifacts) + + Information($"Listing all {nameof(artifacts)}..."); + foreach (var artifact in artifacts) { var codePackage = packagesDir + File(artifact); if (FileExists(codePackage)) diff --git a/docs/building/building.rst b/docs/building/building.rst index ec794e296..5873350b8 100644 --- a/docs/building/building.rst +++ b/docs/building/building.rst @@ -10,4 +10,4 @@ Building * There is a `Makefile `_ to make it easier to call the various targets in `build.cake `_. The scripts are called with **.sh** but can be easily changed to **.ps1** if you are using Windows. -* Alternatively you can build the project in VS2022 with the latest `.NET 7.0 `_ SDK. +* Alternatively you can build the project in VS2022 with the latest `.NET 8.0 `_ SDK. diff --git a/docs/building/releaseprocess.rst b/docs/building/releaseprocess.rst index ada142c39..ba7cff45a 100644 --- a/docs/building/releaseprocess.rst +++ b/docs/building/releaseprocess.rst @@ -10,7 +10,7 @@ Ocelot uses the following process to accept work into the NuGet packages. 1. User creates an issue or picks up an `existing issue `_ in GitHub. An issue can be created by converting `discussion `_ topics if necessary and agreed upon. -2. User creates a fork and branches from this (unless a member of core team, they can just create a branch on the head repo) e.g. ``feature/xxx``, ``bug/xxx`` etc. +2. User creates `a fork `_ and branches from this (unless a member of core team, they can just create a branch on the head repo) e.g. ``feature/xxx``, ``bug/xxx`` etc. It doesn't really matter what the "xxx" is. It might make sense to use the issue number and maybe a short description. 3. When the contributor is happy with their work they can create a pull request against **develop** in GitHub with their changes. diff --git a/docs/conf.py b/docs/conf.py index c8dbe77bd..8bd28ecbf 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,8 +8,8 @@ project = 'Ocelot' copyright = ' 2023 ThreeMammals Ocelot team' -author = 'Tom Pallister, Ocelot Core team at ThreeMammals and Ocelot GitHub community' -release = '20.0.0' +author = 'Tom Pallister, Ocelot Core team at ThreeMammals' +release = '21.0' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -19,8 +19,6 @@ templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/docs/features/configuration.rst b/docs/features/configuration.rst index feec24721..589c4a0b0 100644 --- a/docs/features/configuration.rst +++ b/docs/features/configuration.rst @@ -94,7 +94,7 @@ to you: Ocelot will now use the environment specific configuration and fall back to **ocelot.json** if there isn't one. You also need to set the corresponding environment variable which is ``ASPNETCORE_ENVIRONMENT``. -More info on this can be found in the ASP.NET Core docs: `Use multiple environments in ASP.NET Core `_. +More info on this can be found in the ASP.NET Core docs: `Use multiple environments in ASP.NET Core `_. Merging Configuration Files --------------------------- diff --git a/docs/features/dependencyinjection.rst b/docs/features/dependencyinjection.rst index 711340efc..9dbd9b2be 100644 --- a/docs/features/dependencyinjection.rst +++ b/docs/features/dependencyinjection.rst @@ -108,7 +108,7 @@ It gives you full control on design and buiding of Ocelot pipeline, but be caref Warning! Most of services from minimal part of the pipeline should be reused, but only a few of services could be removed. Warning!! The method above is called after adding required services of ASP.NET MVC pipeline building by -`AddMvcCore `_ method +`AddMvcCore `_ method over the ``Services`` property in upper calling context. These services are absolute minimum core services for ASP.NET MVC pipeline. They must be added to DI container always, and they are added implicitly before calling of the method by caller in upper context. So, ``AddMvcCore`` creates an ``IMvcCoreBuilder`` object with its assignment to the ``MvcCoreBuilder`` property. @@ -124,13 +124,13 @@ The Problem ^^^^^^^^^^^ The default `AddOcelot <#the-addocelot-method>`_ method adds -`Newtonsoft JSON `_ services +`Newtonsoft JSON `_ services by the ``AddNewtonsoftJson`` extension method in default builder (the `AddDefaultAspNetServices <#the-adddefaultaspnetservices-method>`_ method). The ``AddNewtonsoftJson`` method calling was introduced in old .NET and Ocelot releases which was necessary when Microsoft did not launch the ``System.Text.Json`` library, but now it affects normal use, so we have an intention to solve the problem. -Modern `JSON services `_ -out of `the box `_ +Modern `JSON services `_ +out of `the box `_ will help to configure JSON settings by the ``JsonSerializerOptions`` property for JSON formatters during (de)serialization. Solution diff --git a/docs/features/logging.rst b/docs/features/logging.rst index 36572f778..979b16145 100644 --- a/docs/features/logging.rst +++ b/docs/features/logging.rst @@ -2,7 +2,7 @@ Logging ======= Ocelot uses the standard logging interfaces ``ILoggerFactory`` and ``ILogger`` at the moment. -This is encapsulated in ``IOcelotLogger`` and ``IOcelotLoggerFactory`` with an implementation for the standard `ASP.NET Core logging `_ stuff at the moment. +This is encapsulated in ``IOcelotLogger`` and ``IOcelotLoggerFactory`` with an implementation for the standard `ASP.NET Core logging `_ stuff at the moment. This is because Ocelot adds some extra info to the logs such as **request ID** if it is configured. There is a global `error handler middleware `_ that should catch any exceptions thrown and log them as errors. @@ -16,8 +16,8 @@ Nicely onto the next feature. Warning ------- -If you are logging to `Console `_, you will get terrible performance. -The team has had so many issues about performance issues with Ocelot and it is always logging level **Debug**, logging to `Console `_. +If you are logging to `Console `_, you will get terrible performance. +The team has had so many issues about performance issues with Ocelot and it is always logging level **Debug**, logging to `Console `_. * **Warning!** Make sure you are logging to something proper in production environment! * Use **Error** and **Critical** levels in production environment! diff --git a/docs/features/middlewareinjection.rst b/docs/features/middlewareinjection.rst index bf0ac2152..d1ee78478 100644 --- a/docs/features/middlewareinjection.rst +++ b/docs/features/middlewareinjection.rst @@ -38,7 +38,7 @@ So, the next called middlewares **will not** affect Ocelot configuration. ASP.NET Core Middlewares and Ocelot Pipeline Builder ---------------------------------------------------- -Ocelot pipeline is a part of entire `ASP.NET Core Middlewares `_ conveyor aka app pipeline. +Ocelot pipeline is a part of entire `ASP.NET Core Middlewares `_ conveyor aka app pipeline. The `BuildOcelotPipeline `_ method encapsulates Ocelot pipeline. The last middleware in the ``BuildOcelotPipeline`` method is ``HttpRequesterMiddleware`` that calls the next middleware, if added to the pipeline. diff --git a/docs/features/ratelimiting.rst b/docs/features/ratelimiting.rst index e0cf56690..9a69f4ded 100644 --- a/docs/features/ratelimiting.rst +++ b/docs/features/ratelimiting.rst @@ -57,9 +57,9 @@ There is no decision at the moment, and the old version of the feature is includ See more about new feature being added into ASP.NET Core 7.0 release: -* `RateLimiter Class `_, since ASP.NET Core **7.0** +* `RateLimiter Class `_, since ASP.NET Core **7.0** * `System.Threading.RateLimiting `_ NuGet package -* `Rate limiting middleware in ASP.NET Core `_ article by Arvin Kahbazi, Maarten Balliauw, and Rick Anderson +* `Rate limiting middleware in ASP.NET Core `_ article by Arvin Kahbazi, Maarten Balliauw, and Rick Anderson However, it makes sense to keep the old implementation as a Ocelot built-in native feature, but we are going to migrate to the new Rate Limiter from ``Microsoft.AspNetCore.RateLimiting`` namespace. diff --git a/docs/features/websockets.rst b/docs/features/websockets.rst index 8dfc23321..5e1e4fc54 100644 --- a/docs/features/websockets.rst +++ b/docs/features/websockets.rst @@ -38,7 +38,7 @@ Links * WHATWG: `WebSockets Standard `_ * Mozilla Developer Network: `The WebSocket API (WebSockets) `_ -* Microsoft Learn: `WebSockets support in ASP.NET Core `_ +* Microsoft Learn: `WebSockets support in ASP.NET Core `_ * Microsoft Learn: `WebSockets support in .NET `_ SignalR @@ -65,10 +65,10 @@ So, SignalR is `the part -More information on framework compatibility can be found in instrictions: `Use ASP.NET Core APIs in a class library `_. +More information on framework compatibility can be found in instrictions: `Use ASP.NET Core APIs in a class library `_. **Second**, you need to tell your application to use *SignalR*. -Complete reference is here: `ASP.NET Core SignalR configuration `_ +Complete reference is here: `ASP.NET Core SignalR configuration `_ .. code-block:: csharp @@ -79,7 +79,7 @@ Complete reference is here: `ASP.NET Core SignalR configuration `_ to allow *WebSockets* connections. +so `configure allowed transports `_ to allow *WebSockets* connections. **Then** in your **ocelot.json** add the following to proxy a Route using SignalR. Note normal Ocelot routing rules apply the main thing is the scheme which is set to ``ws``. diff --git a/docs/index.rst b/docs/index.rst index 38d6c0a87..3ec283703 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -Welcome to Ocelot 20.0 +Welcome to Ocelot 21.0 ====================== Thanks for taking a look at the Ocelot documentation! Please use the left hand navigation to get around. diff --git a/docs/introduction/gettingstarted.rst b/docs/introduction/gettingstarted.rst index efe296971..333261992 100644 --- a/docs/introduction/gettingstarted.rst +++ b/docs/introduction/gettingstarted.rst @@ -1,16 +1,16 @@ Getting Started =============== -Ocelot is designed to work with ASP.NET and is currently on ``net7.0`` framework. +Ocelot is designed to work with ASP.NET and is currently on ``net6.0``, ``net7.0`` and ``net8.0`` frameworks. -.NET 7.0 +.NET 8.0 -------- Install NuGet package ^^^^^^^^^^^^^^^^^^^^^ Install Ocelot and it's dependencies using `NuGet `_. -You will need to create a `ASP.NET Core 7.0 project `_ and bring the package into it. +You will need to create a `ASP.NET Core minimal API project `_ and bring the package into it. Then follow the startup below and :doc:`../features/configuration` sections to get up and running. .. code-block:: powershell diff --git a/docs/introduction/gotchas.rst b/docs/introduction/gotchas.rst index e62e1eedb..9a8f856ae 100644 --- a/docs/introduction/gotchas.rst +++ b/docs/introduction/gotchas.rst @@ -4,14 +4,14 @@ Gotchas IIS ----- - Microsoft Learn: `Host ASP.NET Core on Windows with IIS `_ + Microsoft Learn: `Host ASP.NET Core on Windows with IIS `_ We do not recommend to deploy Ocelot app to IIS environments, but if you do, keep in mind the gotchas below. * When using ASP.NET Core 2.2+ and you want to use In-Process hosting, replace ``UseIISIntegration()`` with ``UseIIS()``, otherwise you will get startup errors. * Make sure you use Out-of-process hosting model instead of In-process one - (see `Out-of-process hosting with IIS and ASP.NET Core `_), + (see `Out-of-process hosting with IIS and ASP.NET Core `_), otherwise you will get very slow responses (see `1657 `_). * Ensure all DNS servers of all downstream hosts are online and they function perfectly, otherwise you will get slow responses (see `1630 `_).