.NET SDK 프로젝트용 MSBuild 참조

  • 아티클

이 페이지는 .NET 프로젝트를 구성하는 데 사용할 수 있는 MSBuild 속성 및 항목에 대한 참조입니다.

참고 항목

이 페이지는 진행 중인 작업이며 .NET SDK의 유용한 MSBuild 속성이 모두 나열된 것은 아닙니다. 일반적인 MSBuild 속성의 목록을 보려면 일반 MSBuild 속성을 참조하세요.

어셈블리 유효성 검사 속성

이러한 속성과 항목은 ValidateAssemblies 작업에 전달됩니다. 어셈블리 유효성 검사에 대한 자세한 내용은 어셈블리 유효성 검사를 참조하세요.

이 섹션에서 설명하는 MSBuild 속성은 다음과 같습니다.

참고 항목

이러한 속성은 아직 .NET SDK의 일부가 아닙니다. 이를 사용하려면 Microsoft.DotNet.ApiCompat.Task에 PackageReference도 추가해야 합니다.

또한 패키지 유효성을 검사 속성에 설명된 다음 속성도 어셈블리 유효성 검사에 적용됩니다.

ApiCompatStrictMode

true로 설정되면 ApiCompatStrictMode 속성은 API 호환성 검사가 strict 모드에서 수행되어야 함을 지정합니다.

<PropertyGroup>
  <ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>

ApiCompatValidateAssemblies

ApiCompatValidateAssemblies 속성은 지정된 어셈블리에 대한 일련의 유효성 검사를 사용하도록 설정합니다. 자세한 내용은 어셈블리 유효성 검사를 참조하세요.

<PropertyGroup>
  <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>

프레임워크 속성

이 섹션에서 설명하는 MSBuild 속성은 다음과 같습니다.

TargetFramework

TargetFramework 속성은 앱의 대상 프레임워크 버전을 지정합니다. 유효한 대상 프레임워크 모니커의 목록을 보려면 SDK 스타일 프로젝트의 대상 프레임워크를 참조하세요.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

자세한 내용은 SDK 스타일 프로젝트의 대상 프레임워크를 참조하세요.

TargetFrameworks

앱의 대상 플랫폼을 여러 개 지정하려면 TargetFrameworks 속성을 사용합니다. 유효한 대상 프레임워크 모니커의 목록을 보려면 SDK 스타일 프로젝트의 대상 프레임워크를 참조하세요.

참고 항목

TargetFramework(단수형)이 지정되면 이 속성은 무시됩니다.

<PropertyGroup>
  <TargetFrameworks>net8.0;net462</TargetFrameworks>
</PropertyGroup>

자세한 내용은 SDK 스타일 프로젝트의 대상 프레임워크를 참조하세요.

NetStandardImplicitPackageVersion

참고 항목

이 속성은 netstandard1.x를 사용하는 프로젝트에만 적용됩니다. netstandard2.x를 사용하는 프로젝트에는 적용되지 않습니다.

메타패키지 버전보다 낮은 프레임워크 버전을 지정하려면 NetStandardImplicitPackageVersion 속성을 사용합니다. 다음 예제의 프로젝트 파일은 netstandard1.3을 대상으로 하지만 NETStandard.Library의 1.6.0 버전을 사용합니다.

<PropertyGroup>
  <TargetFramework>netstandard1.3</TargetFramework>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

어셈블리 특성 속성

GenerateAssemblyInfo

GenerateAssemblyInfo 속성은 프로젝트의 AssemblyInfo 특성 생성을 제어합니다. 기본값은 true입니다. 파일 생성을 사용하지 않도록 설정하려면 다음과 같이 false를 사용합니다.

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

Generatedassemblyinfofile 설정은 생성된 파일의 이름을 제어합니다.

GenerateAssemblyInfo 값이 true이면 패키지 관련 프로젝트 속성이 어셈블리 특성으로 변환됩니다.

프로젝트 파일을 사용하여 어셈블리 특성을 생성하는 방법에 대한 자세한 내용은 프로젝트 파일에서 어셈블리 특성 설정을 참조하세요.

GeneratedAssemblyInfoFile

GeneratedAssemblyInfoFile 속성은 생성된 어셈블리 정보 파일의 상대 또는 절대 경로를 정의합니다. 기본값은 $(IntermediateOutputPath)(일반적으로 obj) 디렉터리에 있는 [project-name].AssemblyInfo.[cs|vb] 파일입니다.

<PropertyGroup>
  <GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>

패키지 속성

설명 속성

PackageId, PackageVersion, PackageIcon, Title, Description과 같은 속성을 지정하여 프로젝트에서 생성되는 패키지를 설명할 수 있습니다. 이러한 속성 및 다른 속성에 대한 자세한 내용은 팩 대상을 참조하세요.

<PropertyGroup>
  ...
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>John Doe</Authors>
  <Company>Contoso</Company>
</PropertyGroup>

PackRelease

PackRelease 속성은 dotnet pack의 기본 동작을 변경한다는 점을 제외하면 PublishRelease 속성과 유사합니다. 이 속성은 .NET 7에서 도입되었습니다.

<PropertyGroup>
  <PackRelease>true</PackRelease>
</PropertyGroup>

참고 항목

  • .NET 8 SDK부터 PackRelease의 기본값은 true입니다. 자세한 내용은 'dotnet pack'이 릴리스 구성을 사용함을 참조하세요.
  • .NET 7 SDK만 해당: Visual Studio 솔루션의 일부인 프로젝트에서 PackRelease를 사용하려면 환경 변수 DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS를 true(또는 다른 값)로 설정해야 합니다. 프로젝트가 많은 솔루션의 경우 이 변수를 설정하면 압축하는 데 필요한 시간이 늘어납니다.

패키지 유효성을 검사 속성

이러한 속성과 항목은 ValidatePackage 작업에 전달됩니다. 패키지 유효성을 검사에 대한 자세한 내용은 패키지 유효성을 검사 개요를 참조하세요.

ValidateAssemblies 작업의 속성은 어셈블리 유효성 검사 속성을 참조하세요.

이 섹션에는 다음 MSBuild 속성 및 항목이 설명되어 있습니다.

ApiCompatEnableRuleAttributesMustMatch

true로 설정하면 ApiCompatEnableRuleAttributesMustMatch 속성은 특성이 일치하는지 유효성을 검사하는 유효성 검사 규칙을 사용하도록 설정합니다. 기본값은 false입니다.

<PropertyGroup>
  <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
</PropertyGroup>

ApiCompatEnableRuleCannotChangeParameterName

true로 설정하면 ApiCompatEnableRuleCannotChangeParameterName 속성이 공용 메서드에서 매개 변수 이름이 변경되었는지 유효성을 검사하는 유효성 검사 규칙을 사용하도록 설정합니다. 기본값은 false입니다.

<PropertyGroup>
  <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
</PropertyGroup>

ApiCompatExcludeAttributesFile

ApiCompatExcludeAttributesFile 항목은 DocId 형식으로 제외할 특성이 포함된 파일의 경로를 지정합니다.

<ItemGroup>
  <ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
  <ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
</ItemGroup>

ApiCompatGenerateSuppressionFile

ApiCompatGenerateSuppressionFile 속성은 호환성 제거 파일을 생성할지 여부를 지정합니다.

<PropertyGroup>
  <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
</PropertyGroup>

ApiCompatPermitUnnecessarySuppressions

ApiCompatPermitUnnecessarySuppressions 속성은 제거 파일에서 불필요한 제거를 허용할지 여부를 지정합니다.

기본값은 false입니다.

<PropertyGroup>
  <ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
</PropertyGroup>

ApiCompatPreserveUnnecessarySuppressions

ApiCompatPreserveUnnecessarySuppressions 속성은 제거 파일을 다시 생성할 때 불필요한 제거를 유지할지 여부를 지정합니다. 기존 제거 파일이 다시 생성되면 해당 콘텐츠를 읽고 제거 집합으로 역직렬화한 다음 목록에 저장합니다. 비호환성이 해결되면 일부 제거 기능이 더 이상 필요하지 않을 수 있습니다. 제거가 다시 디스크에 직렬화되면 이 속성을 true로 설정하여 기존(역직렬화된) 식을 모든 유지하도록 선택할 수 있습니다.

기본값은 false입니다.

<PropertyGroup>
  <ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
</PropertyGroup>

ApiCompatRespectInternals

ApiCompatRespectInternals 속성은 public API 외에 internal API의 호환성도 검사해야 하는지 여부를 지정합니다.

<PropertyGroup>
  <ApiCompatRespectInternals>true</ApiCompatRespectInternals>
</PropertyGroup>

ApiCompatSuppressionFile

ApiCompatSuppressionFile 항목은 읽을 하나 이상의 제거 파일에 대한 경로를 지정합니다. 지정하지 않으면 제거 파일 <project-directory>/CompatibilitySuppressions.xml을 읽습니다(있는 경우).

<ItemGroup>
  <ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
</ItemGroup>

ApiCompatSuppressionOutputFile

ApiCompatSuppressionOutputFile 속성은 <ApiCompatGenerateSuppressionFile>이 true일 때 쓸 제거 파일의 경로를 지정합니다. 지정하지 않으면 첫 번째 ApiCompatSuppressionFile 항목이 사용됩니다.

EnablePackageValidation

EnablePackageValidation 속성을 사용하면 Pack 작업 후에 패키지에 대한 일련의 유효성 검사를 수행할 수 있습니다. 자세한 내용은 패키지 유효성 검사를 참조하세요.

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

EnableStrictModeForBaselineValidation

true로 설정하면 EnableStrictModeForBaselineValidation 속성이 패키지 기준 검사에 대해 strict 모드를 사용하도록 설정합니다. 기본값은 false입니다.

EnableStrictModeForCompatibleFrameworksInPackage

true로 설정하면 EnableStrictModeForCompatibleFrameworksInPackage 속성이 대상 프레임워크를 기반으로 호환되는 어셈블리에 대해 strict 모드를 사용하도록 설정합니다. 기본값은 false입니다.

