Visare

Den huvudsakliga dokumentvisarklassen

Viewer (namespace Doconut) är den offentliga ingångspunkten för att öppna dokument från Razor‑sidor, MVC‑kontroller, Blazor‑komponenter eller minimala API:er. Den är sealed, registrerad som en transient tjänst av AddDoconut(), och löses upp via konstruktor‑injektion — skapa den aldrig direkt.

Viewer har ingen per‑begäran‑stat och implementerar not IDisposable: dokumentsessioner lever oberoende i sessionscachen, så att avyttra tjänsten aldrig kan stänga ett öppet dokument (se Core Concepts → How the Viewer Works).

OpenDocumentAsync

Öppnar ett dokument och returnerar sessionstoken som klient‑widgeten använder för alla efterföljande begäran.

ÖverlagringAnvänd när
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Öppning från disk med automatisk formatdetektering och formatets standardkonfiguration
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Du behöver per‑format renderingsalternativ (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)Dokumentet är inte en fil på disk (uppladdning, databas, blob). fileInfo måste ha rätt filändelse — den styr formatdetektering
csharp
// Enkel öppning
string token = await viewer.OpenDocumentAsync(path);

// Med per-format konfiguration och alternativ
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Från en uppladdning
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Undantag att hantera:

  • LicenseException — en hittad licens avvisas (meddelandet innehåller avvisningsorsaken), eller så kräver formatet en plugin‑funktion som inte längre beviljas. Kalenderutgång utan avvisningsmeddelande degraderas till vattenstämpel‑rendering istället för att kasta ett undantag.
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — filinnehållet är korrupt eller matchar inte dess filändelse.

CloseDocument

text
void CloseDocument(string token)

Tar bort sessionen från cachen (avyttrar dokumentmotorn omedelbart), raderar säkerhetsmarkören och återkallar åtkomstbehörigheten. Valfritt — glidande utgång utför samma städning — men rekommenderas för stora dokument.

GetPageCount

text
int GetPageCount(string token)

Totalt antal sidor i den öppna sessionen. Kastar InvalidOperationException (Document session not found. Please re-open document.) om token är okänd eller har gått ut, och ArgumentException för en tom token.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

Dokumentets standardrenderade sidstorlek vid 100 % zoom — koordinatrymden för annotationer byggda i kod. page accepteras för kompatibilitet; resultatet är dokumentets standard. Kastar InvalidOperationException (Document session not found. Please re-open document.) om token är okänd eller har gått ut, och ArgumentException för en tom token.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Returnerar bladnamnen i ett öppet kalkylblad, i arbetsbokens ordning, eller en tom lista när det öppna dokumentet inte är ett kalkylblad.

Endast renderade blad listas: dolda och tomma blad exkluderas, och när ExcelConfig.SheetNames begränsar rendering visas endast de bladen. Ett blad är inte alltid en sida — ett mycket stort blad renderas över flera sidor. Kastar InvalidOperationException (Document session not found. Please re-open document.) om token är okänd eller har gått ut, och ArgumentException för en tom token.

Tillagd i 26.9.0.

Kapacitetsflaggor

MemberMeaning
bool IsSearchEnabledDen aktuella licensen beviljar Search
bool IsAnnotationEnabledDen aktuella licensen beviljar Annotation

Använd dessa i en Razor‑vy för att rendera ett licensierat Ribbon endast när servern faktiskt kommer att leverera det — se Snabbstart.

Dokumentalternativ

Per öppning, formatoberoende alternativ (namnrymd Doconut):

TypEgenskapStandardBeskrivning
stringPassword""Lösenord för skyddade dokument (kopieras automatiskt till formatkonfigurationen).
intImageResolution0Föråldrad. Behålls endast för kompatibilitet — ange ImageResolution i formatkonfigurationen istället.
stringWatermark""Anpassad vattenstämpeltext som ritas på renderade sidor. Formatsträng: "^Text~Color~FontSize~FontName~Opacity~Angle", t.ex. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Sessionens glidande utgång i minuter.
boolIsSecuredtrueEj för närvarande verkställd — reserverad. Tokenbindning styrs globalt av DoconutOptions.UnsafeMode (se Kärnkoncepter → Sessioner & Säkerhet).

Klassen exponerar också specialiserade egenskaper som avsiktligt ligger utanför det normala enkla‑värd‑visningsflödet:

TypEgenskapStandardBeskrivning
boolIsWebFarmfalseFöråldrad — har ingen effekt. Publicera dokumentet med DistributedDocumentPublisher.PublishAsync (eller IDistributedPublishQueue.EnqueueAsync) och ange FileShareConfig.RootPath istället.
stringWebFarmPath""Föråldrad — har ingen effekt. Använd FileShareConfig.RootPath istället.
boolEditModefalseReserverad för det separat distribuerade Editor‑arbetsflödet; lämna false för standardvisaren.

