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 minimal‑API:er. Den är sealed, registrerad som en transient‑tjänst av AddDoconut(), och löses upp via konstruktörsinjektion — skapa den aldrig direkt.

Det föregående .NET Standard‑biblioteket exponerade en offentlig konstruktor som tog minnescachen, HTTP‑kontext‑åtkomsten och en eller flera licensvägar. Den konstruktorn är borta; tjänstegrafen tillhandahåller dessa beroenden.

Viewer har ingen per‑begäran‑status och avsiktligt inte implementerar IDisposable: dokumentsessioner lever oberoende i sessionscachen, så att avyttra tjänsten aldrig kan avsluta ett öppet dokument (se Grundläggande koncept → Hur Visaren fungerar).

OpenDocumentAsync

Öppnar ett dokument och returnerar sessionstoken som klientwidgeten använder för alla efterföljande förfrågningar. Varje öppning är asynkron — det finns ingen synkron OpenDocument.

Ö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 renderingsalternativ per format (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)Dokumentet är inte en fil på disken (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ämpelrendering 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 inbyggda 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.

HämtaKalkylbladsnamn

text
IReadOnlyList<string> GetWorksheetNames(string token)

Returnerar kalkylbladsnamnen för ett öppet kalkylblad, i arbetsboksordning, eller en tom lista när det öppna dokumentet inte är ett kalkylblad.

Endast renderade kalkylblad listas: dolda och tomma kalkylblad exkluderas, och när ExcelConfig.SheetNames begränsar rendering, visas endast dessa kalkylblad. Ett kalkylblad ä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.

Tillagt i 26.9.0.

Kapacitetsflaggor

MedlemBetydelse
bool IsSearchEnabledDen aktuella licensen ger Search
bool IsAnnotationEnabledDen aktuella licensen ger 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 — sätt 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 Core Concepts → Sessions & Security).

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

TypEgenskapStandardBeskrivning
boolIsWebFarmfalseFöråldrad — har ingen effekt. Publicera dokumentet med DistributedDocumentPublisher.PublishAsync (eller IDistributedPublishQueue.EnqueueAsync) och sätt FileShareConfig.RootPath istället. Observera skiftläget — det tidigare biblioteket stavade detta IsWebfarm.
stringWebFarmPath""Föråldrad — har ingen effekt. Använd FileShareConfig.RootPath, enligt beskrivningen i Distribuerade distributioner. Tidigare stavades WebfarmPath.
boolEditModefalseReserverad för ett separat distribuerat redigeringsflöde; lämna false för standardvisaren.

Anpassad vattenstämpel

DocOptions.Watermark använder sex tilde‑avgränsade 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
Leading ^^Valfri layout med alla hörn. Utan den används normal vattenstämpelplacering.
TextConfidentialText som renderas på varje sida. Den får inte vara tom.
ColorRedNamngiven färg som förstås av ritlagret.
FontSize24Teckenstorlek; ogiltig numerisk inmatning faller tillbaka på renderarens standard.
FontNameVerdanaBegärd teckensnittsfamilj. Säkerställ att den är installerad i distributionsmiljön.
Opacity80Bytevärde från 0 till 255. Det måste kunna parsas korrekt.
Angle-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 visningslicensJaAnpassat vattenstämpel
Aktiv tillfällig/demo-basvisareNejRen basvisarsida
Aktiv tillfällig/demo-basvisareJaAnpassat vattenstämpel när den rena basvisarvägen gäller
Saknad, avvisad, utgången, fel version eller ogiltig domänlicensBådaGenomdrivnings-/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 annoteringsexporter. Animerad GIF-utmatning stämplas bildruta för bildruta. Ett anpassat vattenstämpel är därför en licensierad programfunktion, inte ett sätt att ersätta eller undertrycka utvärderingsvattenstämpeln.

Annotations-API

Server‑sidans annoteringsladdning och export. Den fullständiga genomgången finns i Guider → Annotations; gränssnittet är:

MedlemSyfte
AnnotationManager GetAnnotationManager(string token)Manager bunden till den öppna sessionens sidimensioner
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Manager med explicita sidimensioner
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Sessionsoberoende manager
void LoadAnnotationData(string token, AnnotationManager manager)Läs in annoteringar byggda i C# i sessionen
void LoadAnnotationData(string token, string annotationData)Läs in annoteringar från den kodade sidan/Base64‑omslaget som returneras av AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Läs in annoteringar från XML
XmlDocument GetAnnotationXML(string token)Exportera sessionens annoteringar som XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF med inbrända annoteringar
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)En PNG per sida, annoteringar inbrända, skrivet 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 annoteringar

Var och en av dessa tar sessionstoken. Det föregående bibliotekets sessionsfria GetAnnotationManager(pageWidth, pageHeight)-format överlever för att bygga annoteringar utanför en session, men laddning av dem kräver fortfarande en token.

DICOM-metadata

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

Metoden finns för API‑justering, men detta paket kan inte tillhandahålla tekniska DICOM‑taggar: metadata‑läsaren levereras endast med en .NET 8‑byggnad. 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. Sid-, ram‑ och animationsrendering fortsätter att stödjas.

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 annotering genereras endast när licensen möjliggör dem, så att klient‑UI‑et förblir konsekvent med serverbeteendet.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig‑flaggor: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (sök‑styrd), IncludeAnnotationCss (annoterings‑styrd).

ScriptConfig‑flaggor: IncludeJQuery (krävs av alla andra), IncludeBootstrap, IncludeViewerScripts (kärna: docViewer.js + splitter + länkar), IncludeSearchScripts och IncludeSearchBar (sök‑styrd), IncludeAnnotationScripts och IncludeAnnotationBar (annoterings‑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 }))

Dessa hjälpare är det stödjade sättet att leverera webbläsarresurserna. Applikationer som kopierade docViewer.js, documentLinks.js och docViewer.UI.js till wwwroot bör ta bort dessa kopior när sidan renderas från de genererade taggarna.

Var den här sidan hjälpsam?