Allow filtering endpoints from the default reference set

[danegsta]

Description

We were including additional endpoints (such as the Keycloak management dashboard endpoint) as part of the service discovery endpoints for a resource when referenced via WithReference(resource). This is problematic because the management endpoint is not intended to be referenced by a Keycloak client, it's dashboard for users to access.

This PR adds an additional property that can be set on an EndpointAnnotation to exclude it from the set of endpoints covered by a default EndpointReferenceAnnotation. These non-default endpoints can still be referenced via an explicit WithReference(resource.GetEndpoint("name")) call.

Endpoints will be included in the default set unless explicitly opted out.

To exclude an endpoint from the default set:

builder.WithHttpEndpoint(port: 1234, targetPort: 4567)
    .WithEndpoint("http", ep => ep.IsDefaultReferenceEndpoint = false);

The following resource endpoints are now excluded from the default set:

• Keycloak management endpoint
• Azure ComsosDB Emulator health endpoint
• Azure EventHubs Emulator health endpoint
• Azure ServiceBus Emulator health endpoint

Fixes #15547

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Link to aspire.dev issue:
      • New issue
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 15558

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 15558"

[Copilot]

Pull request overview

This PR updates Aspire.Hosting’s default WithReference(resource) behavior to allow endpoint authors to exclude specific endpoints (e.g., management/health) from the default reference set, while still permitting explicit references to those endpoints when needed.

Changes:

• Adds EndpointAnnotation.IsDefaultReferenceEndpoint (default true) and plumbs it into WithReference environment-variable injection logic.
• Exposes EndpointReference.IsDefaultReferenceEndpoint to reflect the underlying annotation setting.
• Excludes selected management/health endpoints (Keycloak management, Azure emulator health endpoints) from default references and adds unit tests covering the new behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/Aspire.Hosting.Tests/WithReferenceTests.cs	Adds coverage for default-vs-explicit endpoint reference behavior and default property value.
src/Aspire.Hosting/ResourceBuilderExtensions.cs	Updates endpoint injection filtering and documents the new default reference semantics.
src/Aspire.Hosting/ApplicationModel/EndpointReference.cs	Adds IsDefaultReferenceEndpoint to reflect endpoint default-reference inclusion.
src/Aspire.Hosting/ApplicationModel/EndpointAnnotation.cs	Introduces IsDefaultReferenceEndpoint (default true) with XML documentation.
src/Aspire.Hosting.Keycloak/KeycloakResourceBuilderExtensions.cs	Marks Keycloak management endpoint as non-default for WithReference(resource).
src/Aspire.Hosting.Azure.ServiceBus/AzureServiceBusExtensions.cs	Marks ServiceBus emulator health endpoint as non-default for WithReference(resource).
src/Aspire.Hosting.Azure.EventHubs/AzureEventHubsExtensions.cs	Marks EventHubs emulator health endpoint as non-default for WithReference(resource).
src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs	Marks CosmosDB emulator health endpoint as non-default for WithReference(resource).

[mitchdenny]

This is a good idea.

[JamesNK]

What is the breaking change?

[davidfowl]

IsDefaultReferenceEndpoint = ExcludeReferenceEndpoint?

@eerhardt ? We can punt this to API review.

What is the breaking change?

Old code could be using that env variable (directly or indirectly).

[JamesNK]

IsDefaultReferenceEndpoint = ExcludeReferenceEndpoint?

+1. Default value to false is more idomatic in .NET land.

[fdohrendorfG]

Thanks for very quickly addressing the issue.