EnableStrictModeForCompatibleTfms

true로 설정하면 EnableStrictModeForCompatibleTfms 속성은 호환되는 모든 대상 프레임워크의 계약 및 구현 어셈블리에 대해 strict 모드를 사용하도록 설정합니다. 기본값은 true입니다.

NoWarn

NoWarn 속성은 억제할 진단 ID를 지정합니다.

<PropertyGroup>
  <NoWarn>$(NoWarn);PKV0001</NoWarn>
</PropertyGroup>

PackageValidationBaselineFrameworkToIgnore

PackageValidationBaselineFrameworkToIgnore 항목은 기준 패키지에서 무시할 대상 프레임워크를 지정합니다. 프레임워크 문자열은 기준 패키지의 폴더 이름과 정확히 일치해야 합니다.

<ItemGroup>
  <PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
</ItemGroup>

PackageValidationBaselineName

PackageValidationBaselineName 속성은 현재 패키지의 유효성을 검사할 기준 패키지의 이름을 지정합니다. 지정하지 않으면 PackageId 값이 사용됩니다.

PackageValidationBaselineVersion

PackageValidationBaselineVersion 속성은 현재 패키지의 유효성을 검사할 기준 패키지 버전을 지정합니다.

PackageValidationReferencePath

PackageValidationReferencePath 항목은 TFM별로 참조 어셈블리를 찾을 수 있는 디렉터리 경로를 지정합니다.

<ItemGroup>
  <PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
</ItemGroup>

RoslynAssembliesPath

RoslynAssembliesPath 속성은 사용하려는 Microsoft.CodeAnalytic 어셈블리가 포함된 디렉터리의 경로를 지정합니다. SDK에 있는 것보다 최신 컴파일러로 테스트하려는 경우에만 이 속성을 설정하면 됩니다.

이 섹션에서 설명하는 MSBuild 속성은 다음과 같습니다.

AppendTargetFrameworkToOutputPath

AppendTargetFrameworkToOutputPath 속성은 TFM(대상 프레임워크 모니커)을 출력 경로(OutputPath에 정의)에 추가할지 여부를 제어합니다. .NET SDK는 대상 프레임워크와 런타임 식별자(있는 경우)를 출력 경로에 자동으로 추가합니다. AppendTargetFrameworkToOutputPath를 false로 설정하면 TFM이 출력 경로에 추가되지 않습니다. 그러나 출력 경로에 TFM이 없으면 여러 빌드 아티팩트가 서로 덮어쓸 수 있습니다.

예를 들어 .NET 5 앱에서 다음과 같이 설정하면 출력 경로가 bin\Debug\net5.0에서 bin\Debug로 변경됩니다.

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

AppendRuntimeIdentifierToOutputPath

AppendRuntimeIdentifierToOutputPath 속성은 RID(런타임 식별자)를 출력 경로에 추가할지 여부를 제어합니다. .NET SDK는 대상 프레임워크와 런타임 식별자(있는 경우)를 출력 경로에 자동으로 추가합니다. AppendRuntimeIdentifierToOutputPath를 false로 설정하면 RID가 출력 경로에 추가되지 않습니다.

예를 들어 .NET 5 앱 및 RID의 win-x64경우 다음 설정은 출력 경로를 다음으로 bin\Debug\net5.0\win-x64bin\Debug\net5.0변경합니다.

<PropertyGroup>
  <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

CopyLocalLockFileAssemblies

CopyLocalLockFileAssemblies 속성은 다른 라이브러리에 대한 종속성이 있는 플러그 인 프로젝트에 유용합니다. 이 속성을 true로 설정하면 NuGet 패키지 종속성이 출력 디렉터리에 복사됩니다. 즉, dotnet build의 출력을 사용하여 모든 머신에서 플러그 인을 실행할 수 있습니다.

<PropertyGroup>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

팁

또는 dotnet publish를 사용하여 클래스 라이브러리를 게시할 수 있습니다. 자세한 내용은 dotnet publish를 참조하세요.

ErrorOnDuplicatePublishOutputFiles

ErrorOnDuplicatePublishOutputFiles 속성은 MSBuild가 게시 출력에서 중복 파일을 검색하지만 제거할 파일을 결정할 수 없는 경우 SDK에서 NETSDK1148 오류를 생성하는지 여부와 관련이 있습니다. 오류가 생성되지 않도록 하려면 ErrorOnDuplicatePublishOutputFiles 속성을 false로 설정하세요.

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>

이 속성은 .NET 6에서 도입되었습니다.

GenerateRuntimeConfigDevFile

.NET 6 SDK부터 [Appname].runtimesettings.dev.json 파일은 컴파일 시 더 이상 기본적으로 생성되지 않습니다. 그래도 이 파일을 생성하려면 GenerateRuntimeConfigDevFile 속성을 true로 설정합니다.

<PropertyGroup>
  <GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>

GenerateRuntimeConfigurationFiles

GenerateRuntimeConfigurationFiles 속성은 런타임 구성 옵션이 runtimeconfig.template.json 파일에서[appname].runtimeconfig.json 파일로 복사되는지 여부를 제어합니다. runtimeconfig.json 파일이 필요한 앱의 경우(즉, 앱의 OutputType이 Exe) 이 속성은 기본적으로 true로 설정됩니다.

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>

Core를 위한 위성 어셈블리 생성

GenerateSatelliteAssembliesForCore 속성은 .NET Framework 프로젝트에서 csc.exe 또는 Al.exe(어셈블리 링커)를 사용하여 위성 어셈블리를 생성할지 여부를 제어합니다. (.NET Core 및 .NET 5+ 프로젝트는 항상 csc.exe를 사용하여 위성 어셈블리를 생성합니다.) .NET Framework 프로젝트의 경우 위성 어셈블리는 기본적으로 al.exe에 의해 만들어집니다. GenerateSatelliteAssembliesForCore 속성을 true로 설정하면 위성 어셈블리가 대신 csc.exe에 의해 만들어집니다. 다음 상황에서는 csc.exe를 사용하는 것이 유리할 수 있습니다.

<PropertyGroup>
  <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>

IsPublishable

IsPublishable 속성을 사용하면 Publish 대상을 실행할 수 있습니다. 이 속성은 .*proj 파일 및 Publish 대상(예: dotnet publish 명령)을 사용하는 프로세스에만 영향을 줍니다. PublishOnly 대상을 사용하는 Visual Studio에서의 게시에는 영향을 주지 않습니다. 기본값은 true입니다.

이 속성은 게시해야 하는 프로젝트를 자동으로 선택할 수 있게 해주므로 솔루션 파일에서 dotnet publish를 실행하는 경우 유용합니다.

<PropertyGroup>
  <IsPublishable>false</IsPublishable>
</PropertyGroup>

PreserveCompilationContext

PreserveCompilationContext 속성을 사용하면 빌드되거나 게시된 애플리케이션이 빌드 타임에 사용된 것과 같은 설정을 사용하여 런타임에 더 많은 코드를 컴파일할 수 있습니다. 빌드 타임에 참조된 어셈블리는 출력 디렉터리의 ref 하위 디렉터리에 복사됩니다. 참조 어셈블리의 이름은 컴파일러에 전달된 옵션과 함께 애플리케이션의 .deps.json 파일에 저장됩니다. DependencyContext.CompileLibraries 및 DependencyContext.CompilationOptions 속성을 사용하여 이 정보를 검색할 수 있습니다.

이 기능은 주로 Razor 파일의 런타임 컴파일을 지원하기 위해 ASP.NET Core MVC 및 Razor Pages에서 내부적으로 사용됩니다.

<PropertyGroup>
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

PreserveCompilationReferences

PreserveCompilationReferences 속성은 PreserveCompilationContext 속성과 유사합니다. 단, 참조된 어셈블리를 게시 디렉터리에만 복사하고 .deps.json 파일에는 복사하지 않습니다.

<PropertyGroup>
  <PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>

자세한 내용은 Razor SDK 속성을 참조하세요.

ProduceReferenceAssemblyInOutDir

.NET 5 및 이전 버전에서는 참조 어셈블리가 항상 OutDir 디렉터리에 기록됩니다. .NET 6 이상 버전에서는 ProduceReferenceAssemblyInOutDir 속성을 사용하여 참조 어셈블리가 OutDir 디렉터리에 기록되는지 여부를 제어할 수 있습니다. 기본값은 false이며 참조 어셈블리는 IntermediateOutputPath 디렉터리에만 기록됩니다. 참조 어셈블리를 OutDir 디렉터리에 쓰려면 값을 true로 설정합니다.

<PropertyGroup>
  <ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>

자세한 내용은 중간 출력에 참조 어셈블리 쓰기를 참조하세요.

PublishDocumentationFile

이 속성이 true이면 프로젝트의 XML 설명서 파일(생성된 경우)이 프로젝트의 게시 출력에 포함됩니다. 이 속성은 기본적으로 true입니다.

팁

컴파일 시 XML 설명서 파일을 생성하려면 GenerateDocumentationFile을 true로 설정합니다.

PublishDocumentationFiles

이 속성은 다양한 종류의 XML 설명서 파일이 기본적으로 게시 디렉터리에 복사되는지 여부를 제어하는 여러 다른 속성(예: PublishDocumentationFile 및 PublishReferencesDocumentationFiles)에 대한 사용 플래그입니다. 해당 속성이 설정되지 않고 이 속성이 설정된 경우 해당 속성의 기본값은 true입니다. 이 속성은 기본적으로 true입니다.

PublishReferencesDocumentationFiles

이 속성이 true이면 DLL 파일과 같은 런타임 자산 대신 프로젝트 참조에 대한 XML 설명서 파일이 게시 디렉터리에 복사됩니다. 이 속성은 기본적으로 true입니다.

PublishRelease

