알려진 문제 해결

  • 아티클

이 문서에서는 .NET 다중 플랫폼 앱 UI(.NET MAUI)의 알려진 문제 중 일부와 이를 해결하거나 해결하는 방법을 설명합니다. .NET MAUI 리포지토리에는 알려진 몇 가지 문제도 자세히 설명합니다.

.NET MAUI 워크로드를 찾을 수 없습니다.

.NET MAUI 워크로드를 설치하는 두 가지 옵션이 있습니다.

  1. Windows의 Visual Studio는 각 워크로드 팩에 .msi 파일을 설치할 수 있습니다.
  2. dotnet workload install 명령을.

Windows에서 Visual Studio 설치 관리자를 dotnet workload install 통해 .NET MAUI를 설치한 후 실행하는 경우 Visual Studio는 .NET MAUI 워크로드를 찾을 수 없는 상태를 입력할 수 있습니다. .NET MAUI 워크로드를 설치하라는 빌드 오류가 표시되고 워크로드를 복구하거나 다시 설치할 수 없는 상태를 입력할 수 있습니다. 자세한 내용은 GitHub 문제 dotnet/sdk#22388을 참조하세요.

Windows

Windows에서 이 문제에 대한 해결 방법은 CLI를 통해 .NET MAUI 워크로드를 제거하고, 제어판 .NET SDK를 제거하고, Visual Studio에서 .NET MAUI 워크로드를 제거하는 것입니다. 이러한 제거는 다음 프로세스로 수행할 수 있습니다.

  1. 명령을 사용한 dotnet workload install 적이 있는 경우 실행 dotnet workload uninstall maui 합니다.
  2. 제어판 독립 실행형 .NET SDK 설치 관리자를 제거합니다. 이러한 설치 관리자의 이름은 다음과 유사합니다 Microsoft .NET SDK 6.0.300.
  3. Visual Studio의 모든 인스턴스에서 .NET 다중 플랫폼 앱 UI 개발 및 .NET 데스크톱 개발 Visual Studio 워크로드를 제거합니다.

그런 다음, 다음 명령을 실행하여 제거해야 하는 추가 .msi 파일이 있는지 검사.

reg query HKLM\SOFTWARE\Microsoft\Windows\currentversion\uninstall\ -s -f manifest

이 reg query 명령은 다음과 같이 컴퓨터에 여전히 설치된 .NET 6+ SDK를 나열합니다.

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\currentversion\uninstall\{EEC1BB5F-3391-43C2-810E-42D78ADF3140}
    InstallSource    REG_SZ    C:\ProgramData\Microsoft\VisualStudio\Packages\Microsoft.MacCatalyst.Manifest-6.0.300,version=125.179.40883,chip=x64,productarch=neutral\
    DisplayName    REG_SZ    Microsoft.NET.Sdk.MacCatalyst.Manifest-6.0.300

비슷한 출력을 수신하는 경우 각 패키지에 대한 GUID를 복사하고 다음 명령을 사용하여 msiexec 패키지를 제거해야 합니다.

msiexec /x {EEC1BB5F-3391-43C2-810E-42D78ADF3140} /q IGNOREDEPENDENCIES=ALL

그런 다음 결과를 반환하지 않을 때까지 명령을 계속 실행 reg query 해야 합니다. 결과가 더 이상 없고 모든 .NET 6+ SDK가 제거되면 다음 폴더를 삭제하는 것도 고려해야 합니다.

  • C:\Program Files\dotnet\sdk-manifests
  • C:\Program Files\dotnet\metadata
  • C:\Program Files\dotnet\packs
  • C:\Program Files\dotnet\library-packs
  • C:\Program Files\dotnet\template-packs
  • C:\Program Files\dotnet\sdk\6.* 또는 C:\Program Files\dotnet\sdk\7.*
  • C:\Program Files\dotnet\host\fxr\6.* 또는 C:\Program Files\dotnet\host\fxr\7.*

이 프로세스를 수행한 후에는 Visual Studio를 통해 또는 선택한 .NET SDK 버전을 설치하고 명령을 실행하여 .NET MAUI를 dotnet workload install maui 다시 설치할 수 있습니다.

Mac

Mac용 Visual Studio 설치 관리자 및 업데이트 프로그램은 명령을 사용하여 dotnet workload install .NET MAUI .pkg 파일을 설치합니다.

.pkg 파일을 제거할 수 없으므로 Mac에서 워크로드를 제거하는 가장 간단한 방법은 다음 명령을 실행하여 지정된 폴더를 삭제하는 것입니다.

rm -r ~/.dotnet/
sudo rm -r /usr/local/share/dotnet/

이러한 명령을 실행한 후에는 Mac용 Visual Studio 통해 또는 선택한 .NET SDK 버전을 설치하고 명령을 실행 dotnet workload install maui 하여 .NET MAUI를 다시 설치할 수 있습니다.

플랫폼 버전이 없습니다.

프로젝트를 컴파일하려고 하고 다음 텍스트와 유사한 오류를 수신하는 경우 Visual Studio에서 필요한 워크로드를 해결하지 못할 수 있습니다.

