설치

Doconut을 .NET Framework 4.7.2 웹 애플리케이션에 추가

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 애플리케이션 풀의 기본값).
  • 서버가 Windows에서 실행됩니다. 이 패키지는 Windows 전용입니다.

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

패키지 설치

패키지 관리자 콘솔에서:

powershell
Install-Package Doconut.NETFramework

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

bash
dotnet add package Doconut.NETFramework

버전이 지정되지 않은 명령은 최신 안정 버전을 설치합니다. 이 문서에서 설명하는 릴리스를 고정하려면 버전을 지정하십시오:

powershell
Install-Package Doconut.NETFramework -Version 26.10.0
bash
dotnet add package Doconut.NETFramework --version 26.10.0

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

Web.config 구성

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

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

두 항목과 해당 설정을 추가합니다:

xml
<configuration>
  <system.web>
    <!-- MVC 5 only: Razor는 런타임에 뷰를 컴파일하고 netstandard 파사드가 필요합니다. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength는 KILOBYTES 단위: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- UTF-8로 .cshtml 및 .aspx 파일을 읽고, 서버의 ANSI 코드 페이지로 읽지 마세요. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength는 BYTES 단위: 동일한 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"> — 바이트 순서 표시가 없는 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은 DoconutHost.Initialize가 Application_Start에서 한 번 워커 프로세스당 구성하고, DoconutHost.Shutdown가 Application_End에서 해제합니다:

csharp
// 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는 다음 설정 가능한 속성을 허용합니다. 모두 선택 사항입니다.

속성기본값설명
UnsafeModefalsefalse인 경우, DocImage.axd는 문서를 연 ASP.NET 세션에만 페이지를 제공합니다. true인 경우, 토큰을 포함한 모든 요청이 제공됩니다. false 상태로 두세요.
ShowDoconutInfofalsetrue인 경우, token가 없는 DocImage.axd 요청은 404 대신 버전 배너를 응답합니다. 스모크 체크에 유용하며, 프로덕션에서는 끄세요.
ResourcesPath"/doconut-res"리소스 모듈이 임베디드 스크립트, 스타일 및 아이콘을 제공하는 위치입니다. 뷰어의 ResPath 및 모든 MVC IgnoreRoute와 함께 변경하십시오.
LicensePath""라이선스 파일의 전체 경로입니다. 비어 있으면 다음 소스로 넘어가고, 그 다음 자동 검색으로 넘어갑니다.
LicenseContent""원시 라이선스 내용 — 환경 변수, 비밀 저장소 또는 데이터베이스에서 가져옵니다.
LicenseStreamnull시작 시 한 번 읽는 스트림 형태의 라이선스.
MiddlewarePath"/doconut"이 패키지에서는 사용되지 않습니다. 페이지 엔드포인트는 Web.config에 선언된 DocImage.axd 핸들러이며, 설정값에 관계없이 사용됩니다. 여전히 검증되며, /로 시작하고 ResourcesPath와 달라야 합니다.
ResetLicensefalse이 패키지에서는 사용되지 않습니다. 라이선스는 DoconutHost.Initialize에서 한 번 읽히며, 라이선스 파일을 교체한 후 애플리케이션 풀을 재시작하십시오.
MaxConcurrentEditorSessions200실시간 편집기 세션(DocOptions.EditMode로 연 문서)의 최대 수입니다. 이를 초과하면 가장 오래된 유휴 편집기 세션이 종료됩니다. 일반 뷰어 세션은 계산되지 않습니다. 0 또는 음수 값은 제한이 없음을 의미합니다.
EditorSnapshotEveryOps50편집기 지속성이 활성화된 경우(AddDoconutEditorPersistence), N개의 기록된 변경마다 실시간 문서를 스냅샷합니다. 0 또는 음수 값은 세션 중 스냅샷을 하지 않습니다. 지속성이 비활성화되면 효과가 없습니다.

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

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // viewer\u0027s JS/CSS/images 가 제공되는 위치
    options.UnsafeMode      = false;          // 세션 보안을 유지합니다
    options.ShowDoconutInfo = false;
});
// 여기서는 페이지 엔드포인트를 사용할 수 없습니다: Web.config에 선언된 DocImage.axd 핸들러입니다.

다음 단계

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

이 페이지가 도움이 되었나요?