새 .NET 버전으로 업그레이드

새 .NET 버전은 매년 릴리스됩니다. 많은 개발자가 새 버전을 사용할 수 있도록 즉시 업그레이드 프로세스를 시작하지만 다른 개발자는 사용 중인 버전이 더 이상 지원되지 않을 때까지 기다립니다. 업그레이드 프로세스에는 고려해야 할 여러 측면이 있습니다.

새 .NET 버전으로 업그레이드하는 일반적인 이유:

• 현재 사용되는 .NET 버전은 더 이상 지원되지 않습니다.
• 새 버전은 새 운영 체제를 지원합니다.
• 새 버전에는 중요한 API, 성능 또는 보안 기능이 있습니다.

개발 환경 업그레이드

새 .NET 버전으로 업그레이드하기 위해 .NET SDK는 설치할 기본 구성 요소입니다. 업데이트된 .NET CLI, 빌드 시스템 및 런타임 버전이 포함됩니다.

.NET 웹 사이트는 지원되는 운영 체제 및 아키텍처에서 다운로드하고 사용할 수 있는 설치 관리자 및 보관 파일을 제공합니다.

일부 운영 체제에는 새 .NET 버전을 설치하는 데 사용할 수 있는 패키지 관리자가 있습니다.

• 맥OS
• 리눅스
• Windows

Visual Studio는 새 .NET SDK 버전을 자동으로 설치합니다. Visual Studio 사용자의 경우 최신 Visual Studio 버전으로 업그레이드하는 것으로 충분합니다.

소스 코드 업그레이드

앱을 업그레이드하는 데 필요한 유일한 변경은 프로젝트 파일의 TargetFramework 속성을 최신 .NET 버전으로 업데이트하는 것입니다.

그 방법은 다음과 같습니다.

• 프로젝트 파일(*.csproj, *.vbproj 또는 *.fsproj 파일)을 엽니다.
• 예를 들어 <TargetFramework> 속성 값을 net6.0에서 net8.0(을)로 변경합니다.
• 사용 중인 경우 <TargetFrameworks> 속성에 동일한 패턴이 적용됩니다.

다음 단계는 새 SDK를 사용하여 프로젝트(또는 솔루션)를 빌드하는 것입니다. 추가 변경이 필요한 경우 SDK는 사용자를 안내하는 경고 및 오류를 제공합니다.

새 SDK 버전으로 워크로드를 복원하려면 dotnet workload restore(을)를 실행해야 할 수 있습니다.

추가 리소스:

• .NET 9의 호환성이 손상되는 변경
• ASP.NET Core 앱 마이그레이션
• .NET MAUI를 .NET 7에서 .NET 8로 업그레이드

버전 고정 설정

.NET SDK, Visual Studio 또는 기타 구성 요소와 같은 개발 도구를 업그레이드할 때 새 동작, 분석기 경고 또는 빌드 프로세스에 영향을 주는 호환성이 손상되는 변경이 발생할 수 있습니다. 버전에 고정하면 프로젝트에서 특정 구성 요소가 업데이트되는 시기를 제어하면서 개발 환경을 업그레이드할 수 있습니다.

버전 고정은 다음과 같은 몇 가지 이점을 제공합니다.

• 예측 가능한 빌드: 여러 컴퓨터 및 CI/CD 환경에서 일관된 빌드 결과를 보장합니다.
• 점진적 채택: 새로운 기능을 한 번에 채택하는 대신 증분 방식으로 채택할 수 있습니다.
• 예기치 않은 변경 방지: 새 분석기 규칙, SDK 동작 또는 패키지 버전에서 빌드 오류가 발생하지 않도록 방지합니다.
• 팀 조정: 도구를 업데이트할 때 팀이 개별적으로 업그레이드하지 않고 계획된 시간에 함께 업그레이드할 수 있습니다.
• 디버깅 및 문제 해결: 변경된 버전을 제어할 때 문제를 보다 쉽게 격리할 수 있습니다.

다음 섹션에서는 .NET 프로젝트에서 다양한 구성 요소의 버전을 제어하기 위한 다양한 메커니즘을 설명합니다.

• global.json사용하여 SDK 버전 제어
• 제어 분석기 동작
• NuGet 패키지 버전 제어
• MSBuild 버전 제어

global.json 사용하여 SDK 버전 제어

global.json 파일을 사용하여 프로젝트 또는 솔루션에 대한 .NET SDK 버전을 고정할 수 있습니다. 이 파일은 .NET CLI 명령을 실행할 때 사용할 SDK 버전을 지정하며 프로젝트가 대상으로 하는 런타임 버전과 독립적입니다.

솔루션 루트 디렉터리에 global.json 파일을 만듭니다.

dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature

이 명령은 9.0 주 버전 내에서 SDK를 버전 9.0.100 이상 패치 또는 기능 밴드에 고정하는 다음 global.json 파일을 만듭니다.

{
  "sdk": {
    "version": "9.0.100",
    "rollForward": "latestFeature"
  }
}

정책은 rollForward 정확한 버전을 사용할 수 없을 때 SDK 버전을 선택하는 방법을 제어합니다. 이 구성을 사용하면 Visual Studio를 업그레이드하거나 새 SDK를 설치할 때 global.json파일을 명시적으로 업데이트할 때까지 프로젝트에서 SDK 9.0.x를 계속 사용할 수 있습니다.

자세한 내용은 global.json 개요를 참조하세요.

제어 분석기 동작

코드 분석기는 새 경고를 도입하거나 버전 간에 동작을 변경할 수 있습니다. 속성을 사용하여 일관된 빌드를 유지하도록 분석기 버전을 제어할 AnalysisLevel수 있습니다. 이 속성을 사용하면 특정 버전의 분석기 규칙을 잠글 수 있으므로 SDK를 업그레이드할 때 새 규칙이 도입되지 않습니다.

