DICOM Plugin
View medical images with DicomPlugin
The DICOM plugin adds medical-image viewing to Doconut: multi-frame DICOM files render as an animated overview, individual frames, or both. DICOM is a plugin-only format — without this plugin (and its license capability), .dcm files cannot be opened at all.
On .NET Framework 4.7.2, DICOM files render fully — pages, frames, and animation — but technical metadata (the DICOM tags) is not available.
Viewer.GetDicomMetadataAsyncalways returnsnull, and the viewer's metadata request (?token=…&meta=1onDocImage.axd) answers404, so the viewer shows no DICOM properties panel. UseDoconut.NET8if your application needs the tags.
| Surface | Use it when |
|---|---|
Viewer with DicomConfig (C#) | You open DICOM files on the server and choose how their frames are presented |
The viewer (docViewer) on DocImage.axd | You show the study in your page: animation and frames |
The plugin has no widget of its own: DICOM files open in the regular viewer. With the Converter plugin also registered, .dcm and .ima files can be converted to Pdf, Png, Jpeg, Bmp, Tiff or Gif; that conversion needs the Dicom capability as well.
Install the package
Install-Package Doconut.NETFramework.DicomTo pin the plugin to the release this documentation describes:
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0Keep the DICOM package at the same version as Doconut.NETFramework.
The plugin's license file, Doconut.Viewer.Dicom.lic, goes in the same folder as Doconut.Viewer.lic; it is read together with the viewer license.
Register the plugin
Doconut.DoconutHost.Initialize(options =>
{
options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});The plugin (Name: "Doconut DICOM Viewer") registers viewers for the .dcm and .ima extensions, gated by the Dicom capability. If the license does not grant it, DoconutHost.Initialize throws from Application_Start:
The Dicom plugin is registered via AddPlugin but no active license grants Dicom. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Dicom.In System.Web that means every request answers an empty 500, and the reason is only in the Windows event log (source ASP.NET). It throws for no license, a legacy TRIAL file, a license without Dicom, and a paid license used outside its version window. Temporary Demo/NFR licenses are accepted. See License Setup.
Because no built-in viewer handles these formats, opening one fails outright if the capability later becomes unavailable:
LicenseException: This document type requires the 'Dicom' plugin license.Licensing & watermark
| License state | Startup | DICOM output |
|---|---|---|
Paid license granting Dicom, within its version window | Starts | Rendered under the normal page watermark rules |
| Active Temporary (Demo/NFR) license | Starts | Rendered with the evaluation watermark |
No license, a legacy TRIAL file, a license without Dicom, or a paid license outside its version window | Application_Start throws; every request answers an empty 500 | — |
The normal page watermark decision also applies to DICOM output. For animated output, each GIF frame is stamped, so the mark stays visible throughout playback. A custom DocOptions.Watermark is used only when the license permits custom watermarks; it cannot replace an evaluation watermark.
Use from C#
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
DisplayMode = DicomDisplayMode.AnimationAndFrames
});var metadata = await viewer.GetDicomMetadataAsync(token);
// On .NET Framework this is always null: the DICOM metadata reader is not available for this
// target. Pages, frames and animation render normally.The method exists on this package so that code shared with the .NET 8 package compiles, but reading DICOM tags needs a component that has no .NET Framework build. Plan your user interface without them — for example, hide a metadata panel when the result is null.
Display modes and resolution
Display modes
Multi-frame DICOM files can be presented three ways (DicomDisplayMode):
| Mode | Pages produced | Use for |
|---|---|---|
AnimationOnly | Page 1 = animated GIF looping all frames | Quick cinematic review |
FramesOnly | Pages 1..N = one static PNG per frame | Frame-by-frame diagnostic navigation |
AnimationAndFrames (default) | Page 1 = animated GIF, pages 2..N+1 = one static PNG per frame (N = frame count) | Overview and detail in one document |
Animation timing is controlled by AnimationFrameDelayMs (default 100 ms = 10 FPS; GIF timing uses 10 ms units) and LoopCount (0 = loop forever).
The viewer finds out that page 1 is animated by sending a HEAD request for it. The DocImage.axd handler must therefore accept HEAD in Web.config (verb="GET,HEAD,POST", see Installation); without it, IIS answers 404 before Doconut runs and animation detection never works.
Resolution
DicomConfig renders at 100 DPI per axis by default. If you don't set HorizontalResolution/VerticalResolution explicitly, they follow BaseConfig.ImageResolution when that is set, and only then fall back to 100.
// Uniform bump via the base property…
new DicomConfig { ImageResolution = 150 };
// …or per-axis control
new DicomConfig { HorizontalResolution = 200, VerticalResolution = 150 };Build your own frontend
Page images, including the animated first page, use the standard DocImage.axd image route. The metadata request, GET /DocImage.axd?token=<token>&meta=1, answers 404 on this package for every document, DICOM files included, because the metadata reader is not available.
In production
Multi-frame studies can produce both an animation and one static page per frame. AnimationAndFrames gives the richest navigation but also the highest rendering and memory cost — and on a single server that memory belongs to the IIS worker process. For large studies:
- use
FramesOnlywhen frame inspection matters more than playback; - avoid raising both resolution axes without measuring memory;
- close the session explicitly when the study is no longer open;
- keep
CachePageson only when repeat access is worth the retained images.
Put Doconut.Viewer.Dicom.lic next to Doconut.Viewer.lic on every server, and keep HEAD in the handler's verb list.
API reference
DicomConfig, DicomDisplayMode and DicomMetadata are in the Doconut namespace. DicomPlugin is in Doconut.Plugins.Dicom. The complete DicomConfig property table is in Format Configs.
DicomConfig
public sealed class DicomConfig : BaseConfig
{
public int HorizontalResolution { get; set; } // default: ImageResolution when set, else 100
public int VerticalResolution { get; set; } // default: ImageResolution when set, else 100
public int AnimationFrameDelayMs { get; set; } = 100;
public ushort LoopCount { get; set; } = 0; // 0 = loop forever
public DicomDisplayMode DisplayMode { get; set; } = DicomDisplayMode.AnimationAndFrames;
}DicomDisplayMode
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }Viewer.GetDicomMetadataAsync
public Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default);Always returns null on this package. Throws InvalidOperationException when the token is unknown or expired. DicomMetadata is defined so that code shared with the .NET 8 package compiles.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Every request answers an empty 500 after adding the plugin; the Windows event log (source ASP.NET) shows The Dicom plugin is registered via AddPlugin but no active license grants Dicom. | No license, a TRIAL file, a license without Dicom, or a paid license outside its version window | Install a license that grants Dicom, or remove AddPlugin<DicomPlugin>() |
Opening a .dcm file throws Document format '.dcm' is not supported. | DicomPlugin is not registered, or its package is not deployed | Add AddPlugin<DicomPlugin>() in DoconutHost.Initialize and deploy the package |
Opening a .dcm file throws LicenseException: This document type requires the 'Dicom' plugin license. | The loaded license no longer grants Dicom | Install a license that grants Dicom |
| Only one page appears | The source is single-frame, or DisplayMode is AnimationOnly | Use FramesOnly or AnimationAndFrames for a multi-frame source |
| Page 1 does not animate | The handler in Web.config does not accept HEAD | Use verb="GET,HEAD,POST" |
| Animation is too fast or slow | AnimationFrameDelayMs is off; GIF timing uses 10 ms units | Adjust AnimationFrameDelayMs |
| Memory grows on large multi-frame files | Display mode, resolution and page cache all add retained images | See In production; close sessions explicitly |
Metadata is always null | Expected on this package | Use the .NET 8 package when you need the tags |
GetDicomMetadataAsync throws Document session not found. Please re-open document. | The token expired or was never opened | Open the document again |
Framework notes
Compared with the ASP.NET Core packages, this package differs in hosting and in DICOM metadata:
- Registration is in
Application_Start, throughDoconutHost.Initialize, instead ofbuilder.Services.AddDoconut. - Startup failures surface as an empty
500on every request, with the reason in the Windows event log. - Animation detection needs
HEADin theDocImage.axdhandler'sverblist. - No DICOM metadata.
Viewer.GetDicomMetadataAsyncalways returnsnulland logs a one-time warning for a DICOM session; theDocImage.axdmetadata request answers404, not the501of the .NET 6 and .NET Standard packages. - Windows only, like the rest of the .NET Framework package.
Was this page helpful?