* [Querystrings](#querystrings)

* [Dynamic Querystring Parameters](#dynamic-querystring-parameters)

* [Collections as Querystring parameters](#collections-as-querystring-parameters)

* [Unescape Querystring parameters](#unescape-querystring-parameters)

* [Custom Querystring Parameter formatting](#custom-querystring-parameter-formatting)

**Formatting Keys**

To customize the format of query keys, you have two main options:

1. **Using the `AliasAs` Attribute**:

You can use the `AliasAs` attribute to specify a custom key name for a property. This attribute will always take precedence over any key formatter you specify.

```csharp

public class MyQueryParams

{

[AliasAs("order")]

public string SortOrder { get; set; }

public int Limit { get; set; }

}

[Get("/group/{id}/users")]

Task<List<User>> GroupList([AliasAs("id")] int groupId, [Query] MyQueryParams params);

params.SortOrder = "desc";

params.Limit = 10;

GroupList(1, params);

```

This will generate the following request:

```

```

2. **Using the `RefitSettings.UrlParameterKeyFormatter` Property**:

By default, Refit uses the property name as the query key without any additional formatting. If you want to apply a custom format across all your query keys, you can use the `UrlParameterKeyFormatter` property. Remember that if a property has an `AliasAs` attribute, it will be used regardless of the formatter.

The following example uses the built-in `CamelCaseUrlParameterKeyFormatter`:

```csharp

public class MyQueryParams

{

public string SortOrder { get; set; }

[AliasAs("queryLimit")]

public int Limit { get; set; }

}

[Get("/group/users")]

Task<List<User>> GroupList([Query] MyQueryParams params);

params.SortOrder = "desc";

params.Limit = 10;

```

The request will look like:

```

```

**Note**: The `AliasAs` attribute always takes the top priority. If both the attribute and a custom key formatter are present, the `AliasAs` attribute's value will be used.

In Refit, the `UrlParameterFormatter` property within `RefitSettings` allows you to customize how parameter values are formatted in the URL. This can be particularly useful when you need to format dates, numbers, or other types in a specific manner that aligns with your API's expectations.

**Using `UrlParameterFormatter`**:

Assign a custom formatter that implements the `IUrlParameterFormatter` interface to the `UrlParameterFormatter` property.

public class CustomDateUrlParameterFormatter : IUrlParameterFormatter

{

public string? Format(object? value, ICustomAttributeProvider attributeProvider, Type type)

{

if (value is DateTime dt)

{

return dt.ToString("yyyyMMdd");

}

return value?.ToString();

}

}

var settings = new RefitSettings

{

UrlParameterFormatter = new CustomDateUrlParameterFormatter()

};

In this example, a custom formatter is created for date values. Whenever a `DateTime` parameter is encountered, it formats the date as `yyyyMMdd`.

**Formatting Dictionary Keys**:

When dealing with dictionaries, it's important to note that keys are treated as values. If you need custom formatting for dictionary keys, you should use the `UrlParameterFormatter` as well.

For instance, if you have a dictionary parameter and you want to format its keys in a specific way, you can handle that in the custom formatter:

public class CustomDictionaryKeyFormatter : IUrlParameterFormatter

{

public string? Format(object? value, ICustomAttributeProvider attributeProvider, Type type)

{

if (attributeProvider is PropertyInfo prop && prop.PropertyType.IsGenericType && prop.PropertyType.GetGenericTypeDefinition() == typeof(Dictionary<,>))

{

return value?.ToString().ToUpperInvariant();

}

return value?.ToString();

}

}

var settings = new RefitSettings

{

UrlParameterFormatter = new CustomDictionaryKeyFormatter()

};

In the above example, the dictionary keys will be converted to uppercase.

<TargetFrameworks>net462;netstandard2.0;net6.0;net8.0</TargetFrameworks>

using Xunit;

namespace Refit.Tests;

public class CamelCaselTestsRequest

public string alreadyCamelCased { get; set; }

public string NOTCAMELCased { get; set; }

public class CamelCaseUrlParameterKeyFormatterTests

[Fact]

public void Format_EmptyKey_ReturnsEmptyKey()

{

var urlParameterKeyFormatter = new CamelCaseUrlParameterKeyFormatter();

var output = urlParameterKeyFormatter.Format(string.Empty);

Assert.Equal(string.Empty, output);

}

[Fact]

public void FormatKey_Returns_ExpectedValue()

{

var urlParameterKeyFormatter = new CamelCaseUrlParameterKeyFormatter();

var refitSettings = new RefitSettings { UrlParameterKeyFormatter = urlParameterKeyFormatter };

var fixture = new RequestBuilderImplementation<IDummyHttpApi>(refitSettings);

var factory = fixture.BuildRequestFactoryForMethod(nameof(IDummyHttpApi.ComplexQueryObjectWithDictionary));

var complexQuery = new CamelCaselTestsRequest

{

alreadyCamelCased = "value1",

NOTCAMELCased = "value2"

};

var output = factory([complexQuery]);

var uri = new Uri(new Uri("http://api"), output.RequestUri);

Assert.Equal("/foo?alreadyCamelCased=value1&notcamelCased=value2", uri.PathAndQuery);

}

using Xunit;

namespace Refit.Tests;

public class RefitSettingsTests

[Fact]

public void Can_CreateRefitSettings_WithoutException()

{

var contentSerializer = new NewtonsoftJsonContentSerializer();

var urlParameterFormatter = new DefaultUrlParameterFormatter();

var urlParameterKeyFormatter = new CamelCaseUrlParameterKeyFormatter();

var formUrlEncodedParameterFormatter = new DefaultFormUrlEncodedParameterFormatter();

var exception = Record.Exception(() => new RefitSettings());

Assert.Null(exception);

exception = Record.Exception(() => new RefitSettings(contentSerializer));

Assert.Null(exception);

exception = Record.Exception(() => new RefitSettings(contentSerializer, urlParameterFormatter));

Assert.Null(exception);

exception = Record.Exception(() => new RefitSettings(contentSerializer, urlParameterFormatter, formUrlEncodedParameterFormatter));

Assert.Null(exception);

exception = Record.Exception(() => new RefitSettings(contentSerializer, urlParameterFormatter, formUrlEncodedParameterFormatter, urlParameterKeyFormatter));

Assert.Null(exception);

}