IHttpClientFactory - HttpClient as a service, handle cross-cutting concerns like caching, retry logic, timeouts and circuit breakers

[Rick-Anderson]

aspnet/HttpClientFactory#42

[stevejgordon]

I've written a bit about IHttpClientFactory on my blog (https://www.stevejgordon.co.uk/introduction-to-httpclientfactory-aspnetcore and https://www.stevejgordon.co.uk/httpclientfactory-named-typed-clients-aspnetcore) - Would like to have a crack at contributing to the docs if this is open to community engagement?

[scottaddie]

@stevejgordon This absolutely is open to community engagement. We'd love to have your help.

The first step is to propose an outline for the new doc. We'll need to get approval on it before writing. Do you have a rough outline in mind?

@danroth27 Thoughts on a title for this doc? I'm hoping to avoid using IHttpClientFactory in the title; it would be meaningless to beginners. Also, are you okay with the doc being located under the Fundamentals TOC node?

[stevejgordon]

@scottaddie I was going to suggest the following:

(2.1 preview 1):

• Introduction and Benefits
• Basic Usage
• NamedClients
• TypedClients
• Outgoing Request Middleware (DelegatingHandlers)

Future (2.1 preview 2?):

• Polly

However I see that the wiki page does include a lot of content already by @glennc that pretty much covers the above and perhaps just needs to be moved to the docs?
https://github.com/aspnet/HttpClientFactory/wiki

I'm sure the team will weigh in with other options for a title but perhaps something more description for the use case, rather than the feature name... e.g. "Making HTTP Requests"

[scottaddie]

@glennc @danroth27 Please see the proposed outline above? Thoughts?

[glennc]

We also had this issue: aspnet/HttpClientFactory#37

I think all the content for those headings needs to exist. We also wanted specific examples for how to use it in things like WebForms as well as details on unit testing with the factory, both your pages/controllers and your typed clients. Would that be a separate document?

[rynowak]

In addition to this we need to cover the connection management/handler rotation/dns kinds of things. The landscape is somewhat complex in 2.1 and will get better in the future, but we should be able to come up with a good set of comprehensive guidance. We should talk more about this when you're ready to start on that part.

List looks good to me overall, and we can close our bug tracking this!

[scottaddie]

@glennc Will this API be supported in ASP.NET 4.x? Your reference to WebForms leads me to believe that. I'd like to narrow the focus of this doc and create a separate doc for unit testing. That particular doc will live under our Test and debug TOC node.

[scottaddie]

@stevejgordon Please proceed with writing according to your proposed outline. Assume that the doc will be located under the Fundamentals TOC node. In the meantime, I'll meet with @rynowak & @glennc and help fill in the gaps once your PR is submitted. Let me know if you have any questions.

[glennc]

It's a netstandard package, so yes. But it is designed to be used with some of ASP.NET Cores primitives. Which you can get with the GenericHost that was done at the start of 2.1. Effectively spinning up some core-isms into your System.Web app.

[glennc]

I wasn't as clear as I wanted to be there. It is netstandard which means it can be used in net4.x, but all of ASP.NET Core is that. This one in particular I want to explore using in non Core apps as well. Effectively bridging the experiences.

[scottaddie]

@glennc Since this repo/docset is dedicated to ASP.NET Core, I suggest documenting the WebForms stuff in the ASP.NET 4.x docset. Putting it here could lead customers to believe that WebForms is a supported app model in ASP.NET Core. We can easily link over to that doc from here. Are you okay with that approach?

[glennc]

Sure. As long as the content exists I am ok with you putting it where it makes the most sense for our customers.

[stevejgordon]

@scottaddie Thanks. Excited to have a go at this. I'll start working on it and put in WIP PR in once I have something to show. I may need to advice/guidance on how/where to include samples/snippets. There are samples in the main HttpClientFactory repo but I see that some docs have their own sample project here in order to support building snippets? If it's okay, I'll start by copying over/fleshing out some text and take it from there.

In addition to this we need to cover the connection management/handler rotation/dns kinds of things. The landscape is somewhat complex in 2.1 and will get better in the future, but we should be able to come up with a good set of comprehensive guidance. We should talk more about this when you're ready to start on that part.

Absolutely! I wasn't sure how much the team wanted to cover on that since I read that the handler rotation is considered less of a key feature once the managed Handler work is ready. I may have mis-interpreted that from @glennc comments though.

@rynowak - Would it be possible to get in touch offline via email? I have some questions that are likely outside the scope of the docs / feature to deepen my understanding of the DNS piece.

[rynowak]

Sure that would be great! My email is my github username + microsoft.com

[stevejgordon]

@rynowak / @glennc - Do you think we should include a section about the logging from HttpClientFactory and managing the verbosity per client etc?

[rynowak]

Yeah, some information about logging is important. I'm a little worried exactly how much will change in between now and release based on feedback...

I'd suggest documenting a few basics for now, and we can revisit after we finish all of the work in this area.