3.66Enabling the JSON Response Deserialization Wrapper

Created on Aug 17, 2026~6 min read

When communicating with a third-party API over HTTP, a unified JSON response structure is usually returned, such as the ApiResult<T> type, where the actual data is stored in the Data property:

cs
public class ApiResult<T>{    public bool Success { get; set; }    public T? Data { get; set; }    // Actual returned data}

When the JSON response deserialization wrapper is not enabled, each call requires explicitly specifying the ApiResult<T> type:

cs
var content = await httpRemoteService.SendAsAsync<ApiResult<string>>(    HttpRequestBuilder.Get("https://furion.net"));

Enabling

1. Enable for a single request

To simplify the calling process, you can configure the JSON response deserialization wrapper so that it automatically extracts the content of the Data property:

cs
// Configure the default HTTP clientservices.AddHttpClient(string.Empty)    .ConfigureOptions(options =>    {        options.JsonResponseWrapper = new JsonResponseWrapper(typeof(ApiResult<>), nameof(ApiResult<>.Data));    });

After configuration, enable the feature by calling UseJsonResponseWrapper(), and afterwards you only need to specify the target data type without repeatedly declaring ApiResult<T>:

cs
var content = await httpRemoteService.SendAsAsync<string>(    HttpRequestBuilder.Get("https://furion.net").UseJsonResponseWrapper());

The framework will automatically create an ApiResult<string> instance at runtime and return the value of its Data property.

2. Enable globally (applies to all requests by default)

You can also enable the JSON response deserialization wrapper globally by simply setting UseJsonResponseWrapper to true:

cs
// Configure the default HTTP clientservices.AddHttpClient(string.Empty)    .ConfigureOptions(options =>    {        options.JsonResponseWrapper = new JsonResponseWrapper(typeof(ApiResult<>), nameof(ApiResult<>.Data));        options.UseJsonResponseWrapper = true;    });

After enabling globally, all requests use the wrapper by default:

cs
var content = await httpRemoteService.SendAsAsync<string>(    HttpRequestBuilder.Get("https://furion.net")); // No need to explicitly call UseJsonResponseWrapper()

3. Disabling Once (Overriding Global Settings)

If you need to disable this feature for a specific request, call the following method:

cs
var content = await httpRemoteService.SendAsAsync<ApiResult<string>>(    HttpRequestBuilder.Get("https://furion.net").UseJsonResponseWrapper(false));

By default, not calling UseJsonResponseWrapper() means the feature is not enabled, in which case you must pass the complete response type, unless UseJsonResponseWrapper = true is configured globally.

Custom Result Handling (ResultHandler)

Sometimes, in addition to extracting Data, you need to perform additional validation or transformation on the response. This can be achieved through the ResultHandler callback:

cs
// Configure the default HTTP clientservices.AddHttpClient(string.Empty)    .ConfigureOptions(options =>    {        options.JsonResponseWrapper = new JsonResponseWrapper(typeof(ApiResult<>), nameof(ApiResult<>.Data))        {            ResultHandler = context =>            {                if (context.Instance is { } instance)                {                     // You can access the wrapper type instance and get any of its properties                    var success = context.GetPropertyValue<bool>(nameof(ApiResult<>.Success));                }                // For example, ensure the request succeeds                context.ResponseMessage.EnsureSuccessStatusCode();                // Return the final target result (i.e., the value of Data)                return context.Result;            }        };    });

Through ResultHandler, you can execute any custom logic (such as validation, transformation, or exception handling) before returning the final data, making request processing more flexible.

The type of the context parameter is JsonResponseWrapperContext, which contains the following properties and methods:

  • Properties:

    • Instance: The concrete instance of the wrapper type (such as ApiResult<T>, of type object?).
    • Result: The target result (i.e., the value of Data, of type object?).
    • ResponseMessage: The response message (of type HttpResponseMessage).

  • Methods:

    • GetPropertyValue<T>(propertyName): Gets the value of a specified property from the concrete type of the wrapper (i.e., Instance).