[.NET 11 미리보기] C# 파일 기반 앱의 진화
한 파일로 시작한 도구에서 코드를 나누고 공유하는 방법
![[.NET 11 미리보기] C# 파일 기반 앱의 진화](https://cdn.hashnode.com/uploads/covers/60adcb82557cc70e51211e5c/8ee81c38-e411-421d-a41f-d4099b44a508.jpg)
C# 파일 하나로 도구를 만들어도 출력 형식이 늘거나 다른 도구와 기능을 공유할 때는 코드를 나눌 필요가 생깁니다. .NET 11의 #:include는 여러 파일의 소스를 한 앱에서 함께 컴파일하고, #:ref는 다른 파일 기반 앱을 별도 어셈블리로 참조합니다. Damian Edwards의 .NET Conf 2026 발표 초록은 이 변화와 함께 반복 실행 속도, NuGet 참조, CLI 명령의 개선을 예고했습니다. 2026년 11월 10일 기준 .NET 11 RC3에서 두 지시문과 반복 실행이 어떻게 동작하는지 살펴봅니다. 공식 세션 초록
C# 파일 실행과 SDK의 역할
.NET 10부터는 dotnet run --file App.cs처럼 진입점 파일을 지정해 앱을 빌드하고 실행할 수 있습니다. SDK는 메모리에 가상 프로젝트를 만들고 파일 머리의 #: 지시문을 MSBuild 속성과 항목으로 해석합니다. NuGet 패키지 복원, 대상 프레임워크 지정, 빌드 결과 생성에는 이 프로젝트의 구성을 사용합니다. C# 컴파일러는 진입점 파일의 최상위 문을 컴파일합니다. Microsoft Learn 파일 기반 앱 안내
같은 폴더에 여러 .cs 파일을 두어도 기본 컴파일 대상은 진입점 파일 하나입니다. 도구별로 진입점을 두고, 앱마다 필요한 소스와 어셈블리를 명시할 수 있습니다. RC3 SDK 가상 프로젝트 생성기
소스 포함과 앱 참조
#:include Helpers.cs를 쓰면 Helpers.cs가 현재 앱의 컴파일에 포함됩니다. 이 파일에 형식이나 메서드를 선언하고, 최상위 실행 문은 진입점에 둡니다. 같은 어셈블리에 들어가는 코드이므로 앱에서 internal 멤버에 접근할 수 있습니다. #:include는 .NET 11의 앞선 미리 보기와 .NET 10 SDK의 후속 업데이트에서도 제공됐습니다. Microsoft Learn의 파일 포함 규칙
#:ref ./Meter.cs는 Meter.cs에서 만든 가상 프로젝트를 참조합니다. SDK가 두 앱을 따로 컴파일하므로 참조한 앱에서는 Meter.cs의 공개 형식에 접근할 수 있습니다. Meter.cs에 진입점이 있다면 그 파일을 직접 실행할 때만 진입점이 동작합니다. 진입점 없이 라이브러리로 쓸 파일에는 #:property OutputType=Library를 선언합니다. .csproj를 참조할 때는 #:project를 씁니다. RC3 SDK 설계 문서의 참조 규칙
#:package에서 패키지 ID와 버전 뒤에 Aliases=CommandLine 같은 메타데이터를 붙일 수 있습니다. 예를 들어 #:package System.CommandLine@2.0.1 Aliases=CommandLine으로 참조를 추가하면 코드에서 extern alias CommandLine;으로 별칭을 가져와 이 참조를 구분할 수 있습니다. #:project와 #:ref도 뒤에 메타데이터를 받을 수 있습니다. #:property Company="Contoso Tools"처럼 공백이 들어간 값은 따옴표로 묶습니다. SDK는 이렇게 지정한 값을 가상 프로젝트의 MSBuild 항목과 속성에 반영합니다. Microsoft Learn의 .NET 11 SDK 변경 사항
RC3의 참조 처리와 실행 경로
RC3의 VirtualProjectBuilder는 #:ref가 가리키는 파일의 가상 프로젝트를 만듭니다. 그 파일에 또 다른 참조가 있으면 같은 과정을 반복하고, 각각을 ProjectReference 항목으로 연결합니다. 패키지에 붙인 메타데이터는 PackageReference에 기록합니다. dotnet reference add --file 명령은 입력 경로가 C# 진입점이면 파일 기반 앱의 참조를 편집하는 코드에 처리를 맡깁니다. RC3 소스 태그 가상 참조 프로젝트 생성 패키지 및 프로젝트 항목 생성 참조 명령 구현
SDK는 기존 빌드 결과를 실행하거나, 저장한 인수로 C# 컴파일러를 직접 호출하거나, MSBuild로 전체 빌드를 수행합니다. Native AOT CLI는 캐시에 남은 빌드 성공 기록이 유효하고 실행 정보가 일치할 때 기존 빌드 결과를 바로 실행합니다. 이를 판단할 때 SDK와 런타임 버전, 전역 속성, 진입점과 추가 입력 파일의 변경 여부를 확인합니다. 조건에 맞지 않으면 관리형 CLI가 실행을 이어받습니다. RC3 실행 계획과 캐시 판정 입력 변경 확인
RC3는 #:project나 #:ref가 있거나 #:include에 와일드카드를 쓴 앱을 빌드할 때 이 최적화에 필요한 캐시를 저장하지 않습니다. 아래에서는 앱 간 참조와 재실행 캐시를 서로 다른 예제로 확인합니다. 발표 예상으로는 의존성이 단순한 앱을 골라 첫 실행과 재실행의 차이를 보여 줄 수 있습니다. 초록에는 실제 시연 구성이나 성능 수치가 공개되지 않았습니다. RC3 캐시 저장 조건 공식 세션 초록
파일 포함과 앱 참조 예제
빈 폴더에 다음 세 파일을 저장합니다. 예제에는 Native AOT 게시 도구 없이 실습할 수 있도록 PublishAot=false를 지정했습니다. Dashboard.cs를 빌드하면 Labels.cs는 앱과 함께 컴파일되고 Meter.cs는 별도 어셈블리로 참조됩니다. 앱은 이 어셈블리에서 Meter의 공개 메서드를 호출합니다.
Dashboard.cs
#!/usr/bin/env dotnet
#:property PublishAot=false
#:ref ./Meter.cs
#:include ./Labels.cs
Console.WriteLine($"{Labels.Today} {Meter.Format(12)}");
Console.WriteLine(typeof(Meter).Assembly.GetName().Name);
Labels.cs
internal static class Labels
{
internal const string Today = "Today";
}
Meter.cs
#:property PublishAot=false
Console.WriteLine(Meter.Format(5));
public static class Meter
{
public static string Format(int count) => $"{count} jobs";
}
파일을 저장한 폴더에서 dotnet --version을 실행해 .NET 11 RC3 SDK가 선택됐는지 확인합니다. SDK가 여러 개 설치돼 있다면 아래 릴리스 노트에서 RC3 SDK의 전체 버전을 확인해 global.json의 sdk.version에 적습니다. rollForward를 disable, allowPrerelease를 true로 지정하면 해당 SDK 버전을 고정할 수 있습니다. Microsoft Learn의 global.json 규칙
dotnet run --file Dashboard.cs
dotnet run --file Meter.cs
dotnet reference list --file Dashboard.cs
첫 명령을 실행하면 Today 12 jobs와 참조한 어셈블리 이름 Meter가 나옵니다. Meter.cs 진입점의 5 jobs는 두 번째 명령에서만 출력됩니다. 마지막 명령은 참조 목록에 ./Meter.cs를 표시합니다. 같은 명령의 remove와 add로 참조 지시문을 바꿀 수 있습니다. Windows에서 RC3 SDK로 세 명령의 출력을 확인했습니다. RC3 참조 명령 구현
패키지 별칭과 재실행 캐시를 보려면 아래 코드를 AliasDemo.cs에 저장합니다. System.CommandLine을 예제에 지정한 버전으로 복원할 수 있는 NuGet 패키지 소스나 로컬 캐시가 필요합니다.
#:property PublishAot=false
#:property Company="Queue Tools"
#:package System.CommandLine@2.0.1 Aliases=CommandLine
extern alias CommandLine;
using System.Reflection;
var commandType = typeof(CommandLine::System.CommandLine.RootCommand);
var app = Assembly.GetExecutingAssembly();
Console.WriteLine(commandType.Assembly.GetName().Name);
Console.WriteLine(app.GetCustomAttribute<AssemblyCompanyAttribute>()?.Company);
dotnet run --file AliasDemo.cs를 실행하면 System.CommandLine과 Queue Tools가 나옵니다. Windows의 RC3 SDK에서 DOTNET_CLI_CONTEXT_VERBOSE=true를 설정하고 이 명령을 두 번 실행했습니다. 처음에는 관리형 CLI가 빌드했고, 파일을 그대로 둔 채 다시 실행하자 AOT run tier: CachedLaunch (CacheValid)가 기록됐습니다. RC3 실행 계획 구현
명령 해석과 게시 설정의 제약
현재 폴더에 프로젝트 파일이 있으면 dotnet run App.cs에서 App.cs가 기존 프로젝트의 실행 인수로 해석될 수 있습니다. 파일 자체를 실행할 때는 예제처럼 --file을 붙입니다. 여러 파일을 쓰는 앱이라면 진입점 첫 줄에 셔뱅(shebang)을 넣어 IDE가 진입점을 찾기 쉽게 할 수 있습니다. dotnet build App.cs와 dotnet format App.cs에도 파일 경로를 넘길 수 있습니다. 빌드 구성이 복잡해지면 dotnet project convert App.cs로 가상 프로젝트 구성을 .csproj로 옮길 수 있습니다. RC3 SDK 설계 문서
파일 기반 앱의 기본 게시 설정은 PublishAot=true, 기본 패키징 설정은 PackAsTool=true입니다. CLI가 기존 빌드 결과를 캐시에서 찾아 실행하는 것과 앱 자체를 Native AOT로 게시하는 것은 별개의 기능입니다. 배포용 앱을 게시할 때는 대상 플랫폼에서 쓸 Native AOT 도구와 의존 패키지의 호환성을 확인합니다. Microsoft Learn 파일 기반 앱 안내 Microsoft Learn Native AOT 배포
결론
한 도구 안에서 코드를 정리할 때는 #:include로 구현을 나눌 수 있습니다. 여러 도구에 공개 API를 제공할 때는 #:ref로 공유 코드를 별도 어셈블리에 둡니다. 파일 기반 앱을 유지하면서도 어떤 코드가 함께 컴파일되고, 어떤 코드가 참조를 통해 공유되는지 드러낼 수 있습니다.
1차 출처
Frequently asked questions
What is the purpose of `#:include` in .NET 11?
#:include allows you to include additional C# files into your application's compilation. It helps organize code by dividing it into separate files while keeping it part of the same assembly.
How does `#:ref` work in .NET 11?
#:ref lets you reference another file-based app as a separate assembly. This allows your app to access public types from the referenced app, keeping them compiled separately.
How do you specify the entry point for a C# file-based app?
You specify the entry point using the dotnet run --file App.cs command. The SDK creates a virtual project and compiles the top-level statements in the specified entry file.
Can you use metadata with `#:package` in .NET 11?
Yes, you can append metadata like Aliases=CommandLine to #:package. This allows you to use extern alias in your code to distinguish between different package references.
How are execution and caching handled in .NET 11 RC3?
The SDK checks if the existing build result is valid based on SDK version, runtime, and file changes. If valid, it executes the cached result; otherwise, it rebuilds and runs the app.
What is the default publish setting for file-based apps in .NET 11?
The default publish setting is PublishAot=true, meaning apps are set to be published with Native AOT. Ensure compatibility with target platforms and dependencies when deploying.
Comments
Join the discussionNo comments yet. Be the first to comment.





