{"record":{"id":"bc08f7c156978d9c","repo":"microsoft/aspire","slug":"endpoint-references-do-not-support-connectionname-optional","errorCode":null,"errorMessage":"Endpoint references do not support connectionName, optional, or name options.","messagePattern":"Endpoint references do not support connectionName, optional, or name options\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/ResourceBuilderExtensions.cs","lineNumber":926,"sourceCode":"    /// Adds a reference to another resource\n    /// </summary>\n    [AspireExport]\n    internal static IResourceBuilder<TDestination> WithReference<TDestination>(\n        this IResourceBuilder<TDestination> builder,\n        [AspireUnion(typeof(IResourceBuilder<IResource>), typeof(EndpointReference), typeof(string), typeof(Uri))] object source,\n        string? connectionName = null,\n        bool optional = false,\n        string? name = null)\n        where TDestination : IResourceWithEnvironment\n    {\n        ArgumentNullException.ThrowIfNull(builder);\n        ArgumentNullException.ThrowIfNull(source);\n\n        return source switch\n        {\n            IResourceBuilder<IResource> resourceBuilder => WithReferenceResource(builder, resourceBuilder, connectionName, optional, name),\n            EndpointReference endpointReference when connectionName is null && !optional && name is null => builder.WithReference(endpointReference),\n            EndpointReference => throw new InvalidOperationException(\"Endpoint references do not support connectionName, optional, or name options.\"),\n            Uri uri when connectionName is null && !optional && name is not null => builder.WithReference(name, uri),\n            Uri => throw new InvalidOperationException(\"URI references require the name option and do not support connectionName or optional.\"),\n            string uriString when connectionName is null && !optional && name is not null => builder.WithReference(name, CreateUri(uriString)),\n            string => throw new InvalidOperationException(\"URI references require the name option and do not support connectionName or optional.\"),\n            _ => throw new ArgumentException(\"Source must be a resource builder, endpoint reference, or URI string.\", nameof(source))\n        };\n    }\n\n    // Preserve the historical dispatcher signature for internal reflection-based tests.\n    internal static IResourceBuilder<TDestination> WithReference<TDestination>(\n        this IResourceBuilder<TDestination> builder,\n        IResourceBuilder<IResource> source,\n        string? connectionName = null,\n        bool optional = false,\n        string? name = null)\n        where TDestination : IResourceWithEnvironment\n    {\n        ArgumentNullException.ThrowIfNull(builder);","sourceCodeStart":908,"sourceCodeEnd":944,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L908-L944","documentation":"Aspire's WithReference dispatcher accepts resource builders, EndpointReference, string URIs, or Uri instances, but endpoint references only work in their bare form. EndpointReference values model a direct endpoint binding (host/port injected via service discovery), so options like connectionName, optional, or name have no meaning for them. When an EndpointReference is passed together with any of those options, the dispatcher throws this InvalidOperationException instead of silently ignoring the options.","triggerScenarios":"Calling builder.WithReference(endpointReference, connectionName: \"db\"), .WithReference(endpointReference, optional: true), or .WithReference(endpointReference, name: \"my-service\") — i.e. passing an EndpointReference while any of connectionName != null, optional == true, or name != null. The matching switch arm is src/Aspire.Hosting/ResourceBuilderExtensions.cs:926.","commonSituations":"Copying a call pattern from a connection-string resource reference (which supports connectionName/optional) and reusing it for an endpoint reference; trying to mark an endpoint reference as optional because the endpoint may not be running; attempting to alias an endpoint reference under a friendly service name.","solutions":["Remove the connectionName, optional, and name arguments and call builder.WithReference(endpointReference) with only the endpoint reference.","If you need a custom service name or optional semantics, reference the resource builder instead: builder.WithReference(resourceBuilder, name: \"...\", optional: true) (name requires the source to implement IResourceWithServiceDiscovery; optional requires a connection string resource).","If you need the endpoint under a different key, inject the environment variable manually via WithEnvironment using endpointReference.Property(EndpointProperty.HostAndPort)."],"exampleFix":"// before\nbuilder.WithReference(frontend.GetEndpoint(\"https\"), optional: true);\n\n// after\nbuilder.WithReference(frontend.GetEndpoint(\"https\"));","handlingStrategy":"validation","validationCode":"if (source is EndpointReference && (connectionName is not null || optional || name is not null))\n{\n    throw new ArgumentException(\"Endpoint references cannot be combined with connectionName, optional, or name.\");\n}","typeGuard":"bool isBareEndpointReference(object source, string? connectionName, bool optional, string? name) => source is EndpointReference && connectionName is null && !optional && name is null;","tryCatchPattern":null,"preventionTips":["Call endpoint references bare: WithReference(endpoint) with no extra arguments.","Remember optional/connectionName apply only to connection-string resources, name only to service-discovery resources.","Check the source value's type before choosing which optional arguments to pass."],"tags":["aspire","withreference","endpoint-reference","invalid-argument-combination"],"backgroundTag":"conflicting-config-options","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}