Skip to main content

Hello World (first programs) · Beginner · 17 min

Hello World in C#: dotnet new, top-level statements and file-based apps

By Padding · Updated 18 Nov 2026
Ubuntu 26.04 · .NET 10 LTS SDK (runtime 10.0.15, C# 14) · mcr.microsoft.com/dotnet/sdk:10.0

You will install the .NET 10 SDK, create and run a C# console app with dotnet new and dotnet run, run a single .cs file with no project, read a name safely from the keyboard and publish a self-contained executable.

On this page

C# is the main language of .NET, Microsoft's open-source platform for building programs that run on Windows, Linux and macOS. It is compiled twice. The C# compiler turns your source code into an intermediate language (IL) stored in a .dll file, and when the program starts, the .NET runtime compiles that IL into machine code for your processor. That second step is why a C# program needs either the .NET runtime on the machine, or a copy of the runtime bundled with it. You do both in this tutorial.

The version here is .NET 10, the current long-term support (LTS) release, which comes with C# 14. .NET 11 came out on 10 November 2026, but it is a standard-term (STS) release with two years of support, and both reach end of support on the same day in November 2028. Most teams and hosting providers standardise on the LTS, so that is what you learn first. Everything in this tutorial works the same on .NET 11.

You work in a throwaway folder, ~/csharp-hello-demo, and delete it at the end.

Step 1 · Install the .NET 10 SDK

.NET comes in two parts. The runtime runs finished programs. The SDK (software development kit) contains the runtime plus the compiler and the dotnet command-line tool that creates, builds and publishes projects. To write code you need the SDK.

On Ubuntu 26.04, .NET 10 is in Ubuntu's own main archive, so there is no extra repository to add:

Bash
sudo apt update
sudo apt install -y dotnet-sdk-10.0

Microsoft also publishes its own .deb packages. Pick one source and stay with it: mixing Ubuntu's and Microsoft's .NET packages on one machine is a known cause of dotnet failing to find its SDK.

On Windows, run winget install Microsoft.DotNet.SDK.10 in a terminal, or download the SDK installer from dotnet.microsoft.com. On macOS, download the .pkg installer for your processor (Arm64 for Apple silicon) from the same site. Open a new terminal after installing, so it picks up the dotnet command.

Now ask what you have:

Bash
dotnet --version
dotnet --list-sdks
dotnet --list-runtimes

Check it worked

dotnet --version prints a version that starts with 10.0., such as 10.0.114 from Ubuntu's package or 10.0.115 from Microsoft. --list-sdks shows that SDK, and --list-runtimes shows at least Microsoft.NETCore.App 10.0. followed by a patch number. If you see No .NET SDKs were found, you installed only a runtime; install the dotnet-sdk-10.0 package.

The first time you run a dotnet command it prints a welcome message, including a note that the SDK sends anonymous usage data to Microsoft. To turn that off, add export DOTNET_CLI_TELEMETRY_OPTOUT=1 to your ~/.bashrc.

Step 2 · Create a console app with dotnet new

dotnet new creates a project from a template. The console template is the smallest program that runs:

Bash
mkdir -p ~/csharp-hello-demo
cd ~/csharp-hello-demo
dotnet new console -o HelloApp
cd HelloApp
ls
cat Program.cs

-o HelloApp makes a folder called HelloApp and names the project after it. The folder holds HelloApp.csproj, Program.cs and an obj folder that the SDK uses for its working files.

Program.cs holds two lines. The first starts with //, which makes it a comment: the compiler ignores it, and here it only points to Microsoft's documentation. The second is the whole program:

C#
Console.WriteLine("Hello, World!");
  • Console is a class from the System namespace that represents the terminal window.
  • .WriteLine(...) is a method on that class. It prints the text you give it, then a newline.
  • "Hello, World!" is a string literal: text between double quotes.
  • ; ends the statement. C# needs one after every statement.

Check it worked

ls lists HelloApp.csproj, Program.cs and obj, and cat shows the comment line and the Console.WriteLine line.

Step 3 · Read the project file and run the app

Look at the project file, the .csproj:

Bash
cd ~/csharp-hello-demo/HelloApp
cat HelloApp.csproj

It is a short piece of XML that tells the SDK how to build the program:

  • <Project Sdk="Microsoft.NET.Sdk"> chooses the basic SDK for console apps and libraries. Web apps use Microsoft.NET.Sdk.Web instead.
  • <OutputType>Exe</OutputType> says the result is a program you can run, not a library.
  • <TargetFramework>net10.0</TargetFramework> says which .NET version the program is built for and runs on.
  • <ImplicitUsings>enable</ImplicitUsings> imports common namespaces such as System for every file, which is why Program.cs can write Console instead of System.Console.
  • <Nullable>enable</Nullable> turns on warnings about values that might be null. You see one of these later.

Now build and run the program:

Bash
cd ~/csharp-hello-demo/HelloApp
dotnet run

dotnet run restores any packages, compiles the project into bin/Debug/net10.0/HelloApp.dll, and starts it on the .NET runtime. The first run takes a few seconds; later runs are faster because only changed files are rebuilt.

Check it worked

The terminal prints Hello, World!. A bin folder now sits next to obj. If you see Couldn't find a project to run, you are in the wrong folder: dotnet run looks for a .csproj in the current folder, so cd into HelloApp first.

Step 4 · See what top-level statements hide

Older C# programs, and most code you will read online, wrap the same line in a namespace, a class and a Main method. Since C# 9 you can leave all of that out and write statements at the top of one file. These are called top-level statements. The compiler still produces a class and an entry-point method around them; you just do not type them. Only one file in a project may contain top-level statements, because a program has one starting point.

The generated method takes the command-line arguments, and your code can use them under the name args. Replace Program.cs to try it:

Bash
cd ~/csharp-hello-demo/HelloApp
cat > Program.cs <<'CS'
var who = args.Length > 0 ? args[0] : "World";
Console.WriteLine($"Hello, {who}!");
CS
dotnet run
dotnet run -- Ada
  • var declares a variable and lets the compiler work out its type from the value. Here who is a string.
  • args is an array of the words typed after the program name. args.Length > 0 ? args[0] : "World" reads "if there is at least one argument, use the first, otherwise use World".
  • $"Hello, {who}!" is an interpolated string: the $ lets you put values inside curly braces.
  • In dotnet run -- Ada, the -- separates options for dotnet from arguments for your program.

The implicit using lines are real files too. The build writes them into obj:

Bash
cd ~/csharp-hello-demo/HelloApp
cat obj/Debug/net10.0/HelloApp.GlobalUsings.g.cs

Check it worked

The first run prints Hello, World! and the second prints Hello, Ada!. The .g.cs file lists lines that start global using and name System, System.IO, System.Linq and a few others. Do not edit it; the build regenerates it.

Step 5 · Run a single file with no project

.NET 10 added file-based apps: a single .cs file that dotnet run builds and runs without a .csproj. They suit small scripts and trying out an idea. Keep them in a folder of their own, because inside a project folder dotnet run hello.cs runs the project and passes hello.cs to it as an argument.

Bash
mkdir -p ~/csharp-hello-demo/scripts
cd ~/csharp-hello-demo/scripts
cat > hello.cs <<'CS'
var now = DateTime.Now;
Console.WriteLine($"Hello from a single file. It is {now:HH:mm} here.");
Console.WriteLine($"Running on .NET {Environment.Version}");
CS
dotnet run hello.cs

The SDK creates a hidden project for the file, with the same defaults as the console template (top-level statements, implicit usings and nullable warnings), and caches the build in a temporary folder so the next run starts faster. {now:HH:mm} formats the time as hours and minutes, and Environment.Version is the version of the runtime that is running the code.

A file-based app can carry its own settings in lines that start #:, such as #:package to use a NuGet library. When the script grows, dotnet project convert hello.cs turns it into a normal project in a new folder and leaves the original file alone.

Check it worked

The output has two lines: Hello from a single file. It is with the current time, and Running on .NET 10.0. followed by the runtime's patch number. The scripts folder still holds only hello.cs; there is no bin, obj or .csproj in it.

Step 6 · Read a name and handle null

Console.ReadLine() reads one line typed at the keyboard. When there is nothing left to read, for example when input comes from an empty file or the user presses Ctrl+D (Ctrl+Z then Enter on Windows), it returns null, which means "no value". Its return type is string?: the ? marks a string that might be null.

First write the careless version, to see the compiler warn you:

Bash
cd ~/csharp-hello-demo/HelloApp
cat > Program.cs <<'CS'
Console.Write("What is your name? ");
string name = Console.ReadLine();
Console.WriteLine($"Hello, {name.Trim()}!");
CS
dotnet build

The build succeeds, but it prints a warning with the code CS8600, something like Converting null literal or possible null value to non-nullable type, and may add CS8602 for the .Trim() call. string without a ? promises the variable is never null, and Console.ReadLine() cannot promise that. Nullable warnings are a compile-time check only. Run the program with no input and the promise breaks:

Bash
dotnet run < /dev/null

The program stops with an unhandled System.NullReferenceException, because it calls .Trim() on a value that is not there. Now write it properly:

Bash
cd ~/csharp-hello-demo/HelloApp
cat > Program.cs <<'CS'
Console.Write("What is your name? ");
string? name = Console.ReadLine();

if (string.IsNullOrWhiteSpace(name))
{
    name = "stranger";
}

Console.WriteLine($"Hello, {name.Trim()}!");
Console.WriteLine($"Your name has {name.Trim().Length} characters.");
CS
dotnet build
echo "Ada" | dotnet run
dotnet run < /dev/null
  • string? name says honestly that name may be null.
  • string.IsNullOrWhiteSpace(name) is true for null, an empty line or a line of spaces, so every bad case gets the default.
  • After the if, the compiler knows name holds a value, so it no longer warns about .Trim().
  • .Length counts characters (strictly, UTF-16 code units). Names in most scripts, including accented Yorùbá letters typed as single characters, count as you expect; some emoji count as two.

Run dotnet run on its own and type your name to try it interactively.

Check it worked

dotnet build reports success with no CS8600 or other warnings. With piped input the output reads What is your name? Hello, Ada! on one line, because piped text is not echoed to the screen, followed by Your name has 3 characters. With no input it prints Hello, stranger! instead of crashing.

Step 7 · Publish a self-contained executable

dotnet run is for development. To hand the program to someone, publish it. A self-contained publish copies the .NET runtime into the output, so the other machine does not need .NET installed. PublishSingleFile packs it all into one executable:

Bash
cd ~/csharp-hello-demo/HelloApp
dotnet publish -c Release --use-current-runtime --self-contained -p:PublishSingleFile=true -o publish
ls -lh publish
echo "Grace" | ./publish/HelloApp
  • -c Release builds with optimisations on. It is already the default for dotnet publish since .NET 8, but writing it makes the intent clear (dotnet build and dotnet run default to Debug).
  • --use-current-runtime builds for the operating system and processor you are on. To build for another one, use -r with a runtime identifier instead, such as -r win-x64, -r linux-arm64 or -r osx-arm64.
  • --self-contained bundles the runtime, and -o publish puts the result in the publish folder.

The executable is tens of megabytes, because it carries the runtime with it. The first self-contained publish for a platform also downloads that runtime from NuGet once and caches it in ~/.nuget/packages, which matters if you are on prepaid mobile data. If the target machine already has .NET 10, leave out --self-contained and PublishSingleFile: the output is then a small .dll plus a launcher that uses the installed runtime. File-based apps go one step further and publish with native ahead-of-time compilation by default, producing machine code with no IL step at start-up.

Check it worked

ls -lh shows a HelloApp file of tens of megabytes (HelloApp.exe on Windows), and running it prints What is your name? Hello, Grace! and Your name has 5 characters. without dotnet in the command.

Step 8 · Avoid common beginner mistakes and clean up

Mistakes that stop most first C# programs:

  • Wrong capitals. C# is case-sensitive. console.writeline fails with error CS0103 (the name does not exist in the current context); it must be Console.WriteLine.
  • Missing semicolon. The build fails with CS1002: ; expected and gives the file, line and column.
  • Single quotes around text. 'Hello' is an error: single quotes are for one character ('A'), double quotes are for strings.
  • Ignoring warnings. A build with nullable warnings still runs. Treat each CS86xx warning as a bug report and fix it, as you did above.
  • Running a file inside a project folder. dotnet run hello.cs in a folder with a .csproj runs the project. Keep scripts elsewhere, or use dotnet run --file hello.cs.

Where C# is used: web APIs and websites with ASP.NET Core, which runs well on Linux servers; Windows desktop apps; cross-platform mobile and desktop apps with .NET MAUI; cloud functions on Azure and AWS; and games, since Unity uses C# as its scripting language. Many banks and other large enterprises run C# back ends, so it turns up often in enterprise job adverts.

When you are done, remove the demo folder:

Bash
rm -rf ~/csharp-hello-demo

To remove .NET itself on Ubuntu, run sudo apt remove dotnet-sdk-10.0 and then sudo apt autoremove to remove the runtime it pulled in.

Check it worked

ls ~/csharp-hello-demo reports No such file or directory.

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.