Create exceptional interactive documentation with Try .NET - The Polly NuGet library did!

I've blogged at length about the great open source project called "Polly"

• NuGet Package of the Week: Polly wanna fluently express transient exception handling policies in .NET?
• Adding Cross-Cutting Memory Caching to an HttpClientFactory in ASP.NET Core with Polly
• The Programmer's Hindsight - Caching with HttpClientFactory and Polly Part 2
• Adding Resilience and Transient Fault handling to your .NET Core HttpClient with Polly

and I've blogged about "Try .NET" which is a wonderful .NET Core global tool that lets you make interactive in-browser documentation and create workshops that can be run both online and locally (totally offline!)

• Introducing the Try .NET Global Tool - interactive in-browser documentation and workshop creator

If you've got .NET Core installed, you can try it in minutes! Just do this:

dotnet tool install --global dotnet-try

dotnet try demo

Even better, you can just clone a Try .NET enabled repository with markdown files that have a few magic herbs and spices, then run "dotnet try" in that cloned folder.

What does this have to do with Polly, the lovely .NET resilience and transient fault handling library that YOU should be using every day? Well, my friends, check out this lovely bit of work by Bryan J Hogan! He's created some interactive workshop-style demos using Try .NET!

How easy is it to check out? Let's give it a try. I've run dotnet tool install --global dotnet-try already. You may need to run update if you've installed it a while back.

git clone https://github.com/bryanjhogan/trydotnet-polly.git

dotnet try

That's it. What does it do? It'll launch your browser to a local website powered by Try .NET that looks like this!

Sweet! Ah, but Dear Reader, scroll down! Let me try out one of the examples. You'll see a Monaco-based local text editor (the same edit that powers VS Code) and you're able to run - and modify - local code samples IN THE BROWSER!

Here's the code as text to make it more accessible.

RetryPolicy retryPolicy = Policy.Handle<Exception>()

    .Retry(3, (exception, retryCount) =>

    {

        Console.WriteLine($"{exception.GetType()} thrown, retrying {retryCount}.");

    });



int result = retryPolicy.Execute(() => errorProneCode.QueryTheDatabase());



Console.WriteLine($"Received a response of {result}.");

And the output appears below the sample, again, in a console within the browser:

System.Exception thrown, retrying 1.

System.InsufficientMemoryException thrown, retrying 2.

Received a response of 0.

You can see that Polly gives you a RetryPolicy that can envelop your code and handle things like transient errors, occasional flaky server responses, or whatever else you want it to do. It can be configured as a policy outside your code, or coded inline fluently like this.

NOTE the URL! See that it's a .MD or Markdown file? Try .NET has a special handler that reads in a regular markdown file and executes it. The result is an HTML representation of your Markdown *and* your sample, now executable!

What's the page/image above look like as Markdown? Like this:

# Polly Retries Part 2



### Retrying When an Exception Occurs

The Polly NuGet package has been added and we are going to use the Retry Policy when querying database. 

The policy states that if an exception occurs, it will retry up to three times.



Note how you execute the unreliable code inside the policy. `retryPolicy.Execute(() => errorProneCode.QueryTheDatabase());`





``` cs --region retryIfException --source-file .\src\Program.cs --project .\src\PollyDemo.csproj 

```



#### Next: [Retrying Based on a Result  »](./retryIfIncorrectStatus.md) Previous: [Before You Add Polly «](../lettingItFail.md)

Note the special ``` region. The code isn't inline, but rather it lives in a named region in Program.cs in a project in this same repository, neatly under the /src folder. The region is presented in the sample, but as samples are usually more complex and require additional libraries and such, the region name and project context is passed into your app as Try.NET executes it.

Go check out some Try .NET enabled sample repositories. Just make sure you have the Try .NET global tool installed, then go clone and "dotnet try" any of these!

• https://github.com/bryanjhogan/trydotnet-polly
• https://github.com/dotnet/try-samples (there's like 5 sample areas in here, do "dotnet try" in the different directories!)

If you're doing classwork, teaching workshops, making assignments for homework, or even working in a low-bandwidth or remote environment this is great as you can put the repositories on a USB key and once they've run once they'll run offline!

Now, be inspired by (and star on GitHub) Bryan's great work and go make your own interactive .NET documentation!

Sponsor: Like C#? We do too! That’s why we've developed a fast, smart, cross-platform .NET IDE which gives you even more coding power. Clever code analysis, rich code completion, instant search and navigation, an advanced debugger... With JetBrains Rider, everything you need is at your fingertips. Code C# at the speed of thought on Linux, Mac, or Windows. Try JetBrains Rider today!