Hızlı Başlangıç

İlk belgenizi MVC 5 veya Web Forms içinde render edin

Bu adım adım kılavuz, .NET Framework 4.7.2 üzerinde bir ASP.NET uygulamasını kurulu bir paketten tarayıcıda render edilen bir belgeye götürür: Global.asax, bir açma uç noktası, görüntüleyicinin varlıkları, widget ve bunları bağlayan token. Web.config kayıtlarının Kurulum bölümünden geldiği varsayılır — DocImage.axd işleyicisi ve kaynak modülü olmadan, aşağıdakilerin hiçbiri sunucuya ulaşamaz.

Global.asax içinde Doconut'u Oluşturun

MVC 5 uygulaması için tam bir Application_Start:

csharp
// Global.asax.cs - compose once per worker process, release on shutdown.
protected void Application_Start()
{
    Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.UnsafeMode  = false; // a page is served only to the session that opened the document
    });

    // MVC only: keep the two Doconut endpoints out of routing.
    RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}
  • Encoding.RegisterProvider bazı belge formatlarının kullandığı eski kod sayfalarını işleme sunar. İlk belge açılmadan önce bir kez çağırın.
  • UnsafeMode = false varsayılan ayardır ve yanlışlıkla değiştirilmemesi için açıkça belirtilmiştir: DocImage.axd yalnızca belgeyi açan ASP.NET oturumuna bir sayfa sunar.
  • İki IgnoreRoute çağrısı MVC yönlendirmesini DocImage.axd ve /doconut-res/* yollarından uzak tutar; bu yollar işleyici ve modül tarafından sunulur. Web Forms uygulamasının MVC rotası yoktur ve bu satırlara ihtiyacı yoktur.
  • DoconutHost.Shutdown Doconut'un arka plan çalışmasını durdurur ve uygulama havuzu yeniden başlatıldığında hizmetlerini serbest bırakır. Initialize hiç çalışmamış olsa bile güvenle çağrılabilir.

Bir belge açın

Bir belge açmak opak bir token döndürür. Widget bu token'ı her sayfa isteğiyle gönderir.

MVC 5'te bir denetleyici eylemi Viewer hizmetini DoconutHost.Services üzerinden çözer — MVC 5 bunun için yapıcı enjeksiyonu sağlamaz:

csharp
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // The token is opaque - hand it to the viewer, never log or persist it.
    string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
    return Json(new { token });
}

Belge, oturum durumu olan bir istek içinde açılmalıdır, çünkü açılması mevcut ASP.NET oturumuna sayfalara erişim izni verir. MVC denetleyicileri ve Web Forms sayfaları varsayılan olarak oturum durumuna sahiptir. Özel bir IHttpHandler bunu sağlamaz, System.Web.SessionState.IRequiresSessionState arayüzünü uygulamazsa. Bir işleyiciden oturum durumu olmadan belge açarsanız, görüntüleyici her sayfada "You Are Not Authorized To View This Page." mesajını gösterir.

Web Forms'ta, sayfa kendi kod‑arkasında belgeyi açabilir. OpenDocument, OpenDocumentAsync'in senkron formudur ve asenkron sayfalar kullanmayan kod‑arkası için tasarlanmıştır:

csharp
// Default.aspx.cs
protected string Token;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}

Token'ı bir taşıyıcı kimlik bilgisi gibi ele alın: asla kaydetmeyin veya saklamayın; sadece widget'a verin. Belge oturumu sona erdiğinde çalışmayı durdurur — yeni bir token almak için belgeyi tekrar açın.

Görüntüleyici varlıklarını referans ver

Viewer.ReferenceCss ve Viewer.ReferenceScripts gömülü varlıklar için <link> ve <script> etiketlerini bağımlılık sırasına göre, /doconut-res/ adresine işaret ederek üretir. Widget bir jQuery eklentisidir, bu yüzden jQuery önce gelir.

MVC 5. Görünümlerde @inject yoktur, bu yüzden etiketleri denetleyicide üretip ViewBag üzerinden aktarın:

csharp
public ActionResult Index()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
    {
        IncludeBootstrapCss = true,
        IncludeViewerCss    = true
    });
    ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
    {
        IncludeJQuery        = true,
        IncludeBootstrap     = true,
        IncludeViewerScripts = true
    });
    return View();
}
html
@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)

Bu işi denetleyicide tutun. MVC 5 görünümleri ilk kez sunulduğunda derler ve ekstra bir derleyici paketi olmadan bu derleyici yalnızca C# 5'i anlar — ?. yok, $"..." yok, nameof yok. Bunları kullanan bir görünüm Visual Studio'da sorunsuz derlenir, ardından tarayıcıda boş bir 500 hatası verir.

Web Forms. Aynı dizeleri kod‑arkasından ortaya çıkarın ve <%= %> ile yazın:

html
<head>
    <%= ViewerCss %>
</head>
<body>
    ...
    <%= ViewerScripts %>
</body>

IncludeViewerCss ve IncludeViewerScripts zorunlu çekirdektir. Arama ve Açıklama şeritlerini eklemek için ayrıca IncludeSearchCss, IncludeAnnotationCss, IncludeSearchScripts, IncludeSearchBar, IncludeAnnotationScripts ve IncludeAnnotationBar ayarlarını da yapın. Lisans bu yeteneği vermediğinde her iki yöntem de bir şeridin dosyalarını dışarı bırakır; görüntüleyici yine de başlar.

Görüntüleyiciyi bir sayfaya ekleyin

Renderleme yüzeyi iki iç içe div'dir:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Dış div'e gerçek bir yükseklik verin — görüntüleyici konteynerini doldurur ve başladığında onu ölçer. Görüntüleyici kendi araç çubuğunu çizmez: GotoPage, Next, Zoom, FitType ve diğerleri, sayfanızın kendi düğmelerine bağladığı yöntemlerdir ve görüntüleyicinin yanına yerleştirilir:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
</nav>

Görüntüleyiciyi başlatın ve belgeyi gösterin

Görüntüleyici betiklerinden sonra widget'ı oluşturun, ardından ona token'ı verin:

javascript
var objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // '/' means DocImage.axd at the site root
    ResPath:    'doconut-res/images',  // no leading '/'
    onViewerReady: function () {
        // pages are visible; hide a loading indicator here
    },
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

fetch('/Document/Open', { method: 'POST' })
    .then(function (resp) { return resp.json(); })
    .then(function (data) { objViewer.View(data.token); });

Web Forms'ta, sayfanın belgeyi kendisi açtığı yerde, son üç satır objViewer.View('<%= Token %>'); haline gelir.

Buradaki dört detay hata mesajı olmadan başarısız olur:

  • BasePath: '/' site kökünde DocImage.axd adresini gösterir. Sanal bir dizinde bir uygulama için, adını eğik çizgi olmadan kullanın ('myapp' /myapp/DocImage.axd isteği yapar). Başta bir eğik çizgi ('/myapp') //myapp/DocImage.axd üretir, tarayıcı bunu başka bir ana bilgisayara istek olarak okur.
  • ResPath: 'doconut-res/images' — simgeler kaynak kökünün bir klasör altındadır. 'doconut-res' ile her simge 404 döner: araç çubuğu glifleri ve yükleme döndürücüsü yok, belge ise yine de renderlanır. Baştaki eğik çizgi, BasePath gibi aynı şekilde bozar.
  • Geri çağrılar seçeneklerdir. onViewerReady, onError ve diğerleri docViewer(...)'a geçirilen nesne içinde yer alır. Görüntüleyicinin adıyla aynı olan bir global fonksiyon, örneğin ctlDoc_ViewerReady, asla çağrılmaz.
  • Görüntüleyiciyi tutun, ardından View'i ayrı ayrı çağırın. docViewer(...) Zoom, Next ve FitType içeren nesneyi döndürür; View(...) başka bir şey döndürür. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) belgeyi renderlar, ardından ilk araç çubuğu tıklamasında objViewer.Zoom is not a function hatası verir.

Seçenek adları camelCase (showThumbs, autoLoad, pageZoom) ve PascalCase (FitType, BasePath, ResPath) karışımıdır. Yanlış yazılmış bir seçenek yok sayılır ve widget varsayılanını kullanır.

Tek satırlık alternatif

Yalnızca bir belge göstermeniz gereken, kendi araç çubuğunuz olmayan bir sayfa için, Viewer.RenderViewer tüm başlatma betiğini yazar — docViewer(...) ile BasePath: '/' ve ResPath: 'doconut-res/images', ardından .View(token). Bu yalnızca bu pakette bulunur:

csharp
// Web Forms code-behind, after opening the document
ViewerInit = viewer.RenderViewer("div_ctlDoc", Token);
html
<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>

Yakınlaştırma, sığdırma veya küçük resim panelini değiştirmek için üçüncü argüman olarak bir ViewerConfig geçin. Oluşturulan betik görüntüleyiciye referans tutmadığından, sayfanızın kendi araç çubuğuna ihtiyacı olduğunda yukarıdaki elle yazılmış başlatmayı kullanın.

Belgeyi kapat

Kullanıcı görüntüleyiciden ayrıldığında veya bir yenisi açıldığında objViewer.Close(true) çağırın: widget'ı temizler ve DocImage.axd adresine bir kapatma isteği gönderir. Argümansız objViewer.Close() yalnızca widget'ı temizler. Sunucuda, viewer.CloseDocument(token) belge oturumunu anında kaldırır, render kaynaklarını serbest bırakır ve oturumun sayfalara erişimini iptal eder. Kayma süresi sonunda aynı şeyi yapar, ancak büyük belgeleri açıkça kapatmak belleği daha erken serbest bırakır.

Çalıştır

~/files/Sample.pdf konumuna bir PDF koyun, siteyi IIS Express'te (Visual Studio'da F5) başlatın ve widget'ı barındıran sayfayı açın. İlk sayfa, sol tarafta küçük resimlerle görüntülenir. Görüntülenmezse, Sorun Giderme bölümüne bakın.

Lisans olmadan neler elde edersiniz

Eksik bir lisans hata vermez. Görüntüleyici normal şekilde render eder, ancak her sayfa bir değerlendirme filigranı taşır. Doconut'un lisansınızı nerede aradığını görmek için Lisans Kurulumu bölümüne bakın.

Bu sayfa yardımcı oldu mu?