PublishRelease 속성은 기본적으로 Debug 구성 대신 Release 구성을 사용하도록 dotnet publish에 알립니다. 이 속성은 .NET 7에서 도입되었습니다.

<PropertyGroup>
  <PublishRelease>true</PublishRelease>
</PropertyGroup>

참고 항목

  • .NET 8 SDK부터 .NET 8 이상을 대상으로 하는 프로젝트의 경우 PublishRelease의 기본값은 true입니다. 자세한 내용은 'dotnet publish'가 릴리스 구성을 사용함을 참조하세요.
  • 이 속성은 dotnet build /t:Publish의 동작에 영향을 주지 않으며 .NET CLI를 통해 게시할 때만 구성을 변경합니다.
  • .NET 7 SDK만 해당: Visual Studio 솔루션의 일부인 프로젝트에서 PublishRelease를 사용하려면 환경 변수 DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS를 true(또는 다른 값)로 설정해야 합니다. 이 변수가 사용하도록 설정된 솔루션을 게시하면 실행 가능한 프로젝트의 PublishRelease 값이 우선적으로 적용되며 새 기본 구성이 솔루션의 다른 프로젝트에 전달됩니다. 솔루션에 PublishRelease 값이 서로 다른 여러 실행 가능 프로젝트 또는 최상위 프로젝트가 포함되어 있는 경우 솔루션이 성공적으로 게시되지 않습니다. 프로젝트가 많은 솔루션의 경우 이 설정을 사용하면 게시하는 데 필요한 시간이 늘어납니다.

PublishSelfContained

PublishSelfContained 속성은 dotnet publish에게 앱을 자체 포함 앱으로 게시하도록 알립니다. 이 속성은 솔루션 수준에서 게시하는 경우와 같이 dotnet publish 명령에 --self-contained 인수를 사용할 수 없는 경우에 유용합니다. 이 경우 프로젝트 또는 Directory.Build.Props 파일에 PublishSelfContained MSBuild 속성을 추가할 수 있습니다.

이 속성은 .NET 7에서 도입되었습니다. 이는 publish 동사에만 해당된다는 점을 제외하면 SelfContained 속성과 유사합니다. SelfContained 대신 PublishSelfContained를 사용하는 것이 좋습니다.

<PropertyGroup>
  <PublishSelfContained>true</PublishSelfContained>
</PropertyGroup>

RollForward

RollForward 속성은 여러 런타임 버전을 사용할 수 있는 경우 애플리케이션이 런타임을 선택하는 방법을 제어합니다. 이 값은 rollForward 설정으로 .runtimeconfig.json에 출력됩니다.

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

RollForward를 다음 값 중 하나로 설정합니다.

값 설명
Minor 지정되지 않은 경우 기본값입니다.
요청된 부 버전이 없을 경우 가장 낮은 더 높은 부 버전으로 롤포워드합니다. 요청된 부 버전이 있으면 LatestPatch 정책이 사용됩니다.
Major 요청된 주 버전이 없을 경우 다음으로 사용 가능한 더 높은 주 버전과 가장 낮은 부 버전으로 롤포워드합니다. 요청된 주 버전이 있으면 Minor 정책이 사용됩니다.
LatestPatch 가장 높은 패치 버전으로 롤포워드합니다. 이 값은 부 버전 롤포워드를 사용하지 않도록 설정합니다.
LatestMinor 요청된 부 버전이 있는 경우에도 가장 높은 부 버전으로 롤포워드합니다.
LatestMajor 요청된 주 버전이 있는 경우에도 가장 높은 주 버전과 가장 높은 부 버전으로 롤포워드합니다.
Disable 롤포워드하지 않고 지정된 버전에만 바인딩합니다. 이 정책은 최신 패치로 롤포워드할 수 있는 기능을 사용하지 않도록 설정하므로 일반 용도에는 권장되지 않습니다. 이 값은 테스트용으로만 사용하는 것이 좋습니다.

자세한 내용은 롤포워드 동작 제어를 참조하세요.

RuntimeFrameworkVersion

RuntimeFrameworkVersion 속성은 게시할 때 사용할 런타임의 버전을 지정합니다. 다음과 같이 런타임 버전을 지정합니다.

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

프레임워크 종속 애플리케이션을 게시할 때 이 값은 필요한 ‘최소’ 버전을 지정합니다. 자체 포함 애플리케이션을 게시할 때 이 값은 필요한 ‘정확한’ 버전을 지정합니다.

RuntimeIdentifier

RuntimeIdentifier 속성을 사용하여 프로젝트의 단일 RID(런타임 식별자)를 지정할 수 있습니다. RID를 통해 자체 포함 배포를 게시할 수 있습니다.

<PropertyGroup>
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

RuntimeIdentifiers 속성을 사용하여 프로젝트에 대해 세미콜론으로 구분된 RID(런타임 식별자) 목록을 지정할 수 있습니다. 여러 런타임에 게시해야 하는 경우 이 속성을 사용합니다. RuntimeIdentifiers는 복원 시간에 올바른 자산이 그래프에 있는지 확인하는 데 사용됩니다.

팁

단일 런타임만 필요한 경우에는 RuntimeIdentifier(단수형)를 사용하면 빌드 속도가 더 빨라집니다.

<PropertyGroup>
  <RuntimeIdentifiers>win-x64;osx-x64;linux-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

SatelliteResourceLanguages 속성을 사용하여 빌드 및 게시 중에 위성 리소스 어셈블리를 보존할 언어를 지정할 수 있습니다. 많은 NuGet 패키지는 지역화된 리소스 위성 어셈블리를 메인 패키지에 포함하고 있습니다. 이러한 NuGet 패키지를 참조하지만 지역화된 리소스가 필요하지 않는 프로젝트의 경우 지역화된 어셈블리로 인해 빌드 및 게시 출력 크기가 불필요하게 확장될 수 있습니다. 프로젝트 파일에 SatelliteResourceLanguages 속성을 추가하면 지정하는 언어에 대한 지역화된 어셈블리만 빌드 및 게시 출력에 포함됩니다. 예를 들어, 다음 프로젝트 파일에서는 영어(미국) 및 독일어(독일) 리소스 위성 어셈블리만 보존됩니다.

<PropertyGroup>
  <SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

참고 항목

  • 이 속성은 지역화된 리소스 위성 어셈블리가 포함된 NuGet 패키지를 참조하는 프로젝트에서 지정해야 합니다.

  • 여러 언어를 dotnet publish에 대한 인수로 지정하려면 언어 식별자 주위에 따옴표 세 쌍을 추가해야 합니다. 예시:

    dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""

SelfContained

SelfContained 속성은 dotnet build 및 dotnet publish에게 앱을 자체 포함 앱으로 빌드하거나 게시하도록 알립니다. 이 속성은 솔루션 수준에서 게시하는 경우와 같이 dotnet 명령과 함께 --self-contained 인수를 사용할 수 없는 경우에 유용합니다. 이 경우 프로젝트 또는 Directory.Build.Props 파일에 SelfContained MSBuild 속성을 추가할 수 있습니다.

이 속성은 PublishSelfContained 속성과 유사합니다. 가능하면 SelfContained 대신 PublishSelfContained를 사용하는 것이 좋습니다.

<PropertyGroup>
  <SelfContained>true</SelfContained>
</PropertyGroup>

UseAppHost

UseAppHost 속성은 배포용으로 네이티브 실행 파일을 만들지 여부를 제어합니다. 자체 포함 배포의 경우 네이티브 실행 파일이 필요합니다. 프레임워크 종속 실행 파일은 기본적으로 만들어집니다. UseAppHost 속성을 false로 설정하여 실행 파일 생성을 사용하지 않도록 설정합니다.

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

배포에 대한 자세한 내용은 .NET 애플리케이션 배포를 참조하세요.

자체 포함 배포에서 사용되지 않는 코드를 잘라내는 기능인 자르기를 미세 조정하는 데 다양한 MSBuild 속성을 사용할 수 있습니다. 이러한 옵션은 자르기 옵션에서 자세히 설명합니다. 다음 표는 빠른 참조를 제공합니다.

속성 값 설명
PublishTrimmed true 또는 false 게시하는 동안 자르기를 사용하도록 설정할지 여부를 제어합니다.
TrimMode full 또는 partial 기본값은 full입니다. 자르기 세분성을 제어합니다.
SuppressTrimAnalysisWarnings true 또는 false 자르기 분석 경고가 생성되는지 여부를 제어합니다.
EnableTrimAnalyzer true 또는 false 자르기 분석 경고의 하위 집합이 생성되는지 여부를 제어합니다. PublishTrimmed가 false로 설정된 경우에도 분석을 사용하도록 설정할 수 있습니다.
ILLinkTreatWarningsAsErrors true 또는 false 자르기 경고를 오류로 처리할지 여부를 제어합니다. 예를 들어, TreatWarningsAsErrors가 true로 설정된 경우 이 속성을 false로 설정할 수 있습니다.
TrimmerSingleWarn true 또는 false 어셈블리당 단일 경고를 표시할지 아니면 모든 경고를 표시할지 제어합니다.
TrimmerRemoveSymbols true 또는 false 잘린 애플리케이션에서 모든 기호를 제거할지 여부를 제어합니다.

이 섹션에서 설명하는 MSBuild 속성은 다음과 같습니다.

LangVersion 및 Nullable과 같은 C# 컴파일러 옵션은 프로젝트 파일에서 MSBuild 속성으로 지정할 수도 있습니다. 자세한 내용은 C# 컴파일러 옵션을 참조하세요.

ContinuousIntegrationBuild

ContinuousIntegrationBuild 속성은 빌드가 CI(연속 통합) 서버에서 실행되고 있는지 여부를 나타냅니다. true로 설정하면 이 속성은 개발자 컴퓨터의 로컬 빌드가 아닌 공식 빌드에만 적용되는 설정을 사용하도록 설정합니다. 예를 들어, 저장된 파일 경로는 공식 빌드에 대해 정규화됩니다. 그러나 로컬 개발 컴퓨터에서는 파일 경로가 정규화되면 디버거가 로컬 원본 파일을 찾을 수 없습니다.

