어셈블리 참조 문제 해결하기

ResolveAssemblyReference 작업에서 발생하는 어셈블리 참조를 확인하는 것은 MSBuild 및 .NET 빌드 프로세스에서 가장 중요한 작업 중 하나입니다. 이 문서에서는 향후 발생 가능한 빌드 실패 문제를 해결하는 방법에 대한 몇 가지 세부 정보를 ResolveAssemblyReference의 작동 방식과 ResolveAssemblyReference이(가) 참조를 해결하지 못할 경우를 대비하기 위해 설명합니다. MSBuild 로그를 확인하기 위해 구조적 로그 뷰어를 설치함으로써 어셈블리 참조 오류를 조사할 수 있습니다. 구조적 로그 뷰어에서 이 문서의 스크린샷을 가져옵니다.

ResolveAssemblyReference의 목적은 파일 시스템의 어셈블리 파일에 대한 경로에 매핑하기 위해 .csproj 파일(또는 다른 위치)에 지정된 모든 참조를 <Reference> 항목을 통해 가져오는 것입니다.

ResolveAssemblyReference은(는) 프로젝트 파일에 표시되는 mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 등의 문자열을 C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.6.1\mscorlib.dll 등의 경로로 변환한 후 /r 스위치를 통해 컴파일러에 전달하며, 이는 컴파일러는 파일 시스템의 .dll 경로만 참조로 수락할 수 있기 때문입니다.

덧붙여, ResolveAssemblyReference은(는) 모든 .dll및 .exe 참조의 전체 집합(실제 그래프 이론 용어로는 이행적 폐쇄)을 재귀적으로 결정하며, 빌드 출력 디렉터리에 각 집합을 복사할지 여부를 결정합니다. 복사할 파일의 항목 목록을 준비하며, 실제 복사는 수행하지 않습니다(향후 실제 컴파일 단계 후에 처리됩니다).

ResolveAssemblyReference은(는) ResolveAssemblyReferences 대상에서 호출됩니다.

순서를 확인해 보면, ResolveAssemblyReferences이(가) Compile보다 먼저 발생하고, 물론 CopyFilesToOutputDirectory은(는) Compile 뒤에 발생합니다.

참고 항목

MSBuild 설치 폴더의 표준 .targets 파일 Microsoft.Common.CurrentVersion.targets에서 ResolveAssemblyReference 작업이 호출됩니다. https://github.com/dotnet/msbuild/blob/a936b97e30679dcea4d99c362efa6f732c9d3587/src/Tasks/Microsoft.Common.CurrentVersion.targets#L1991-L2140에서 온라인으로 .NET SDK MSBuild 대상을 찾아볼 수도 있습니다. 이는 .targets 파일에서 ResolveAssemblyReference 작업이 호출되는 위치를 정확하게 보여주는 링크입니다.

ResolveAssemblyReference 입력

ResolveAssemblyReference은(는) 다음과 같이 입력을 로깅하는 방법에 대해 포괄적입니다.

Parameters 노드는 모든 작업에 대해 표준이지만, 추가적으로 ResolveAssemblyReference은(는) 입력에서 자체 정보 집합을 로깅합니다(기본적으로 Parameters에서와 동일하지만 다르게 구조화됩니다).

가장 중요한 입력은 다음의 Assemblies 및 AssemblyFiles입니다.

    <ResolveAssemblyReference
        Assemblies="@(Reference)"
        AssemblyFiles="@(_ResolvedProjectReferencePaths);@(_ExplicitReference)"

Assemblies은(는) 프로젝트에 대해 ResolveAssemblyReference이(가) 호출되는 순간 Reference MSBuild 항목의 내용을 사용합니다. 이 항목에는 NuGet 참조를 포함하는 모든 메타데이터 및 어셈블리 참조가 포함되어야 합니다. 다음과 같은 다양한 메타데이터 집합이 각 참조에 연결되어 있습니다.

