diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index c100f18aa05..aea8dc309c7 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -13,6 +13,12 @@ "commands": [ "mdsnippets" ] + }, + "docfx": { + "version": "2.70.3", + "commands": [ + "docfx" + ] } } } \ No newline at end of file diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 00000000000..b0c0a2858d2 --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,37 @@ +# This is a basic workflow to help you get started with Actions + +name: github-pages + +# Controls when the workflow will run +on: + # Triggers the workflow on push or pull request events but only for the "main" branch + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + publish-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Dotnet Setup + uses: actions/setup-dotnet@v3 + with: + dotnet-version: 7.x + + - run: dotnet tool restore + + - run: dotnet docfx docs/docfx.json + + - name: Deploy + # if: startsWith(github.ref, 'refs/tags/') + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/_site diff --git a/README.md b/README.md index fcf82f49f56..d33a84ef399 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ > :rotating_light::rotating_light: **Polly v8 feature-complete!** :rotating_light::rotating_light: > - Polly v8 Beta 2 is now available on [NuGet.org](https://www.nuget.org/packages/Polly/8.0.0-beta.2). > - The Beta 2 version is considered feature-complete and the public API surface is stable. -> - Explore the [v8 documentation](https://github.com/App-vNext/Polly/blob/main/README_V8.md). +> - Explore the [v8 documentation](https://www.pollydocs.org/). # Polly @@ -1063,4 +1063,4 @@ Licensed under the terms of the [New BSD License](http://opensource.org/licenses ## Resources -Visit the [documentation](docs/README.md) to explore more Polly-related resources. +Visit the [documentation]() to explore more Polly-related resources. diff --git a/README_V8.md b/README_V8.md index b0d82748755..c6e169ac407 100644 --- a/README_V8.md +++ b/README_V8.md @@ -432,7 +432,7 @@ Rate limiter strategy throws `RateLimiterRejectedException` if execution is reje ## Next steps -To learn more about Polly, visit the [documentation](docs/README.md) or check out the [samples](#samples). +To learn more about Polly, visit the . ## Samples diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000000..4378419e7fc --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,9 @@ +############### +# folder # +############### +/**/DROP/ +/**/TEMP/ +/**/packages/ +/**/bin/ +/**/obj/ +_site diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 7f93c94b8e9..00000000000 --- a/docs/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# Polly Documentation - -Polly is a .NET resilience and transient-fault-handling library that allows developers to express resilience strategies such as Retry, Circuit Breaker, Hedging, Timeout, Rate Limiter and Fallback in a fluent and thread-safe manner. - -We are a member of the [.NET Foundation](https://www.dotnetfoundation.org/about)! - -![Polly logo](https://raw.github.com/App-vNext/Polly/main/Polly-Logo.png) - -## Resilience strategies - -| Strategy | Reactive | Premise | AKA | How does the strategy mitigate?| -| ------------- | --- | ------------- |:-------------: |------------- | -|[Retry](strategies/retry.md) |Yes|Many faults are transient and may self-correct after a short delay.| *Maybe it's just a blip* | Allows configuring automatic retries. | -|[Circuit-breaker](strategies/circuit-breaker.md) |Yes|When a system is seriously struggling, failing fast is better than making users/callers wait.

Protecting a faulting system from overload can help it recover. | *Stop doing it if it hurts*

*Give that system a break* | Breaks the circuit (blocks executions) for a period, when faults exceed some pre-configured threshold. | -|[Timeout](strategies/timeout.md)|No|Beyond a certain wait, a success result is unlikely.| *Don't wait forever* |Guarantees the caller won't have to wait beyond the timeout. | -|[Rate Limiter](strategies/rate-limiter.md)|No|Limiting the rate a system handles requests is another way to control load.