플랫폼은 net8.0-android, net8.0-ios, net8.0-maccatalyst 플랫폼을 지정했음에도 불구하고 하나 이상의 대상 프레임워크에 대해 존재하지 않습니다.

이 문제는 일반적으로 x86 및 x64 SDK가 설치되어 있고 x86 버전이 사용되고 있기 때문에 발생합니다. Visual Studio 및 .NET MAUI에는 x64 .NET SDK가 필요합니다. 운영 체제에 x86 SDK를 먼저 확인하는 시스템 전체 PATH 변수가 있는 경우 변수에서 PATH x86 .NET SDK를 제거하거나 x64 .NET SDK를 승격하여 먼저 해결해야 합니다. x86 및 x64 SDK 해상도 문제 해결에 대한 자세한 내용은 Windows에 .NET 설치 - 문제 해결을 참조 하세요.

형식 또는 네임스페이스 'Default'가 없습니다.

API를 Contacts 사용하는 경우 iOS 및 macOS와 관련된 다음 오류가 표시 될 수 있습니다.

The type or namespace name 'Default' does not exist in the namespace 'Contacts' (are you missing an assembly reference?)

iOS 및 macOS 플랫폼에는 이름이 루트 Contacts네임스페이스가 포함되어 있습니다. 이 충돌은 형식을 포함하는 네임스페이스와 해당 플랫폼에 Microsoft.Maui.ApplicationModel.Communication 대한 충돌을 일으킵니다 Contacts . Microsoft.Maui.ApplicationModel.Communication 네임스페이스는 프로젝트 파일의 <ImplicitUsings> 설정에 의해 자동으로 가져옵니다.

iOS 및 macOS용으로 컴파일하는 코드를 작성하려면 형식을 정규화합니다 Contacts . 또는 코드 파일의 맨 위에 지시문을 제공하여 using 네임스페이스를 매핑합니다 Communication .

using Communication = Microsoft.Maui.ApplicationModel.Communication;

// Code that uses the namespace:
var contact = await Communication.Contacts.Default.PickContactAsync();

Xcode가 현재 설치되어 있지 않거나 찾을 수 없음

Xcode 명령줄 도구를 사용하여 xcode-select --install설치한 후 iOS 또는 Mac Catalyst를 대상으로 하는 .NET MAUI 앱을 빌드하려고 할 때 Mac용 Visual Studio "Xcode가 현재 설치되어 있지 않거나 찾을 수 없습니다" 메시지가 표시될 수 있습니다. 이 시나리오에서는 App Store에서 Xcode도 설치되어 있는지 검사. 그런 다음 Xcode를 시작하고 Xcode > 기본 설정 > 위치 > 명령줄 도구로 이동하여 드롭다운이 비어 있으면 검사. 비어 있는 경우 드롭다운을 선택한 다음 Xcode 명령줄 도구의 위치를 선택합니다. 그런 다음 Xcode를 닫고 Mac용 Visual Studio 다시 시작합니다.

유효한 Xcode 앱 번들을 찾을 수 없습니다.

iOS 또는 Mac Catalyst를 대상으로 하는 .NET MAUI 앱을 빌드하려고 할 때 "'/Library/Developer/CommandLineTools'에서 유효한 Xcode 앱 번들을 찾을 수 없습니다" 오류가 표시되면 Xcode에 설명된 솔루션이 현재 설치되어 있지 않거나 찾을 수 없습니다. 여전히 Xcode > 기본 설정 > 위치 > 명령줄 도구 드롭다운에 액세스할 수 없는 경우 다음 명령을 실행합니다.

sudo xcode-select --reset

Xcode 버전을 배치할 수 없습니다.

일부 시나리오에서는 iOS 또는 Mac Catalyst에서 .NET MAUI 앱을 빌드하면 컴퓨터에 더 이상 설치되지 않은 Xcode 버전을 사용하려고 시도할 수 있습니다. 이 경우 다음과 유사한 오류 메시지가 표시됩니다.

xcodebuild: error: SDK "/Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" cannot be located.
xcrun: error: sh -c '/Applications/Xcode_14.1.app/Contents/Developer/usr/bin/xcodebuild -sdk /Applications/Xcode_14.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk -find dsymutil 2> /dev/null' failed with exit code 16384: (null) (errno=Invalid argument)
xcrun: error: unable to find utility "dsymutil", not a developer tool or in PATH

앱을 빌드할 때 .NET iOS 및 .NET Mac Catalyst는 다음 프로세스를 사용하여 사용할 Xcode 버전을 결정합니다.

  1. 환경 변수가 MD_APPLE_SDK_ROOT 설정된 경우 해당 값을 사용합니다.
  2. ~/Library/Preferences/Xamarin/설정.plist 파일이 있는 경우 내부에 정의된 값을 사용합니다.
  3. 의 값을 xcode-select -p사용합니다.
  4. /Applications/Xcode.app을 사용합니다.

