Complete Guide to Passing List of Objects to MVC Controller Using jQuery Ajax

Problem Background and Phenomenon Analysis

In ASP.NET MVC development, passing data from the frontend to backend controllers via jQuery Ajax is a common requirement. However, developers often encounter issues where controller method parameters become null when attempting to pass arrays of objects. This typically occurs when JavaScript array objects are directly passed to C# controller methods.

The original code example illustrates a typical problem scenario: the frontend defines an array containing three objects, each with id and color properties, then sends it via Ajax POST request to the /Xhr/ThingController/PassThing endpoint. Despite serializing the data with JSON.stringify(), the things parameter in the controller remains null.

Root Cause Analysis

The core issue lies in ASP.NET MVC's model binding mechanism. When Ajax requests send data, the MVC framework needs to correctly map incoming JSON data to controller method parameters. When array objects are passed directly, the model binder cannot identify the correspondence between parameter names and the data.

Specifically, when using data: JSON.stringify(things), the data sent to the server has the format: [{"id":1,"color":"yellow"},{"id":2,"color":"blue"},{"id":3,"color":"red"}]. This format lacks parameter name information, preventing MVC from binding the data to the parameter named things.

Solution Implementation

The correct solution involves wrapping the array within an object and specifying the parameter name. The modified Ajax call should use: data: JSON.stringify({ 'things': things }). This generates data in the format: {"things":[{"id":1,"color":"yellow"},{"id":2,"color":"blue"},{"id":3,"color":"red"}]}.

The complete implementation code is as follows:

<script type="text/javascript">
    $(document).ready(function () {
        var things = [
            { id: 1, color: 'yellow' },
            { id: 2, color: 'blue' },
            { id: 3, color: 'red' }
        ];      
        
        things = JSON.stringify({ 'things': things });

        $.ajax({
            contentType: 'application/json; charset=utf-8',
            dataType: 'json',
            type: 'POST',
            url: '/Home/PassThings',
            data: things,
            success: function () {          
                $('#result').html('"PassThings()" successfully called.');
            },
            failure: function (response) {          
                $('#result').html(response);
            }
        }); 
    });
</script>

The corresponding C# controller code:

public void PassThings(List<Thing> things)
{
    var t = things;
}

public class Thing
{
    public int Id { get; set; }
    public string Color { get; set; }
}

Key Technical Points

Importance of contentType and dataType Settings: These parameters are crucial in Ajax requests. contentType: 'application/json; charset=utf-8' informs the server that JSON format data is being sent, while dataType: 'json' specifies the expected data type from the server. Omitting these settings can prevent proper data parsing.

Parameter Naming Convention: When wrapping the object, the property name must exactly match the controller method parameter name. For example, if the controller parameter is named things, the key in the JSON object must also be things.

Data Type Compatibility: C# controllers can accept various collection types such as Thing[], List<Thing>, or IEnumerable<Thing>, as long as property names and types match the frontend data.

Alternative Approaches Comparison

In addition to the JSON.stringify method, jQuery's $.post simplified method can be used:

$.post('@Url.Action("PassThings")', { things: things },
   function () {
        $('#result').html('"PassThings()" successfully called.');
   });

This approach does not require manual setting of contentType and dataType, as jQuery automatically handles data serialization. The corresponding controller method can be annotated as:

[HttpPost]
public void PassThings(IEnumerable<Thing> things)
{
    // do stuff with things here...
}

Both methods have their advantages: $.ajax offers finer control, while $.post is more concise and easier to use.

Best Practices Summary

In practical development, it is recommended to follow these best practices: always explicitly specify contentType and dataType parameters to ensure consistent data formats between frontend and backend; use consistent naming conventions to avoid binding failures due to case or spelling differences; prefer $.ajax for complex scenarios to gain better control; for simple scenarios, $.post can provide a more straightforward solution.

By correctly understanding the MVC model binding mechanism and Ajax data transmission principles, developers can avoid common parameter binding issues and build more stable and reliable web applications.