Migrating Newtonsoft To System Text Json (Microsoft)

---

name: migrating-newtonsoft-to-system-text-json
description: >
  Migrates .NET projects from Newtonsoft.Json to System.Text.Json, updating package references,
  code files, and handling API differences. Use when asked to "migrate Newtonsoft", "switch to
  System.Text.Json", "replace Newtonsoft.Json", or "upgrade JSON library". Triggers for
  .csproj/.vbproj files referencing Newtonsoft.Json and .cs/.vb files using Newtonsoft.Json
  namespaces. Also applies when modernizing .NET dependencies or removing third-party JSON
  libraries.
metadata:
  origin: Microsoft
  discovery: lazy
  traits: .NET|CSharp|VisualBasic|DotNetCore
---


# Newtonsoft.Json to System.Text.Json Migration

## Overview

Migrate .NET projects from `Newtonsoft.Json` to `System.Text.Json`, including package references, code files, and configuration changes while preserving application behavior.

## Scope Determination

- If a single project is specified, migrate that project only.
- If a solution is specified, migrate all projects in the solution referencing `Newtonsoft.Json`.
- NuGet package names, assembly names, and project names are **case-insensitive** — account for this when searching for and removing dependencies.

## Workflow

Complete all steps in order without pausing between them. Continue until the migration is finished or user input is genuinely required. Ordering matters because later steps depend on earlier ones (e.g., code updates rely on package references being correct first).

```
Migration Progress:
- [ ] Step 1: Update package dependencies
- [ ] Step 2: Update code files
- [ ] Step 3: Validate migration
- [ ] Step 4: Build verification
```

### Step 1: Update Package Dependencies

For each project with an **explicit** dependency on `Newtonsoft.Json` in the project file or imported MSBuild targets (skip projects that only receive it transitively to avoid adding unnecessary new package references):

1. Remove the `Newtonsoft.Json` package reference and assembly reference from the project file.
2. Add a `System.Text.Json` package reference with a version supporting the project's target framework. Use tools to determine the best version; fall back to manual determination if unavailable.
3. If using Central Package Management (CPM):
   - Remove the `Newtonsoft.Json` `PackageVersion` entry from `Directory.Packages.props`.
   - Add `System.Text.Json` `PackageReference` without a version in project files.
   - Add a `System.Text.Json` `PackageVersion` entry to `Directory.Packages.props`.

### Step 2: Update Code Files

Update code files in affected projects **and** projects that depend on them (transitive dependents may use `Newtonsoft.Json` types received through project references):

1. Search for all code files using `Newtonsoft.Json` — prefer search tools when available, passing root folders for all affected projects.
2. Replace `Newtonsoft.Json` API usage with `System.Text.Json` equivalents. Preserve business logic, comments, and formatting. Never add placeholder code.
3. Handle using statements correctly:
   - If a file still uses Newtonsoft API after partial conversion, replace `Newtonsoft.Json` usings with appropriate `System.Text.Json` usings.
   - If no Newtonsoft API remains after conversion, remove the usings entirely — do not replace them with `System.Text.Json` usings.
   - If no `Newtonsoft.Json` usings existed originally, do not add `System.Text.Json` usings.
   - Skip comments and string literal constants when checking for Newtonsoft API usage.
4. Add namespace-specific usings when replacement types live in sub-namespaces. For example, replacing `JsonPropertyAttribute` with `JsonPropertyNameAttribute` requires `using System.Text.Json.Serialization;` because the type moved from the root namespace to a child namespace.
5. Track any code that cannot be cleanly converted or has potential runtime behavior changes — flag these for the user.

### Step 3: Validate Migration

Search all affected projects for any remaining `Newtonsoft.Json` references. If any are found, return to Step 2. Repeat until no references remain. This loop catches references missed in large solutions where transitive dependencies can hide usages.

### Step 4: Build Verification

Build all modified projects. Fix all build errors before proceeding — iterating until the build succeeds ensures the migration is mechanically correct.

## API Differences

### Key Behavioral Differences

| Behavior | Newtonsoft.Json | System.Text.Json |
|----------|----------------|------------------|
| Property name matching | Case-insensitive by default | Case-sensitive by default — use `PropertyNameCaseInsensitive` if needed |
| Character escaping | Permissive | Escapes more characters for XSS protection |
| Comments/trailing commas | Allowed by default | Requires `ReadCommentHandling` and `AllowTrailingCommas` |
| Numbers in quotes | Accepted | Requires `NumberHandling` configuration |
| Quote style | Single quotes and unquoted names allowed | Requires double quotes per RFC 8259 |

### Common Type Mappings

| Newtonsoft.Json | System.Text.Json |
|-----------------|------------------|
| `JsonPropertyAttribute` | `JsonPropertyNameAttribute` (in `System.Text.Json.Serialization`) |
| `NullValueHandling.Ignore` | `DefaultIgnoreCondition` global option |
| `[JsonConstructor]` | `[JsonConstructor]` (same attribute exists) |
| `PreserveReferencesHandling` | `ReferenceHandler` global setting |
| `TypeNameHandling` | `JsonDerivedTypeAttribute` for polymorphism |
| `JsonConvert.SerializeObject()` | `JsonSerializer.Serialize()` |
| `JsonConvert.DeserializeObject()` | `JsonSerializer.Deserialize()` |

### Target Framework Support

System.Text.Json is included in:
- .NET Core 3.1+
- .NET Standard 2.0+ (via NuGet package)
- .NET Framework 4.6.2+ (via NuGet package)

## Success Criteria

- No `Newtonsoft.Json` references remain in affected projects
- All modified projects build without errors
- Any unconvertible patterns or behavioral changes flagged for the user