AssemblyFiles은(는) ResolveProjectReference 대상의 출력 항목에서 _ResolvedProjectReferencePaths을(를) 가져옵니다. ResolveProjectReference은(는) ResolveAssemblyReference 이전에 실행되며 <ProjectReference> 항목을 디스크에서 빌드된 어셈블리의 경로로 변환합니다. 그러므로 현재 프로젝트의 참조된 모든 프로젝트에서 빌드한 어셈블리가 AssemblyFiles에 포함됩니다.

_FindDependencies 속성에서 해당 값을 가져오는 부울 FindDependencies 매개 변수는 또 다른 유용한 입력입니다.

FindDependencies="$(_FindDependencies)"

전이적 종속성 어셈블리 분석을 해제하려면 빌드에서 이 속성을 false(으)로 설정할 수 있습니다.

ResolveAssemblyReference 알고리즘

다음은 ResolveAssemblyReference 작업에 대한 간소화된 알고리즘입니다.

1. 입력을 기록합니다.
2. MSBUILDLOGVERBOSERARSEARCHRESULTS 환경 변수를 확인합니다. 자세한 로그를 가져오려면 이 변수를 모든 값으로 설정합니다.
3. 참조 개체의 테이블을 초기화합니다.
4. obj 디렉터리에서 캐시 파일을 읽습니다(있는 경우).
5. 종속성의 닫기를 계산합니다.
6. 출력 테이블을 빌드합니다.
7. 캐시 파일을 obj 디렉터리에 씁니다.
8. 결과를 기록합니다.

알고리즘은 어셈블리의 입력 목록을 (메타데이터 및 프로젝트 참조 모두에서) 가져오고, (메타데이터를 읽음으로써) 각 어셈블리에 대한 참조 목록을 검색하며, 참조된 모든 어셈블리의 전체 집합(이행적 폐쇄)을 빌드하고, 다양한 위치(예시: GAC, AssemblyFoldersEx 등)에서 이를 해결합니다.

더 이상 새 참조가 추가되지 않을 때까지 참조된 어셈블리가 반복적으로 목록에 추가됩니다. 그 후 알고리즘이 중지됩니다.

작업에 제공한 직접 참조는 기본 참조라고 불립니다. 전이적 참조로 인해 집합에 추가된 간접 어셈블리는 종속성이라고 불립니다. 이를 포함하며 해당 메타데이터로 이어진 모든 기본("루트") 항목을 각 간접 어셈블리에 대한 레코드가 추적합니다.

ResolveAssemblyReference 작업에 대한 결과

결과의 자세한 로깅을 ResolveAssemblyReference이(가) 제공합니다.

두 가지 범주인 기본 참조 및 종속성으로 해결된 어셈블리가 나눠집니다. 빌드 중인 프로젝트의 참조로 기본 참조가 명시적으로 지정되었습니다. 참조의 참조로부터 종속성이 전이적으로 유추되었습니다.

Important

ResolveAssemblyReference은(는) 지정된 어셈블리의 참조를 확인하기 위해 어셈블리 메타데이터를 읽습니다. C# 컴파일러가 어셈블리를 내보내는 경우에는 실제로 필요한 어셈블리에 대한 참조만 추가합니다. 그러므로 특정 프로젝트를 컴파일하는 경우 어셈블리에 구워지지 않는 불필요한 참조를 프로젝트에서 지정할 수 있습니다. 필요하지 않은 프로젝트에 참조를 추가해도 되며, 이러한 참조는 무시됩니다.

CopyLocal 항목 메타데이터

참조에는 CopyLocal 메타데이터가 있거나 없을 수 있습니다. 참조에 CopyLocal = true이(가) 있는 경우, 향후 CopyFilesToOutputDirectory 대상에 의해 출력 디렉터리에 복사됩니다. 이 예시에서는 DataFlow에서 CopyLocal이(가) true로 설정되지만, Immutable에서는 그렇지 않습니다.

CopyLocal 메타데이터가 완전히 누락된 경우, 이는 기본적으로 true로 간주됩니다. 그러므로 ResolveAssemblyReference은(는) 기본적으로 종속성을 출력에 복사하려고 시도합니다. ResolveAssemblyReference은(는) 특정 참조를 CopyLocal(으)로 선택하거나 하지 않은 이유를 기록합니다.

