C# notebooks are useful for experimenting with code, testing APIs, exploring data, and learning new .NET features without creating a complete application.
Traditional notebook formats, however, can introduce some practical problems when they are used in development workflows.
One common issue is stale output. When notebook cells are executed out of order, the displayed result may no longer represent the current state of the code. Another problem is version control. Many notebook systems store cells and their outputs in structured JSON files, which can make Git diffs difficult to review.
An alternative approach is to use ordinary C# source files and divide them into executable cells.
This article explores that approach and looks at how a C# notebook system can provide reactive execution, dependency tracking, interactive controls, package management, and other notebook capabilities while keeping the underlying source code as a normal .cs file.
What Is a C# Notebook?
A C# notebook allows developers to write and execute small pieces of C# code independently.
Instead of creating a complete project for every experiment, developers can write code such as:
var numbers = new[] { 10, 20, 30, 40 };
var total = numbers.Sum();
Console.WriteLine(total);The code can be divided into multiple cells:
Cell 1
↓
Define data
Cell 2
↓
Transform data
Cell 3
↓
Display resultEach cell can then be executed independently.
This workflow is useful for:
Learning C#
Exploring .NET APIs
Testing algorithms
Querying data
Prototyping ideas
Testing libraries
Exploring APIs
Creating technical demonstrations
The Problem with Traditional Notebook Workflows
Notebook environments are convenient, but their execution model can cause problems.
Consider two cells:
// %%
var price = 100;and:
// %%
var tax = price * 0.18;
Console.WriteLine(tax);If the first cell is changed but the second cell is not executed again, the visible output may represent an earlier state.
The notebook can therefore contain code that says one thing while the displayed output represents another execution state.
This becomes particularly confusing when a notebook contains many cells and developers execute them in different orders.
Using Plain C# Source Files
A different approach is to store notebook code as a regular .cs file.
Cells can be separated using a marker such as:
// %%For example:
// %%
var price = 100;
// %%
var tax = price * 0.18;
// %%
Console.WriteLine($"Tax: {tax}");The important difference is that the notebook is still a normal C# source file.
This provides several advantages for development workflows:
Git can display normal source-code diffs
Developers can edit the file using standard text editors
Code remains easy to search
The file can be stored alongside other source files
AI coding tools can work with the file
Developers are not tied to a JSON notebook format
Reactive Cell Execution
A useful improvement over simple cell execution is dependency-aware execution.
Suppose a notebook contains:
// %%
var price = 100;
// %%
var tax = price * 0.18;
// %%
var total = price + tax;The dependency relationship is:
price
↓
tax
↓
totalIf price changes, the cells that depend on it need to be recalculated.
A reactive notebook can analyze these relationships and execute only the affected cells.
For example:
Change price
|
v
Recalculate tax
|
v
Recalculate totalThis avoids manually rerunning unrelated cells.
Dependency Analysis with Roslyn
The C# compiler platform, Roslyn, provides APIs for analyzing C# source code.
A notebook system can use Roslyn's syntax and semantic analysis capabilities to determine relationships between cells.
For example, if one cell defines:
var customer = GetCustomer();and another contains:
Console.WriteLine(customer.Name);the second cell depends on the value created by the first cell.
A dependency-aware execution engine can use this information to determine which cells need to be evaluated again when code changes.
This is different from simply executing cells from top to bottom.
Handling Deleted Cells
Dependency tracking also becomes important when a cell is deleted.
Consider:
// %%
var customerName = "Alex";
// %%
Console.WriteLine(customerName);If the first cell is removed, customerName should no longer be available to the second cell.
A notebook execution engine therefore needs to maintain an accurate representation of the current source state rather than preserving variables from previous executions.
This helps prevent stale variables and stale output from remaining in the notebook.
Interactive Controls
Notebook environments can also provide interactive controls.
For example, a notebook could expose a slider for a numeric value:
Discount: [--------|---]Changing the value can trigger dependent cells to execute again.
Similarly, dropdowns and text inputs can be used to provide parameters to notebook code.
This can be useful for demonstrations and exploratory analysis.
For example:
Select product:
[ Laptop ▼ ]
Quantity:
[ 5 ]
Discount:
[ 10% ]The notebook can then recalculate the results when the inputs change.
Displaying Rich Results
A notebook does not have to display only console output.
A modern C# notebook environment can support different types of results, including:
Tables
Charts
Markdown
HTML
Images
Text output

Join the conversation! Your thoughts help the community grow.