파일 기반 앱

이 문서는 .NET 10 SDK 이상 버전 ✔️ 적용됩니다.

파일 기반 앱을 사용하면 기존 프로젝트 파일을 만들지 않고 단일 C# 파일에서 .NET 애플리케이션을 빌드, 실행 및 게시할 수 있습니다. 기존 .NET 프로젝트에 대한 간단한 대안을 제공합니다. 이 방법은 스크립트, 유틸리티 및 소규모 애플리케이션에 대한 개발을 간소화합니다. .NET SDK는 원본 파일의 지시문에 따라 필요한 프로젝트 구성을 자동으로 생성합니다.

주요 이점은 다음과 같습니다.

• 간단한 애플리케이션에 대한 상용구 감소.
• 자체 구성을 포함하는 단독 소스 파일입니다.
• 네이티브 AOT 게시가 기본으로 활성화됩니다.
• .NET 도구로 자동 패키징

이 문서에서는 파일 기반 앱을 효과적으로 만들고 구성하고 작업하는 방법을 알아봅니다.

지원되는 지시문

파일 기반 앱은 #:로 시작하는 지시문을 사용하여 빌드를 구성하고 애플리케이션을 실행합니다. 지원되는 지시문에는 #:package, #:project, #:property, 및 #:sdk가 포함됩니다. 이러한 지시문을 C# 파일의 맨 위에 배치합니다.

#:package

애플리케이션에 NuGet 패키지 참조를 추가합니다.

#:package Newtonsoft.Json
#:package Serilog@3.1.1
#:package Spectre.Console@*

비고

패키지 이름 뒤의 버전 번호를 생략하는 것은 현재 파일과 함께 Directory.Packages.props 중앙 패키지 관리를 사용하는 경우에만 작동합니다. 그렇지 않은 경우 버전 번호를 명시적으로 지정하거나 패키지 이름 뒤를 추가하여 @* 최신 버전을 사용합니다.

#:project

프로젝트 파일이 포함된 다른 프로젝트 파일 또는 디렉터리를 참조합니다.

#:project ../SharedLibrary/SharedLibrary.csproj

#:property

MSBuild 속성 값을 설정합니다.

#:property TargetFramework=net10.0
#:property PublishAot=false

#:sdk

사용할 SDK를 지정합니다. 기본값은 Microsoft.NET.Sdk입니다.

#:sdk Microsoft.NET.Sdk.Web
#:sdk Aspire.AppHost.Sdk@13.0.2

CLI 명령

.NET CLI는 친숙한 명령을 통해 파일 기반 앱에 대한 모든 지원을 제공합니다.

애플리케이션 실행

옵션 dotnet run과 함께 --file 명령을 사용하여 파일 기반 앱을 실행합니다.

dotnet run --file file.cs

또는 명령 뒤에 파일 이름을 사용합니다 dotnet run .

dotnet run file.cs

비고

현재 작업 디렉터리에 dotnet run file.cs 프로젝트 파일이 있는 경우 옵션 없이 --file 해당 프로젝트를 실행하고 이전 버전과의 호환성을 유지하기 위해 대상 앱에 인수로 전달 file.cs 합니다.

또는 약식 구문을 사용합니다.

dotnet file.cs

인수 전달

다음 후에 --인수를 배치하여 애플리케이션에 인수를 전달합니다.

dotnet run file.cs -- arg1 arg2

stdin의 파이프 코드

인수 dotnet run와 함께 표준 입력을 사용하여 C# 코드를 -로 직접 전달합니다. 인수는 - 파일 대신 표준 입력에서 코드를 읽는 것을 dotnet run 나타냅니다. 인수 - 를 dotnet run 사용하면 현재 작업 디렉터리에서 시작 프로필과 같은 다른 파일을 검색하지 않습니다. 현재 디렉터리가 프로그램을 빌드하고 실행하는 작업 디렉터리입니다.

PowerShell:

