개발 환경 구성: 14.1. 오류 유형 - GAC 에 등록된 DLL 에 대한 문서화 시 오류

부모글 보이기/감추기

SandCastle 사용법 소개.

NDoc이 더 이상의 업그레이드를 포기했다는 소식은 전에 알려드렸지요. 그런 와중에 다행히도, Microsoft가 SandCastle이라는 문서화 도구를 공개해 주었는데요. 오늘은 바로 이 "SandCastle" 프로그램을 사용하여 XML 주석 처리된 것에서 CHM 파일을 만드는 방법에 대해 소개해 드리겠습니다. 미리 말씀드리면, 이 문서를 작성하기 위해 제가 참조한 토픽은 다음의 것입니다.

Creating a Chm build using Sandcastle
; http://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx

개인적으로는 위의 설명이 영 ^^; 탐탁치 않습니다. 위에서는 상대 경로를 사용했는데, 그것으로 인해 오히려 무척이나 힘든 경로 설정을 하게 되어 피곤해 지기 때문입니다. 그래서, 저는 아예 절대 경로 설정으로 환경을 구성했으며, 그 점으로 인해 재활용 가능한 "sandcastle.config" 파일을 얻게 되었습니다. ^^; 그 이유에 대해서는 여러분들이 일단 제가 한 방법대로 따라해 보시고, 시간 나시면 위의 토픽에 방법대로 해보시면 아시게 될 것입니다.

우선, 현재(2006-09-15) 가장 최신 버전을 다음의 경로에서 다운로드할 수 있습니다.

Sandcastle - August 2006 Community Technology Preview (CTP)
; http://www.microsoft.com/downloads/details.aspx?FamilyID=e82ea71d-da89-42ee-a715-696e3a4873b2&DisplayLang=en

그다음 HTML Help Workshop을 다음의 경로에서 다운로드해야 합니다.

HTML Help 1.4 SDK - Microsoft HTML Help Downloads
; http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

그럼 전체적인 구조를 한번 살펴볼까요? Sandcastle의 동작방식은 NDoc과는 다소 다릅니다. 아래의 그림을 보면 한눈에 이해하실 수 있을 텐데요.