따라서 컴퓨터에서 Xcode의 위치를 지정하는 권장 방법은 환경 변수를 Xcode 버전의 경로로 설정하는 MD_APPLE_SDK_ROOT 것입니다. 자세한 내용은 특정 버전의 Xcode를 사용하여 빌드를 참조하세요.

그런 다음 컴퓨터에서 ~/Library/Preferences/Xamarin/설정.plist를 안전하게 삭제할 수 있습니다.

Blazor 하이브리드 앱에서 문제 진단

BlazorWebView 에는 Blazor 하이브리드 앱에서 문제를 진단하는 데 도움이 되는 기본 제공 로깅이 있습니다. 이 로깅을 사용하도록 설정하는 단계는 두 가지입니다.

  1. 진단 정보를 기록하기 위한 구성 요소 및 관련 구성 요소를 사용하도록 설정합니다 BlazorWebView .
  2. 로그 출력을 볼 수 있는 위치에 쓰도록 로거를 구성합니다.

자세한 내용은 Blazor 하이브리드 앱에서 문제 진단을 참조 하세요.

이미지 패키징 사용 안 함

문제 해결을 위해 프로젝트 파일의 첫 번째 <PropertyGroup> 노드에서 빌드 속성을 false 설정하여 이미지 리소스 패키징을 사용하지 않도록 설정할 $(EnableMauiImageProcessing) 수 있습니다.

<EnableMauiImageProcessing>false</EnableMauiImageProcessing>

시작 화면 패키징 사용 안 함

문제 해결을 위해 프로젝트 파일의 첫 번째 <PropertyGroup> 노드에서 빌드 속성을 false 설정하여 시작 화면 리소스 생성을 사용하지 않도록 설정할 $(EnableSplashScreenProcessing) 수 있습니다.

<EnableSplashScreenProcessing>false</EnableSplashScreenProcessing>

글꼴 패키징 사용 안 함

문제 해결을 위해 빌드 속성을 false 프로젝트 파일의 $(EnableMauiFontProcessing) 첫 번째 <PropertyGroup> 노드로 설정하여 글꼴 리소스 패키징을 사용하지 않도록 설정할 수 있습니다.

<EnableMauiFontProcessing>false</EnableMauiFontProcessing>

자산 파일 패키징 사용 안 함

문제 해결을 위해 프로젝트 파일의 첫 번째 <PropertyGroup> 노드에서 빌드 속성을 false 설정하여 자산 파일 리소스 패키징을 사용하지 않도록 설정할 $(EnableMauiAssetProcessing) 수 있습니다.

<EnableMauiAssetProcessing>false</EnableMauiAssetProcessing>

빈 시작 화면 생성

문제 해결을 위해 항목이 없고 <MauiSplashScreen> 사용자 지정 시작 화면이 없는 경우 빈 시작 화면을 생성할 수 있습니다. 이 작업은 프로젝트 파일의 $(EnableBlankMauiSplashScreen) 첫 번째 <PropertyGroup> 노드에서 빌드 속성을 설정하여 true 수행할 수 있습니다.

<EnableBlankMauiSplashScreen>true</EnableBlankMauiSplashScreen>

빈 시작 화면을 생성하면 사용자 지정 시작 화면이 재정의되고 앱 스토어가 거부됩니다. 그러나 앱 UI가 올바른지 확인하는 테스트에 유용한 방법이 될 수 있습니다.

중복 이미지 파일 이름 오류

중복 이미지 파일 이름에 대한 빌드 오류가 발생할 수 있습니다.

하나 이상의 중복된 파일 이름이 검색되었습니다. 모든 이미지 출력 파일 이름은 고유해야 합니다.

.NET 8에서 중복된 이미지 리소스 파일 이름이 없도록 .NET MAUI 검사 때문에 항목에 대해 발생 MauiIconMauiImage 합니다.

이 오류는 여러 폴더에 동일한 파일 이름이 있고 다른 폴더에 다른 확장명이 있는 동일한 파일 이름이 있는 경우에 발생합니다. 예를 들어 빌드 시 SVG 파일이 PNG 파일 로 변환되기 때문에 Resources/Images/PNG/dotnet_bot.png PNG 파일 과 Resources/Images/SVG/dotnet_bot.svg SVG 파일에 대한 빌드 오류가 발생합니다.

항목의 특성을 사용하여 폴더에 IncludeMauiImage 모든 이미지를 포함하고 특정 이미지 파일도 포함하는 경우에도 오류가 발생합니다.

<MauiImage Include="Resources\Images\*" />
<MauiImage Include="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

이 빌드 오류가 발생하는 경우 프로젝트 파일에 중복 이미지가 포함되지 않도록 하여 수정할 수 있습니다. 이렇게 하려면 특성 대신 Include 특성을 사용하도록 Update 특정 파일을 참조하는 파일을 변경 MauiIcon 합니다MauiImage.

<MauiImage Include="Resources\Images\*" />
<MauiImage Update="Resources\Images\dotnet_bot.svg" BaseSize="168,208" />

MSBuild 항목 요소 특성에 대한 자세한 내용은 Item 요소(MSBuild): 특성 및 요소를 참조 하세요.