'Console.WriteLine("hello from stdin!");' | dotnet run -

Bash:

echo 'Console.WriteLine("hello from stdin!");' | dotnet run -

이 방법은 빠른 테스트, 일회성 명령 실행 또는 C# 코드를 동적으로 생성하는 셸 스크립트와 통합하는 데 유용합니다.

애플리케이션 빌드

다음 명령을 사용하여 파일 기반 앱을 컴파일합니다.dotnet build

dotnet build file.cs

SDK는 가상 프로젝트를 생성하고 애플리케이션을 빌드합니다. 기본적으로 빌드 출력은 아래 시스템의 임시 디렉터리 <temp>/dotnet/runfile/<appname>-<appfilesha>/bin/<configuration>/로 이동합니다.

--output 옵션과 dotnet build 명령을 사용하여 다른 경로를 지정합니다. 새 기본 출력 경로를 정의하려면 다음 지시문을 OutputPath사용하여 파일 맨 위에 속성을 설정합니다#:property OutputPath=./output.

빌드 출력 정리

다음 명령을 사용하여 빌드 아티팩트 dotnet clean 제거:

dotnet clean file.cs

디렉터리에서 파일 기반 앱에 대한 캐시를 삭제합니다.

dotnet clean file-based-apps

--days 이전 명령과 함께 옵션을 사용하여 아티팩트 폴더를 제거하기 전에 사용하지 않는 데 필요한 일 수를 지정합니다. 기본 일 수는 30입니다.

애플리케이션 게시

파일 기반 앱은 기본적으로 네이티브 AOT 게시를 사용하도록 설정하여 최적화된 자체 포함 실행 파일을 생성합니다. 파일 맨 위에 추가하여 #:property PublishAot=false 이 기능을 사용하지 않도록 설정합니다.

이 dotnet publish 명령을 사용하여 독립 실행 파일을 만듭니다.

dotnet publish file.cs

실행 파일의 기본 위치는 artifacts 애플리케이션의 이름을 따서 명명된 하위 디렉터리가 있는 파일 옆에 .cs 있는 디렉터리입니다. --output 옵션과 dotnet publish 명령을 사용하여 다른 경로를 지정합니다.

도구로서의 패키지

다음 명령을 사용하여 파일 기반 앱을 .NET 도구로 패키지합니다 dotnet pack .

dotnet pack file.cs

파일 기반 앱은 기본값으로 설정됩니다 PackAsTool=true. 파일 맨 위에 추가하여 #:property PackAsTool=false 이 설정을 사용하지 않도록 설정합니다.

프로젝트로 변환

다음 명령을 사용하여 파일 기반 앱을 기존 프로젝트로 변환합니다.dotnet project convert

dotnet project convert file.cs

이 명령은 파일의 복사본을 .cs 만들고 원본 파일의 지시문에 따라 해당하는 SDK 항목, 속성 및 패키지 참조가 있는 파일을 .csproj 만듭니다#:. 두 파일은 모두 원본 .cs 파일 옆에 있는 애플리케이션의 이름이 지정된 디렉터리에 배치되며, 이 디렉터리에는 그대로 유지됩니다.

종속성 복원

다음 명령을 사용하여 파일에서 참조되는 NuGet 패키지를 복원합니다 dotnet restore .

dotnet restore file.cs

기본적으로 복원은 애플리케이션을 빌드하거나 실행할 때 암시적으로 실행됩니다. 그러나 --no-restore를 dotnet build 명령과 dotnet run 명령 모두에 전달하여 암시적으로 복원하지 않고 빌드하거나 실행할 수 있습니다.

기본 포함 항목

파일 기반 앱에는 컴파일 및 패키징을 위한 특정 파일 형식이 자동으로 포함됩니다.

기본적으로 단일 C# 파일이 포함됩니다.

다른 SDK에는 다른 파일 형식이 포함됩니다.

• Microsoft.NET.Sdk.Web 구성 파일이 포함되어 있습니다 *.json.
• 기본이 아닌 SDK에는 ResX 리소스 파일이 포함됩니다.

