파일 기반 앱

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

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

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

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

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

지원되는 지시문

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

`#:package`

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

#:package Newtonsoft.Json
#:package Serilog version="3.1.1"

`#:project`

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

#:project ../SharedLibrary/SharedLibrary.csproj

`#:property`

MSBuild 속성 값을 설정합니다.

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

`#:sdk`

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

#:sdk Microsoft.NET.Sdk.Web

CLI 명령

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

애플리케이션 실행

다음 명령을 사용하여 파일 기반 앱을 직접 실행합니다.dotnet run

dotnet run file.cs

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

dotnet file.cs

인수 전달

다음과 같은 여러 가지 방법으로 애플리케이션에 인수를 전달합니다.

dotnet run file.cs -- arg1 arg2

이후 -- 의 인수는 애플리케이션에 전달됩니다. 인수가 없을 경우 --은 dotnet run 명령으로 전달됩니다.

dotnet run file.cs arg1 arg2

그러나 약식 구문을 사용하면 모든 인수가 애플리케이션으로 이동합니다.

dotnet file.cs arg1 arg2

애플리케이션 빌드

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

dotnet build file.cs

SDK는 임시 프로젝트를 생성하고 애플리케이션을 빌드합니다.

빌드 출력 정리

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

dotnet clean file.cs

디렉터리의 모든 파일 기반 앱을 정리합니다.

dotnet clean file-based-apps

애플리케이션 게시

다음 명령을 사용하여 배포 패키지를 만듭니다.dotnet publish

dotnet publish file.cs

파일 기반 앱은 기본적으로 네이티브 AOT 게시를 사용하도록 설정하여 최적화된 자체 포함 실행 파일을 생성합니다.

도구로서의 패키지

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

dotnet pack file.cs

파일 기반 앱은 기본값으로 설정됩니다 PackAsTool=true.

프로젝트로 변환

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

dotnet project convert file.cs

이 명령은 동등한 SDK 및 속성을 사용하여 파일을 만듭니다 .csproj . 모든 # 지시문은 # 파일에서 제거되어 해당 .csproj 파일의 요소로 변환됩니다.

종속성 복원

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

dotnet restore file.cs

복원은 애플리케이션을 빌드하거나 실행할 때 암시적으로 실행됩니다.

기본 포함 항목

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

기본적으로 다음 항목이 포함됩니다.

단일 C# 파일 자체입니다.
동일한 디렉터리에 있는 ResX 리소스 파일입니다.

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

Microsoft.NET.Sdk.Web 구성 파일이 포함되어 있습니다 *.json.
다른 특수 SDK에는 다른 패턴이 포함될 수 있습니다.

네이티브 AOT 게시

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

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

#:property PublishAot=false

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

사용자 비밀

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

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

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

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

프로필 실행

파일 기반 앱은 개발 중에 애플리케이션이 실행되는 방식을 구성하기 위한 시작 프로필을 지원합니다. 파일 기반 앱은 시작 프로필을 배치 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는 다음 우선 순위를 사용하여 시작 프로필을 선택합니다.

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

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

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

암시적 빌드 파일

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

`Directory.Build.props`

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

`Directory.Build.targets`

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

`Directory.Packages.props`

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

`nuget.config`

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

`global.json`

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

빌드 캐싱

.NET SDK는 후속 빌드의 성능을 향상시키기 위해 빌드 출력을 캐시합니다. 파일 기반 앱은 이 캐싱 시스템에 참여합니다.

캐시 동작

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

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

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

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

해결 방법

플래그를 사용하여 전체 빌드를 실행합니다.--no-cache
```
dotnet build file.cs --no-cache
```
캐시를 무시하도록 클린 빌드를 강제 적용합니다.
```
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

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

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