{"id":56905,"date":"2025-05-28T09:00:25","date_gmt":"2025-05-28T16:00:25","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=56905"},"modified":"2025-05-29T15:08:55","modified_gmt":"2025-05-29T22:08:55","slug":"announcing-dotnet-run-app","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/announcing-dotnet-run-app\/","title":{"rendered":"Announcing dotnet run app.cs &#8211; A simpler way to start with C# and .NET 10"},"content":{"rendered":"<p>We are super excited to introduce a new feature that was released as part of .NET 10 Preview 4 that makes getting started with C# easier than ever. You can now run a C# file directly using <code>dotnet run app.cs<\/code>. This means you no longer need to create a project file or scaffold a whole application to run a quick script, test a snippet, or experiment with an idea. It&#8217;s simple, intuitive, and designed to streamline the C# development experience, especially for those just getting started.<\/p>\n<h2>What is <code>dotnet run app.cs<\/code>?<\/h2>\n<p>Until now, executing C# code using the <code>dotnet<\/code> CLI required a project structure that included a <code>.csproj<\/code> file. With this new capability, which we call <em>file-based apps<\/em>, you can run a standalone <code>.cs<\/code> file directly, much like you would with scripting languages such as Python or JavaScript.<\/p>\n<p>This lowers the entry barrier to trying out C# and makes the language a much more attractive choice for learning, prototyping, or automation scenarios.<\/p>\n<ul>\n<li><strong>Quick Start, No Project File Required<\/strong> \u2013 Great for learning, experimentation, and small scripts.<\/li>\n<li><strong>First-Class CLI Integration<\/strong> \u2013 No extra tools, no dependencies, just <code>dotnet<\/code> and your <code>.cs<\/code> file.<\/li>\n<li><strong>Scales to Real Applications<\/strong> \u2013 This isn&#8217;t a separate dialect or runtime. When your script grows up, it can evolve into a full-fledged project using the same language, syntax, and tooling.<\/li>\n<\/ul>\n<h2>New file-level directives for file-based C# apps<\/h2>\n<p>With .NET 10 Preview 4, file-based apps also support a set of powerful <strong>file-level directives<\/strong> that allow to declare a small number of important things that are stored in project files for project-based apps, all without leaving your single <code>.cs<\/code> file. These directives make file-based apps more flexible and expressive while maintaining compatibility with MSBuild concepts.<\/p>\n<h3>Referencing NuGet packages with <code>#:package<\/code><\/h3>\n<p>You can add NuGet package references directly in your <code>.cs<\/code> file using the <code>#:package<\/code> directive:<\/p>\n<pre><code class=\"language-csharp\">#:package Humanizer@2.14.1\r\n\r\nusing Humanizer;\r\n\r\nvar dotNet9Released = DateTimeOffset.Parse(\"2024-12-03\");\r\nvar since = DateTimeOffset.Now - dotNet9Released;\r\n\r\nConsole.WriteLine($\"It has been {since.Humanize()} since .NET 9 was released.\");<\/code><\/pre>\n<h3>Specifying an SDK with <code>#:sdk<\/code><\/h3>\n<p>By default, file-based apps use the <code>Microsoft.NET.Sdk<\/code> SDK. If you&#8217;re building something like a web API, you can change the SDK using the <code>#:sdk<\/code> directive:<\/p>\n<pre><code class=\"language-csharp\">#:sdk Microsoft.NET.Sdk.Web<\/code><\/pre>\n<p>This tells the tooling to treat the file as if it were part of a web project, enabling features of ASP.NET Core like Minimal APIs and MVC.<\/p>\n<h3>Setting MSBuild properties with <code>#:property<\/code><\/h3>\n<p>You can configure additional build properties using <code>#:property<\/code>. For example:<\/p>\n<pre><code class=\"language-csharp\">#:property LangVersion preview<\/code><\/pre>\n<p>This allows your file-based app to opt into advanced language features and platform targeting, without needing a full project file.<\/p>\n<h3>Using shebang lines for shell scripts<\/h3>\n<p>File-based apps also support <a href=\"https:\/\/en.wikipedia.org\/wiki\/Shebang_%28Unix%29\">shebang<\/a> lines (<code>#!<\/code>), allowing you to write cross-platform C# shell scripts that are executable directly on Unix-like systems. For example:<\/p>\n<pre><code class=\"language-csharp\">#!\/usr\/bin\/dotnet run\r\nConsole.WriteLine(\"Hello from a C# script!\");<\/code><\/pre>\n<p>You can make the file executable and run it directly:<\/p>\n<pre><code class=\"language-bash\">chmod +x app.cs\r\n.\/app.cs<\/code><\/pre>\n<p>This makes C# a convenient option for CLI utilities, automation scripts, and tooling, no project setup required.<\/p>\n<h2>Converting to a project-based app<\/h2>\n<p>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 with:<\/p>\n<pre><code class=\"language-bash\">dotnet project convert app.cs<\/code><\/pre>\n<p>This command creates a new directory named for your file, scaffolds a <code>.csproj<\/code> file, moves your code into a <code>Program.cs<\/code> file, and translates any <code>#:<\/code> directives into MSBuild properties and references.<\/p>\n<h3>Example<\/h3>\n<p>Given this file:<\/p>\n<pre><code class=\"language-csharp\">#:sdk Microsoft.NET.Sdk.Web\r\n#:package Microsoft.AspNetCore.OpenApi@10.*-*\r\n\r\nvar builder = WebApplication.CreateBuilder();\r\n\r\nbuilder.Services.AddOpenApi();\r\n\r\nvar app = builder.Build();\r\n\r\napp.MapGet(\"\/\", () =&gt; \"Hello, world!\");\r\napp.Run();<\/code><\/pre>\n<p>The generated <code>.csproj<\/code> would be:<\/p>\n<pre><code class=\"language-xml\">&lt;Project Sdk=\"Microsoft.NET.Sdk.Web\"&gt;\r\n\r\n  &lt;PropertyGroup&gt;\r\n    &lt;TargetFramework&gt;net10.0&lt;\/TargetFramework&gt;\r\n    &lt;ImplicitUsings&gt;enable&lt;\/ImplicitUsings&gt;\r\n    &lt;Nullable&gt;enable&lt;\/Nullable&gt;\r\n  &lt;\/PropertyGroup&gt;\r\n\r\n  &lt;ItemGroup&gt;\r\n    &lt;PackageReference Include=\"Microsoft.AspNetCore.OpenApi\" Version=\"10.*-*\" \/&gt;\r\n  &lt;\/ItemGroup&gt;\r\n\r\n&lt;\/Project&gt;<\/code><\/pre>\n<p>This makes the transition seamless, from a single file to a fully functional, buildable, and extensible project.<\/p>\n<h2>Existing ways to run C# without projects<\/h2>\n<p>This is far from the first time developers have wanted to run C# without a project. Community projects like <a href=\"https:\/\/github.com\/oleg-shilo\/cs-script\">CS-Script<\/a>, <a href=\"https:\/\/github.com\/dotnet-script\/dotnet-script\">dotnet-script<\/a>, <a href=\"https:\/\/cakebuild.net\/\">Cake<\/a>, and others have long filled this role, enabling scripting workflows, REPL experiences, and other experiences with C#. Here&#8217;s a <a href=\"https:\/\/www.hanselman.com\/blog\/c-and-net-core-scripting-with-the-dotnetscript-global-tool\">blog post by Scott Hanselman from 2018 detailing the <code>dotnet-script<\/code> global tool<\/a>.<\/p>\n<p>These tools remain valuable and are worth checking out, especially for more advanced scripting scenarios. However, with this new built-in support, developers can get started immediately: no additional installation, configuration, or discovery steps required.<\/p>\n<p>Equally important: this isn&#8217;t a separate dialect or mode of C#. We&#8217;re being intentional about making this feature a natural earlier &#8220;click-stop&#8221; from a regular C# project-based app. You&#8217;re writing the same C#, using the same compiler, and when your code grows up, it transitions naturally into a project-based app, if and when you want.<\/p>\n<h2>Getting Started<\/h2>\n<ol>\n<li><strong>Install .NET 10 Preview 4<\/strong>\nDownload and install it from <a href=\"https:\/\/dotnet.microsoft.com\/download\/dotnet\/10.0\">dotnet.microsoft.com<\/a>.<\/li>\n<li><strong>Install Visual Studio Code (recommended)<\/strong>\nIf you&#8217;re using Visual Studio Code, install the <a href=\"https:\/\/marketplace.visualstudio.com\/items?itemName=ms-dotnettools.csdevkit\">C# Dev Kit<\/a> and then follow these instructions to update the C# extension for file-based apps support:<\/p>\n<blockquote><p>To enable support for file-based apps and directives, you&#8217;ll need the latest <strong>pre-release version<\/strong> of the C# extension:<\/p>\n<ul>\n<li>Open the Extensions sidebar (<code>Ctrl+Shift+X<\/code>)<\/li>\n<li>Search for &#8220;C#&#8221;<\/li>\n<li>In the extension page, click the <strong>Switch to Pre-Release Version<\/strong> button<\/li>\n<li>Ensure the version installed is at least <code>2.79.8<\/code><\/li>\n<\/ul>\n<\/blockquote>\n<\/li>\n<li><strong>Write your code<\/strong>\nCreate a file called <code>hello.cs<\/code>:<\/p>\n<pre><code class=\"language-csharp\">Console.WriteLine(\"Hello, world!\");<\/code><\/pre>\n<\/li>\n<li><strong>Run it!<\/strong>\nOpen a terminal in the same folder and run:<\/p>\n<pre><code class=\"language-bash\">dotnet run hello.cs<\/code><\/pre>\n<\/li>\n<li><strong>Convert to a project<\/strong>\nTo convert the file to a project, run:<\/p>\n<pre><code class=\"language-bash\">dotnet project convert hello.cs<\/code><\/pre>\n<\/li>\n<\/ol>\n<h2>Learn more<\/h2>\n<p>Watch this feature in action in this <a href=\"https:\/\/build.microsoft.com\/sessions\/DEM518?source=sessions\">demo session from Microsoft Build<\/a>:\n<a href=\"https:\/\/www.youtube.com\/watch?v=98MizuB7i-w\">No projects, just C# with <code>dotnet run app.cs<\/code><\/a><\/p>\n<p>You&#8217;ll see how easy it is to get started, explore directives, and convert to a full project when ready.\n<iframe width=\"800\" height=\"450\" src=\"https:\/\/www.youtube.com\/embed\/98MizuB7i-w?si=l_k3YRlViQR-rCpr\" allowfullscreen><\/iframe><\/p>\n<p>You&#8217;ll see how easy it is to get started, explore directives, and convert to a full project when ready.<\/p>\n<h2>The road ahead<\/h2>\n<p>With <code>dotnet run app.cs<\/code>, we&#8217;re making C# more approachable, while preserving the full power and depth of the .NET ecosystem. Whether you&#8217;re prototyping, teaching, or building production systems, this new capability helps you move faster from idea to execution.<\/p>\n<p>In upcoming .NET 10 previews we&#8217;re aiming to improve the experience of working with file-based apps in VS Code, with enhnanced IntelliSense for the new file-based directives, improved performance, and support for debugging. At the command line we&#8217;re exploring support for file-based apps with <a href=\"https:\/\/github.com\/dotnet\/sdk\/blob\/main\/documentation\/general\/dotnet-run-file.md#multiple-c-files\">multiple files<\/a>, and ways to make running file-based apps faster.<\/p>\n<p>Try it out today and send your <a href=\"https:\/\/github.com\/dotnet\/sdk\/issues\/new\">feedback to GitHub<\/a> as we continue to shape this experience during .NET 10 and beyond.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>We are super excited to introduce a new feature that was released as part of .NET 10 Preview 4 that makes getting started with C# easier than ever. You can now run a C# file directly using dotnet run app.cs. This means you no longer need to create a project file or scaffold a whole [&hellip;]<\/p>\n","protected":false},"author":693,"featured_media":56908,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685],"tags":[7892,7744],"class_list":["post-56905","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet","tag-dotnet-10","tag-featured-preview"],"acf":[],"blog_post_summary":"<p>We are super excited to introduce a new feature that was released as part of .NET 10 Preview 4 that makes getting started with C# easier than ever. You can now run a C# file directly using dotnet run app.cs. This means you no longer need to create a project file or scaffold a whole [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/56905","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/693"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=56905"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/56905\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/56908"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=56905"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=56905"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=56905"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}