This can apply to the way your system accepts incoming calls, and/or to the way you call downstream services. | *Slow down a bit, will you?* |Constrains executions to not exceed a certain rate. | -|[Fallback](strategies/fallback.md)|Yes|Things will still fail - plan what you will do when that happens.| *Degrade gracefully* |Defines an alternative value to be returned (or action to be executed) on failure. | -|[Hedging](strategies/hedging.md)|Yes|Things can be slow sometimes, plan what you will do when that happens.| *Hedge your bets* | Executes parallel actions when things are slow and waits for the fastest one. | - -Visit the [resilience strategies](strategies/readme.md) section to understand their structure and explore various configuration methods. - -## Next steps - -Visit the [getting started](getting-started.md) section and learn how to quickly start using Polly. - -## Articles - -- [Introduction](readme.md): General information about the project and its goals. -- [Getting started](getting-started.md): A guide to help you get started with the project. -- Resilience strategies: A collection of strategies for improving the resilience of your system. - - [Timeout](strategies/timeout.md): A strategy for setting a maximum time limit for a request. - - [Retry](strategies/retry.md): A strategy for retrying failed requests. - - [Rate limiter](strategies/rate-limiter.md): A strategy for limiting the rate of requests. - - [Hedging](strategies/hedging.md): A strategy for hedging against long request times. - - [Fallback](strategies/fallback.md): A strategy for providing a fallback response in case of failure. - - [Circuit breaker](strategies/circuit-breaker.md): A strategy for breaking the circuit when a system is down. -- Resilience pipelines: Understanding the use of resilience pipelines. - - [Resilience pipeline registry](pipelines/resilience-pipeline-registry.md): Exploring the registry that stores resilience pipelines. -- vanced topics: A collection of advanced topics for further learning. - - [Telemetry and monitoring](advanced/telemetry.md): Insights into telemetry generated by resilience pipelines and strategies. - - [Chaos engineering](advanced/simmy.md): Get to know chaos engineering via the project's capabilities. - - [Dependency injection](advanced/dependency-injection.md): How the project integrates with Dependency Injection. -- Community and resources: A collection of resources and community contributions. - - [Polly-Contrib projects and libraries](community/polly-contrib.md): Learn how to contribute to and extend the project ecosystem. - - [Libraries and contributions](community/libraries-and-contributions.md): Find out which libraries the project depends on and who contributes to its development. - - [Useful resources and links](community/resources.md): Browse through blogs, podcasts, courses, e-books, and other community resources. -- [API](api/readme.md): The API documentation for the project. - -## Articles (previous Polly versions) - -- [Extensibility (v7)](v7/extensibility.md): Learn how you can extend Polly with new policies. - -## Samples - -- [Samples](https://github.com/App-vNext/Polly/tree/main/samples): Samples in this repository that serve as an introduction to Polly. -- [Polly-Samples](https://github.com/App-vNext/Polly-Samples): Contains practical examples for using various implementations of Polly. Please feel free to contribute to the Polly-Samples repository in order to assist others who are either learning Polly for the first time, or are seeking advanced examples and novel approaches provided by our generous community. -- Microsoft's [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers): Sample project demonstrating a .NET Microservices architecture and using Polly for resilience. diff --git a/docs/advanced/telemetry.md b/docs/advanced/telemetry.md index 29a4c0ee023..d0a06cd214b 100644 --- a/docs/advanced/telemetry.md +++ b/docs/advanced/telemetry.md @@ -173,7 +173,7 @@ Execution attempt. Source: '{PipelineName}/{PipelineInstance}/{StrategyName}', O ## Emitting telemetry events -Each resilience strategy can generate telemetry data through the [`ResilienceStrategyTelemetry`](../src/Polly.Core/Telemetry/ResilienceStrategyTelemetry.cs) API. Polly encapsulates event details as [`TelemetryEventArguments`](../src/Polly.Core/Telemetry/TelemetryEventArguments.cs) and emits them via `TelemetryListener`. +Each resilience strategy can generate telemetry data through the [`ResilienceStrategyTelemetry`](xref:Polly.Telemetry.ResilienceStrategyTelemetry) API. Polly encapsulates event details as [`TelemetryEventArguments`](xref:Polly.Telemetry.TelemetryEventArguments`2) and emits them via `TelemetryListener`. To leverage this telemetry data, users should assign a `TelemetryListener` instance to `ResiliencePipelineBuilder.TelemetryListener` and then consume the `TelemetryEventArguments`. diff --git a/docs/api/.gitignore b/docs/api/.gitignore new file mode 100644 index 00000000000..e8079a3bef9 --- /dev/null +++ b/docs/api/.gitignore @@ -0,0 +1,5 @@ +############### +# temp file # +############### +*.yml +.manifest diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 00000000000..78dc9c00575 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,2 @@ +# PLACEHOLDER +TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*! diff --git a/docs/docfx.json b/docs/docfx.json new file mode 100644 index 00000000000..5f8f766e360 --- /dev/null +++ b/docs/docfx.json @@ -0,0 +1,69 @@ +{ + "metadata": [ + { + "src": [ + { + "cwd": "../src", + "files": [ + "**/**.csproj" + ], + "exclude": [ + "**/obj/**", + "**/bin/**", + "_site/**", + "Polly/**", + "v7/**" + ] + } + ], + "dest": "api", + "includePrivateMembers": false, + "disableGitFeatures": false, + "disableDefaultFilter": false, + "noRestore": false, + "namespaceLayout": "flattened", + "memberLayout": "samePage", + "EnumSortOrder": "alphabetic", + "allowCompilationErrors": false + } + ], + "build": { + "globalMetadata": { + "_appLogoPath": "icon.png", + "_appFaviconPath": "icon.png" + }, + "content": [ + { + "files": [ + "api/**.yml", + "api/README.md" + ] + }, + { + "files": [ + "**.md", + "**.yml", + "toc.yml", + "*.md" + ] + } + ], + "resource": [ + { + "files": [ + "icon.png" + ] + } + ], + "output": "_site", + "globalMetadataFiles": [], + "fileMetadataFiles": [], + "template": [ + "default", + "modern" + ], + "postProcessors": [], + "keepFileLink": false, + "disableGitFeatures": false + } +} diff --git a/docs/getting-started.md b/docs/getting-started.md index 2c4d0329a2c..ad0e478e007 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,6 @@ # Getting started -To use Polly, you must provide a callback and execute it using [**resilience pipeline**](pipelines/readme.md). A resilience pipeline is a combination of one or more [**resilience strategies**](strategies/readme.md) such as retry, timeout, and rate limiter. Polly uses **builders** to integrate these strategies into a pipeline. +To use Polly, you must provide a callback and execute it using [**resilience pipeline**](pipelines/index.md). A resilience pipeline is a combination of one or more [**resilience strategies**](strategies/index.md) such as retry, timeout, and rate limiter. Polly uses **builders** to integrate these strategies into a pipeline. To get started, first add the [Polly.Core](https://www.nuget.org/packages/Polly.Core/) package to your project by running the following command: diff --git a/docs/icon.png b/docs/icon.png new file mode 100644 index 00000000000..9b95a0b14ee Binary files /dev/null and b/docs/icon.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000000..66faa1a99ca --- /dev/null +++ b/docs/index.md @@ -0,0 +1,48 @@ +# Meet Polly: The .NET resilience library + +> [!NOTE] +> This is documentation for the upcoming Polly v8 release. + +![Polly logo](https://raw.github.com/App-vNext/Polly/main/Polly-Logo.png) + +Polly is a powerful library for .NET that helps you handle transient faults and improve the resilience of your applications. With Polly, you can easily define and apply strategies such as Retry, Circuit Breaker, Hedging, Timeout, Rate Limiter and Fallback to handle failures and slowdowns in a fluent and thread-safe way. + +Polly is part of the [.NET Foundation](https://www.dotnetfoundation.org/about)! + +## What can Polly do for you? + +Polly lets you use and combine different resilience strategies to cope with various scenarios, such as: + +- [Retry](strategies/retry.md): Try again if something fails. This can be useful when the problem is temporary and might go away. +- [Circuit Breaker](strategies/circuit-breaker.md): Stop trying if something is broken or busy. This can benefit you by avoiding wasting time and making things worse. It can also support the system to recover. +- [Timeout](strategies/timeout.md): Give up if something takes too long. This can improve your performance by freeing up space and resources. +- [Rate Limiter](strategies/rate-limiter.md): Limit how many requests you make or accept. This can enable you to control the load and prevent problems or penalties. +- [Fallback](strategies/fallback.md): Do something else if something fails. This can improve your user experience and keep the program working. +- [Hedging](strategies/hedging.md): Do more than one thing at the same time and take the fastest one. This can make your program faster and more responsive. + +You can learn more about each strategy and how to use them [resilience strategies](strategies/index.md) section. + +## How to get started with Polly? + +Polly is easy to install and use. You can follow the [getting started](getting-started.md) guide to add Polly to your project and use it for your requests. + +## Where to find more information? + +Polly has a rich documentation that covers various topics, such as: + +- [Resilience strategies](strategies/index.md): A collection of strategies for improving the resilience of your system. +- [Resilience pipelines](pipelines/index.md): How to combine and reuse strategies in a flexible and modular way. +- [Telemetry and monitoring](advanced/telemetry.md): How to access and analyze the data generated by Polly strategies and pipelines. +- [Dependency injection](advanced/dependency-injection.md): How to integrate Polly with dependency injection frameworks and containers. +- [Extensibility](advanced/extensibility.md): How to create and use custom strategies and extensions for Polly. +- [Chaos engineering](advanced/simmy.md): How to use Polly to inject faults and test the resilience of your system. + +You can also find many resources and community contributions, such as: + +- [Samples](https://github.com/App-vNext/Polly/tree/main/samples): Samples in this repository that serve as an introduction to Polly. +- [Practical Samples](https://github.com/App-vNext/Polly-Samples): Practical examples for using various implementations of Polly. Please feel free to contribute to the Polly-Samples repository in order to assist others who are either learning Polly for the first time, or are seeking advanced examples and novel approaches provided by our generous community. +- [Polly-Contrib](community/polly-contrib.md)): Community projects and libraries that extend and enhance Polly's functionality and ecosystem. +- [Libraries and contributions](community/libraries-and-contributions.html): Dependencies and contributors that make Polly possible and awesome. +- Microsoft's [eShopOnContainers project](https://github.com/dotnet-architecture/eShopOnContainers): Sample project demonstrating a .NET Microservices architecture and using Polly for resilience. + +You can browse the documentation using the sidebar or visit the [API](api/index.md) section for the reference documentation. diff --git a/docs/migration-v8.md b/docs/migration-v8.md new file mode 100644 index 00000000000..5be94d682ba --- /dev/null +++ b/docs/migration-v8.md @@ -0,0 +1 @@ +# Migration guide from v7 to v8 diff --git a/docs/pipelines/README.md b/docs/pipelines/index.md similarity index 100% rename from docs/pipelines/README.md rename to docs/pipelines/index.md diff --git a/docs/strategies/circuit-breaker.md b/docs/strategies/circuit-breaker.md index 4b232b5c232..79b6f050cd5 100644 --- a/docs/strategies/circuit-breaker.md +++ b/docs/strategies/circuit-breaker.md @@ -3,8 +3,8 @@ ## About - **Options**: - - [`CircuitBreakerStrategyOptions`](../../src/Polly.Core/CircuitBreaker/CircuitBreakerStrategyOptions.cs) - - [`CircuitBreakerStrategyOptions`](../../src/Polly.Core/CircuitBreaker/CircuitBreakerStrategyOptions.TResult.cs) + - [`CircuitBreakerStrategyOptions`](xref:Polly.CircuitBreaker.CircuitBreakerStrategyOptions) + - [`CircuitBreakerStrategyOptions`](xref:Polly.CircuitBreaker.CircuitBreakerStrategyOptions) - **Extensions**: `AddCircuitBreaker` - **Strategy Type**: Reactive - **Exceptions**: diff --git a/docs/strategies/fallback.md b/docs/strategies/fallback.md index 0dd43747573..08005728bbe 100644 --- a/docs/strategies/fallback.md +++ b/docs/strategies/fallback.md @@ -2,7 +2,7 @@ ## About -- **Options**: [`FallbackStrategyOptions`](../../src/Polly.Core/Fallback/FallbackStrategyOptions.TResult.cs) +- **Options**: [`FallbackStrategyOptions`](xref:Polly.Fallback.FallbackStrategyOptions`1) - **Extensions**: `AddFallback` - **Strategy Type**: Reactive diff --git a/docs/strategies/hedging.md b/docs/strategies/hedging.md index 32f348e9c73..62cee851cdb 100644 --- a/docs/strategies/hedging.md +++ b/docs/strategies/hedging.md @@ -2,7 +2,7 @@ ## About -- **Options**: [`HedgingStrategyOptions`](../../src/Polly.Core/Hedging/HedgingStrategyOptions.TResult.cs) +- **Options**: [`HedgingStrategyOptions`](xref:Polly.Hedging.HedgingStrategyOptions`1) - **Extensions**: `AddHedging` - **Strategy Type**: Reactive diff --git a/docs/strategies/README.md b/docs/strategies/index.md similarity index 62% rename from docs/strategies/README.md rename to docs/strategies/index.md index 81d1051669d..ba90dc3d78b 100644 --- a/docs/strategies/README.md +++ b/docs/strategies/index.md @@ -10,9 +10,20 @@ Polly categorizes resilience strategies into two main groups: - **Reactive**: These strategies handle specific exceptions that are thrown, or results that are returned, by the callbacks executed through the strategy. - **Proactive**: Unlike reactive strategies, proactive strategies do not focus on handling errors by the callbacks might throw or return. They can make proactive decisions to cancel or reject the execution of callbacks (e.g., using a rate limiter or a timeout resilience strategy). +## Built-in strategies + +| Strategy | Reactive | Premise | AKA | How does the strategy mitigate?| +| ------------- | --- | ------------- |:-------------: |------------- | +|[Retry](retry.md) |Yes|Many faults are transient and may self-correct after a short delay.| *Maybe it's just a blip* | Allows configuring automatic retries. | +|[Circuit-breaker](circuit-breaker.md) |Yes|When a system is seriously struggling, failing fast is better than making users/callers wait.