[출처 : SandcastleV2.ppt - http://blogs.msdn.com/sandcastle/attachment/681209.ashx]
Documentation Process using Sandcastle

NDoc과는 달라도 꽤나 직관적인 흐름을 갖습니다. 첫 번째 단계로, VS.NET 2005에서 XML Documentation 생성 옵션을 지정하고 빌드하면, assembly와 xml 파일들이 생기는데, assembly 쪽은 별도로 MrefBuilder.exe에서 다시 한번 변환을 한 다음, 최종 결과물들을 BuildAssembler.exe를 사용해서 가공하게 됩니다. 이때의 결과물들도 직접 CHM 파일 형태로 나오는 것이 아니라 HTML Help Workshop에서 처리할 수 있는 입력 파일입니다. 어떻게 보면 단계는 복잡해도 서로 간의 영역을 확실히 함으로써 분업화를 잘 이루었다고 볼 수 있습니다. 나온 결과물도 꽤나 멋들어집니다. ^^ 아래의 화면을 보시면 동의하실 거라 봅니다. 물론, 아직 좀 미숙한 부분도 있지만 아직 RC 버전도 아닌 CTP 버전임을 감안하면 기대해도 좋을 것 같습니다.

[출처 : SandcastleV2.ppt - http://blogs.msdn.com/sandcastle/attachment/681209.ashx]
Documentation Process using Sandcastle

그럼... 구미가 좀 땡기시나요? ^^ 암튼, Microsoft 역시 이 SandCastle로 MSDN 도움말을 만들었다고 하니 지속적인 업데이트는 보장된 듯합니다. NDoc 처럼 중간에 사라질 거란 걱정은 하지 않아도 된다는 얘기입니다. ^^

자, 그럼 이제 실제로 한번 만들어봐야 맛이겠지요. 우선, 환경 설정은 위에서 소개한 "SandCastle"과 "HTML Help Workshop"을 설치하는 것입니다. (아래의 설명에서는 이 프로그램들을 "C:\Program Files" 하위에 설치했다는 것을 가정으로 합니다.)

일반적인 C# 클래스 라이브러리를 만들고 XML 주석 파일이 생성되도록 컴파일된 결과물이 있다고 가정하고 이야기를 진행해 보겠습니다. (첨부된 SandCastleExam.zip을 사용하셔도 됩니다.)

이제부터의 작업은 Sandcastle에서 하라는 대로 해주어야 하는 것만 있습니다.

0. SandCastle이 동작되기 위한 준비 작업을 합니다. 우선, 현재 빌드 결과물 폴더에서 하위로 "comments", "html", "Art", "Scripts", "Styles" 폴더를 각각 만들어 둡니다. 그 후, 다음과 같은 명령을 통해서 파일을 복사해 둡니다.

copy ".\*.xml" .\comments   ; 이 라인에서의 XML 파일은 현재 빌드된 프로젝트에서 생성된 XML Documentation 옵션으로 생성된 파일입니다.
copy "C:\Program Files\Sandcastle\Presentation\Art\*.*" .\Art
copy "C:\Program Files\Sandcastle\Presentation\Scripts\*.*" .\Scripts
copy "C:\Program Files\Sandcastle\Presentation\Styles\*.*" .\Styles

1. 프로젝트 빌드 결과물에 대해서 "MRefBuilder"를 사용하여 Reflection 결과물 생성

MRefBuilder .\*.dll .\*.exe /out:.\reflection.org

위의 경우에는 현재 폴더의 모든 DLL과 EXE에 대해서 Reflection 결과물을 만듭니다.

2. 위의 ORG 파일로부터 Manifest 정보를 담는 XML 파일을 생성.

XslTransform /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\AddOverloads.xsl" .\reflection.org /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\AddGuidFilenames.xsl" /out:.\reflection.xml
XslTransform /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToManifest.xsl"  .\reflection.xml  /out:.\manifest.xml

3. 2번 단계에서 생성한 Manifest 정보와 특정한 Config 파일을 입력으로 각 도움말 페이지의 HTML 파일을 생성.

BuildAssembler /config:sandcastle.config .\manifest.xml

이때, sandcastle.config 파일은 내용을 직접 상황에 맞게 편집하셔야 합니다. (사실, 거의 그대로 쓰셔도 됩니다. ^^) 내용이 너무 길어서, 이 파일은 첨부된 "Build 예제.zip"에 포함된 "SandCastle.config" 파일을 참고하십시오. (참고로, 모든 경로가 "C:\Program Files\sandcastle"에 sandcastle이 설치되어 있다고 맞춰져 있습니다.)

4. Reflection.xml로부터 HHC, HHP, HHK 파일을 생성.

XslTransform /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToChmProject.xsl" .\reflection.xml /out:.\test.hhp
XslTransform /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToChmContents.xsl" .\reflection.xml /arg:html=.\html /out:.\test.hhc
XslTransform /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToChmIndex.xsl" .\reflection.xml /out:.\test.hhk

이러한 파일들은 모두 HTML Help Workshop의 입력 파일로 지정됩니다.

5. HHC 컴파일러를 통해서 최종적으로 CHM 파일을 생성.

hhc .\test.hhp

이때, 3번 단계에서 생성한 HTML 파일들과 함께 CHM 결과물이 생성되게 됩니다.

과정은 위와 같은데, 다소 복잡해 보이긴 해도 간단한게 배치 파일 하나만 만들어 놓으면 모든 과정을 자동화시킬 수 있습니다.

여러분들이 쉽게 실습을 할 수 있도록 제가 모든 파일을 만들어 놓았으니 첨부된 파일을 가지고 다음의 단계를 따라해 보시면 쉽게 CHM 결과물을 보실 수 있으니 참고하십시오.

1. 첨부된 SandCastleExam.zip 파일을 다운로드해서 릴리스 빌드합니다.

2. 첨부된 Build 예제.zip 파일을 압축 해제해서, "[솔루션 폴더]\bin\Release" 폴더에 복사합니다.

3. "Build.bat" 파일을 실행하면, SandCastle 관련 빌드 작업이 수행되고 test.chm 파일이 생성되는 것을 확인할 수 있습니다.

^^ 간단하지요. 이젠 "Build.bat" 파일과 "SandCastle.config" 파일을 여러분들의 구미에 맞게 수정하시기 바랍니다.

[이 토픽에 대해서 여러분들과 의견을 공유하고 싶습니다. 틀리거나 미흡한 부분 또는 의문 사항이 있으시면 언제든 댓글 남겨주십시오.]

WCF 를 참조한 DLL/EXE 에 대한 문서화를 Sandcastle 로 하게 되면 다음과 같은 오류가 발생합니다. (또는, GAC 에 등록된 기타 3rd-party 라이브러리를 참조한 경우.)

C:\...>MRefBuilder .\*.dll /out:.\reflection.org

MRefBuilderStatic (v2.0.2424.18753)
Copyright Microsoft Corp. 2005
Error: Unresolved assembly reference: 
System.ServiceModel (System.ServiceModel,Version=3.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089) 
required by [YourProjectDLL]'

개인적으로는 왜 이런 오류가 나는지 잘 이해가 안됩니다. 어차피 .NET DLL 들도 GAC 에 등록되어 있는데, 특별히 WCF 나 그외의 3rd-party 에 대해서는 GAC 에서 찾아내질 못하고 있습니다. 음... 어쩌면 내부에서 .NET 2.0 라이브러리에 대한 목록을 하드코딩 해놨을지도. ^^;

암튼, 이런 문제로 검색을 해보니, 다음과 같은 문답이 나왔습니다.

Sandcastle issue? Error: Unresolved assembly reference
; http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=616981&SiteID=1

나중 버전에서 이 문제를 수정한다고 하는군요. ^^; 그때까지는 MRefBuilder 의 "/dep" 스위치를 사용해서 해당 DLL 을 지정하라고 하는데요. 중요한 것은 이때 dep 로 의존성을 명시하는 폴더에 "System.ServiceModel.dll" 만 있어서는 안되고, "System.ServiceModel.dll" 이 내부적으로 참조하는 모든 DLL 목록들이 같이 존재해야 한다는 것입니다.

저 같은 경우에는 "dllext" 폴더에 "[목록 1]" 과 같은 DLL 들을 집어 넣은 다음 명령행에서 아래와 같이 입력해서 해결했습니다.

C:\...>MRefBuilder .\*.dll /out:.\reflection.org /dep:..\dllext\System.ServiceModel.dll

[목록 1]
Microsoft.Build.Framework.dll
Microsoft.Build.Tasks.dll
Microsoft.Build.Utilities.dll
Microsoft.Transactions.Bridge.dll
PresentationBuildTasks.dll
PresentationCFFRasterizer.dll
PresentationCore.dll
PresentationFramework.Aero.dll
PresentationFramework.Classic.dll
PresentationFramework.dll
PresentationFramework.Luna.dll
PresentationFramework.Royale.dll
PresentationUI.dll
ReachFramework.dll
SMDiagnostics.dll
sysglobl.dll
System.configuration.dll
System.Deployment.dll
System.IdentityModel.dll
System.IdentityModel.Selectors.dll
System.IO.Log.dll
System.Printing.dll
System.Runtime.Serialization.dll
System.ServiceModel.dll
System.Speech.dll
System.Transactions.dll
System.Workflow.Activities.dll
System.Workflow.ComponentModel.dll
System.Workflow.Runtime.dll
UIAutomationClient.dll
UIAutomationClientsideProviders.dll
UIAutomationProvider.dll
UIAutomationTypes.dll
WindowsBase.dll
WindowsFormsIntegration.dll

; .NET 3.0 WCF 폴더의 것은 그냥(!) 무조건 복사했음.

[이 토픽에 대해서 여러분들과 의견을 공유하고 싶습니다. 틀리거나 미흡한 부분 또는 의문 사항이 있으시면 언제든 댓글 남겨주십시오.]

[최초 등록일: 9/20/2006]
[최종 수정일: 9/21/2006]

이 저작물은 크리에이티브 커먼즈 코리아 저작자표시-비영리-변경금지 2.0 대한민국 라이센스에 따라 이용하실 수 있습니다.

by SeongTae Jeong, mailto:techsharer at outlook.com

No	Writer	Date	Cnt.	Title	File(s)
1303	정성태	6/26/2012	27404	개발 환경 구성: 152. sysnet DB를 SQL Azure 데이터베이스로 마이그레이션
1302	정성태	6/25/2012	29457	개발 환경 구성: 151. Azure 웹 사이트에 사용자 도메인 네임 연결하는 방법
1301	정성태	6/20/2012	25766	오류 유형: 156. KB2667402 윈도우 업데이트 실패 및 마이크로소프트 Answers 웹 사이트 대응
1300	정성태	6/20/2012	31785	.NET Framework: 329. C# - Rabin-Miller 소수 생성방법을 이용하여 RSACryptoServiceProvider의 개인키를 직접 채워보자 [1]	2
1299	정성태	6/18/2012	32897	제니퍼 .NET: 21. 제니퍼 닷넷 - Ninject DI 프레임워크의 성능 분석 [2]	2
1298	정성태	6/14/2012	34411	VS.NET IDE: 72. Visual Studio에서 pfx 파일로 서명한 경우, 암호는 어디에 저장될까? [2]
1297	정성태	6/12/2012	31056	VC++: 63. 다른 프로세스에 환경 변수 설정하는 방법	1
1296	정성태	6/5/2012	27699	.NET Framework: 328. 해당 DLL이 Managed인지 / Unmanaged인지 확인하는 방법 - 두 번째 이야기 [4]	1
1295	정성태	6/5/2012	25086	.NET Framework: 327. RSAParameters와 System.Numerics.BigInteger 이야기	1
1294	정성태	5/27/2012	48544	.NET Framework: 326. 유니코드와 한글 - 유니코드와 닷넷을 이용한 한글 처리 [7]	2
1293	정성태	5/24/2012	29776	.NET Framework: 325. System.Drawing.Bitmap 데이터를 Parallel.For로 처리하는 방법 [2]	1
1292	정성태	5/24/2012	23755	.NET Framework: 324. First-chance exception에 대해 조건에 따라 디버거가 멈추게 할 수는 없을까? [1]	1
1291	정성태	5/23/2012	30283	VC++: 62. 배열 초기화를 위한 기계어 코드 확인 [2]
1290	정성태	5/18/2012	35083	.NET Framework: 323. 관리자 권한이 필요한 작업을 COM+에 대행 [7]	1
1289	정성태	5/17/2012	39242	.NET Framework: 322. regsvcs.exe로 어셈블리 등록 시 시스템 변경 사항 [5]	2
1288	정성태	5/17/2012	26467	.NET Framework: 321. regasm.exe로 어셈블리 등록 시 시스템 변경 사항 (3) - Type Library	1
1287	정성태	5/17/2012	29304	.NET Framework: 320. regasm.exe로 어셈블리 등록 시 시스템 변경 사항 (2) - .NET 4.0 + .NET 2.0 [2]
1286	정성태	5/17/2012	38233	.NET Framework: 319. regasm.exe로 어셈블리 등록 시 시스템 변경 사항 (1) - .NET 2.0 + x86/x64/AnyCPU [5]
1285	정성태	5/16/2012	33267	.NET Framework: 318. gacutil.exe로 어셈블리 등록 시 시스템 변경 사항	1
1284	정성태	5/15/2012	25704	오류 유형: 155. Windows Phone 연결 상태에서 DRIVER POWER STATE FAILURE 블루 스크린 뜨는 현상
1283	정성태	5/12/2012	33316	.NET Framework: 317. C# 관점에서의 Observer 패턴 구현 [1]	1
1282	정성태	5/12/2012	26110	Phone: 6. Windows Phone 7 Silverlight에서 Google Map 사용하는 방법 [3]	1
1281	정성태	5/9/2012	33197	.NET Framework: 316. WPF/Silverlight의 그래픽 단위와 Anti-aliasing 처리를 이해하자 [1]	1
1280	정성태	5/9/2012	26159	오류 유형: 154. Could not load type 'System.ServiceModel.Activation.HttpModule' from assembly 'System.ServiceModel, ...'.
1279	정성태	5/9/2012	24919	.NET Framework: 315. 해당 DLL이 Managed인지 / Unmanaged인지 확인하는 방법 [1]	1
1278	정성태	5/8/2012	26151	오류 유형: 153. Visual Studio 디버깅 - Unable to break execution. This process is not currently executing the type of code that you selected to debug.

AD BLOCK 해제 요청