Navigating the Deprecation of Newtonsoft.Json in VSTest

Overview

Starting with .NET 11 Preview 4 and Visual Studio 18.8, the VSTest platform—the engine behind dotnet test and Test Explorer—no longer ships with Newtonsoft.Json. Instead, it uses System.Text.Json on .NET and JSONite on .NET Framework. This change is driven by security and servicing concerns: older versions of Newtonsoft.Json (below 13.0.0) are flagged as vulnerable on NuGet.org, and the dependency was unnecessary for VSTest itself. Removing it aligns with the broader .NET SDK cleanup. The wire format remains identical, older test hosts stay compatible, and serialization performance is equal or better. Most projects need no changes, but a small subset will encounter clear build or runtime failures. This guide explains everything you need to know to prepare and fix those issues.

Prerequisites

Before diving into the steps, ensure you have the following:

• Knowledge level: Familiarity with .NET test projects, NuGet package references, and basic debugging.
• Environment: Access to a .NET 11 Preview 4+ SDK or Visual Studio 18.8+ for testing the changes. Also have an older SDK handy to verify pre-update behavior.
• Tools: A text editor or IDE (e.g., Visual Studio, VS Code, Rider) to modify project files.
• Test project: A solution containing at least one test project (xUnit, NUnit, MSTest) that you can experiment with.

Step-by-Step Instructions

1. Identify if Your Project Is Affected

First, determine whether your test project falls into the affected category. The majority of projects are not affected:

• Not affected: Projects that do not use Newtonsoft.Json at all, projects that explicitly reference Newtonsoft.Json as a normal PackageReference (with runtime assets included), and xUnit/NUnit projects on .NET or using AppDomains (they already required explicit references).
• Affected: Projects that implicitly relied on Newtonsoft.Json being available via VSTest, i.e., those that use Newtonsoft.Json types (like JObject, JsonConvert) without adding a direct package reference, or projects that exclude runtime assets of Newtonsoft.Json.

Action: Inspect each test project’s .csproj for any PackageReference to Newtonsoft.Json. If absent but your code uses Newtonsoft.Json, you’re implicitly dependent. Also check for <ExcludeAssets>runtime</ExcludeAssets> in any Newtonsoft.Json reference.

2. Fix Missing References (Build Errors)

If a test project uses Newtonsoft.Json types without a direct package reference, the build will now fail with an error like: The type or namespace name 'Newtonsoft' could not be found. This previously compiled because VSTest’s copy leaked into the test project.

Fix: Add an explicit PackageReference for Newtonsoft.Json. Use the latest stable version (13.0.3 as of writing) to avoid future advisories:

<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

Place this inside an <ItemGroup> in your .csproj. Rebuild the project to confirm the error disappears.

3. Fix Runtime Errors (FileNotFoundException)

Projects that reference Newtonsoft.Json but exclude its runtime assets (e.g., with <ExcludeAssets>runtime</ExcludeAssets>) previously relied on VSTest’s copy during test execution. After the update, the test run will throw:

System.IO.FileNotFoundException: Could not load file or assembly 'Newtonsoft.Json, Version=13.0.0.0, ...'

Fix: Remove the <ExcludeAssets>runtime</ExcludeAssets> from the package reference. If you must exclude assets for some other reason, ensure you include the runtime asset for Newtonsoft.Json. The simplest resolution is to change the reference to a standard one:

<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

If you have other assets excluded (like compile), adjust carefully. After the change, rebuild and rerun your tests. The FileNotFoundException should be gone.

4. Fix Test Adapter or Data Collector Extension Errors

Custom test adapters or data collectors that used Newtonsoft.Json without declaring it as a dependency will now fail at load time. The error message looks like:

Data collector 'SampleDataCollector' threw an exception during type loading, construction, or initialization: System.IO.FileNotFoundException: Could not load file or assembly 'Newtonsoft.Json, Version=13.0.0.0, ...'

Fix: Locate the adapter or data collector project and add a direct dependency on Newtonsoft.Json. For example, in its .csproj:

<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />

If the adapter is delivered as a NuGet package, you may need to update the package to include this dependency explicitly. Alternatively, if the adapter targets .NET Framework, consider switching to JSONite (which VSTest uses on .NET Framework) to avoid Newtonsoft.Json entirely—but that’s an advanced change. The immediate fix is to add the reference. Rebuild and redeploy the adapter, then test.

Common Mistakes

• Assuming you can ignore the warning: The failures are non-silent and will appear in test logs, TRX files, and Azure DevOps/GitHub test views. Ignoring them may break CI/CD pipelines. Always apply the appropriate fix.
• Adding the wrong version: Use version 13.0.3 (or later) to avoid the same security concerns. Older versions (e.g., 12.0.3) are still vulnerable and may cause NuGet restore warnings.
• Confusing runtime vs. compile assets: If you use <ExcludeAssets>compile</ExcludeAssets> but keep runtime assets, the build may succeed but tests will fail silently? No—the FileNotFoundException occurs at runtime because VSTest’s copy is gone. Ensure the runtime asset is included.
• Forgetting to update adapter packages: If you distribute a test adapter via NuGet and it previously depended on VSTest’s Newtonsoft.Json, you must ship an updated version with an explicit dependency. Otherwise, users with the new SDK will see load errors.
• Assuming System.Text.Json is a drop-in replacement: It is not. If your code uses Newtonsoft.Json-specific features (like JObject, JsonConvert, or PreserveReferencesHandling), you must keep Newtonsoft.Json. The VSTest change only removes the internal dependency; it does not affect test project serialization.

Summary

The removal of Newtonsoft.Json from VSTest is a proactive security measure that affects only projects that implicitly relied on the package being present via the test host. The fixes are straightforward: add a direct PackageReference to Newtonsoft.Json 13.0.3 if you use its types, remove any <ExcludeAssets>runtime</ExcludeAssets> from existing references, and ensure custom adapters declare their dependencies. By following the steps in this guide, you can upgrade to .NET 11 Preview 4+ or Visual Studio 18.8+ without disruption. For most teams, this is a quick one-line change—or no change at all.