다음 표에는 CopyLocal 의사 결정의 가능한 모든 이유가 나열되어 있습니다. 이러한 문자열을 알고 빌드 로그에서 검색할 수 있도록 하는 것이 유용합니다.

CopyLocal 상태	설명
Undecided	현재 복사 로컬 상태는 미정입니다.
YesBecauseOfHeuristic	참조는 어떤 이유로든 '아니요'가 아니었기 때문에 CopyLocal='true'이(가) 있어야 합니다.
YesBecauseReferenceItemHadMetadata	참조에는 CopyLocal='true'이(가) 있어야 하며, 이는 원본 항목에 Private='true'가 있기 때문입니다.
NoBecauseFrameworkFile	참조에는 CopyLocal='false'이(가) 있어야 하며, 이는 프레임워크 파일이기 때문입니다.
NoBecausePrerequisite	참조에는 CopyLocal='false'이(가) 있어야 하며, 이는 필수 구성 요소 파일이기 때문입니다.
NoBecauseReferenceItemHadMetadata	참조에는 CopyLocal='false'이(가) 있어야 하며, 이는 프로젝트에서 Private 특성이 'false'로 설정되어 있기 때문입니다.
NoBecauseReferenceResolvedFromGAC	참조에는 CopyLocal='false'이(가) 있어야 하며, 이는 GAC에서 확인되었기 때문입니다.
NoBecauseReferenceFoundInGAC	어셈블리가 GAC에서 발견될 경우(심지어 다른 곳에서 해결되었을 때도) CopyLocal='false' 레거시 동작입니다.
NoBecauseConflictVictim	참조에는 CopyLocal='false'이(가) 있어야 하며, 이는 동일한 이름의 어셈블리 파일 간의 충돌을 잃었기 때문입니다.
NoBecauseUnresolved	참조가 해결되지 않았습니다. bin 디렉터리에 복사할 수 없으며, 이는 bin 디렉터리를 찾을 수 없기 때문입니다.
NoBecauseEmbedded	참조가 포함되었습니다. bin 디렉터리에 복사하면 안 되며, 이는 런타임에 로드되지 않기 때문입니다.
NoBecauseParentReferencesFoundInGAC	copyLocalDependenciesWhenParentReferenceInGac 속성이 false로 설정되고 GAC에서 모든 부모 원본 항목이 발견되었습니다.
NoBecauseBadImage	제공된 어셈블리 파일은 잘못된 이미지이며 관리되지 않을 수 있으며 어셈블리가 아닐 수 있으므로 복사하는 행위는 권장되지 않습니다.

개인 항목 메타데이터

모든 기본 참조의 Private메타데이터는 CopyLocal 결정의 중요한 부분입니다. 해당 참조가 클로저에 추가되는 데 기여한 모든 기본 참조(원본 항목) 목록이 각 참조(기본 또는 종속성)에 있습니다.

• Private 메타데이터를 지정하는 원본 항목이 없는 경우 CopyLocal은(는) True(으)로 설정됩니다(또는 설정되지 않습니다. 즉, 기본값 True)
• 원본 항목 중에서 Private=true을(를) 지정한 항목이 있으면 CopyLocal은(는) True(으)로 설정됩니다
• 원본 어셈블리가 Private=true을(를) 지정하지 않았고 하나 이상의 어셈블리가 Private=false(을) 지정하는 경우 CopyLocal은(는) False(으)로 설정됩니다

Private을 false로 설정하는 참조는 무엇입니까?

마지막 포인트는 CopyLocal이(가) This reference is not "CopyLocal" because at least one source item had "Private" set to "false" and no source items had "Private" set to "true". 등의 false로 설정되는 자주 사용되는 이유를 나타냅니다.

MSBuild는 어떤 참조가 Private을(를) false로 설정하였는지 알려주지 않지만 구조적 로그 뷰어는 Private 메타데이터를 위에서 지정한 항목에 추가합니다.

