Scott Hanselman

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

October 23, '19 Comments [9] Posted in DotNetCore | NuGet
Sponsored By

I've blogged at length about the great open source project called "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!)

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!

Interactive local documentation with Try.NET

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!

Checking out Polly exception retries

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 &raquo;](./retryIfIncorrectStatus.md) Previous: [Before You Add Polly &laquo;](../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!

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!

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by SherWeb
Thursday, October 24, 2019 8:47:45 AM UTC
Glad to know about Polly. Thanks for sharing this
Karthick Raju
Thursday, October 24, 2019 9:18:54 AM UTC
These freedoms are vital. They are important not only for individual users, but also for the whole society as a whole, because they contribute to the development of social solidarity - that is, exchange and cooperation. They become even more important because digital technology is increasingly included in our culture and livelihoods. In the world of digital sounds, images and words, free software is becoming increasingly important for freedom in general.

Tens of millions of people around the world use free software today: public schools in some states of India and the provinces of Spain now teach all students how to use the free GNU / Linux operating system. However, most of these users have never heard of the ethical reasons why we developed this system and built a free software community, because today this system and community are referred to as “open source”, correlating them with another philosophy in which these liberties are barely mentioned.
Thursday, October 24, 2019 9:31:58 AM UTC
A very nice use case of try-dotnet!
Thursday, October 24, 2019 10:48:32 AM UTC
The only roadblock to adopting Polly.Net for our team is that it appears to only throw an exception for the circuit breaker. We need it to also support retries for things that don’t throw exceptions too. Exceptions are expensive in high volume scenarios, and Polly fails our load testing requirements. We had to create our own non-exception-based circuit breaker. Maybe things have changed since we last tried Polly.
Lee
Thursday, October 24, 2019 11:56:51 AM UTC
Polly policies support handling result-values (as well as exceptions) since version 4.3.0.

Circuit-Breaker policies surface the breaker state via the public API, which can be used to reduce the number of exceptions thrown in the broken state: https://github.com/App-vNext/Polly/wiki/Circuit-Breaker#reducing-thrown-exceptions-when-the-circuit-is-broken

Dylan Reisenberger
Thursday, October 24, 2019 4:10:34 PM UTC
This is awesome!

@Lee You can do something like this with Polly when not dealing with exceptions https://github.com/App-vNext/Polly/issues/274 (circuit breakers may be another story though)
Monday, October 28, 2019 11:30:01 PM UTC
Ahhh, somebody finally put the pieces together and basically recreated what Playgrounds does for Swift but with C# in a browser. I've been wanting to put something like this together that marries nicely formatted markdown with executable and editable code samples for a long time. Glad to see I wasn't the only one who had this idea, and someone else actually took the time and did it!
Wednesday, October 30, 2019 5:48:15 PM UTC
I am basically trying to limit the range of numbers in a text box, that I have, but I want it then to display a certain number if a checkbox is checked. The problem is, even after it gets the error message about the number being out of range it still shows the number in another messagebox after that one. Here is my code for this part of the program: Can anyone help me here
Tuesday, November 05, 2019 10:33:52 AM UTC
I really like reading through a post that can make people think. Also, many thanks for permitting me to comment!
Comments are closed.

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.