Add ExtraHeaderParameters and ExtraQueryParameters support to DownstreamApi

[Copilot]

This PR implements support for ExtraHeaderParameters and ExtraQueryParameters properties on DownstreamApiOptions to simplify adding custom headers and query parameters to downstream API requests.

Problem

Previously, developers had to use the complex CustomizeHttpRequestMessage delegate to add custom headers and query parameters to downstream API calls:

var result = await downstreamApi.GetForAppAsync<string>(
    "Api",
    options =>
    {
        options.CustomizeHttpRequestMessage = requestMessage =>
        {
            requestMessage.Headers.Add("OData-Version", "4.0");
            // Query parameters would need manual URL manipulation
        };
    });

Solution

This PR adds support for the more convenient ExtraHeaderParameters and ExtraQueryParameters properties:

var result = await downstreamApi.GetForAppAsync<string>(
    "Api",
    options =>
    {
        options.ExtraHeaderParameters = new Dictionary<string, string>
        {
            { "OData-Version", "4.0" },
            { "X-Custom-Header", "value" }
        };
        options.ExtraQueryParameters = new Dictionary<string, string>
        {
            { "version", "v2" },
            { "format", "json" }
        };
    });

Implementation Details

Key Features

• Reflection-based detection - Uses reflection to check if properties exist on DownstreamApiOptions for backward compatibility
• Dual naming support - Supports both "ExtraHeaderParameters" and "ExtraHeadersParameters" naming conventions
• Proper URL encoding - Query parameters are automatically URL-encoded using Uri.EscapeDataString
• Maintains existing behavior - Works alongside existing CustomizeHttpRequestMessage delegate
• Comprehensive test coverage - Tests for headers, query parameters, edge cases, and special characters

Technical Changes

• Added GetExtraHeaderParameters() and GetExtraQueryParameters() helper methods in DownstreamApi class
• Enhanced UpdateRequestAsync() method to apply extra parameters before CustomizeHttpRequestMessage is called
• Updated all target framework InternalAPI files with new method signatures
• Created comprehensive test suite in ExtraParametersTests.cs

Header Processing

• Headers are added using TryAddWithoutValidation to support custom header schemes
• Applied before CustomizeHttpRequestMessage delegate, allowing for override
• Empty or null dictionaries are safely ignored

Query Parameter Processing

• Parameters are properly URL-encoded for safety
• Correctly appends to existing query parameters in the URL
• Handles special characters and spaces correctly

Testing

The implementation includes comprehensive tests covering:

• Adding extra headers to requests
• Adding extra query parameters with proper URL encoding
• Appending to existing query parameters
• Handling special characters and spaces
• Edge cases with null/empty dictionaries
• Alternate naming conventions (ExtraHeadersParameters vs ExtraHeaderParameters)

Backward Compatibility

The implementation uses reflection to detect if these properties exist on DownstreamApiOptions, ensuring full backward compatibility with different versions of the Microsoft.Identity.Abstractions package.

Dependencies

This feature assumes that the ExtraHeaderParameters and ExtraQueryParameters properties will be added to DownstreamApiOptions in the Microsoft.Identity.Abstractions package as mentioned in the related issue.

Fixes #3387.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[jmprieur]

A few suggestions for improvements

[jmprieur]

@copilot I've reviewed the PR and have suggestions for improvements

[Copilot]

@copilot I've reviewed the PR and have suggestions for improvements

I've implemented the improvements by removing the unnecessary helper methods GetExtraHeaderParameters() and GetExtraQueryParameters() that were just pass-through methods. The code now directly accesses effectiveOptions.ExtraHeaderParameters and effectiveOptions.ExtraQueryParameters properties, making it cleaner and more straightforward.

[jmprieur]

@copilot I left a few comments