Protecting a faulting system from overload can help it recover. | *Stop doing it if it hurts*

*Give that system a break* | Breaks the circuit (blocks executions) for a period, when faults exceed some pre-configured threshold. | +|[Timeout](timeout.md)|No|Beyond a certain wait, a success result is unlikely.| *Don't wait forever* |Guarantees the caller won't have to wait beyond the timeout. | +|[Rate Limiter](rate-limiter.md)|No|Limiting the rate a system handles requests is another way to control load.

This can apply to the way your system accepts incoming calls, and/or to the way you call downstream services. | *Slow down a bit, will you?* |Constrains executions to not exceed a certain rate. | +|[Fallback](fallback.md)|Yes|Things will still fail - plan what you will do when that happens.| *Degrade gracefully* |Defines an alternative value to be returned (or action to be executed) on failure. | +|[Hedging](hedging.md)|Yes|Things can be slow sometimes, plan what you will do when that happens.| *Hedge your bets* | Executes parallel actions when things are slow and waits for the fastest one. | + ## Usage -Extensions for adding resilience strategies to the builders are provided by each strategy. Depending on the type of strategy, these extensions may be available for both `ResiliencePipelineBuilder` and `ResiliencePipelineBuilder` or just one of them. Proactive strategies like timeout or rate limiter are available for both types of builders, while specialized reactive strategies are only available for `ResiliencePipelineBuilder`. Adding multiple resilience strategies is supported. +Extensions for adding resilience strategies to e builders are provided by each strategy. Depending on the type of strategy, these extensions may be available for both `ResiliencePipelineBuilder` and `ResiliencePipelineBuilder` or just one of them. Proactive strategies like timeout or rate limiter are available for both types of builders, while specialized reactive strategies are only available for `ResiliencePipelineBuilder`. Adding multiple resilience strategies is supported. Each resilience strategy provides: diff --git a/docs/strategies/rate-limiter.md b/docs/strategies/rate-limiter.md index 4dd271417c1..06948960888 100644 --- a/docs/strategies/rate-limiter.md +++ b/docs/strategies/rate-limiter.md @@ -2,7 +2,7 @@ ## About -- **Options**: [`RateLimiterStrategyOptions`](../../src/Polly.RateLimiting/RateLimiterStrategyOptions.cs) +- **Options**: [`RateLimiterStrategyOptions`](xref:Polly.RateLimiting.RateLimiterStrategyOptions) - **Extensions**: `AddRateLimiter`, `AddConcurrencyLimiter` - **Strategy Type**: Proactive - **Exceptions**: diff --git a/docs/strategies/retry.md b/docs/strategies/retry.md index 6ed0ecd9584..bec3d11a9af 100644 --- a/docs/strategies/retry.md +++ b/docs/strategies/retry.md @@ -3,8 +3,8 @@ ## About - **Options**: - - [`RetryStrategyOptions`](../../src/Polly.Core/Retry/RetryStrategyOptions.cs) - - [`RetryStrategyOptions`](../../src/Polly.Core/Retry/RetryStrategyOptions.TResult.cs) + - [`RetryStrategyOptions`](xref:Polly.Retry.RetryStrategyOptions) + - [`RetryStrategyOptions`](xref:Polly.Retry.RetryStrategyOptions`1) - **Extensions**: `AddRetry` - **Strategy Type**: Reactive diff --git a/docs/strategies/timeout.md b/docs/strategies/timeout.md index 63176805e0e..ba75a1f81cc 100644 --- a/docs/strategies/timeout.md +++ b/docs/strategies/timeout.md @@ -2,7 +2,7 @@ ## About -- **Options**: [`TimeoutStrategyOptions`](../../src/Polly.Core/Timeout/TimeoutStrategyOptions.cs) +- **Options**: [`TimeoutStrategyOptions`](xref:Polly.Timeout.TimeoutStrategyOptions) - **Extensions**: `AddTimeout` - **Strategy Type**: Proactive - **Exceptions**: diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 00000000000..8d2c16f1158 --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,60 @@ +- name: Introduction + href: index.md + +- name: Getting started + href: getting-started.md + +- name: Migrate to v8 + href: migration-v8.md + +- name: Resilience strategies + href: strategies/index.md + expanded: true + items: + - name: Timeout + href: strategies/timeout.md + - name: Retry + href: strategies/retry.md + - name: Rate limiter + href: strategies/rate-limiter.md + - name: Hedging + href: strategies/hedging.md + - name: Fallback + href: strategies/fallback.md + - name: Circuit breaker + href: strategies/circuit-breaker.md + + +- name: Resilience pipelines + href: pipelines/index.md + expanded: true + items: + - name: Resilience pipeline registry + href: pipelines/resilience-pipeline-registry.md + +- name: Advanced topics + expanded: true + items: + - name: Telemetry and monitoring + href: advanced/telemetry.md + - name: Extensibility + href: advanced/extensibility.md + - name: Dependency injection + href: advanced/dependency-injection.md + - name: Resilience context + href: advanced/resilience-context.md + - name: Chaos engineering + href: advanced/simmy.md + +- name: Community and resources + expanded: true + items: + - name: Polly-Contrib projects and libraries + href: community/polly-contrib.md + - name: Libraries and contributions + href: community/libraries-and-contributions.md + - name: Useful resources and links + href: community/resources.md + +- name: API + href: api/