참고 항목

현재 이 속성을 true로 설정하는 것은 특정 SourceLink 공급자 패키지 참조 또는 <SourceRoot Include="$(MyDirectory)" /> 항목을 추가하는 경우에만 작동합니다. 자세한 내용은 dotnet/roslyn 문제 55860을 참조하세요.

CI 시스템의 변수를 사용하여 조건부로 ContinuousIntegrationBuild 속성을 설정할 수 있습니다. 예를 들어, Azure Pipelines의 변수 이름은 TF_BUILD입니다.

<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

GitHub Actions의 경우 변수 이름은 GITHUB_ACTIONS입니다.

<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

CopyDebugSymbolFilesFromPackages

이 속성이 true로 설정되면 프로젝트의 PackageReference 항목에 있는 모든 기호 파일(PDB 파일이라고도 함)이 빌드 출력에 복사됩니다. 이러한 파일은 예외에 대한 더 많은 정보를 제공하는 스택 추적을 제공하고 실행 중인 애플리케이션의 메모리 덤프 및 추적을 더 쉽게 이해할 수 있도록 해줍니다. 그러나 이러한 파일을 포함하면 배포 번들 크기가 늘어납니다.

이 속성은 .NET SDK 7.0.100에 도입되었지만 기본적으로 지정되지 않습니다.

CopyDocumentationFilesFromPackages

이 속성이 true로 설정되면 프로젝트의 PackageReference 항목에서 생성된 모든 XML 설명서 파일이 빌드 출력에 복사됩니다. 이 기능을 사용하도록 설정하면 배포 번들 크기가 증가합니다.

이 속성은 .NET SDK 7.0.100에 도입되었지만 기본적으로 지정되지 않습니다.

DisableImplicitFrameworkDefines

