Using the Custom Reference Handler

Oct 13, 2025 by leolavanderia.com.br 29 views

Introduction

When working with ASP.NET Core, it's essential to choose the right JSON serializer to handle complex data structures. Newtonsoft.Json has been a popular choice for many years, but with the introduction of System.Text.Json in .NET Core 3.0, many developers are now opting for the new serializer. However, one of the challenges when migrating from Newtonsoft.Json to System.Text.Json is handling reference loops. In this article, we'll explore how to convert the Newton Json ReferenceLoopHandling to System.Text.Json.

Newtonsoft.Json ReferenceLoopHandling

Newtonsoft.Json provides a feature called ReferenceLoopHandling, which allows you to handle reference loops in JSON serialization. The ReferenceLoopHandling property can be set to one of the following values:

Ignore: Ignore the reference loop and serialize the object as if it were a new object.
Error: Throw an exception when a reference loop is detected.
Replace: Replace the reference loop with a new object.

To enable ReferenceLoopHandling in Newtonsoft.Json, you can use the following code:

builder.Services
    .AddControllers()
    .AddNewtonsoftJson(o => o.SerializerSettings.ReferenceLoopHandling = Newtonsoft.Json.ReferenceLoopHandling.Ignore);

System.Text.Json ReferenceLoopHandling

System.Text.Json also provides a way to handle reference loops, but it's not as straightforward as Newtonsoft.Json. To handle reference loops in System.Text.Json, you need to create a custom JsonSerializerOptions instance and set the ReferenceHandler property to a custom implementation.

Here's an example of how to create a custom JsonSerializerOptions instance:

var options = new JsonSerializerOptions();
options.ReferenceHandler = ReferenceHandler.IgnoreCycles;

The ReferenceHandler property can be set to one of the following values:

IgnoreCycles: Ignore the reference loop and serialize the object as if it were a new object.
Throw: Throw an exception when a reference loop is detected.

Converting Newtonsoft.Json to System.Text.Json

To convert the Newtonsoft.Json ReferenceLoopHandling to System.Text.Json, you need to create a custom JsonSerializerOptions instance and set the ReferenceHandler property to a custom implementation. Here's an example of how to do it:

builder.Services
    .AddControllers()
    .AddSystemTextJson(options =>
    {
        options.ReferenceHandler = ReferenceHandler.IgnoreCycles;
    });

Custom Reference Handler

If you want to create a custom reference handler, you can implement the JsonReferenceHandler interface. Here's an example of how to create a custom reference handler:

public class CustomReferenceHandler : JsonReferenceHandler
{
    public override ValueTask<object> HandleReferenceAsync(JsonSerializer serializer, object target, string reference, JsonProperty property, Type typeToSerialize)
    {
        // Handle the reference loop here
        return ValueTask.FromResult<object>(null);
    }
}

Using the Custom Reference Handler

To use the custom reference handler, you need to create a custom JsonSerializerOptions instance and set the ReferenceHandler property to the custom implementation. Here's an example of how to do it:

var options = new JsonSerializerOptions();
options.ReferenceHandler = new CustomReferenceHandler();

Conclusion

In this article, we've explored how to convert the Newton Json ReferenceLoopHandling to System.Text.Json. We've seen how to create a custom JsonSerializerOptions instance and set the ReferenceHandler property to a custom implementation. We've also seen how to create a custom reference handler and use it in System.Text.Json. By following these steps, you can easily convert your Newtonsoft.Json ReferenceLoopHandling to System.Text.Json.

Best Practices

Here are some best practices to keep in mind when working with System.Text.Json:

Use the JsonSerializerOptions instance: When working with System.Text.Json, it's essential to create a custom JsonSerializerOptions instance and set the ReferenceHandler property to a custom implementation.
Use a custom reference handler: If you want to handle reference loops in a custom way, you can implement the JsonReferenceHandler interface and use it in System.Text.Json.
Test your code: When working with System.Text.Json, it's essential to test your code thoroughly to ensure that it works as expected.

Common Issues

Here are some common issues to watch out for when working with System.Text.Json:

