어셈블리 참조 문제 해결

MSBuild 및 .NET 빌드 프로세스에서 가장 중요한 작업 중 하나는 작업에서 ResolveAssemblyReference 발생하는 어셈블리 참조를 확인하는 것입니다. 이 문서에서는 ResolveAssemblyReference의 작동 방식과, ResolveAssemblyReference가 참조를 해결할 수 없을 때 발생할 수 있는 빌드 실패 문제를 해결하는 방법에 대한 몇 가지 세부 사항을 설명합니다. 어셈블리 참조 오류를 조사하려면 구조적 로그 뷰어를 설치하여 MSBuild 로그를 볼 수 있습니다. 이 문서의 스크린샷은 구조적 로그 뷰어에서 가져옵니다.

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

컴파일러는 파일 시스템의 경로 .dll만 참조로 수락할 수 있으므로, 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 스위치를 통해 컴파일러에 전달합니다.

ResolveAssemblyReference 또한 모든 항목과 .dll 참조의 전체 집합(실제로 그래프 이론 용어의 .exe기)을 재귀적으로 결정하고 각 집합에 대해 빌드 출력 디렉터리에 복사해야 하는지 여부를 결정합니다. 실제 복사는 수행하지 않지만(나중에 실제 컴파일 단계 후에 처리됨) 복사할 파일의 항목 목록을 준비합니다.

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

순서를 보면, ResolveAssemblyReferences가 Compile 전에 일어난다, 그리고 물론 CopyFilesToOutputDirectory가 Compile 후에 발생합니다.

ResolveAssemblyReference 입력

ResolveAssemblyReference 은 입력을 로깅하는 방법에 대해 포괄적입니다.

모든 작업에 대해 Parameters 노드는 표준으로 사용되지만, ResolveAssemblyReference는 '입력' 섹션 아래에서 자체 정보 집합을 기록하며 Parameters, 기본적으로 동일하지만 다른 구조로 되어 있습니다.

가장 중요한 입력은 다음과 Assemblies같습니다AssemblyFiles.

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

Assemblies는 프로젝트에 대해 호출되는 순간에 Reference MSBuild 항목의 ResolveAssemblyReference 내용을 사용합니다. 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 는 결과의 자세한 로깅을 제공합니다.

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

CopyLocal 항목 메타데이터

참조에는 메타데이터가 CopyLocal 있을 수도 있고, 없을 수도 있습니다. 참조에 CopyLocal = true가 포함된 경우, 나중에 목표 대상 CopyFilesToOutputDirectory에 의해 출력 디렉터리에 복사됩니다. 이 예제에서는 DataFlow는 true로 설정되어 있고, CopyLocal는 true로 설정되어 있지만 Immutable는 설정되지 않았습니다.

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

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

개인 항목 메타데이터

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

• 원본 항목 중 어느 것도 Private 메타데이터를 지정하지 않을 경우, CopyLocal이 True로 설정되거나 설정되지 않아 기본값인 True으로 유지됩니다.
• 지정된 원본 항목이 Private=true를 명시하는 경우, CopyLocal를 True로 설정하십시오.
• 하나 이상의 어셈블리가 Private=false 및 CopyLocal를 지정하고, 어떤 원본 어셈블리도 Private=true를 지정하지 않은 경우 False가 설정됩니다.

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

마지막 점은 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".

MSBuild는 어떤 참조가 false로 설정 Private 되었는지 알려주지 않지만 구조화된 로그 뷰어는 위에서 지정한 항목에 메타데이터를 추가 Private 합니다.

문제의 조사가 간소화되고, CopyLocal=false로 설정된 문제의 종속성을 유발한 참조를 정확하게 알려 줍니다.

전역 어셈블리 캐시

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

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

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

AssemblySearchPaths

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

AssemblySearchPaths 는 세미콜론으로 구분된 목록입니다. 내장된 자리 표시자 세트(예: {HintPathFromItem} 및 {GAC})를 지원하며, 해결 과정에서 실제 위치로 확장됩니다.

기본적으로 비 SDK 스타일 프로젝트는 다음 검색 경로 순서를 사용합니다.

1. 후보 어셈블리 파일({CandidateAssemblyFiles})
2. ReferencePath 속성($(ReferencePath))
3. <Reference> 항목의 힌트 경로 ({HintPathFromItem})
4. 대상 프레임워크 디렉터리({TargetFrameworkDirectory})
5. AssemblyFolders.config에서 온 $(AssemblyFoldersConfigFileSearchPath) 어셈블리 폴더
6. 레지스트리({Registry:...})
7. 레거시 등록된 어셈블리 폴더({AssemblyFolders})
8. GAC(전역 어셈블리 캐시)({GAC})
9. 값을 <Reference Include="..."> 실제 파일 이름으로 처리({RawFileName})
10. 출력 디렉터리($(OutDir))

.NET SDK는 더 작은 기본값 AssemblySearchPaths 을 설정합니다(기본적으로 GAC/레지스트리/출력 디렉터리 검색 제외).

• {CandidateAssemblyFiles}
• {HintPathFromItem}
• {TargetFrameworkDirectory}
• {RawFileName}

빌드의 효과적인 값을 확인하려면, ResolveAssemblyReference가 기록한 SearchPaths 입력을 검사하세요 (예: MSBuild 구조적 로그 뷰어 사용) 또는 msbuild /pp로 프로젝트를 전처리하세요.

관련 플래그 false를 다음으로 설정하여 각 항목을 사용하지 않도록 설정할 수 있습니다.

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

충돌이 발생했습니다.

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

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

관련 콘텐츠

• ResolveAssemblyReference 작업