Proposal: Add a TreatAsString field to QueryAttribute (#1943)

* Proposal: Add a `TreatAsString` field to `QueryAttribute`

The proposal arises from the need to pass custom types or structs which might represent types with rules and conversions.

For example:

```csharp
record readonly struct ZipCode(ushort ZipCode) {
    public override string ToString() =>
        ZipCode.ToString();
}
```

To solve the problem the proposal seeks to add a field to the QueryAttribute called `TreatAsString`.

The new field is used when the query string is created and simply calls the `ToString()` function on a type.

There is a workaround that is not documented. The current workaround is to implement `IFormattable` on the type, which feels redundant if `ToString()` is already implemented on a custom type.

* Updated unit test verification files

* update to unit test files

Author: mark-pro

Refit.Tests/API/ApiApprovalTests.Refit.DotNet8_0.verified.txt

@@ -338,6 +338,7 @@ namespace Refit
         public string? Format { get; set; }
         public bool IsCollectionFormatSpecified { get; }
         public string? Prefix { get; protected set; }
+        public bool TreatAsString { get; set; }
     }
     [System.AttributeUsage(System.AttributeTargets.Method)]
     public class QueryUriFormatAttribute : System.Attribute

Refit.Tests/API/ApiApprovalTests.Refit.DotNet9_0.verified.txt

@@ -338,6 +338,7 @@ namespace Refit
         public string? Format { get; set; }
         public bool IsCollectionFormatSpecified { get; }
         public string? Prefix { get; protected set; }
+        public bool TreatAsString { get; set; }
     }
     [System.AttributeUsage(System.AttributeTargets.Method)]
     public class QueryUriFormatAttribute : System.Attribute

Refit.Tests/API/_snapshots/ApiApprovalTests.Refit.DotNet8_0.verified.txt

@@ -338,6 +338,7 @@ namespace Refit
         public string? Format { get; set; }
         public bool IsCollectionFormatSpecified { get; }
         public string? Prefix { get; protected set; }
+        public bool TreatAsString { get; set; }
     }
     [System.AttributeUsage(System.AttributeTargets.Method)]
     public class QueryUriFormatAttribute : System.Attribute

Refit.Tests/API/_snapshots/ApiApprovalTests.Refit.DotNet9_0.verified.txt

@@ -338,6 +338,7 @@ namespace Refit
         public string? Format { get; set; }
         public bool IsCollectionFormatSpecified { get; }
         public string? Prefix { get; protected set; }
+        public bool TreatAsString { get; set; }
     }
     [System.AttributeUsage(System.AttributeTargets.Method)]
     public class QueryUriFormatAttribute : System.Attribute

Refit.Tests/RequestBuilder.cs

@@ -2044,6 +2044,7 @@ Task QueryWithOptionalParameters(
             int id,
             [Query] string text = null,
             [Query] int? optionalId = null,
+            [Query(TreatAsString = true)] Foo foo = null,
             [Query(CollectionFormat = CollectionFormat.Multi)] string[] filters = null
         );
 
@@ -3541,12 +3542,12 @@ string expectedQuery
         }
 
         [Theory]
-        [InlineData("/api/123?text=title&optionalId=999&filters=A&filters=B")]
+        [InlineData("/api/123?text=title&optionalId=999&foo=foo&filters=A&filters=B")]
         public void TestNullableQueryStringParams(string expectedQuery)
         {
             var fixture = new RequestBuilderImplementation<IDummyHttpApi>();
             var factory = fixture.BuildRequestFactoryForMethod("QueryWithOptionalParameters");
-            var output = factory(new object[] { 123, "title", 999, new string[] { "A", "B" } });
+            var output = factory(new object[] { 123, "title", 999, new Foo(), new string[] { "A", "B" } });
 
             var uri = new Uri(new Uri("http://api"), output.RequestUri);
             Assert.Equal(expectedQuery, uri.PathAndQuery);
@@ -3558,7 +3559,7 @@ public void TestNullableQueryStringParamsWithANull(string expectedQuery)
         {
             var fixture = new RequestBuilderImplementation<IDummyHttpApi>();
             var factory = fixture.BuildRequestFactoryForMethod("QueryWithOptionalParameters");
-            var output = factory(new object[] { 123, "title", null, new string[] { "A", "B" } });
+            var output = factory(new object[] { 123, "title", null, null, new string[] { "A", "B" } });
 
             var uri = new Uri(new Uri("http://api"), output.RequestUri);
             Assert.Equal(expectedQuery, uri.PathAndQuery);
@@ -3944,6 +3945,14 @@ public void ComplexQueryObjectWithDictionaryAndCustomFormatterProducesCorrectQue
         }
     }
 
+    public record Foo
+    {
+        public override string ToString()
+        {
+            return "foo";
+        }
+    }
+
     static class RequestBuilderTestExtensions
     {
         public static Func<object[], HttpRequestMessage> BuildRequestFactoryForMethod(

Refit/Attributes.cs

@@ -465,6 +465,12 @@ public QueryAttribute(CollectionFormat collectionFormat)
             CollectionFormat = collectionFormat;
         }
 
+        /// <summary>
+        /// Used to specify that the value should be treated as a string.
+        /// Set to true if you want to call ToString() on the object before adding it to the query string.
+        /// </summary>
+        public bool TreatAsString { get; set; }
+
         /// <summary>
         /// Used to customize the name of either the query parameter pair or of the form field when form encoding.
         /// </summary>

Refit/RequestBuilderImplementation.cs

@@ -947,7 +947,18 @@ void AddQueryParameters(RestMethodInfoInternal restMethod, QueryAttribute? query
             List<KeyValuePair<string, string?>> queryParamsToAdd, int i, RestMethodParameterInfo? parameterInfo)
         {
             var attr = queryAttribute ?? DefaultQueryAttribute;
-            if (DoNotConvertToQueryMap(param))
+            if (attr.TreatAsString)
+            {
+                queryParamsToAdd.AddRange(
+                    ParseQueryParameter(
+                        param.ToString(),
+                        restMethod.ParameterInfoArray[i],
+                        restMethod.QueryParameterMap[i],
+                        attr
+                    )
+                );
+            }
+            else if (DoNotConvertToQueryMap(param))
             {
                 queryParamsToAdd.AddRange(
                     ParseQueryParameter(