Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 182 ยท Getting Started

How C# and .NET Work

Understand how C# source code becomes a running program on .NET 10 - the Roslyn compiler, IL, assemblies, the JIT and CLR, NuGet, and the dotnet CLI.

You press Run and text appears. Between those two moments there is a surprising amount of machinery, and knowing the outline of it makes you a better C# developer. It explains why error messages look the way they do, why a .dll file exists, why the first call to a method can be slower than the next one, and what people mean by the "runtime", the "SDK" or ".NET Standard".

The short version is a pipeline: your C# source is compiled by the Roslyn compiler into IL (intermediate language) stored in an assembly, and the CLR (Common Language Runtime) turns that IL into machine code with a JIT (just-in-time) compiler as the program runs. The rest of this lesson unpacks each step.

The pipeline from source to running code

  1. You write source code in .cs files.
  2. Roslyn, the C# compiler, checks syntax and types. If there is a mistake, it prints an error like CS0029 and stops. If everything is fine, it emits an assembly: a .dll (library) or .exe-style file holding IL plus metadata that describes every type and member.
  3. The CLR loads the assembly when you run it. It verifies it, and as each method is first called, the JIT compiler translates that method's IL into machine code for your actual CPU (x64, Arm64, and so on).
  4. The machine code runs. The CLR also provides services around it: memory management with the garbage collector, exception handling, threading and type safety.

Compare that with two other families. C++ compiles straight to machine code for one platform, so it is fast to start but you ship a separate binary per platform. A language like Python reads source (or bytecode) and interprets it, so it starts instantly but is slower in hot loops. C# sits in between: IL is portable across operating systems and processors, and the JIT produces optimized native code for whatever machine it is on. Modern .NET even does tiered compilation: it first produces quick, lightly optimized code so the program starts fast, and then recompiles the hot methods (the ones called over and over) with heavy optimization.

You can see the runtime that is executing right now.

C# Which runtime is running this code?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The first line reports .NET 10.0.13, the runtime version on our server. Your own assembly has a name (the compiler picked main), and the standard string type lives in an assembly called System.Private.CoreLib, the heart of the base class library.

Assemblies: the unit of deployment

An assembly is the file Roslyn produces. It contains:

  • the IL for all your methods,
  • metadata: a complete description of your types, their members and signatures, which is why tools can inspect code without running it,
  • a manifest: name, version and the list of assemblies it depends on.

A console program is an assembly with an entry point; a library is an assembly without one. In a real project, dotnet build produces something like MyApp.dll next to a small launcher. Metadata makes reflection possible (asking a program about its own types at run time) and is the reason reflection works at all.

The IL itself looks like assembly language for an imaginary stack-based machine. You never need to write it, but seeing it once removes the mystery. This is what a method int Add(int a, int b) => a + b; becomes. It is a read-only snippet from a disassembler such as ILSpy, because our editor has no disassembler:

TEXT
.method public static int32 Add(int32 a, int32 b) cil managed
{
    ldarg.0      // push argument a onto the evaluation stack
    ldarg.1      // push argument b
    add          // pop both, push their sum
    ret          // return the value on top of the stack
}

Because IL is the same on every platform, the very same .dll runs on Windows, Linux and macOS. The IL and JIT lesson goes deeper if you are curious.

Seeing the JIT at work

You normally cannot observe the JIT, but you can see that a method is compiled lazily, on first use. The next program calls the same method repeatedly and shows a result that is identical every time: JIT compilation is invisible to correctness, it only affects speed.

C# The same method, called many times

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The first line prints 385 (1 + 4 + 9 + ... + 100). The second prints 667667000000 (333,833,500 for each of the 2,000 rounds). Timing such code properly is a topic for Performance Basics: the first call is slower than later ones, which is why benchmarks run a method many times before they measure.

SDK versus runtime

Two installable pieces are easy to confuse:

Piece What it is Who needs it
.NET Runtime The CLR, the JIT, the garbage collector and the base class library. Runs programs. Servers and users that only run apps
ASP.NET Core Runtime The extra web libraries (Kestrel, minimal APIs, ...) Machines that run web apps
.NET SDK Everything above, plus the Roslyn compiler, the dotnet command, MSBuild and templates. Builds programs. Developers

A developer machine installs the SDK. A production server needs only the runtime, or nothing at all if the app is published self-contained (the runtime is bundled with the app).

Our editor is a small SDK in disguise: it compiles with the real Roslyn from the .NET 10 SDK and runs on the real runtime.

Framework, library, platform

A few words that get mixed up:

  • A library is code you call: you decide when. System.Text.Json is a library.
  • A framework is code that calls you: you plug your code into its structure. ASP.NET Core is a framework: it listens for web requests, and calls your handlers.
  • The base class library (BCL) is the standard collection of types that ship with .NET: string, List<T>, File, HttpClient, and thousands more.
  • A platform bundles runtime, libraries and tools: .NET is a platform.

.NET, .NET Framework and .NET Standard

