Windows, macOS 또는 Linux에서 네이티브 플랫폼 간 .NET MAUI 앱 개발을 시작하려면 설치 단계에 따라 최신 Visual Studio Code를 설치합니다.
필수 조건
iOS용 .NET MAUI 앱을 빌드, 서명 및 배포하려면 다음이 필요합니다.
설치
.NET MAUI 앱을 만들려면 최신 Visual Studio Code를 설치해야 합니다.
Visual Studio Code의 확장 탭에서 ".NET MAUI"를 검색하고 .NET MAUI 확장을 설치합니다. .NET MAUI 확장은 .NET MAUI 확장을 실행하는 데 필요한 C# 개발 키트 및 C# 확장을 자동으로 설치합니다.
참고 항목
.NET MAUI 확장에는 C# 개발 키트 및 C# 확장이 필요합니다. .NET MAUI 확장 기능을 사용하려면 C# Dev Kit에 로그인해야 합니다. 자세한 내용은 이 블로그 게시물을 참조하여 C# Dev Kit 및 확장 제품군에 대해 자세히 알아보세요.
.NET 및 .NET MAUI 워크로드 설치
.NET 9를 설치 합니다.
Windows에서는 Visual Studio 설치 관리자를 사용하여 .NET 및 .NET MAUI 워크로드 설치를 관리하는 것이 좋습니다. Visual Studio 설치 관리자 사용에 대한 지침은 여기에서 찾을 수 있습니다.
Linux에서 스크립팅 된 설치 지침을 사용하여 설치합니다.
.NET MAUI 워크로드를 설치합니다.
Windows에서 Visual Studio 설치 관리자를 통해 설치되지 않는 한 터미널에서 다음 명령을 실행합니다.
dotnet workload install maui
macOS에서 터미널에서 다음 명령을 실행합니다.
sudo dotnet workload install maui
Linux에서 터미널에서 다음 명령을 실행합니다.
dotnet workload install maui-android
Visual Studio Code에서 .NET MAUI 앱을 디버그하려면 개발 머신의 운영 체제를 기준으로 유효한 대상 플랫폼이 있어야 합니다. 잘못된 대상 플랫폼을 포함하면 프로젝트가 빌드되지 않습니다. 앱의 프로젝트 파일(.csproj)에서 대상 플랫폼을 관리할 수 있습니다.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net9.0-android;net9.0-ios;net9.0-maccatalyst</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net9.0-windows10.0.19041.0</TargetFrameworks>
| 운영 체제 |
지원되는 대상 플랫폼 |
| Windows |
Windows, Android |
| macOS |
Android, iOS, macOS |
| Linux |
Android |
iOS 및 macOS
Visual Studio Code에서 iOS 또는 macOS 대상으로 디버그하려면 다음을 수행합니다.
- 사용 중인 .NET MAUI 버전에 필요한 Xcode 버전을 설치합니다. 자세한 내용은 릴리스 버전을 참조 하세요. 안정적인 최신 Xcode 릴리스는 Apple App Store에서 다운로드할 수 있습니다.
- 터미널에서 실행
xcode-select --install 하여 Xcode 명령줄 도구를 가져옵니다.
- Xcode를 열고 사용권 계약에 동의해야 합니다.
Android
Visual Studio Code에서 Android 대상으로 디버그하려면 다음을 수행합니다.
- Microsoft OpenJDK 17을 설치 합니다.
- 다음 방법 중 하나를 통해 Android SDK를 설치합니다.
- (권장) 새 .NET MAUI 프로젝트(
dotnet new maui)를 만들고 InstallAndroidDependencies 대상을 사용합니다.
- Visual Studio를 통해 설치합니다(Windows에만 해당).
- Android Studio를 통해 설치합니다.
- Linux에서 기본 패키지 관리자를 통해 설치합니다.
문제 해결
Visual Studio Code용 .NET MAUI 확장을 설정할 때 문제가 발생할 수 있습니다. 확장과 관련된 오류에 대한 세부 정보를 보려면 출력 창(Ctrl/CMD + Shift + u)으로 이동하고 드롭다운에서 .NET MAUI를 선택합니다. 문제를 해결하는 데 도움이 되는 아래 섹션을 참조하세요. 문제 해결 단계를 수행한 후에도 여전히 문제가 발생하는 경우 문제를 보고하세요.
프로젝트 만들기
새 프로젝트를 만들려고 하고 파일 탐색기가 무한 루프에서 계속 팝업되는 경우 빈 폴더를 선택하지 않을 수 있습니다. 숨겨진 파일이나 폴더가 없는지 확인하거나, 새 폴더를 만들거나, 명령줄 dotnet new maui에서 .NET MAUI 앱을 만듭니다.
InstallAndroidDependencies 대상 사용
.NET 9에는 Android 환경을 설정하는 데 도움이 되는 빌드 대상이 있습니다. 터미널에서 다음 명령을 실행하여 컴퓨터를 구성하고 Android 환경을 설정합니다.
dotnet build -t:InstallAndroidDependencies -f:net9.0-android -p:AndroidSdkDirectory="<AndroidSdkPath>" -p:JavaSdkDirectory="<JavaSdkPath>" -p:AcceptAndroidSDKLicenses=True
위의 명령에서 다음을 수행합니다.
AndroidSdkDirectory="<AndroidSdkPath>": Android 종속성을 지정된 절대 경로로 설치하거나 업데이트합니다.
- Windows: 제안된 AndroidSdkPath는
%LOCALAPPDATA%/Android/Sdk.
- macOS: 제안된 AndroidSdkPath는
$HOME/Library/Android/sdk.
JavaSdkDirectory="<JavaSdkPath>": 지정된 절대 경로에 Java를 설치합니다.AcceptAndroidSDKLicenses=True: 개발에 필요한 Android 라이선스를 허용합니다.
Android SDK 또는 Java SDK를 찾을 수 없다는 오류가 있습니다.
- 명령 팔레트(Ctrl/Cmd + Shift + P)를 열고 명령을 검색합니다
.NET MAUI: Configure Android . "Android SDK 경로 설정" 및 "Android JDK 경로 설정"을 모두 선택하고 각각 설치를 가리키는지 확인합니다.
- Android SDK 폴더에는 다음과 같은
build-toolscmdline-toolsplatform-tools하위 폴더가 있어야 합니다.
- Java OpenJDK 폴더에는 등과 같은
binlib하위 폴더가 있어야 합니다.
- Windows에서 Visual Studio를 통해 설치하는 경우 Java SDK가 있고
C:\Program Files\Microsoft\ Android SDK가 있습니다 C:\Program Files (x86)\Android\android-sdk.
- 환경 변수를
JAVA_HOME 유효한 Java OpenJDK 경로로 설정합니다.
- 환경 변수를
ANDROID_HOME Android SDK 경로로 설정합니다.
- 설치된 Android 종속성의 최소 버전을 확인합니다.
- build-tools >= 34.0.0
- cmdline-tools == 11.0
- 플랫폼; android-34*
- .NET 9: platform-tools = 34.0.5
Android 라이선스가 허용되지 않는 오류가 있습니다.
관리자 권한 명령 프롬프트 또는 터미널에서 Android SDK의 cmdline-tools/latest/bin/ 폴더로 이동한 다음 CLI sdkmanager --licenses 프롬프트를 따릅니다.
내 Android 종속성이 솔루션 탐색기 로드되지 않지만 앱이 잘 빌드됩니다.
이는 Windows에 설치하는 %APPDATA% 경우 알려진 문제이며 향후 릴리스에서 해결될 예정입니다.
iOS/Xcode 설치
- Xcode를 찾을 수 없다는 오류가 발생하면 터미널에서 실행
xcode-select --install 한 다음 Xcode 설치를 가리키는지 xcode-select -p 확인합니다.
- 여전히 문제가 발생하는 경우 Xcode 자체를 열어 올바르게 로드되는지 확인합니다. Xcode가 열리면 Xcode 설정 위치로 이동하여 명령줄 도구 필드가 올바른 Xcode를 가리키는지 확인합니다.> >
- iOS/macOS 앱을 배포하기 위해 두 번 빌드해야 하는 알려진 문제가 있습니다. 이 문제는 이후 릴리스에서 해결될 예정입니다.
이슈 디버깅
- 여러 가지 이유로 디버깅을 시작하지 못할 수 있습니다. 출력 창에 명확한 오류가 없는 경우 먼저 Visual Studio Code에서 C# 실행 구성을 사용하고 있는지 다시 확인합니다.
- 이전 버전의 .NET을 사용하는 경우 C# 디버거는 .NET MAUI 앱에 대해 지원되지 않습니다. 확장 설정 MAUI 구성 실험 > 적 VSDbg 사용을 선택 취소하여 레거시 .NET MAUI > 디버그 구성 > 을 사용할 수 있습니다.
- 터미널에서 명령줄 빌드를 시도하여 코드 또는 .NET MAUI 확장에 오류가 있는지 확인할 수 있습니다. 예를 들어 실행하여 Visual Studio Code 외부에서 Android 빌드가 성공하는지 확인할 수
dotnet build -f:net9.0-android 있습니다. 이 빌드가 성공하면 문제를 보고하세요 .
알려진 제한 사항
- 현재는 IntelliSense의 대상 프레임워크를 전환할 수 없습니다(.csproj 파일에 나열된 첫 번째 대상 프레임워크에 대해서만 구문 강조 표시됨). 이 기능은 진행 중입니다. 다른 대상(예: iOS 대신 Android)에 대한 구문 강조 표시를 얻으려면 프로젝트 파일에서 대상 프레임워크의 순서를 다시 지정할 수 있습니다.
- .NET 핫 다시 로드 현재 C# 개발 키트에서 미리 보기로 제공됩니다.
이 새로운 환경을 계속 빌드하면서 보고 싶은 다른 기능에 대한 피드백을 보내주세요!
피드백 제공
새 문제 또는 제안을 제출하기 전에 C# Dev Kit FAQ를 읽고 기존 알려진 문제를 확인하세요. 도움말 > 보고서 문제 대화 상자를 통해 Visual Studio Code 내에서 제안 및 문제를 제출할 수 있습니다. 드롭다운에서 "확장"을 선택한 다음 .NET MAUI 확장을 선택해야 합니다.
