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.
| Överlagring | Anvä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 |
// 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
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
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
(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
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
| Medlem | Betydelse |
|---|---|
bool IsSearchEnabled | Den aktuella licensen ger Search |
bool IsAnnotationEnabled | Den 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):
| Typ | Egenskap | Standard | Beskrivning |
|---|---|---|---|
string | Password | "" | Lösenord för skyddade dokument (kopieras automatiskt till formatkonfigurationen). |
int | ImageResolution | 0 | Föråldrad. Behålls endast för kompatibilitet — sätt ImageResolution i formatkonfigurationen istället. |
string | Watermark | "" | 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". |
int | TimeOut | 60 | Sessionens glidande utgång i minuter. |
bool | IsSecured | true | Ej 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:
| Typ | Egenskap | Standard | Beskrivning |
|---|---|---|---|
bool | IsWebFarm | false | Fö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. |
string | WebFarmPath | "" | Föråldrad — har ingen effekt. Använd FileShareConfig.RootPath, enligt beskrivningen i Distribuerade distributioner. Tidigare stavades WebfarmPath. |
bool | EditMode | false | Reserverad 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~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Fält | Exempel | Betydelse |
|---|---|---|
Leading ^ | ^ | Valfri layout med alla hörn. Utan den används normal vattenstämpelplacering. |
| Text | Confidential | Text som renderas på varje sida. Den får inte vara tom. |
| Color | Red | Namngiven färg som förstås av ritlagret. |
| FontSize | 24 | Teckenstorlek; ogiltig numerisk inmatning faller tillbaka på renderarens standard. |
| FontName | Verdana | Begärd teckensnittsfamilj. Säkerställ att den är installerad i distributionsmiljön. |
| Opacity | 80 | Bytevärde från 0 till 255. Det måste kunna parsas korrekt. |
| Angle | -45 | Rotationsvinkel 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
| Licensstatus | Anpassat värde tillhandahållet | Renderat resultat |
|---|---|---|
| Giltig betald visningslicens | Nej | Ren sida |
| Giltig betald visningslicens | Ja | Anpassat vattenstämpel |
| Aktiv tillfällig/demo-basvisare | Nej | Ren basvisarsida |
| Aktiv tillfällig/demo-basvisare | Ja | Anpassat vattenstämpel när den rena basvisarvägen gäller |
| Saknad, avvisad, utgången, fel version eller ogiltig domänlicens | Båda | Genomdrivnings-/utvärderingsvattenstämpel; det anpassade värdet åsidosätter den inte |
| Plugin-rendering under utvärderingsregler | Båda | Utvä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:
| Medlem | Syfte |
|---|---|
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
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.
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).
@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?