설치

Doconut.NETFramework는 .NET Framework 4.7.2에서 클래식 ASP.NET 애플리케이션에 Doconut 뷰어를 호스팅합니다 — IIS 또는 IIS Express, MVC 5 또는 Web Forms. 설정은 세 부분으로 구성됩니다: NuGet 패키지, Web.config에 두 개의 등록, 그리고 Global.asax에서 한 번의 호출. 이 페이지는 세 가지 모두를 다룹니다; 빠른 시작에서는 페이지에 문서를 배치합니다.

요구 사항

• 웹 프로젝트가 .NET Framework 4.7.2 이상을 대상으로 합니다. 4.7 프로젝트는 이 패키지를 사용할 수 없으므로 먼저 대상 프레임워크를 변경하십시오.
• 사이트가 통합 파이프라인에서 실행됩니다 (IIS 및 IIS Express 애플리케이션 풀의 기본값).

이 페이지는 Doconut.NETFramework 26.9.0 및 이후 버전을 다룹니다. 26.8.0 및 이전 버전은 .NET Framework 4.7을 대상으로 하며 다른 API를 사용했습니다; 해당 라인은 중단되었습니다. 기존 애플리케이션을 해당 경계 너머로 업데이트하는 방법은 마이그레이션에서 다룹니다.

패키지 설치

패키지 관리자 콘솔에서:

Install-Package Doconut.NETFramework

또는 SDK 스타일 프로젝트에서는:

dotnet add package Doconut.NETFramework

렌더링 엔진은 패키지에 포함되어 있습니다: 별도의 엔진 어셈블리를 참조하거나 복사하거나 배포할 필요가 없습니다. 선택적 기능은 자체 패키지로 제공됩니다 — 예를 들어 Doconut.NETFramework.Converter 및 Doconut.NETFramework.Dicom — 각각은 라이선스가 필요합니다 (자세히는 플러그인 시스템).

Web.config 구성

Doconut은 두 종류의 요청을 제공하며, IIS는 두 요청 모두를 Web.config를 통해 라우팅합니다:

• DocImage.axd — 뷰어의 페이지, 썸네일, 검색 및 주석 엔드포인트이며, Doconut.DocImageHandler가 제공합니다.
• /doconut-res/* — 뷰어 자체의 스크립트, 스타일시트 및 아이콘으로, 어셈블리에 포함되어 Doconut.DoconutResourceModule이 제공합니다.

두 항목과 이들이 의존하는 설정을 추가합니다:

<configuration>
  <system.web>
    <!-- MVC 5 only: Razor compiles views at run time and needs the netstandard facade. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength is in KILOBYTES: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Read .cshtml and .aspx files as UTF-8, not as the server's ANSI code page. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength is in BYTES: the same 200 MB. -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

각 라인은 예외를 발생시키지 않는 실패를 방지합니다:

• verb="GET,HEAD,POST" — HEAD를 유지합니다. 뷰어는 애니메이션 이미지를 감지하기 위해 페이지 1에 HEAD 요청을 보냅니다. 이 동사가 없으면 IIS가 핸들러가 실행되기 전에 404를 반환합니다: 문서는 표시되지만 애니메이션 감지는 작동하지 않으며 브라우저 콘솔에 404가 가득합니다.
• runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css, .png 파일은 정적 파일처럼 보이며, IIS는 리소스 모듈이 처리하기 전에 정적 파일 핸들러에 전달합니다. 그 결과 스크립트와 아이콘이 없는 뷰어가 됩니다.
• <globalization fileEncoding="utf-8"> — 바이트 순서 표시(BOM) 없이 UTF-8로 저장된 페이지 파일은 서버의 ANSI 코드 페이지로 읽히게 되어, 모든 비ASCII 문자가 브라우저에 이중 인코딩되어 전달됩니다 (예: em 대시가 —로 표시). 파일 자체는 디스크에 올바르게 저장되어 있으며, 페이지는 여전히 <meta charset="utf-8">를 선언합니다.
• netstandard 어셈블리 (MVC 5) — Razor는 뷰가 처음 요청될 때 컴파일하며, 이 어셈블리 목록에 해당 파사드가 포함되지 않습니다. 단순 멤버 접근을 넘어 동적인 작업을 수행하는 뷰는 CS0012 오류가 발생하고 빈 500 응답을 반환하며, 해당 뷰만 실패합니다. 컴파일러 오류는 Windows 이벤트 로그(소스: ASP.NET)에만 나타납니다. Web Forms 애플리케이션은 이 라인이 필요하지 않습니다.
• 업로드 제한 — ASP.NET은 어떤 핸들러가 실행되기 전에 전체 요청 본문을 읽으므로, 이 제한을 초과하는 업로드는 IIS에 의해 자체 오류 페이지로 거부됩니다. maxRequestLength(킬로바이트)와 maxAllowedContentLength(바이트)를 일치시키고, 사용자가 열거나 업로드할 가장 큰 파일보다 크게 설정하십시오.

두 가지 설정이 더 중요하며, 보통 이미 올바르게 설정되어 있습니다:

• 세션 상태가 유지됩니다. 기본적으로 페이지는 문서를 연 ASP.NET 세션에만 제공되므로, 사이트에서 <sessionState mode="Off" />를 설정하면 안 됩니다. 자세히는 세션 및 보안 참고.
• 바인딩 리다이렉트. NuGet이 Web.config에 기록하는 <runtime> 바인딩 리다이렉트를 유지하십시오. SDK 스타일 프로젝트에서는 생성된 bin\<YourApp>.dll.config에서 복사하십시오. 클래식 ASP.NET은 Web.config에서만 리다이렉트를 읽기 때문입니다. bin\에 없는 버전을 지정한 리다이렉트는 시작 시 전체 애플리케이션을 빈 500 오류와 함께 중단시킵니다.

Global.asax에서 Doconut 등록

System.Web에는 빌더와 미들웨어 파이프라인이 없습니다. Doconut은 Application_Start에서 DoconutHost.Initialize에 의해 워커 프로세스당 한 번 구성되고, Application_End에서 DoconutHost.Shutdown에 의해 해제됩니다:

// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize는 핸들러, 리소스 모듈 및 사용자가 작성한 코드를 위한 서비스를 구성합니다. 코드는 DoconutHost.Services를 통해 접근합니다(DoconutHost 참고). 첫 번째 호출만 설정을 적용하고 두 번째 호출은 무시됩니다. MVC 애플리케이션에서는 두 Doconut 경로를 라우팅에서 제외해야 합니다 — 빠른 시작에서 전체 Application_Start 예시를 확인할 수 있습니다.

모든 옵션

DoconutOptions는 다음과 같은 설정 가능한 속성을 허용합니다. 모든 속성은 선택 사항입니다.

여러 라이선스 소스가 설정된 경우, LicenseStream이 LicenseContent보다 우선하고, LicenseContent가 LicensePath보다 우선하며, LicensePath가 자동 검색보다 우선합니다 — 라이선스 설정 참고.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // where the viewer's JS/CSS/images are served from
    options.UnsafeMode      = false;          // keep session security on
    options.ShowDoconutInfo = false;
});
// The page endpoint is not an option here: it is the DocImage.axd handler declared in Web.config.

다음 단계

• 빠른 시작 — 문서를 열고 브라우저에 렌더링합니다(MVC 5 또는 Web Forms).
• 라이선스 설정 — Doconut이 라이선스 파일을 찾는 위치입니다.