DisableImplicitFrameworkDefines 속성은 SDK가 .NET 프로젝트의 대상 프레임워크 및 플랫폼에 대한 전처리기 기호를 생성하는지 여부를 제어합니다. 이 속성이 false로 설정되거나 설정되지 않은 경우(기본값) 다음에 대한 전처리기 기호가 생성됩니다.

  • 버전이 없는 프레임워크(NETFRAMEWORK, NETSTANDARD, NET)
  • 버전이 있는 프레임워크(NET48, NETSTANDARD2_0, NET6_0)
  • 버전 최소 경계가 있는 프레임워크(NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

대상 프레임워크 모니커 및 이러한 암시적 전처리기 기호에 대한 자세한 내용은 대상 프레임워크를 참조하세요.

또한 프로젝트에서 운영 체제별 대상 프레임워크를 지정하는 경우(예: net6.0-android) 다음 전처리기 기호가 생성됩니다.

  • 버전이 없는 플랫폼(ANDROID, IOS, WINDOWS)
  • 버전이 있는 플랫폼(IOS15_1)
  • 버전 최소 경계가 있는 플랫폼(IOS15_1_OR_GREATER)

운영 체제별 대상 프레임워크 모니커에 대한 자세한 내용은 OS별 TFM을 참조하세요.

마지막으로, 대상 프레임워크가 이전 대상 프레임워크에 대한 지원을 암시하는 경우 해당 이전 프레임워크에 대한 전처리기 기호가 내보내집니다. 예를 들어, net6.0암시는 net5.0을 지원하며 이는 .netcoreapp1.0까지 돌아가 지원합니다. 따라서 이러한 각 대상 프레임워크에 대해 버전 최소 제한이 있는 프레임워크 기호가 정의됩니다.

DocumentationFile

DocumentationFile 속성을 사용하면 라이브러리에 대한 설명서가 포함된 XML 파일의 파일 이름을 지정할 수 있습니다. IntelliSense가 설명서에서 제대로 작동하려면 파일 이름이 어셈블리 이름과 동일해야 하며 어셈블리와 동일한 디렉터리에 있어야 합니다. 이 속성을 지정하지 않고 GenerateDocumentationFile을 true로 설정하면 설명서 파일의 이름은 기본적으로 어셈블리의 이름이 되지만 파일 확장명이 .xml로 지정됩니다. 따라서 이 속성을 생략하고 대신 GenerateDocumentationFile 속성을 사용하는 것이 더 쉬운 경우가 많습니다.

이 속성을 지정하고 GenerateDocumentationFile을 false로 설정하면 컴파일러가 설명서 파일을 생성하지 않습니다. 이 속성을 지정하고 GenerateDocumentationFile 속성을 생략하면 컴파일러는 설명서 파일을 생성합니다.

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>

EmbeddedResourceUseDependentUponConvention

EmbeddedResourceUseDependentUponConvention 속성은 리소스 파일과 공동 배치된 소스 파일의 형식 정보에서 리소스 매니페스트 파일 이름을 생성할지 여부를 정의합니다. 예를 들어 Form1.resx가 Form1.cs와 동일한 폴더에 있고 EmbeddedResourceUseDependentUponConvention가 true로 설정된 경우 생성된 .resources 파일은 Form1.cs에 정의된 첫 번째 형식에서 이름을 가져옵니다. MyNamespace.Form1이 Form1.cs에 정의된 첫 번째 형식인 경우 생성된 파일 이름은 MyNamespace.Form1.resources입니다.

참고 항목

LogicalName, ManifestResourceName 또는 DependentUpon 메타데이터가 EmbeddedResource 항목에 대해 지정된 경우 해당 리소스 파일에 대해 생성된 매니페스트 파일 이름은 이러한 메타데이터를 기반으로 합니다.

기본적으로 .NET Core 3.0 이상 버전을 대상으로 하는 새 .NET 프로젝트에서 이 속성은 true로 설정됩니다. 이 속성이 false로 설정되고 프로젝트 파일의 EmbeddedResource 항목에 대해 LogicalName, ManifestResourceName 또는 DependentUpon 메타데이터가 지정되지 않은 경우 리소스 매니페스트 파일 이름은 프로젝트의 루트 네임스페이스와 .resx 파일의 상대 파일 경로를 기반으로 합니다. 자세한 내용은 리소스 매니페스트 파일 이름이 지정되는 방식을 참조하세요.

<PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

EnablePreviewFeatures

EnablePreviewFeatures 속성은 프로젝트가 RequiresPreviewFeaturesAttribute 특성으로 데코레이트된 API 또는 어셈블리에 종속하는지 여부를 정의합니다. 이 특성은 API 또는 어셈블리가 사용 중인 SDK 버전의 미리 보기에 있는 것으로 간주되는 기능을 사용함을 나타내는 데 사용됩니다. 미리 보기 기능은 지원이 제공되지 않으며 이후 버전에서 제거될 수 있습니다. 미리 보기 기능을 사용하려면 이 속성을 True로 설정합니다.

<PropertyGroup>
  <EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>

프로젝트에 이 속성이 True로 설정된 경우 다음 어셈블리 수준 특성이 AssemblyInfo.cs 파일에 추가됩니다.

[assembly: RequiresPreviewFeatures]

EnablePreviewFeatures가 True로 설정되지 않은 프로젝트의 종속성에 이 특성이 있는 경우 분석기는 경고를 표시합니다.

미리 보기 어셈블리를 제공하려는 라이브러리 작성자는 이 속성을 True로 설정해야 합니다. 미리 보기 API와 비 미리 보기 API를 혼합하여 어셈블리를 제공해야 하는 경우 아래 GenerateRequiresPreviewFeaturesAttribute 섹션을 참조하세요.

EnableWindowsTargeting

Windows가 아닌 플랫폼에서 Windows 앱(예: Windows Forms 또는 Windows Presentation Foundation 앱)을 빌드하려면 EnableWindowsTargeting 속성을 true로 설정합니다. 이 속성을 true로 설정하지 않으면 빌드 경고 NETSDK1100이 표시됩니다. 이 오류는 지원되지 않는 플랫폼에서 대상 지정 및 런타임 팩이 자동으로 다운로드되지 않기 때문에 발생합니다. 이 속성을 설정하면 교차 대상 지정 시 해당 팩이 다운로드됩니다.

참고 항목

이 속성은 현재 Windows가 아닌 플랫폼에서 개발을 허용하는 데 권장됩니다. 그러나 애플리케이션을 릴리스할 준비가 되면 Windows에서 빌드해야 합니다. Windows가 아닌 플랫폼에서 빌드할 때 출력은 Windows에서 빌드할 때와 동일하지 않을 수 있습니다. 특히 시작 파일은 Windows 애플리케이션으로 표시되지 않으며(즉, 항상 콘솔 창을 시작함을 의미) 아이콘이 포함되지 않습니다.

<PropertyGroup>
  <EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

GenerateDocumentationFile

GenerateDocumentationFile 속성은 컴파일러가 라이브러리에 대한 XML 문서 파일을 생성하는지 여부를 제어합니다. 이 속성을 true로 설정하고 DocumentationFile 속성을 통해 파일 이름을 지정하지 않으면 생성된 XML 파일은 어셈블리와 동일한 출력 디렉터리에 배치되고 동일한 파일 이름이 지정되지만 확장명은 .xml입니다.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

코드 주석에서 설명서를 생성하는 자세한 내용은 XML 문서 주석(C#), XML로 코드 문서화(Visual Basic) 또는 XML로 코드 문서화(F#)를 참조하세요.

GenerateRequiresPreviewFeaturesAttribute

GenerateRequiresPreviewFeaturesAttribute 속성은 EnablePreviewFeatures 속성과 밀접하게 관련되어 있습니다. 라이브러리가 미리 보기 기능을 사용하지만 전체 어셈블리를 RequiresPreviewFeaturesAttribute 특성(모든 소비자가 미리 보기 기능 사용을 설정하도록 요구)으로 표시하지 않으려는 경우 이 속성을 False로 설정합니다.

<PropertyGroup>
    <EnablePreviewFeatures>True</EnablePreviewFeatures>
    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>

Important

GenerateRequiresPreviewFeaturesAttribute 속성을 False로 설정하는 경우 미리 보기 기능을 사용하는 모든 공용 API를 RequiresPreviewFeaturesAttribute로 데코레이트해야 합니다.

OptimizeImplicitlyTriggeredBuild

빌드 시간을 단축하기 위해 null 허용 분석을 포함하여 Visual Studio에 의해 암시적으로 트리거된 빌드가 코드 분석을 건너뜁니다. 예를 들어 테스트를 실행할 때 Visual Studio가 암시적 빌드를 트리거합니다. 그러나 암시적 빌드는 TreatWarningsAsErrors가 true로 설정되지 않은 경우에만 최적화됩니다. TreatWarningsAsErrors를 true로 설정했지만 암시적으로 트리거된 빌드를 최적화하려면 OptimizeImplicitlyTriggeredBuild를 True로 설정할 수 있습니다. 암시적으로 트리거된 빌드에 대한 빌드 최적화를 해제하려면 OptimizeImplicitlyTriggeredBuild를 False로 설정합니다.

<PropertyGroup>
    <OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>

DisableRuntimeMarshalling

DisableRuntimeMarshalling 속성을 사용하면 프로젝트에 대한 런타임 마샬링 지원을 사용하지 않도록 설정하도록 지정할 수 있습니다. 이 속성이 true로 설정된 경우 DisableRuntimeMarshallingAttribute가 어셈블리에 추가되고 모든 P/Invoke 또는 대리자 기반 상호 운용성은 사용 중지된 런타임 마샬링 규칙을 따릅니다.

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</PropertyGroup>

기본 항목 포함 속성

이 섹션에서 설명하는 MSBuild 속성은 다음과 같습니다.

자세한 내용은 기본 포함 및 제외를 참조하세요.

DefaultItemExcludes

DefaultItemExcludes 속성을 사용하면 GLOB 포함, 제외 및 제거에서 제외할 파일과 폴더의 GLOB 패턴을 정의할 수 있습니다. 기본적으로 ./bin 및 ./obj 폴더는 GLOB 패턴에서 제외됩니다.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>

DefaultItemExcludesInProjectFolder

DefaultItemExcludesInProjectFolder 속성을 사용하면 GLOB 포함, 제외, 제거에서 제외할 프로젝트 폴더에 있는 파일과 폴더의 GLOB 패턴을 정의할 수 있습니다. 기본적으로 .git, .vs 등과 같이 마침표(.)로 시작하는 폴더는 GLOB 패턴에서 제외됩니다.

이 속성은 DefaultItemExcludes 속성과 매우 유사하지만 프로젝트 폴더의 파일과 폴더만 고려한다는 점만 다릅니다. 의도치 않게 GLOB 패턴이 상대 경로를 사용하는 프로젝트 폴더 외부의 항목과 일치되는 경우에는 DefaultItemExcludes 속성 대신 DefaultItemExcludesInProjectFolder 속성을 사용합니다.

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</PropertyGroup>

EnableDefaultItems

EnableDefaultItems 속성은 컴파일 항목, 포함 리소스 항목, None 항목을 프로젝트에 암시적으로 포함할지 여부를 제어합니다. 기본값은 true입니다. 모든 암시적 파일 포함을 사용하지 않으려면 EnableDefaultItems 속성을 false로 설정합니다.

<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>

EnableDefaultCompileItems

EnableDefaultCompileItems 속성은 컴파일 항목을 프로젝트에 암시적으로 포함할지 여부를 제어합니다. 기본값은 true입니다. *.cs 및 기타 언어 확장 파일의 암시적 포함을 사용하지 않으려면 EnableDefaultCompileItems 속성을 false로 설정합니다.

<PropertyGroup>
  <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>

EnableDefaultEmbeddedResourceItems

EnableDefaultEmbeddedResourceItems 속성은 포함 리소스 항목을 프로젝트에 암시적으로 포함할지 여부를 제어합니다. 기본값은 true입니다. 포함 리소스 파일의 암시적 포함을 사용하지 않으려면 EnableDefaultEmbeddedResourceItems 속성을 false로 설정합니다.

<PropertyGroup>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>

EnableDefaultNoneItems

EnableDefaultNoneItems 속성은 None 항목(빌드 프로세스에서 아무 역할이 없는 파일)을 프로젝트에 암시적으로 포함할지 여부를 제어합니다. 기본값은 true입니다. None 항목의 암시적 포함을 사용하지 않으려면 EnableDefaultNoneItems 속성을 false로 설정합니다.

<PropertyGroup>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>

코드 분석 속성

이 섹션에서 설명하는 MSBuild 속성은 다음과 같습니다.

AnalysisLevel

AnalysisLevel 속성을 사용하면 .NET 릴리스에 따라 실행되는 코드 분석기 집합을 지정할 수 있습니다. .NET 5부터 각 .NET 릴리스에는 코드 분석 규칙 집합이 포함됩니다. 이 집합에서는 릴리스에 대해 기본적으로 사용하도록 설정되는 규칙이 코드를 분석합니다. 예를 들어 .NET 8으로 업그레이드하되 기본 코드 분석 규칙 집합을 변경하고 싶지 않다면 AnalysisLevel을 7로 설정합니다.

<PropertyGroup>
  <AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>

.NET 6부터는 이 속성에 대한 복합 값을 지정하여 규칙 활성화의 적극성 수준을 지정할 수 있습니다. 복합 값은 <version>-<mode> 형식을 사용합니다. 여기서 <mode> 값은 AnalysisMode 값 중 하나입니다. 다음 예제에서는 코드 분석기의 미리 보기 버전을 사용하고 권장되는 규칙 집합을 사용하도록 설정합니다.

<PropertyGroup>
  <AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>

기본값:

  • 프로젝트가 .NET 5 이상을 대상으로 하거나 AnalysisMode 속성을 추가한 경우 기본값은 latest입니다.
  • 그렇지 않으면 프로젝트 파일에 명시적으로 추가하지 않는 한 이 속성이 생략됩니다.

다음 표에서는 지정할 수 있는 값을 확인할 수 있습니다.

값 의미
latest 릴리스된 최신 코드 분석기가 사용됩니다. 기본값입니다.
latest-<mode> 릴리스된 최신 코드 분석기가 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
preview 최신 코드 분석기는 미리 보기로 제공되는 경우에도 사용됩니다.
preview-<mode> 최신 코드 분석기는 미리 보기로 제공되는 경우에도 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
8.0 최신 규칙을 사용할 수 있는 경우에도 .NET 8 릴리스에서 사용되었던 규칙 집합이 사용됩니다.
8.0-<mode> 최신 규칙을 사용할 수 있는 경우에도 .NET 8 릴리스에서 사용되었던 규칙 집합이 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
8 최신 규칙을 사용할 수 있는 경우에도 .NET 8 릴리스에서 사용되었던 규칙 집합이 사용됩니다.
8-<mode> 최신 규칙을 사용할 수 있는 경우에도 .NET 8 릴리스에서 사용되었던 규칙 집합이 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
7.0 최신 규칙을 사용할 수 있는 경우에도 .NET 7 릴리스에서 사용되었던 규칙 집합이 사용됩니다.
7.0-<mode> 최신 규칙을 사용할 수 있는 경우에도 .NET 7 릴리스에서 사용되었던 규칙 집합이 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
7 최신 규칙을 사용할 수 있는 경우에도 .NET 7 릴리스에서 사용되었던 규칙 집합이 사용됩니다.
7-<mode> 최신 규칙을 사용할 수 있는 경우에도 .NET 7 릴리스에서 사용되었던 규칙 집합이 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
6.0 최신 규칙을 사용할 수 있는 경우에도 .NET 6 릴리스에서 사용되었던 규칙 집합이 사용됩니다.
6.0-<mode> 최신 규칙을 사용할 수 있는 경우에도 .NET 6 릴리스에서 사용되었던 규칙 집합이 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
6 최신 규칙을 사용할 수 있는 경우에도 .NET 6 릴리스에서 사용되었던 규칙 집합이 사용됩니다.
6-<mode> 최신 규칙을 사용할 수 있는 경우에도 .NET 6 릴리스에서 사용되었던 규칙 집합이 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
5.0 최신 규칙을 사용할 수 있는 경우에도 .NET 5 릴리스에서 사용되었던 규칙 집합이 사용됩니다.
5.0-<mode> 최신 규칙을 사용할 수 있는 경우에도 .NET 5 릴리스에서 사용되었던 규칙 집합이 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.
5 최신 규칙을 사용할 수 있는 경우에도 .NET 5 릴리스에서 사용되었던 규칙 집합이 사용됩니다.
5-<mode> 최신 규칙을 사용할 수 있는 경우에도 .NET 5 릴리스에서 사용되었던 규칙 집합이 사용됩니다. <mode> 값은 사용하도록 설정되는 규칙을 결정합니다.

참고 항목

  • .NET 6부터 EnforceCodeStyleInBuild를 true로 설정하면 이 속성은 코드 품질 규칙 외에도 코드 스타일(IDEXXXX) 규칙에 영향을 미칩니다.
  • AnalysisLevel의 복합 값을 설정했다면 AnalysisMode는 지정하지 않아도 됩니다. 하지만 지정한다면 AnalysisLevel이 AnalysisMode보다 우선적으로 적용됩니다.
  • 이 속성은 프로젝트 SDK를 참조하지 않는 프로젝트의 코드 분석에 영향을 주지 않습니다(예: Microsoft.CodeAnalysis.NetAnalyzers NuGet 패키지를 참조하는 레거시 .NET Framework 프로젝트).

AnalysisLevel<Category>

이 속성은 특정 코드 분석 규칙 범주에만 적용된다는 점을 제외하면 AnalyticLevel과 동일합니다. 이 속성을 사용하면 특정 범주에 다른 버전의 코드 분석기를 사용하거나, 다른 수준의 규칙을 다른 규칙 범주에 사용하거나 사용하지 않도록 설정할 수 있습니다. 특정 규칙 범주에 이 속성을 누락하면 기본적으로 AnalysisLevel 값이 됩니다. 사용 가능한 값은 AnalysisLevel의 값과 동일합니다.

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>

<PropertyGroup>
  <AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>

다음 표에서는 각 규칙 범주의 속성 이름을 나열합니다.

Property name 규칙 범주
<AnalysisLevelDesign> 디자인 규칙
<AnalysisLevelDocumentation> 설명서 규칙
<AnalysisLevelGlobalization> 세계화 규칙
<AnalysisLevelInteroperability> 이식성 및 상호 운용성 규칙
<AnalysisLevelMaintainability> 유지 관리 규칙
<AnalysisLevelNaming> 명명 규칙
<AnalysisLevelPerformance> 성능 규칙
<AnalysisLevelSingleFile> 단일 파일 애플리케이션 규칙
<AnalysisLevelReliability> 안정성 규칙
<AnalysisLevelSecurity> 보안 규칙
<AnalysisLevelStyle> 코드 스타일(IDEXXXX) 규칙
<AnalysisLevelUsage> 사용 규칙

AnalysisMode

.NET SDK는 모든 "CA" 코드 품질 규칙과 함께 제공됩니다. 기본적으로 각 .NET 릴리스에서 일부 규칙만 빌드 경고로 사용하도록 설정됩니다. AnalysisMode 속성을 사용하면 기본적으로 사용하도록 설정되는 규칙 집합을 사용자 지정할 수 있습니다. 규칙을 개별적으로 옵트아웃할 수 있는 보다 적극적인 분석 모드로 전환하거나 특정 규칙을 옵트인할 수 있는 보다 보수적인 분석 모드로 전환할 수 있습니다. 예를 들어 모든 규칙을 빌드 경고로 사용하도록 설정하려는 경우 값을 All로 설정합니다.

<PropertyGroup>
  <AnalysisMode>All</AnalysisMode>
</PropertyGroup>

다음 표에는 사용 가능한 옵션 값이 나와 있습니다. 옵션은 활성화한 규칙 수가 많은 순서대로 나열됩니다.

값 설명
None 모든 규칙이 사용하지 않도록 설정됩니다. 개별 규칙을 선택적으로 옵트인하여 사용하도록 설정할 수 있습니다.
Default 특정 규칙이 빌드 경고로 사용되고, 다른 특정 규칙이 Visual Studio IDE 추천으로 사용되며, 나머지는 사용하지 않도록 설정되는 기본 모드입니다.
Minimum Default 모드보다 더 공격적인 모드입니다. 빌드 적용에 강력하게 권장되는 특정 제안은 빌드 경고로 사용하도록 설정됩니다. 여기에 포함된 규칙을 확인하려면 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig 파일을 검사합니다.
Recommended Minimum 모드보다 더 적극적인 모드로, 더 많은 규칙이 빌드 경고로 사용하도록 설정됩니다. 여기에 포함된 규칙을 확인하려면 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig 파일을 검사합니다.
All 모든 규칙이 빌드 경고로 사용하도록 설정됩니다*. 개별 규칙을 선택적으로 옵트아웃하여 사용하지 않도록 설정할 수 있습니다.

* 다음 규칙은 AnalysisMode를 All로 설정하거나 AnalysisLevel을 latest-all로 설정하면 사용하도록 설정되지 않습니다: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 및 코드 메트릭 분석기 규칙(CA1501, CA1502, CA1505, CA1506 및 CA1509). 이러한 레거시 규칙은 향후 버전에서 더 이상 사용되지 않을 수 있습니다. 그러나 dotnet_diagnostic.CAxxxx.severity = <severity> 항목을 사용하여 개별적으로 사용하도록 설정할 수 있습니다.

참고 항목

  • .NET 6부터 EnforceCodeStyleInBuild를 true로 설정하면 이 속성은 코드 품질 규칙 외에도 코드 스타일(IDEXXXX) 규칙에 영향을 미칩니다.
  • AnalysisLevel에 복합 값(예: <AnalysisLevel>8-recommended</AnalysisLevel>)을 사용하는 경우에는 이 속성을 완전히 생략해도 됩니다. 하지만 두 속성을 모두 지정하면 AnalysisLevel이 AnalysisMode보다 우선적으로 적용됩니다.
  • 이 속성은 프로젝트 SDK를 참조하지 않는 프로젝트의 코드 분석에 영향을 주지 않습니다(예: Microsoft.CodeAnalysis.NetAnalyzers NuGet 패키지를 참조하는 레거시 .NET Framework 프로젝트).

AnalysisMode<Category>

이 속성은 특정 코드 분석 규칙 범주에만 적용된다는 점을 제외하면 AnalyticMode와 동일합니다. 이 속성을 사용하면 다른 수준의 규칙을 다른 규칙 범주에 사용하거나 사용하지 않도록 설정할 수 있습니다. 특정 규칙 범주에 이 속성을 누락하면 기본적으로 AnalysisMode 값이 됩니다. 사용 가능한 값은 AnalysisMode의 값과 동일합니다.

<PropertyGroup>
  <AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>

다음 표에서는 각 규칙 범주의 속성 이름을 나열합니다.

Property name 규칙 범주
<AnalysisModeDesign> 디자인 규칙
<AnalysisModeDocumentation> 설명서 규칙
<AnalysisModeGlobalization> 세계화 규칙
<AnalysisModeInteroperability> 이식성 및 상호 운용성 규칙
<AnalysisModeMaintainability> 유지 관리 규칙
<AnalysisModeNaming> 명명 규칙
<AnalysisModePerformance> 성능 규칙
<AnalysisModeSingleFile> 단일 파일 애플리케이션 규칙
<AnalysisModeReliability> 안정성 규칙
<AnalysisModeSecurity> 보안 규칙
<AnalysisModeStyle> 코드 스타일(IDEXXXX) 규칙
<AnalysisModeUsage> 사용 규칙

CodeAnalysisTreatWarningsAsErrors

CodeAnalysisTreatWarningsAsErrors 속성을 사용하면 코드 품질 분석 경고(CAxxxx)를 경고로 처리할지 여부를 구성하고 빌드를 중단할 수 있습니다. 프로젝트를 빌드할 때 -warnaserror 플래그를 사용하면 .NET 코드 품질 분석 경고도 오류로 처리됩니다. 코드 품질 분석 경고를 오류로 처리하지 않으려는 경우 프로젝트 파일에서 CodeAnalysisTreatWarningsAsErrors MSBuild 속성을 false로 설정할 수 있습니다.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

EnableNETAnalyzers

.NET 5 이상 버전을 대상으로 하는 프로젝트의 경우 기본적으로 .NET 코드 품질 분석이 사용됩니다. .NET 5 이상 SDK를 사용하여 개발하는 경우 EnableNETAnalyzers 속성을 true로 설정하여 이전 버전의 .NET을 대상으로 하는 SDK 스타일 프로젝트에서 .NET 코드 분석을 사용할 수 있습니다. 모든 프로젝트에서 코드 분석을 사용하지 않으려면 해당 속성을 false로 설정합니다.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

참고 항목

이 속성은 특히 .NET 5+ SDK의 기본 제공 분석기에 적용됩니다. NuGet 코드 분석 패키지를 설치할 때 사용해서는 안 됩니다.

EnforceCodeStyleInBuild

.NET 코드 스타일 분석은 모든 .NET 프로젝트에 대해 빌드 시 기본적으로 사용하지 않도록 설정됩니다. EnforceCodeStyleInBuild 속성을 true로 설정하여 .NET 프로젝트에 대해 코드 스타일 분석을 사용하도록 설정할 수 있습니다.

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

경고 또는 오류로 구성된 모든 코드 스타일 규칙은 빌드 및 보고 위반 시 실행됩니다.

_SkipUpgradeNetAnalyzersNuGetWarning

_SkipUpgradeNetAnalyzersNuGetWarning 속성을 사용하면 최신 .NET SDK의 코드 분석기와 비교할 때 오래된 NuGet 패키지의 코드 분석기를 사용하는 경우 경고를 가져올지 여부를 구성할 수 있습니다. 경고는 다음과 유사합니다.

.NET SDK에는 'Microsoft.CodeAnalytic.NetAnalyzers' 패키지의 '5.0.3' 버전보다 '6.0.0' 버전의 최신 분석기가 있습니다. 이 패키지 참조를 업데이트하거나 제거합니다.

이 경고를 제거하고 NuGet 패키지의 코드 분석기 버전을 계속 사용하려면 프로젝트 파일에서 _SkipUpgradeNetAnalyzersNuGetWarning을 true로 설정합니다.

<PropertyGroup>
  <_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>

런타임 구성 속성

앱의 프로젝트 파일에서 MSBuild 속성을 지정하여 몇 가지 런타임 동작을 구성할 수 있습니다. 런타임 동작을 구성하는 다른 방법에 관한 내용은 런타임 구성 설정을 참조하세요.

AutoreleasePoolSupport

AutoreleasePoolSupport 속성은 지원되는 macOS 플랫폼에서 실행할 때 각 관리형 스레드가 암시적 NSAutoreleasePool을 수신하는지 여부를 구성합니다. 자세한 내용은 AutoreleasePool관리 스레드를 참조하세요.

<PropertyGroup>
  <AutoreleasePoolSupport>true</AutoreleasePoolSupport>
</PropertyGroup>

ConcurrentGarbageCollection

ConcurrentGarbageCollection 속성은 백그라운드(동시) 가비지 수집이 사용하도록 설정되었는지 여부를 구성합니다. 백그라운드 가비지 수집을 사용하지 않으려면 값을 false로 설정합니다. 자세한 내용은 백그라운드 GC를 참조하세요.

<PropertyGroup>
  <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
</PropertyGroup>

InvariantGlobalization

InvariantGlobalization 속성은 앱이 문화권별 데이터에 액세스할 수 없는 ‘세계화 고정’ 모드에서 실행되는지 여부를 구성합니다. 세계화 고정 모드에서 실행하려면 값을 true로 설정합니다. 자세한 내용은 고정 모드를 참조하세요.

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

PredefinedCulturesOnly

.NET 6 이상 버전에서 PredefinedCulturesOnly 속성은 세계화 고정 모드가 사용되는 경우 앱이 고정 문화권 이외의 문화권을 만들 수 있는지를 구성합니다. 기본값은 true입니다. 세계화 고정 모드에서 모든 새 문화권 만들기를 허용하려면 값을 false로 설정합니다.

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

자세한 내용은 세계화 고정 모드의 문화권 만들기 및 대/소문자 매핑을 참조하세요.

RetainVMGarbageCollection

RetainVMGarbageCollection 속성은 삭제된 메모리 세그먼트를 나중에 사용하기 위해 대기 목록에 넣거나 릴리스하도록 가비지 수집기를 구성합니다. 값을 true로 설정하여 가비지 수집기가 대기 목록에 세그먼트를 넣도록 지시합니다. 자세한 내용은 VM 유지를 참조하세요.

<PropertyGroup>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
</PropertyGroup>

ServerGarbageCollection

ServerGarbageCollection 속성은 애플리케이션이 워크스테이션 가비지 수집 또는 서버 가비지 수집을 사용할지 여부를 구성합니다. 서버 가비지 수집을 사용하려면 값을 true로 설정합니다. 자세한 내용은 워크스테이션과 서버 비교를 참조하세요.

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ThreadPoolMaxThreads

ThreadPoolMaxThreads 속성은 작업자 스레드 풀의 최대 스레드 수를 구성합니다. 자세한 내용은 최대 스레드를 참조하세요.

<PropertyGroup>
  <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
</PropertyGroup>

ThreadPoolMinThreads

ThreadPoolMinThreads 속성은 작업자 스레드 풀의 최소 스레드 수를 구성합니다. 자세한 내용은 최소 스레드를 참조하세요.

<PropertyGroup>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
</PropertyGroup>

TieredCompilation

TieredCompilation 속성은 JIT(Just-In-Time) 컴파일러가 계층화된 컴파일을 사용하는지 여부를 구성합니다. 계층화된 컴파일을 사용하지 않으려면 값을 false로 설정합니다. 자세한 내용은 계층화된 컴파일을 참조하세요.

<PropertyGroup>
  <TieredCompilation>false</TieredCompilation>
</PropertyGroup>

TieredCompilationQuickJit

TieredCompilationQuickJit 속성은 JIT 컴파일러가 빠른 JIT를 사용하는지 여부를 구성합니다. 빠른 JIT를 사용하지 않으려면 값을 false로 설정합니다. 자세한 내용은 빠른 JIT를 참조하세요.

<PropertyGroup>
  <TieredCompilationQuickJit>false</TieredCompilationQuickJit>
</PropertyGroup>

TieredCompilationQuickJitForLoops

TieredCompilationQuickJitForLoops 속성은 JIT 컴파일러가 루프를 포함하는 메서드에서 빠른 JIT를 사용할지 여부를 구성합니다. 루프를 포함하는 메서드에서 빠른 JIT를 사용하려면 값을 true로 설정합니다. 자세한 내용은 루프에 대한 빠른 JIT를 참조하세요.

<PropertyGroup>
  <TieredCompilationQuickJitForLoops>true</TieredCompilationQuickJitForLoops>
</PropertyGroup>

TieredPGO

TieredPGO 속성은 동적 또는 계층형 PGO(프로필 기반 최적화)가 사용하도록 설정되는지 여부를 제어합니다. 계층화된 PGO를 사용하도록 설정하려면 값을 true로 설정합니다. 자세한 내용은 프로필 기반 최적화를 참조하세요.

<PropertyGroup>
  <TieredPGO>true</TieredPGO>
</PropertyGroup>

UseWindowsThreadPool

UseWindowsThreadPool 속성은 스레드 풀 스레드 관리가 Windows 스레드 풀에 위임되는지 여부를 구성합니다(Windows에만 해당). 기본값은 false이며, 이 경우 .NET 스레드 풀이 사용됩니다. 자세한 내용은 Windows 스레드 풀을 참조하세요.

<PropertyGroup>
  <UseWindowsThreadPool>true</UseWindowsThreadPool>
</PropertyGroup>

이 섹션에서 설명하는 MSBuild 속성은 다음과 같습니다.

AssetTargetFallback

AssetTargetFallback 속성을 사용하여 프로젝트 참조 및 NuGet 패키지에 대해 호환되는 추가 프레임워크 버전을 지정할 수 있습니다. 예를 들어 PackageReference를 사용하여 패키지 종속성을 지정하지만 해당 패키지에 프로젝트의 TargetFramework와 호환되는 자산이 포함되지 않은 경우 AssetTargetFallback 속성이 작동합니다. 참조된 패키지의 호환성은 AssetTargetFallback에 지정된 각 대상 프레임워크를 사용하여 다시 확인됩니다. 해당 속성은 사용되지 않는 속성 PackageTargetFallback을 대체합니다.

AssetTargetFallback 속성을 하나 이상의 대상 프레임워크 버전으로 설정할 수 있습니다.

<PropertyGroup>
  <AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>

DisableImplicitFrameworkReferences

DisableImplicitFrameworkReferences 속성은 .NET Core 3.0 이상 버전을 대상으로 하는 경우 암시적 FrameworkReference 항목을 제어합니다. .NET Core 2.1 또는 .NET Standard 2.0 이전 버전을 대상으로 하는 경우에는 메타패키지의 패키지에 대한 암시적 PackageReference 항목을 제어합니다. (메타패키지는 다른 패키지에 대한 종속성으로만 구성된 프레임워크 기반 패키지입니다.) 이 속성은 .NET Framework를 대상으로 지정할 때 System 및 System.Core와 같은 암시적 참조도 제어합니다.

암시적 FrameworkReference 또는 PackageReference 항목을 사용하지 않도록 설정하려면 이 속성을 true로 설정합니다. 이 속성을 true로 설정하면 필요한 프레임워크나 패키지에만 명시적 참조를 추가할 수 있습니다.

<PropertyGroup>
  <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>

DisableTransitiveFrameworkReferenceDownloads

프로젝트에서 직접 참조하지 않는 추가 런타임 및 대상 팩을 다운로드하지 않으려면 DisableTransitiveFrameworkReferenceDownloads 속성을 true로 설정합니다.

<PropertyGroup>
  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>

DisableTransitiveProjectReferences

DisableTransitiveProjectReferences 속성은 암시적 프로젝트 참조를 제어합니다. 암시적 ProjectReference 항목을 사용하지 않도록 설정하려면 이 속성을 true로 설정합니다. 암시적 프로젝트 참조를 사용하지 않도록 설정하면 레거시 프로젝트 시스템과 유사한 비전이적 동작이 발생합니다.

이 속성이 true이면 종속 프로젝트의 모든 종속성에 대해 PrivateAssets="All"을 설정하는 것과 비슷한 효과가 있습니다.

이 속성을 true로 설정하면 필요한 프로젝트에만 명시적 참조를 추가할 수 있습니다.

<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

ManagePackageVersionsCentrally

ManagePackageVersionsCentrally 속성은 .NET 7에서 도입되었습니다. 리포지토리 루트에 있는 Directory.Packages.props 파일에서 이를 true로 설정하면 한 위치에서 프로젝트의 공통 종속성을 관리할 수 있습니다. Directory.Packages.props 파일의 PackageVersion 항목을 사용하여 공통 패키지 종속성에 대한 버전을 추가합니다. 그런 다음 개별 프로젝트 파일에서 중앙 관리 패키지를 참조하는 모든 PackageReference 항목에서 Version 특성을 생략할 수 있습니다.

예 Directory.Packages.props 파일:

<PropertyGroup>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
  <PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>

개별 프로젝트 파일:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>

자세한 내용은 CPM(중앙 패키지 관리)를 참조하세요.

참조된 패키지를 복원하면 패키지의 직접 종속성과 해당 종속성의 종속성이 모두 설치됩니다. RestorePackagesPath 및 RestoreIgnoreFailedSources와 같은 속성을 지정하여 패키지 복원을 사용자 지정할 수 있습니다. 이러한 속성 및 다른 속성에 대한 자세한 내용은 복원 대상을 참조하세요.

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

UseMauiEssentials

MAUI Essentials에 의존하는 프로젝트 또는 패키지에 대한 명시적 참조를 선언하려면 UseMauiEssentials 속성을 true로 설정합니다. 이 설정을 사용하면 프로젝트가 MAUI Essentials에 대해 올바르게 알려진 프레임워크 참조를 가져오도록 할 수 있습니다. 프로젝트가 MAUI Essentials를 사용하는 프로젝트를 참조하지만 이 속성을 true로 설정하지 않은 경우 빌드 경고 NETSDK1186이 발생할 수 있습니다.

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

ValidateExecutableReferencesMatchSelfContained

ValidateExecutableReferencesMatchSelfContained 속성을 사용하면 실행 가능한 프로젝트 참조와 관련된 오류를 사용하지 않도록 설정할 수 있습니다. .NET에서 자체 포함 실행 프로젝트가 프레임워크 종속 실행 파일을 참조하거나 그 반대로 참조하는 것을 감지하면 각각 NETSDK1150 및 NETSDK1151 오류가 생성됩니다. 참조가 의도적인 경우 이러한 오류를 방지하려면 ValidateExecutableReferencesMatchSelfContained 속성을 false로 설정합니다.

<PropertyGroup>
  <ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>

WindowsSdkPackageVersion

WindowsSdkPackageVersion 속성을 사용하여 Windows SDK 대상 패키지 버전을 재정의할 수 있습니다. 이 속성은 .NET 5에서 도입되었으며 이 목적을 위해 FrameworkReference 항목의 사용을 대체합니다.

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

참고 항목

Windows SDK 대상 패키지가 .NET 5+ SDK에 포함되어 있으므로 Windows SDK 버전을 재정의하지 않는 것이 좋습니다. 그 대신 최신 Windows SDK 패키지를 참조하려면 .NET SDK 버전을 업데이트하세요. 이 속성은 미리 보기 패키지를 사용하거나 C#/WinRT 버전을 재정의해야 하는 경우와 같이 드문 경우에만 사용해야 합니다.

다음 속성은 dotnet run 명령을 사용하여 앱을 시작하는 데 사용됩니다.

RunArguments

RunArguments 속성은 앱이 실행될 때 앱에 전달되는 인수를 정의합니다.

<PropertyGroup>
  <RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>

팁

dotnet run의 -- 옵션을 사용하면 앱에 전달할 추가 인수를 지정할 수 있습니다.

RunWorkingDirectory

RunWorkingDirectory 속성은 애플리케이션 프로세스를 시작할 작업 디렉터리를 정의합니다. 절대 경로이거나 프로젝트 디렉터리의 상대 경로일 수 있습니다. 디렉터리를 지정하지 않으면 OutDir이 작업 디렉터리로 사용됩니다.

<PropertyGroup>
  <RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>

이 섹션에서 설명하는 MSBuild 속성은 다음과 같습니다.

EnableComHosting

EnableComHosting 속성은 어셈블리가 COM 서버를 제공함을 나타냅니다. EnableComHosting을 true로 설정하면 EnableDynamicLoading도 true입니다.

<PropertyGroup>
  <EnableComHosting>True</EnableComHosting>
</PropertyGroup>

자세한 내용은 COM에 .NET 구성 요소 공개를 참조하세요.

EnableDynamicLoading

EnableDynamicLoading 속성은 어셈블리가 동적으로 로드된 구성 요소임을 나타냅니다. 구성 요소는 네이티브 호스트에서 사용할 수 있거나 플러그 인으로 사용할 수 있는 COM 라이브러리 또는 비 COM 라이브러리일 수 있습니다. 이 속성을 true로 설정하면 다음과 같은 효과가 있습니다.

  • .runtimeconfig.json 파일이 생성됩니다.
  • RollForward가 LatestMinor로 설정됩니다.
  • NuGet 참조가 로컬로 복사됩니다.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

생성된 파일 속성

다음 속성은 생성된 파일의 코드와 관련이 있습니다.

DisableImplicitNamespaceImports

DisableImplicitNamespaceImports 속성은 .NET 6 이상 버전을 대상으로 하는 Visual Basic 프로젝트에서 암시적 네임스페이스 가져오기를 사용하지 않도록 설정하는 데 사용할 수 있습니다. 암시적 네임스페이스는 Visual Basic 프로젝트에서 전역적으로 가져온 기본 네임스페이스입니다. 암시적 네임스페이스 가져오기를 사용하지 않도록 설정하려면 이 속성을 true로 설정합니다.

<PropertyGroup>
  <DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>

ImplicitUsings

ImplicitUsings 속성은 .NET 6 이상 버전과 C# 10 이상 버전을 대상으로 하는 C# 프로젝트에서 암시적 global using 지시문을 사용 및 사용하지 않도록 설정하는 데 사용할 수 있습니다. 이 기능을 사용하도록 설정하면 .NET SDK는 프로젝트 SDK의 형식을 기반으로 기본 네임스페이스 집합에 대한 global using 지시문을 추가합니다. 암시적 global using 지시문을 사용하려면 이 속성을 true 또는 enable로 설정합니다. 암시적 global using 지시문을 사용하지 않으려면 해당 속성을 제거하거나 false 또는 disable로 설정합니다.

<PropertyGroup>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

참고 항목

.NET 6 이상을 대상으로 하는 새 C# 프로젝트의 템플릿은 기본적으로 ImplicitUsings가 enable로 설정되어 있습니다.

명시적 global using 지시문을 정의하려면 Using 항목을 추가합니다.

아이템

MSBuild 항목은 빌드 시스템에 대한 입력입니다. 항목은 해당 형식(요소 이름)에 따라 지정됩니다. 예를 들어 Compile 및 Reference는 두 가지 일반 항목 형식입니다. 다음 추가 항목 형식은 .NET SDK에서 사용할 수 있습니다.

이러한 항목에는 표준 항목 특성(예: Include 및 Update)을 사용할 수 있습니다. Include를 사용하여 새 항목을 추가하고 Update를 사용하여 기존 항목을 수정합니다. 예를 들어 Update는 .NET SDK에서 암시적으로 추가된 항목을 수정하는 데 자주 사용됩니다.

AssemblyMetadata

AssemblyMetadata 항목은 키-값 쌍 AssemblyMetadataAttribute 어셈블리 특성을 지정합니다. Include 메타데이터는 키가 되고 Value 메타데이터는 값이 됩니다.

<ItemGroup>
  <AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>

InternalsVisibleTo

InternalsVisibleTo 항목은 지정된 friend 어셈블리에 대한 InternalsVisibleToAttribute 어셈블리 특성을 생성합니다.

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>

friend 어셈블리가 서명된 경우 선택적 Key 메타데이터를 지정하여 전체 공개 키를 지정할 수 있습니다. Key 메타데이터를 지정하지 않고 $(PublicKey)를 사용할 수 있는 경우 해당 키가 사용됩니다. 그렇지 않으면 특성에 공개 키가 추가되지 않습니다.

FrameworkReference

FrameworkReference 항목은 .NET 공유 프레임워크에 대한 참조를 정의합니다.

Include 특성은 프레임워크 ID를 지정합니다.

다음 예의 프로젝트 파일 코드 조각은 Microsoft.AspNetCore.App 공유 프레임워크를 참조하세요.

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

PackageReference

PackageReference 항목은 NuGet 패키지에 대한 참조를 정의합니다.

Include 특성은 패키지 ID를 지정합니다. Version 특성은 버전 또는 버전 범위를 지정합니다. 최소 버전, 최대 버전, 범위 또는 정확한 일치를 지정하는 방법에 대한 자세한 내용은 버전 범위를 참조하세요.

다음 예제의 프로젝트 파일 코드 조각은 System.Runtime 패키지를 참조합니다.

<ItemGroup>
  <PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>

PrivateAssets와 같은 메타데이터를 사용하여 종속성 자산을 제어할 수도 있습니다.

<ItemGroup>
  <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

자세한 내용은 프로젝트 파일의 패키지 참조를 참조하세요.

TrimmerRootAssembly

TrimmerRootAssembly 항목을 사용하면 ‘트리밍’에서 어셈블리를 제외할 수 있습니다. 트리밍은 패키지된 애플리케이션에서 런타임의 사용되지 않은 부분을 제거하는 프로세스입니다. 일부 경우에는 트리밍이 필요한 참조를 잘못 제거할 수 있습니다.

다음 XML은 트리밍에서 System.Security 어셈블리를 제외합니다.

<ItemGroup>
  <TrimmerRootAssembly Include="System.Security" />
</ItemGroup>

자세한 내용은 자르기 옵션을 참조하세요.

사용

Using 항목을 사용하면 C# 프로젝트에서 전역적으로 네임스페이스를 포함할 수 있으므로 소스 파일 맨 위에 네임스페이스에 대한 using 지시문을 추가할 필요가 없습니다. 이 항목은 Visual Basic 프로젝트에서 동일한 목적으로 사용할 수 있는 Import 항목과 유사합니다. 이 속성은 .NET 6부터 사용할 수 있습니다.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" />
</ItemGroup>

Using 항목을 사용하여 전역 using <alias> 및 using static <type> 지시문을 정의할 수도 있습니다.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>

예시:

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" />에서 global using Results = global::Microsoft.AspNetCore.Http.Results; 내보냄
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" />에서 global using static global::Microsoft.AspNetCore.Http.Results; 내보냄

자세한 내용은 별칭이 지정된 using 지시문 및 using static <type> 지시문을 참조하세요.

항목 메타데이터

표준 MSBuild 항목 특성 외에도 .NET SDK에서 다음 항목 메타데이터 태그를 사용할 수 있습니다.

CopyToPublishDirectory

MSBuild 항목의 CopyToPublishDirectory 메타데이터는 항목이 게시 디렉터리에 복사되는 시기를 제어합니다. 허용되는 값은 항목이 변경된 경우에만 항목을 복사하는 PreserveNewest, 항목을 항상 복사하는 Always, 항목을 복사하지 않는 Never입니다. 성능 관점에서 증분 빌드를 사용하기 때문에 PreserveNewest를 사용하는 것이 좋습니다.

<ItemGroup>
  <None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

LinkBase

프로젝트 디렉터리와 해당 하위 디렉터리의 외부에 있는 항목의 경우 게시 대상은 항목의 Link 메타데이터를 사용하여 항목을 복사할 위치를 결정합니다. Link는 프로젝트 트리 외부의 항목이 Visual Studio의 솔루션 탐색기 창에 표시되는 방식도 결정합니다.

프로젝트 범위 밖에 있는 항목에 대해 Link를 지정하지 않으면 기본적으로 %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension)으로 설정됩니다. LinkBase를 사용하여 프로젝트 범위 밖에 있는 항목의 적절한 기본 폴더를 지정할 수 있습니다. 기본 폴더 아래의 폴더 계층 구조는 RecursiveDir을 통해 유지됩니다. LinkBase를 지정하지 않으면 Link 경로에서 생략됩니다.

<ItemGroup>
  <Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>

다음 이미지는 이전 항목 Include GLOB를 통해 포함되는 파일이 솔루션 탐색기에 표시되는 방식을 보여 줍니다.

Solution Explorer showing item with LinkBase metadata.

참고 항목