네이티브 AOT 게시

파일 기반 앱은 기본적으로 네이티브 AOT(Ahead-Of-Time) 컴파일을 사용하도록 설정합니다. 이 기능은 시작 속도가 빨라지고 메모리 공간이 더 작은 최적화된 자체 포함 실행 파일을 생성합니다.

네이티브 AOT를 사용하지 않도록 설정해야 하는 경우 다음 설정을 사용합니다.

#:property PublishAot=false

네이티브 AOT에 대한 자세한 내용은 네이티브 AOT 배포를 참조하세요.

사용자 비밀

파일 기반 앱은 전체 파일 경로의 해시를 기반으로 안정적인 사용자 비밀 ID를 생성합니다. 이 ID를 사용하면 소스 코드와 별도로 중요한 구성을 저장할 수 있습니다.

기존 프로젝트와 동일한 방식으로 사용자 비밀에 액세스합니다.

dotnet user-secrets set "ApiKey" "your-secret-value" --file file.cs

파일 기반 앱에 대한 사용자 암호를 나열합니다.

dotnet user-secrets list --file file.cs

이 dotnet user-secrets list 명령은 비밀의 값을 출력합니다. 공용 컨텍스트에서 실행되는 스크립트에는 이 명령을 배치하지 마세요.

자세한 내용은 개발 중인 앱 비밀의 안전한 스토리지를 참조하세요.

프로필 실행

파일 기반 앱은 개발 중에 애플리케이션이 실행되는 방식을 구성하기 위한 시작 프로필을 지원합니다. 파일 기반 앱은 시작 프로필을 배치 Properties/launchSettings.json하는 대신 원본 파일과 동일한 디렉터리에 명명된 [ApplicationName].run.json 플랫 시작 설정 파일을 사용할 수 있습니다.

플랫 시작 설정 파일

애플리케이션의 이름을 따서 명명된 시작 설정 파일을 만듭니다. 예를 들어, 파일 기반 앱이 app.cs인 경우, 동일한 디렉터리에 app.run.json를 만드세요.

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

여러 파일 기반 앱

동일한 디렉터리에 여러 파일 기반 앱이 있는 경우 각 앱에는 자체 시작 설정 파일이 있을 수 있습니다.

📁 myapps/
├── foo.cs
├── foo.run.json
├── bar.cs
└── bar.run.json

프로필 선택

.NET CLI는 다음 우선 순위를 사용하여 시작 프로필을 선택합니다.

1. 옵션으로 지정된 프로필입니다 --launch-profile .
2. 환경 변수에 지정된 프로필입니다 DOTNET_LAUNCH_PROFILE .
3. 시작 설정 파일에 정의된 첫 번째 프로필입니다.

특정 프로필로 실행하려면 다음을 수행합니다.

dotnet run app.cs --launch-profile https

기존 시작 설정

파일 기반 앱은 기존 Properties/launchSettings.json 파일도 지원합니다. 두 파일이 모두 있는 경우 기존 위치가 우선합니다. 두 파일이 모두 있는 경우 .NET CLI는 사용되는 파일을 명확히 하기 위해 경고를 기록합니다.

셸 실행

Shebang 줄 및 실행 권한을 사용하여 Unix와 유사한 시스템에서 파일 기반 앱을 직접 실행할 수 있습니다.

파일의 맨 위에 shebang을 추가하세요.

#!/usr/bin/env dotnet
#:package Spectre.Console

using Spectre.Console;

AnsiConsole.MarkupLine("[green]Hello, World![/]");

파일을 실행 가능하게 만듭니다.

chmod +x file.cs

직접 실행:

./file.cs

비고

shebang 추가 시 LF 대신 CRLF 줄 끝을 사용합니다. 파일에 BOM을 포함하지 마세요.

암시적 빌드 파일

