Create, edit and run multiple C# file-based apps in the same project in the IDE, honoring per-file #:package
references, #:property project values and even #:sdk 😍
To ensure the long-term sustainability of this project, users of this package who generate revenue must pay an Open Source Maintenance Fee. While the source code is freely available under the terms of the License, this package and other aspects of the project require adherence to the Maintenance Fee.
To pay the Maintenance Fee, become a Sponsor at the proper OSMF tier. A single fee covers all of Devlooped packages.
C# top-level programs allow a very intuitive, simple and streamlined experience for quickly spiking or learning C#. The addition of file-based apps in .NET 10 takes this further by allowing package references and even MSBuild properties to be specified per file:
#:package Humanizer@2.14.1
#:property ImplicitUsings=true
#:property Nullable=enable
using Humanizer;
var dotNet9Released = DateTimeOffset.Parse("2024-12-03");
var since = DateTimeOffset.Now - dotNet9Released;
Console.WriteLine($"It has been {since.Humanize()} since .NET 9 was released.");Editing these standalone files in VSCode, however, is suboptimal compared with the full C#
experience in Visual Studio. In Visual Studio, though, you can only have one top-level program
in a project, and as of now, you cannot leverage the #:package and #:property directives
at all.
SmallSharp allows dynamically selecting the file to run, right from the Start button/dropdown
(for compilation and launch/debug). It also automatically restores the #:package references so
the project system can resolve them, and even emits the #:property directives if present to customize
the build as needed.
This list is automatically kept in sync as you add more .cs files to the project. When you select
one target C# file, that becomes the only top-level program to be compiled, so you don't have to
modify any of the others since they automatically become None items.
Tip
An initial build after selection change migh be needed to restore the packages and compile the selected file, unless you're using the SDK mode for SmallSharp (see below).
All compile files directly under the project directory root are considered top-level programs for selection and compilation purposes. If you need to share code among them, you can place additional files in subdirectories and those will behave like normal compile items.
The recommended way to use SmallSharp is via the SDK mode, which provides the most streamlined and seamless experience across IDE and CLI builds:
<Project Sdk="SmallSharp/2.2.3">
<PropertyGroup>
<OutputType>Exe</OutputType>
<!-- 👇 allows c# file to override the TF via a #:property -->
<TargetFramework Condition="$(TargetFramework) == ''">net10.0</TargetFramework>
</PropertyGroup>
</Project>The SDK mode will always produce a successful build in a single dotnet build pass even if you
change the ActiveFile between builds.
Important
If no #:sdk directive is provided by a specific C# file-based app, the Microsoft.NET.SDK will be
used by default in this SDK mode.
If you prefer, you can also use SmallSharp as a regular package reference in a C# console project:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<!-- 👇 allows c# file to override the TF via a #:property -->
<TargetFramework Condition="$(TargetFramework) == ''">net10.0</TargetFramework>
<!-- 👇 additional properties required in package mode -->
<ImportProjectExtensionProps>true</ImportProjectExtensionProps>
<ImportProjectExtensionTargets>true</ImportProjectExtensionTargets>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="SmallSharp" Version="*" PrivateAssets="all" />
</ItemGroup>
</Project>This package-reference mode works, but it has some caveats and limitations:
- You cannot use the
#:sdkdirective to specify a different SDK per file, since the project file already specifies one. - CLI-based builds may require multiple passes to restore and build the selected file, since the package is only restored after the first build.
- You must add ImportProjectExtensionProps/ImportProjectExtensionTargets manually, polluting the project file.
Keep adding as many top-level programs as you need, and switch between them easily by simply selecting the desired file from the Start button dropdown.
When running from the command-line, you can select the file to run by passing it as an argument to dotnet run:
dotnet run -p:start=program1.csYou can also use the shortcut -p:s=[FILE].
This nuget package leverages in concert the following standalone and otherwise unrelated features of the compiler, nuget and MSBuild:
- The C# compiler only allows one top-level program per compilation.
- Launch profiles (the entries in the Run dropdown) are populated from the Properties\launchSettings.json file
- Whenever changed, the dropdown selection is persisted as the
$(ActiveDebugProfile)MSBuild property in a file named after the project with the.userextension - This file is imported before NuGet-provided MSBuild targets
- VS ignores
#:directives when adding the flagFileBasedProgramto the$(Features)project property.
Using the above features in concert, SmallSharp essentially does the following:
-
Emit top-level files as a
launchSettings.jsonprofile and set the$(ActiveDebugProfile). -
Exclude
.csfiles at the project level from being included as<Compile>by the default SDK includes and include them explicitly as<None>instead so they show up in the solution explorer. This prevents the compiler from causing an error for multiple top-level programs. -
Explicitly include as
<Compile>only the$(ActiveDebugProfile)property value. -
Emit
#:packageand#:propertydirective to an automatically importedobj\SmallSharp.targetsfile -
SmallSharp MSBuild SDK automatically imports the
SmallSharp.targetsfile, which causes a new restore to automatically happen in Visual Studio, bringing all required dependencies automatically.
This basically mean that this it will also work consistently if you use dotnet run from the command-line,
since the "Main" file selection is performed exclusively via MSBuild item manipulation.
Tip
It is recommended to keep the project file to its bare minimum, usually having just the SmallSharp
SDK reference, and do all project/package references in the top-level files using the #:package and
#:property directives for improved isolation between the different file-based apps.