<PropertyGroup>
  <AnalysisLevel>9.0</AnalysisLevel>
</PropertyGroup>

로 9.0설정하면 .NET 10 SDK를 사용하는 경우에도 .NET 9와 함께 제공되는 분석기 규칙만 사용하도록 설정됩니다. 이렇게 하면 문제를 해결할 준비가 될 때까지 새 .NET 10 분석기 규칙이 빌드에 영향을 주지 않습니다.

자세한 내용은 AnalysisLevel을 참조하세요.

NuGet 패키지 버전 제어

프로젝트 간에 패키지 버전을 일관되게 관리하면 예기치 않은 업데이트를 방지하고 신뢰할 수 있는 빌드를 유지할 수 있습니다.

• 패키지 잠금 파일
• 중앙 패키지 관리
• 패키지 원본 매핑

패키지 잠금 파일

패키지 잠금 파일은 패키지 복원 작업에서 서로 다른 환경에서 정확히 동일한 패키지 버전을 사용하도록 합니다. 잠금 파일(packages.lock.json)은 모든 패키지의 정확한 버전과 해당 종속성을 기록합니다.

프로젝트 파일에서 잠금 파일을 사용하도록 설정합니다.

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

잠금 파일이 만료된 경우 빌드가 실패하도록 하려면 다음을 수행합니다.

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  <RestoreLockedMode>true</RestoreLockedMode>
</PropertyGroup>

잠금 파일을 사용하도록 설정한 후 실행 dotnet restore 하여 packages.lock.json 파일을 생성합니다. 이 파일을 소스 제어에 커밋합니다.

중앙 패키지 관리

CPM(중앙 패키지 관리)을 사용하면 솔루션의 모든 프로젝트에 대해 단일 위치에서 패키지 버전을 관리할 수 있습니다. 이 방법은 버전 관리를 간소화하고 프로젝트 간에 일관성을 보장합니다.

솔루션 루트에 Directory.Packages.props 파일을 만듭니다.

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Azure.Identity" Version="1.17.0" />
    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.1" />
  </ItemGroup>
</Project>

프로젝트 파일에서 버전을 지정하지 않고 패키지를 참조합니다.

<ItemGroup>
  <PackageReference Include="Azure.Identity" />
  <PackageReference Include="Microsoft.Extensions.AI" />
</ItemGroup>

패키지 소스 매핑

패키지 원본 매핑을 사용하면 특정 패키지에 사용되는 NuGet 피드를 제어하여 보안 및 안정성을 향상시킬 수 있습니다.

nuget.config 파일에서 원본 매핑을 구성합니다.

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso" value="https://contoso.com/packages/" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso">
      <package pattern="Contoso.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

이 구성을 사용하면 Contoso.로 시작하는 모든 패키지는 contoso 피드에서만 복원되고, 다른 패키지는 nuget.org에서 복원됩니다.

자세한 내용은 NuGet 패키지 복원을 참조하세요.

MSBuild 버전 제어

Visual Studio는 여러 버전의 병렬 설치를 지원합니다. 예를 들어 동일한 컴퓨터에 Visual Studio 2026 및 Visual Studio 2022를 설치할 수 있습니다. 각 Visual Studio 버전에는 해당 .NET SDK가 포함됩니다. Visual Studio를 업데이트하면 포함된 SDK 버전도 업데이트됩니다. 그러나 .NET 다운로드 페이지에서 별도로 설치하여 이전 SDK 버전을 계속 사용할 수 있습니다.

MSBuild 버전은 Visual Studio 버전에 해당합니다. 예를 들어 Visual Studio 2022 버전 17.8에는 MSBuild 17.8이 포함됩니다. .NET SDK에는 MSBuild도 포함됩니다. dotnet build를 사용할 때, global.json에 지정된 SDK 또는 최신으로 설치된 SDK에 포함된 MSBuild 버전을 사용하게 됩니다.

특정 MSBuild 버전을 사용하려면 다음을 수행합니다.

• dotnet build고정된 SDK 버전과 함께 사용합니다.
• 해당 Visual Studio 버전의 MSBuild에 대한 환경을 설정하는 적절한 Visual Studio 개발자 명령 프롬프트를 시작합니다.
• 특정 Visual Studio 설치(예 "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe": )에서 MSBuild를 직접 호출합니다.

자세한 내용은 .NET SDK, MSBuild 및 Visual Studio 버전 관리를 참조하세요.

CI(지속적인 통합) 업데이트

CI 파이프라인은 프로젝트 파일 및 Dockerfiles와 유사한 업데이트 프로세스를 따릅니다. 일반적으로 버전 값만 변경하여 CI 파이프라인을 업데이트할 수 있습니다.

호스팅 환경 업데이트

애플리케이션 호스팅에 사용되는 많은 패턴이 있습니다. 호스팅 환경에 .NET 런타임이 포함된 경우 새 버전의 .NET 런타임을 설치해야 합니다. Linux에서는 종속성을 설치해야 하지만 일반적으로 .NET 버전 간에는 변경되지 않습니다.

컨테이너의 경우 새 버전 번호를 포함하도록 FROM문을 변경해야 합니다.

다음 Dockerfile 예제에서는 ASP.NET Core 9.0 이미지를 당기는 방법을 보여 줍니다.

FROM mcr.microsoft.com/dotnet/aspnet:9.0

Azure App Service와 같은 클라우드 서비스에서는 구성 변경이 필요합니다.

참고하십시오

• .NET 11의 주요 변경 내용
• .NET 10의 주요 변경 내용
• ASP.NET Core 앱 마이그레이션