Skip to content

Add breaking change documentation for project.json removal from dotnet restore #47986

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 18, 2025
Merged

Add breaking change documentation for project.json removal from dotnet restore #47986

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
74ae660
Initial plan
Copilot Aug 16, 2025
0daa8c0
Add breaking change documentation for project.json removal from dotne…
Copilot Aug 16, 2025
486a6db
Apply suggestions from code review
gewarren Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/core/compatibility/10.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
| [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change | Preview 2 |
| [`dotnet package list` performs restore](sdk/10.0/dotnet-package-list-restore.md) | Behavioral change | Preview 4 |
| [`dotnet restore` audits transitive packages](sdk/10.0/nugetaudit-transitive-packages.md) | Behavioral change | Preview 3 |
| [project.json not supported in `dotnet restore`](sdk/10.0/dotnet-restore-project-json-unsupported.md) | Source incompatible | Preview 7 |
| [SHA-1 fingerprint support deprecated in `dotnet nuget sign`](sdk/10.0/dotnet-nuget-sign-sha1-deprecated.md) | Behavioral change | Preview 1 |
| [MSBUILDCUSTOMBUILDEVENTWARNING escape hatch removed](sdk/10.0/custom-build-event-warning.md) | Behavioral change | Preview 1 |
| [MSBuild custom culture resource handling](sdk/10.0/msbuild-custom-culture.md) | Behavioral change | Preview 1 |
Expand Down
47 changes: 47 additions & 0 deletions docs/core/compatibility/sdk/10.0/dotnet-restore-project-json-unsupported.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
title: "Breaking change - project.json is no longer supported in dotnet restore"
description: "Learn about the breaking change in .NET 10 where dotnet restore no longer supports project.json based projects."
ms.date: 08/16/2025
ai-usage: ai-assisted
ms.custom: https://github.com/dotnet/docs/issues/47968
---

# project.json no longer supported in dotnet restore

Starting with .NET 10, the [`dotnet restore` command](../../../tools/dotnet-restore.md) no longer supports `project.json` based projects. Such projects are ignored during the restore operation.

## Version introduced

.NET 10 Preview 7

## Previous behavior

The `dotnet restore` command restored dependencies for `project.json` based projects.

## New behavior

The `dotnet restore` command ignores `project.json` based projects and no longer restores their dependencies.

## Type of breaking change

This change can affect [source compatibility](../../categories.md#source-compatibility).

## Reason for change

The `project.json` format was originally available only in .NET Core previews (through Preview 2 of .NET Core 1.0) and was completely replaced by PackageReference in 2017. The format has been marked as deprecated since 2017.

When the `project.json` format was replaced, users migrated these projects using the [`dotnet migrate`](../../../tools/dotnet-migrate.md) command, but that command was removed from the CLI in the .NET Core 3.0 SDK.

The removal of `project.json` support completes this transition and allows the .NET team to focus on delivering a better experience for PackageReference-based projects.

## Recommended action

Migrate your `project.json` projects to use PackageReference format instead.

If you have .NET Core based `project.json` projects, you can use older versions of the .NET SDK that still include the [`dotnet migrate` command](../../../tools/dotnet-migrate.md) to convert them to the modern project format.

For more information about migrating from `project.json`, see [Migrating from project.json to .csproj](/nuget/archive/project-json#migrate-projectjson-to-packagereference).

## Affected APIs

None.
2 changes: 2 additions & 0 deletions docs/core/compatibility/toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,8 @@ items:
href: sdk/10.0/dotnet-tool-pack-publish.md
- name: "`dotnet restore` audits transitive packages"
href: sdk/10.0/nugetaudit-transitive-packages.md
- name: project.json not supported in `dotnet restore`
href: sdk/10.0/dotnet-restore-project-json-unsupported.md
- name: Default workload configuration from 'loose manifests' to 'workload sets' mode
href: sdk/10.0/default-workload-config.md
- name: "`dotnet package list` performs restore"
Expand Down