Reference loops: System.Text.Json can throw an exception when a reference loop is detected. To handle this, you can create a custom JsonSerializerOptions instance and set the ReferenceHandler property to a custom implementation.
Serialization errors: System.Text.Json can throw an exception when a serialization error occurs. To handle this, you can create a custom JsonSerializerOptions instance and set the JsonSerializerOptions property to a custom implementation.

Conclusion

Q: What is the main difference between Newtonsoft.Json and System.Text.Json?

A: The main difference between Newtonsoft.Json and System.Text.Json is that Newtonsoft.Json is a third-party library, while System.Text.Json is a built-in .NET Core library. System.Text.Json is also faster and more efficient than Newtonsoft.Json.

Q: How do I handle reference loops in System.Text.Json?

A: To handle reference loops in System.Text.Json, you need to create a custom JsonSerializerOptions instance and set the ReferenceHandler property to a custom implementation. You can set the ReferenceHandler property to one of the following values:

IgnoreCycles: Ignore the reference loop and serialize the object as if it were a new object.
Throw: Throw an exception when a reference loop is detected.

Q: How do I create a custom reference handler in System.Text.Json?

A: To create a custom reference handler in System.Text.Json, you need to implement the JsonReferenceHandler interface. Here's an example of how to create a custom reference handler:

public class CustomReferenceHandler : JsonReferenceHandler
{
    public override ValueTask<object> HandleReferenceAsync(JsonSerializer serializer, object target, string reference, JsonProperty property, Type typeToSerialize)
    {
        // Handle the reference loop here
        return ValueTask.FromResult<object>(null);
    }
}

Q: How do I use a custom reference handler in System.Text.Json?

A: To use a custom reference handler in System.Text.Json, you need to create a custom JsonSerializerOptions instance and set the ReferenceHandler property to the custom implementation. Here's an example of how to do it:

var options = new JsonSerializerOptions();
options.ReferenceHandler = new CustomReferenceHandler();

Q: What are some common issues to watch out for when working with System.Text.Json?

A: Some common issues to watch out for when working with System.Text.Json include:

Reference loops: System.Text.Json can throw an exception when a reference loop is detected. To handle this, you can create a custom JsonSerializerOptions instance and set the ReferenceHandler property to a custom implementation.
Serialization errors: System.Text.Json can throw an exception when a serialization error occurs. To handle this, you can create a custom JsonSerializerOptions instance and set the JsonSerializerOptions property to a custom implementation.

Q: How do I troubleshoot issues with System.Text.Json?

A: To troubleshoot issues with System.Text.Json, you can use the following steps:

Check the error message: Check the error message to see if it provides any clues about the issue.
Check the stack trace: Check the stack trace to see if it provides any clues about the issue.
Use a debugger: Use a debugger to step through the code and see where the issue is occurring.
Use a logging library: Use a logging library to log the issue and see if it provides any clues about the issue.

Q: What are some best practices to keep in mind when working with System.Text.Json?

A: Some best practices to keep in mind when working with System.Text.Json include:

Use the JsonSerializerOptions instance: When working with System.Text.Json, it's essential to create a custom JsonSerializerOptions instance and set the ReferenceHandler property to a custom implementation.
Use a custom reference handler: If you want to handle reference loops in a custom way, you can implement the JsonReferenceHandler interface and use it in System.Text.Json.
Test your code: When working with System.Text.Json, it's essential to test your code thoroughly to ensure that it works as expected.

Q: Can I use System.Text.Json with ASP.NET Core?

A: Yes, you can use System.Text.Json with ASP.NET Core. In fact, System.Text.Json is the default JSON serializer used by ASP.NET Core. To use System.Text.Json with ASP.NET Core, you can add the following code to your Startup.cs file:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddSystemTextJson(options =>
        {
            options.ReferenceHandler = ReferenceHandler.IgnoreCycles;
        });
}

Q: Can I use System.Text.Json with .NET Core?

A: Yes, you can use System.Text.Json with .NET Core. In fact, System.Text.Json is a built-in .NET Core library. To use System.Text.Json with .NET Core, you can add the following code to your Program.cs file:

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);
    builder.Services.AddControllers()
        .AddSystemTextJson(options =>
        {
            options.ReferenceHandler = ReferenceHandler.IgnoreCycles;
        });
    var app = builder.Build();
    app.Run();
}