The naming history is the most confusing part of the ecosystem, so here is a map.

Name Era Notes
.NET Framework 2002-2019 (4.8 is the last version) Windows-only. Still supported and everywhere in older enterprise code, but gets no new features
.NET Core 2016-2019 (1.0 to 3.1) A fresh, open-source, cross-platform rewrite
.NET 5+ 2020 to today Core dropped the word "Core" and continued: 5, 6, 7, 8, 9, 10 ... Annual releases
.NET Standard 2016-2021 A specification so a library could target both .NET Framework and .NET Core. Obsolete for new code
Mono / Xamarin 2004 on A separate open-source runtime, now folded into modern .NET (used for mobile and Unity-style scenarios)

Practical advice: for new projects, always choose current .NET (10 today). If you maintain a library that must also support old .NET Framework apps, you may still multi-target netstandard2.0. If you meet "Core" in a job description, it means modern .NET.

.NET 10 is an LTS release supported for three years (until November 2028). Even-numbered releases are LTS, odd-numbered ones get 18 months of support.

NuGet: packages for everything else

The base class library is big, but you will want more: JSON parsers, database access, testing frameworks, logging sinks. Code beyond the BCL is shared as NuGet packages, versioned bundles of assemblies hosted at nuget.org. You add one with a command or by editing the project file, and the build downloads it.

The commands below are read-only snippets, because our editor has no dotnet CLI and no package restore. They show what you would type on your own machine:

Terminal
dotnet add package Serilog        # download Serilog and reference it
dotnet remove package Serilog
dotnet list package --outdated    # which packages have newer versions?

In the project file this becomes a single line (more in The dotnet CLI, Projects and Tooling):

XML
<ItemGroup>
  <PackageReference Include="Serilog" Version="4.2.0" />
</ItemGroup>

Everything in our editor works with the base class library and the built-in ASP.NET Core shared framework only, so lessons that need a NuGet package show the package code read-only and give you a runnable stand-in.

Cross-platform and ahead-of-time compilation

Because the IL is portable and .NET itself is open source, the same code runs on Windows, Linux (including Docker containers) and macOS, on x64 and Arm. Most .NET servers today run on Linux.

The default "IL plus JIT" model has a cost: some startup time and memory for the compiler. For small command-line tools and serverless functions you can instead publish Native AOT (ahead-of-time): the whole app is compiled to a single machine-code executable, starting in milliseconds with no JIT. The trade-offs are no run-time code generation and restrictions on reflection. This is read-only in our lessons:

Terminal
dotnet publish -c Release -r linux-x64 -p:PublishAot=true

You will meet the details in Native AOT and Trimming.

The dotnet CLI at a glance

One command, dotnet, drives the whole workflow on your machine. These are the verbs you will use most (a session is shown in The dotnet CLI, Projects and Tooling):

Terminal
dotnet --version        # SDK version, e.g. 10.0.402
dotnet new console -n Hello   # create a project from a template
dotnet run              # compile (if needed) and run
dotnet build            # compile only
dotnet test             # run unit tests
dotnet publish -c Release   # produce the files to deploy

dotnet run does the whole pipeline in one go: Roslyn builds the assembly, the host starts the CLR, the JIT compiles Main, and your program runs.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the Roslyn compiler produce from C# source code?

    Roslyn emits an assembly (.dll) with IL and metadata. The JIT turns IL into machine code later, when the program runs.
  2. 2. What is the job of the JIT compiler?

    The JIT (just-in-time) compiler is part of the CLR. It compiles IL to native code on demand, and with tiered compilation it re-optimizes hot methods.
  3. 3. A production server only needs to run an already-built app. Which piece is the minimum it needs (unless the app is self-contained)?

    The runtime runs programs. The SDK adds the compiler and tools for building them, which production servers usually do not need.
  4. 4. Which statement about .NET naming is correct?

    .NET Framework is the old Windows-only line. Modern .NET (5 and later, successor to .NET Core) is cross-platform, and .NET Standard is obsolete for new code.
  5. 5. What is Native AOT?

    Native AOT publishes machine code directly: very fast startup and no JIT, with restrictions on reflection and dynamic code.

Summary

  • Roslyn compiles C# to IL inside an assembly; the CLR loads it and the JIT compiles IL to machine code as methods are first called.
  • Tiered compilation starts fast and re-optimizes hot methods later.
  • Assemblies hold IL, metadata and a manifest; metadata enables reflection and tooling.
  • The SDK builds programs; the runtime only runs them.
  • A library is code you call, a framework is code that calls you, and the BCL is .NET's standard library.
  • .NET Framework is the old Windows-only line, .NET 5+ is the modern cross-platform successor of .NET Core, and .NET Standard is obsolete for new code.
  • NuGet distributes packages beyond the BCL; Native AOT compiles ahead of time for fast startup.
  • The dotnet CLI (new, run, build, test, publish) drives the workflow on your machine.

Next: C# Syntax covers the building blocks of the language: statements, blocks, names and namespaces.