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.GetDicomMetadataAsync always returns null, and the viewer's metadata request (?token=…&meta=1 on DocImage.axd) answers 404, so the viewer shows no DICOM properties panel. Use Doconut.NET8 if your application needs the tags.

SurfaceUse 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.axdYou 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

powershell
Install-Package Doconut.NETFramework.Dicom

To pin the plugin to the release this documentation describes:

powershell
Install-Package Doconut.NETFramework.Dicom -Version 26.10.0

Keep 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

csharp
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:

text
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:

text
LicenseException: This document type requires the 'Dicom' plugin license.

Licensing & watermark

License stateStartupDICOM output
Paid license granting Dicom, within its version windowStartsRendered under the normal page watermark rules
Active Temporary (Demo/NFR) licenseStartsRendered with the evaluation watermark
No license, a legacy TRIAL file, a license without Dicom, or a paid license outside its version windowApplication_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#

csharp
var token = await viewer.OpenDocumentAsync(path, new DicomConfig
{
    DisplayMode = DicomDisplayMode.AnimationAndFrames
});
csharp
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):

ModePages producedUse for
AnimationOnlyPage 1 = animated GIF looping all framesQuick cinematic review
FramesOnlyPages 1..N = one static PNG per frameFrame-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.

csharp
// 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 FramesOnly when 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 CachePages on 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

csharp
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

csharp
public enum DicomDisplayMode { AnimationOnly, FramesOnly, AnimationAndFrames }

Viewer.GetDicomMetadataAsync

csharp
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

SymptomCauseFix
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 windowInstall 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 deployedAdd 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 DicomInstall a license that grants Dicom
Only one page appearsThe source is single-frame, or DisplayMode is AnimationOnlyUse FramesOnly or AnimationAndFrames for a multi-frame source
Page 1 does not animateThe handler in Web.config does not accept HEADUse verb="GET,HEAD,POST"
Animation is too fast or slowAnimationFrameDelayMs is off; GIF timing uses 10 ms unitsAdjust AnimationFrameDelayMs
Memory grows on large multi-frame filesDisplay mode, resolution and page cache all add retained imagesSee In production; close sessions explicitly
Metadata is always nullExpected on this packageUse 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 openedOpen 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, through DoconutHost.Initialize, instead of builder.Services.AddDoconut.
  • Startup failures surface as an empty 500 on every request, with the reason in the Windows event log.
  • Animation detection needs HEAD in the DocImage.axd handler's verb list.
  • No DICOM metadata. Viewer.GetDicomMetadataAsync always returns null and logs a one-time warning for a DICOM session; the DocImage.axd metadata request answers 404, not the 501 of the .NET 6 and .NET Standard packages.
  • Windows only, like the rest of the .NET Framework package.

Was this page helpful?