Anpassad vattenstämpel

DocOptions.Watermark använder sex tilde‑separerade fält. En valfri inledande ^ begär layout med alla hörn:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
FältExempelBetydelse
Inledande ^^Valfri layout med alla hörn. Utan den används normal placering av vattenstämpeln.
TextConfidentialText som renderas på varje sida. Den får inte vara tom.
FärgRedNamngiven färg som förstås av ritlagret.
FontStorlek24Teckenstorlek; ogiltig numerisk inmatning faller tillbaka på renderarens standardvärde.
FontNamnVerdanaBegärd typsnittsfamilj. Säkerställ att den är installerad i distributionsmiljön.
Opacitet80Byte‑värde från 0 till 255. Det måste kunna tolkas korrekt.
Vinkel-45Rotationsvinkel i grader; ogiltig numerisk inmatning faller tillbaka på standardvärdet.

Parsern förväntar sig exakt sex fält efter den valfria ^. En ogiltig definition ersätts av SDK:ns synliga Invalid Watermark‑fallback istället för att tyst försvinna.

Licensbeslut

LicensstatusAnpassat värde tillhandahålletRenderat resultat
Giltig betald visningslicensNejRen sida
Giltig betald visningslicensJaAnpassad vattenstämpel
Aktiv tillfällig/Demo-basvisareNejRen basvisarsida
Aktiv tillfällig/Demo-basvisareJaAnpassad vattenstämpel när den rena basvisarsidan gäller
Saknad, avvisad, utgången, fel version eller ogiltig domän‑licensBådaGenomdrifts‑/utvärderingsvattenstämpel; det anpassade värdet åsidosätter den inte
Plugin‑rendering under utvärderingsreglerBådaUtvärderingsvattenstämpel

Samma beslut tillämpas på levererade sidbilder och annoteringsexport. Animerad GIF‑utdata stämplas bildruta för bildruta. En anpassad vattenstämpel är därför en licensierad applikationsfunktion, inte ett sätt att ersätta eller undertrycka utvärderingsvattenstämpeln.

Annotations-API

Server‑sidig inläsning och export av annotationer. Den fullständiga genomgången finns i Guider → Annotationer; gränssnittet är:

MedlemSyfte
AnnotationManager GetAnnotationManager(string token)Manager som är bunden till den öppna sessionens sidimensioner
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Manager med explicita sidimensioner
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Sessionoberoende manager
void LoadAnnotationData(string token, AnnotationManager manager)Läs in annotationer byggda i C# i sessionen
void LoadAnnotationData(string token, string annotationData)Läs in annotationer från den kodade sidan/Base64‑omslaget som returneras av AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Läs in annotationer från XML
XmlDocument GetAnnotationXML(string token)Exportera sessionens annotationer som XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF med inbrända annotationer
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)En PNG per sida, annotationer inbrända, skrivs till directoryPath (skapas om den saknas); returnerar antalet skrivna bilder
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP med PNG-filer per sida med inbrända annotationer

DICOM-metadata

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

Metoden finns för API‑anpassning, men .NET 6 DICOM‑visaren kan inte tillhandahålla tekniska taggar. Den returnerar null för DICOM‑ och icke‑DICOM‑sessioner; i en DICOM‑session skriver den också en engångsvarning som förklarar plattformsbegränsningen. Rendering av sidor, ramar och animationer stöds fortfarande.

Resurs‑hjälpare — ReferenceCss / ReferenceScripts

Generera <link>/<script>‑taggarna för de inbäddade resurserna som levereras av UseDoconutResources(), i korrekt beroendeordning. Paket för licensstyrda funktioner såsom sökning och annotation genereras endast när licensen aktiverar dem, så att klient‑UI‑et förblir konsekvent med serverbeteendet.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + visare + sökning + annotering
string ReferenceScripts(ScriptConfig? config = null)

CssConfig‑flaggor: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (sökning‑styrd), IncludeAnnotationCss (annotation‑styrd).

ScriptConfig‑flaggor: IncludeJQuery (krävs av alla andra), IncludeBootstrap, IncludeViewerScripts (kärna: docViewer.js + splitter + länkar), IncludeSearchScripts och IncludeSearchBar (sökning‑styrd), IncludeAnnotationScripts och IncludeAnnotationBar (annotation‑styrd), EmitFeatureFlags (standard true: skriver också ett inbäddat window.Doconut.features = { search, annotation, editor }‑skript; sätt den till false under en Content‑Security‑Policy som blockerar inbäddade skript).

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

Var den här sidan hjälpsam?