From 9a6d90fbc21f30585f96dea8232a9971c51cfe73 Mon Sep 17 00:00:00 2001 From: Mattias Karlsson Date: Tue, 25 Nov 2025 14:15:17 +0100 Subject: [PATCH 1/6] docs: Add documentation for dotnet project convert command Adds documentation for the dotnet project convert command, which converts file-based programs to project-based programs. The documentation includes: - Command synopsis and description - Conversion process details - All command options (--dry-run, --force, --interactive, --output) - Examples showing conversion from file-based to project-based structure - Translation of #:sdk, #:package, and #:property directives --- docs/core/tools/dotnet-project-convert.md | 138 ++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/core/tools/dotnet-project-convert.md diff --git a/docs/core/tools/dotnet-project-convert.md b/docs/core/tools/dotnet-project-convert.md new file mode 100644 index 0000000000000..f7584da948d61 --- /dev/null +++ b/docs/core/tools/dotnet-project-convert.md @@ -0,0 +1,138 @@ +--- +title: dotnet project convert command +description: The 'dotnet project convert' command converts a file-based program to a project-based program. +ms.date: 10/25/2025 +--- +# dotnet project convert + +**This article applies to:** ✔️ .NET 10 SDK and later versions + +## Name + +`dotnet project convert` - Converts a file-based program to a project-based program. + +## Synopsis + +```dotnetcli +dotnet project convert [--dry-run] [--force] [--interactive] + [-o|--output ] [-h|--help] + +dotnet project convert -h|--help +``` + +## Description + +The `dotnet project convert` command converts a file-based program to a project-based program. This command creates a new directory named for your file, scaffolds a *.csproj* file, moves your code into a file with the same name as the input file, and translates any `#:` directives into MSBuild properties and references. + +This makes the transition seamless, from a single file to a fully functional, buildable, and extensible project. When your file-based app grows in complexity, or you simply want the extra capabilities afforded in project-based apps, you can convert it to a standard project. + +### Conversion process + +The command performs the following operations: + +1. Creates a new directory named after the input file (without extension) +2. Generates a *.csproj* file with appropriate SDK and properties +3. Moves the source code to a file with the same name as the input file +4. Removes `#:` directives from the source code +5. Translates `#:sdk` directives: the first `#:sdk` directive becomes the `` or `` attribute, and any additional `#:sdk` directives become `` or `` elements +6. Translates `#:package` directives to `` elements in the project file +7. Translates `#:property` directives to MSBuild properties in the project file +8. Sets appropriate MSBuild properties based on the SDK and framework detected + +## Arguments + +- **`FILE`** + + The path to the file-based program to convert. The file must be a C# source file (typically with a *.cs* extension). + +## Options + +- **`--dry-run`** + + Determines changes without actually modifying the file system. Shows what would be created or modified without performing the conversion. + +- **`--force`** + + Forces conversion even if there are malformed directives. By default, the command fails if it encounters directives that cannot be properly parsed or converted. + +- [!INCLUDE [interactive](../../../includes/cli-interactive.md)] + +- **`-o|--output `** + + Specifies the output directory for the converted project. If not specified, a directory is created with the same name as the input file (without extension) in the current directory. + +- [!INCLUDE [help](../../../includes/cli-help.md)] + +## Examples + +- Convert a file-based program to a project: + + ```dotnetcli + dotnet project convert app.cs + ``` + + Given a folder containing *app.cs* with the following content: + + ```csharp + #:sdk Microsoft.NET.Sdk.Web + #:package Microsoft.AspNetCore.OpenApi@10.*-* + + var builder = WebApplication.CreateBuilder(); + + builder.Services.AddOpenApi(); + + var app = builder.Build(); + + app.MapGet("/", () => "Hello, world!"); + app.Run(); + ``` + + Running `dotnet project convert app.cs` results in a folder called *app* containing: + + *app/app.cs*: + + ```csharp + var builder = WebApplication.CreateBuilder(); + + builder.Services.AddOpenApi(); + + var app = builder.Build(); + + app.MapGet("/", () => "Hello, world!"); + app.Run(); + ``` + + *app/app.csproj*: + + ```xml + + + + Exe + net10.0 + enable + enable + true + true + + + + + + + + ``` + +- Convert a file-based program to a project in a specific output directory: + + ```dotnetcli + dotnet project convert app.cs --output MyProject + ``` + +## See also + +- [dotnet build](dotnet-build.md) +- [dotnet run](dotnet-run.md) +- [dotnet publish](dotnet-publish.md) +- [Build file-based C# apps](../../csharp/fundamentals/tutorials/file-based-programs.md) + From dc3906824db3d427d53db0094313aa98951a4de6 Mon Sep 17 00:00:00 2001 From: Mattias Karlsson Date: Tue, 25 Nov 2025 14:24:49 +0100 Subject: [PATCH 2/6] Address PR feedback --- docs/core/tools/dotnet-project-convert.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/core/tools/dotnet-project-convert.md b/docs/core/tools/dotnet-project-convert.md index f7584da948d61..70b82d96bd3ad 100644 --- a/docs/core/tools/dotnet-project-convert.md +++ b/docs/core/tools/dotnet-project-convert.md @@ -30,14 +30,14 @@ This makes the transition seamless, from a single file to a fully functional, bu The command performs the following operations: -1. Creates a new directory named after the input file (without extension) -2. Generates a *.csproj* file with appropriate SDK and properties -3. Moves the source code to a file with the same name as the input file -4. Removes `#:` directives from the source code -5. Translates `#:sdk` directives: the first `#:sdk` directive becomes the `` or `` attribute, and any additional `#:sdk` directives become `` or `` elements -6. Translates `#:package` directives to `` elements in the project file -7. Translates `#:property` directives to MSBuild properties in the project file -8. Sets appropriate MSBuild properties based on the SDK and framework detected +1. Creates a new directory named after the input file (without extension). +2. Generates a *.csproj* file with appropriate SDK and properties. +3. Moves the source code to a file with the same name as the input file. +4. Removes `#:` directives from the source code. +5. Translates `#:sdk` directives: the first `#:sdk` directive becomes the `` or `` attribute, and any additional `#:sdk` directives become `` or `` elements. +6. Translates `#:package` directives to `` elements in the project file. +7. Translates `#:property` directives to MSBuild properties in the project file. +8. Sets appropriate MSBuild properties based on the SDK and framework detected. ## Arguments @@ -134,5 +134,5 @@ The command performs the following operations: - [dotnet build](dotnet-build.md) - [dotnet run](dotnet-run.md) - [dotnet publish](dotnet-publish.md) -- [Build file-based C# apps](../../csharp/fundamentals/tutorials/file-based-programs.md) +- [Tutorial: Build file-based C# programs](../../csharp/fundamentals/tutorials/file-based-programs.md) From 1f3618e872573a103d07ffba650e18c06a8cc06f Mon Sep 17 00:00:00 2001 From: Mattias Karlsson Date: Tue, 25 Nov 2025 14:29:03 +0100 Subject: [PATCH 3/6] Address PR feedback --- docs/core/tools/dotnet-project-convert.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/core/tools/dotnet-project-convert.md b/docs/core/tools/dotnet-project-convert.md index 70b82d96bd3ad..2c67441b3dd27 100644 --- a/docs/core/tools/dotnet-project-convert.md +++ b/docs/core/tools/dotnet-project-convert.md @@ -2,6 +2,7 @@ title: dotnet project convert command description: The 'dotnet project convert' command converts a file-based program to a project-based program. ms.date: 10/25/2025 +ai-usage: ai-assisted --- # dotnet project convert From 293bd64ee69d7e1b97b02d62a4e0e8e88e24845d Mon Sep 17 00:00:00 2001 From: "Meaghan Osagie (Lewis)" Date: Tue, 25 Nov 2025 12:20:31 -0800 Subject: [PATCH 4/6] Remove empty line in dotnet-project-convert.md --- docs/core/tools/dotnet-project-convert.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/core/tools/dotnet-project-convert.md b/docs/core/tools/dotnet-project-convert.md index 2c67441b3dd27..a373490cc260b 100644 --- a/docs/core/tools/dotnet-project-convert.md +++ b/docs/core/tools/dotnet-project-convert.md @@ -136,4 +136,3 @@ The command performs the following operations: - [dotnet run](dotnet-run.md) - [dotnet publish](dotnet-publish.md) - [Tutorial: Build file-based C# programs](../../csharp/fundamentals/tutorials/file-based-programs.md) - From e105250a85da7e99caf0a79b9e7d98d02875b2ba Mon Sep 17 00:00:00 2001 From: Mattias Karlsson Date: Tue, 25 Nov 2025 22:35:40 +0100 Subject: [PATCH 5/6] docs: Add dotnet project convert to navigation and index Adds the dotnet project convert command to the CLI index and table of contents. --- docs/core/tools/index.md | 1 + docs/navigate/tools-diagnostics/toc.yml | 2 ++ 2 files changed, 3 insertions(+) diff --git a/docs/core/tools/index.md b/docs/core/tools/index.md index fb36452000943..2efd06ea1603f 100644 --- a/docs/core/tools/index.md +++ b/docs/core/tools/index.md @@ -79,6 +79,7 @@ The following commands are installed by default: - [`package remove`](dotnet-package-remove.md) - [`package search`](dotnet-package-search.md) - [`package update`](dotnet-package-update.md) +- [`project convert`](dotnet-project-convert.md) (Available since .NET 10 SDK) - [`reference add`](dotnet-reference-add.md) - [`reference list`](dotnet-reference-list.md) - [`reference remove`](dotnet-reference-remove.md) diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 639decc0c8367..ff1cadc83aa13 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -194,6 +194,8 @@ items: href: ../../core/tools/dotnet-package-update.md - name: dotnet publish href: ../../core/tools/dotnet-publish.md + - name: dotnet project convert + href: ../../core/tools/dotnet-project-convert.md - name: dotnet reference add/list/remove items: - name: dotnet reference add From c69ef43a7cdbab9bf03311eb9815d7f72995ea94 Mon Sep 17 00:00:00 2001 From: Mattias Karlsson Date: Tue, 25 Nov 2025 22:38:40 +0100 Subject: [PATCH 6/6] Address PR feedback --- docs/core/tools/dotnet-project-convert.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/tools/dotnet-project-convert.md b/docs/core/tools/dotnet-project-convert.md index a373490cc260b..65ce1d147e93d 100644 --- a/docs/core/tools/dotnet-project-convert.md +++ b/docs/core/tools/dotnet-project-convert.md @@ -16,7 +16,7 @@ ai-usage: ai-assisted ```dotnetcli dotnet project convert [--dry-run] [--force] [--interactive] - [-o|--output ] [-h|--help] + [-o|--output ] dotnet project convert -h|--help ``` @@ -42,7 +42,7 @@ The command performs the following operations: ## Arguments -- **`FILE`** +- `FILE` The path to the file-based program to convert. The file must be a C# source file (typically with a *.cs* extension).