Hızlı Başlangıç

İlk belgenizi MVC 5 veya Web Forms'ta render edin

Bu kılavuz, .NET Framework 4.7.2 üzerinde bir ASP.NET uygulamasını kurulu bir paketten tarayıcıda render edilen bir belgeye: Global.asax, bir açık uç noktası, görüntüleyicinin varlıkları, widget ve bunları bağlayan token'a götürür. Kurulum adresindeki Web.config kayıtlarının yerinde olduğunu varsayar — DocImage.axd işleyicisi ve kaynak modülü olmadan, aşağıdakiler sunucuya ulaşamaz.

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

Bir MVC 5 uygulaması için tam bir Application_Start:

csharp
// Global.asax.cs - işçi süreci başına bir kez oluştur, kapatıldığında serbest bırak.
protected void Application_Start()
{
    Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.UnsafeMode  = false; // bir sayfa yalnızca belgeyi açan oturuma sunulur
    });

    // MVC yalnızca: iki Doconut uç noktasını yönlendirmeden dışarıda tut.
    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 erişilebilir hâle getirir. İlk belge açılmadan önce bir kez çağırın.
  • UnsafeMode = false, varsayılan ayardır, yanlışlıkla kimsenin değiştirmemesi için açıkça yazılmıştır: DocImage.axd, belgeyi açan ASP.NET oturumuna yalnızca bir sayfa sunar.
  • İki IgnoreRoute çağrısı, işleyici ve modülün hizmet verdiği DocImage.axd ve /doconut-res/*'den MVC yönlendirmesini uzak tutar. Web Forms uygulamasının MVC rotaları yoktur ve bu satıra ihtiyaç duymaz.
  • DoconutHost.Shutdown, Doconut'ın 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'den çö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>();

    // Token opaktır - görüntüleyiciye ver, asla kaydetme veya saklama.
    string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
    return Json(new { token });
}

Belge, oturum durumuna sahip bir istek içinde açılmalıdır, çünkü açılması mevcut ASP.NET oturumuna sayfalarına erişim izni verir. MVC denetleyicileri ve Web Forms sayfaları varsayılan olarak oturum durumuna sahiptir. Özel bir IHttpHandler bunu içermez, ancak System.Web.SessionState.IRequiresSessionState uygularsa içerir. Bir işleyiciden bunu olmadan bir belge açarsanız, görüntüleyici her sayfada "Bu Sayfayı Görüntüleme Yetkiniz Yok." mesajını gösterir.

Web Forms'ta, sayfa kendisi kod arkası (code-behind) içinde belgeyi açabilir. OpenDocument, OpenDocumentAsync'nin 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ına referans

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/'ye işaret ederek üretir. Widget bir jQuery eklentisidir, bu yüzden jQuery önce gelir.

MVC 5. Görünümlerin @inject yoktur, bu yüzden etiketleri denetleyicide üretin ve ViewBag üzerinden iletin:

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 döndürür.

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 ayarlayı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 ekle

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

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

Dış div'a gerçek bir yükseklik verin — görüntüleyici konteynerini doldurur ve başlarken ölçer. Görüntüleyici kendi araç çubuğunu çizmiyor: GotoPage, Next, Zoom, FitType ve geri kalanları, sayfanızın kendi düğmelerine bağladığı yöntemlerdir, görüntüleyicinin yanında yer alır:

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 ve belgeyi göster

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

javascript
var objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // '/' site kökünde DocImage.axd demektir
    ResPath:    'doconut-res/images',  // başında '/' yok
    onViewerReady: function () {
        // sayfalar görünür; burada bir yükleme göstergesi gizlenir
    },
    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 %>'); olur.

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

  • BasePath: '/' site kökünde DocImage.axd adresler. Sanal bir dizinde bir uygulama için, adını eğik çizgi olmadan kullanın ('myapp' /myapp/DocImage.axd istek yapar). Başta bir eğik çizgi ('/myapp') //myapp/DocImage.axd üretir, bu da tarayıcının başka bir ana bilgisayara istek olarak okumasına neden olur.
  • ResPath: 'doconut-res/images' — simgeler kaynak kökünün bir klasör altında bulunur. 'doconut-res' ile, her simge 404 döndürür: araç çubuğu glifleri ve yükleme döndürücüsü yok, belge ise yine de renderlanır. Başta bir eğik çizgi, BasePath gibi aynı şekilde bozar.
  • Geri çağrılar seçeneklerdir. onViewerReady, onError ve geri kalanı docViewer(...)'a geçirilen nesneye konur. Görüntüleyicinin adıyla aynı olan global bir fonksiyon, örneğin ctlDoc_ViewerReady, asla çağrılmaz.
  • Görüntüleyiciyi tutun, ardından View'ı 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 ile başarısız olur.

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

Tek satırlık alternatif

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

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

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
    ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}
html
<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>

Yakınlaştırmayı, sığdırmayı 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 el yazması 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'a 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 geri çeker. 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

Bir PDF'i ~/files/Sample.pdf konumuna 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 renderlanır. Eğer renderlanmazsa, Sorun Giderme bölümüne bakın.

Lisans olmadan ne elde edersiniz

Eksik bir lisans hata vermez. Görüntüleyici normal şekilde renderlanır, 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?