Support dynamic header dictionary

[james-s-tayler]

What kind of change does this PR introduce?
Adds a new feature to allow adding multiple dynamic headers in a single parameter by adding [HeaderCollection] IDictionary<string, string> headers

The docs have also been update to include information on how to use the feature, as well as general advice on how to reduce boilerplate by better leveraging HttpClient middleware / DelegatingHandlers. The worked examples for adding auth headers have been reworked. A table of contents has been added to the docs. A footnote has been added about how .NET 5 changes the behavior of the [Property] attribute feature. A new section has been added detailing how to integrate Polly.Context with Refit.

Comprehensive set of unit tests have been added for the feature also.

What is the current behavior?
Currently developers have to add multiple [Header] parameters creating a lot of boilerplate. There are several open tickets (#936, #884, #197) and one stale PR (#710).

What might this PR break?
It's most likely to interact with all of the other support for static and dynamic headers. The code coverage is solid enough to indicate that nothing has been fundamentally broken and existing functionality has been preserved while new functionality is working as expected.

Please check if the PR fulfills these requirements

• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

Other information:

• IDictionary<string, string> semantics were chosen specifically over IEnumerable<KeyValuePair<string, string>> due to IDictionary enforcing unique keys.
• I opted for a new attribute HeaderCollection rather than reusing Headers as the semantics of Headers indicates it's possible to pass a string to set a key, but that simply doesn't make sense in the case of a dictionary of headers.
• I debated whether or not to outright replace the worked example of adding authorization headers quite a bit. I'm happy to back out that particular change if you wish, but I settled on going for it due to 1) I personally found the examples confusing, 2) I can see a number of github issues and stackoverflow questions that arise from others being confused by the examples present in the docs, 3) a single clear example that's representative of a typical use case is likely better than me tacking on what I did in addition to all of the existing examples, and 4) passing a func into a DelegatingHandler probably isn't going to work out nicely 99% of the time if you're using HttpClientFactory / DI registrations, so it risks leading devs who aren't familiar with DelegatingHandlers down the wrong track.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.