파일 기반 앱은 동일한 디렉터리 또는 부모 디렉터리의 MSBuild 및 NuGet 구성 파일을 준수합니다. 이러한 파일은 SDK가 애플리케이션을 빌드하는 방법에 영향을 줍니다. 파일 기반 앱을 구성할 때 이러한 파일을 염두에 두어야 합니다.

Directory.Build.props

디렉터리 트리의 모든 프로젝트에 적용되는 MSBuild 속성을 정의합니다. 파일 기반 앱은 이러한 속성을 상속합니다.

Directory.Build.targets

MSBuild 대상 및 사용자 지정 빌드 논리를 정의합니다. 파일 기반 앱은 빌드 중에 이러한 대상을 실행합니다.

Directory.Packages.props

NuGet 종속성에 대한 중앙 패키지 관리를 사용하도록 설정합니다. 파일 기반 앱은 중앙에서 관리되는 패키지 버전을 사용할 수 있습니다.

nuget.config

NuGet 패키지 원본 및 설정을 구성합니다. 파일 기반 앱은 패키지를 복원할 때 이러한 구성을 사용합니다.

global.json

사용할 .NET SDK 버전을 지정합니다. 파일 기반 앱은 이 버전 선택을 준수합니다.

빌드 캐싱

.NET SDK는 빌드 출력을 캐시하여 후속 호출에서 성능을 향상시킵니다 dotnet run. 이 캐싱 시스템은 파일 기반 앱에 고유합니다.

캐시 동작

SDK는 다음을 기반으로 빌드 출력을 캐시합니다.

• 원본 파일 콘텐츠입니다.
• 지시문 구성입니다.
• SDK 버전입니다.
• 암시적 빌드 파일 존재 및 콘텐츠.

캐싱은 빌드 성능을 향상하지만 다음과 같은 경우 혼동을 일으킬 수 있습니다.

• 암시적 빌드 파일을 변경해도 다시 작성이 트리거되지 않습니다.
• 파일을 다른 디렉터리로 이동해도 캐시가 무효화되지 않습니다.

해결 방법

• 다음 명령을 사용하여 파일 기반 앱에 대한 캐시 아티팩트 지우기:

dotnet clean file-based-apps

• 캐시를 무시하도록 클린 빌드를 강제 적용합니다.

  dotnet clean file.cs
  dotnet build file.cs
  

폴더 레이아웃 권장 사항

기존 프로젝트 및 암시적 빌드 파일과의 충돌을 방지하기 위해 파일 기반 앱을 신중하게 구성합니다.

프로젝트 파일 원뿔 방지

파일 기반 앱을 프로젝트의 디렉터리 구조 .csproj 내에 배치하지 마세요. 프로젝트 파일의 암시적 빌드 파일 및 설정은 파일 기반 앱을 방해할 수 있습니다.

❌ 권장되지 않음:

📁 MyProject/
├── MyProject.csproj
├── Program.cs
└──📁 scripts/
    └── utility.cs  // File-based app - bad location

✅ 권장:

📁 MyProject/
├── MyProject.csproj
└── Program.cs
📁 scripts/
└── utility.cs  // File-based app - good location

암시적 파일을 염두에 두어야 합니다.

부모 디렉터리의 암시적 빌드 파일은 하위 디렉터리의 모든 파일 기반 앱에 영향을 미칩니다. 다른 빌드 구성이 필요한 경우 파일 기반 앱에 대해 격리된 디렉터리를 만듭니다.

❌ 권장되지 않음:

📁 repo/
├── Directory.Build.props  // Affects everything below
├── app1.cs
└── app2.cs

✅ 권장:

📁 repo/
├── Directory.Build.props
├──📁 projects/
│   └── MyProject.csproj
└──📁 scripts/
    ├── Directory.Build.props  // Isolated configuration
    ├── app1.cs
    └── app2.cs

참고하십시오

• .NET SDK 개요
• dotnet run 명령
• dotnet build 명령
• 네이티브 AOT 배포