Improve Service Discovery Documentation

[andi0b]

I'm new to Aspire and spent just a couple of hours with it. During that time I discovered that the documentation about Service Discovery was not able to let me understand what it actually does and how to use it.

I read those docs: https://github.com/dotnet/aspire/tree/c694a69189cb1579c326944cf8cf2975b1971bea/src/Microsoft.Extensions.ServiceDiscovery https://github.com/dotnet/aspire/blob/c694a69189cb1579c326944cf8cf2975b1971bea/src/Microsoft.Extensions.ServiceDiscovery.Yarp/README.md https://github.com/dotnet/docs-aspire/blob/28829cb18310f306ffc87357620374068f390367/docs/service-discovery/overview.md

Those are the questions that I came up with, and I think it would help also other people if the docs would answer them.

1. What problem does it actually solve? Is there a graphic showing the involved components and what is done where?
2. Is the Service Discovery just relevant for development (with the dashboard) or also for an in production deployed application?
3. Where should I place the code snipptes from the documentation, in the AppHost or one of the service projects? (in some places it's specified, in others it isn't)
4. After adding service discovery with AddHttpClient().UseServiceDiscovery(), how do I use the http client? How does it behave? Do I use it just with relative URLs? Does it do service discovery on every call (round-robin) or does it only do it once?

The YARP extension was especially confusing for me:

1. When should I use that library? What problem does it solve?
2. What is a "destination resolver"?
3. In which format do I specify a destination address in YARP configuration to be resolved? Address = service-name or http://service-name
4. Is there a minimal example that shows what it does?

I think a much better example is the Consul documentation, for example this part: https://developer.hashicorp.com/consul/docs/concepts/service-discovery

The first chapters are even named like some of my questions:

1. What is (product name)?
2. Why chose (product name)?
3. Core Concepts

It starts with an overview and only then goes into details. It doesn't mention implementation details like IServiceEndPointResolverand IServiceEndPointResolverProvider already in the "How it works" section.

[davidfowl]

cc @ReubenBond

[jack775544]

I would love some more docs on this too. I was trying to integrate a Node application with Aspire with a reference to an ASP.NET Core server. When doing this I can see Aspire provides 2 URLs as environment variables that look something like the following:

http://_http.localhost:1234
http://localhost:1234

I checked the node sample code and it seems to be hardcoded to fetch the second URL which doesn't seem like it is exactly correct. In C# code I can just use the service discovery package and it will resolve the correct URL, but that is obviously not an option in my case.

I would like to have some docs on what the algorithm is for resolving the final URL from this list of URLs so I can properly implement it for non C# code.

[DamianEdwards]

I checked the node sample code and it seems to be hardcoded to fetch the second URL which doesn't seem like it is exactly correct. In C# code I can just use the service discovery package and it will resolve the correct URL, but that is obviously not an option in my case.

It's "correct" in as much as for that example it does the right thing, but it's by no means a full implementation of the configuration scheme that service discovery supports (as you're pointing out). Agree that having that scheme be fully documented is goodness.

[danmoseley]

Reuben is this still relevant? Putting in GA for now.

[Plasmadog]

Better docs are definitely needed. They are just mystifying in their current form. This example is baffling to me:

{
  "Services": {
    "basket":
      "https": "https://10.2.3.4:8080", /* the https endpoint, requested via https://basket */
      "dashboard": "https://10.2.3.4:9999" /* the "dashboard" endpoint, requested via https://_dashboard.basket */
    }
  }
}

If "dashboard" needs to specify both the host and port number, then what is it's logical relationship to "basket", or the "https" entry? If it doesn't somehow build on basket, then isn't it effectively a service in itself? How does this relate to the scheme selection logic mentioned elsewhere? What would the config need to look like if I wanted to resolve something like https+http://_dashboard/basket?

The docs are spread across multiple pages that cover more or less the same ground, but are not consistent with each other. Each of those pages consist of sections that seem to have very little connection to each other. It's maddening.

[IEvangelist]

Closing this as I haven't heard back from @ReubenBond on it, and it looks good to me. We can always re-open this if need be.