이렇게 하면 조사가 간소화되고 CopyLocal=false을(를) 통해 문제의 종속성을 설정할 수 있는 참조를 정확히 알려 줍니다.

전역 어셈블리 캐시

참조를 출력에 복사할지 여부를 결정하는 데 GAC(전역 어셈블리 캐시)가 중요한 역할을 합니다. 재현 가능한 빌드에 문제가 발생할 수 있으며, 이는 GAC의 내용이 컴퓨터별로 다르기 때문입니다(GAC와 같은 컴퓨터 상태에 따라 다른 컴퓨터에서 동작이 다른 경우).

상황을 완화하기 위해 최근에 ResolveAssemblyReference(으)로 수정되었습니다. 다음과 같은 두 개의 새 입력으로 동작을 ResolveAssemblyReference(으)로 제어할 수 있습니다.

    CopyLocalDependenciesWhenParentReferenceInGac="$(CopyLocalDependenciesWhenParentReferenceInGac)"
    DoNotCopyLocalIfInGac="$(DoNotCopyLocalIfInGac)"

AssemblySearchPaths

경로 ResolveAssemblyReference 검색 목록을 어셈블리를 찾기 위한 목적으로 사용자 지정하는 방법에는 두 가지가 있습니다. AssemblySearchPaths 속성을 미리 설정하여 목록을 완전히 사용자 지정할 수 있습니다. 순서가 중요합니다. 두 위치에 어셈블리가 있으면, ResolveAssemblyReference은(는) 첫 번째 위치에서 어셈블리를 찾은 뒤 중지됩니다.

기본적으로 10개의 위치 ResolveAssemblyReference 검색(.NET SDK를 사용하는 경우 4개)이 있으며, 각각을 사용하지 않도록 설정하기 위해 관련 플래그를 false로 설정할 수 있습니다.

• AssemblySearchPath_UseCandidateAssemblyFiles 속성을 false로 설정하여 현재 프로젝트에서 파일 검색을 사용할 수 없습니다.
• AssemblySearchPath_UseReferencePath 속성을 false로 설정하여 .user 파일에서 참조 경로 속성을 검색할 수 없습니다.
• AssemblySearchPath_UseHintPathFromItem 속성을 false로 설정하여 항목의 힌트 경로를 사용할 수 없습니다.
• AssemblySearchPath_UseTargetFrameworkDirectory 속성을 false로 설정하여 디렉터리를 MSBuild의 대상 런타임에 사용할 수 없습니다.
• AssemblySearchPath_UseAssemblyFoldersConfigFileSearchPath 속성을 false로 설정하여 AssemblyFolders.config에서 어셈블리 폴더 검색을 사용하지 않도록 설정됩니다.
• AssemblySearchPath_UseRegistry 속성을 false로 설정하여 레지스트리 검색을 사용할 수 없습니다.
• AssemblySearchPath_UseAssemblyFolders 속성을 false로 설정하여 레거시 등록된 어셈블리 폴더를 검색할 수 없습니다.
• AssemblySearchPath_UseGAC 속성을 false로 설정하여 GAC를 검색할 수 없습니다.
• AssemblySearchPath_UseRawFileName 속성을 false로 설정하여 실제 파일 이름으로 참조의 Include를 처리할 수 없습니다.
• AssemblySearchPath_UseOutDir 속성을 false로 설정하여 애플리케이션의 출력 폴더를 확인할 수 없습니다.

충돌이 발생했습니다.

MSBuild가 다른 참조에서 사용되는 동일한 어셈블리의 다른 버전에 대한 경고를 제공하는 것이 일반적인 상황입니다. 바인딩 리디렉션을 app.config 파일에 추가하는 작업이 솔루션에 포함되는 경우가 많습니다.

MSBuild 구조적 로그 뷰어에서 "충돌이 발생했습니다"를 검색하는 것은 이러한 충돌을 조사하는 유용한 방법입니다. 해당 어셈블리 버전이 필요한 참조에 대해 자세한 정보를 보여 줍니다.

관련 콘텐츠

• ResolveAssemblyReference 작업