DICOM Serialization

Contents
[ ]

DICOM Serialization and Deserialization

Aspose.Medical converts DICOM data to and from the DICOM JSON Model and Native DICOM Model XML. The serializers preserve DICOM tags, Value Representations (VRs), nested sequences, text encodings, numeric values, and inline binary data. Loaders and converters support values stored through external Bulk Data references.

The API offers several I/O shapes so an application can choose the one that fits its own data flow:

Scenario JSON XML
Work with text already in memory Serialize or deserialize a string Serialize or deserialize a string
Read or write files and general .NET I/O Synchronous or asynchronous Stream APIs Synchronous or asynchronous Stream APIs
Integrate with ASP.NET Core, pipelines, or backpressure-aware components PipeReader and PipeWriter APIs PipeReader and PipeWriter APIs
Process a collection as items become available Read or write IAsyncEnumerable<Dataset?> Read consecutive XML fragments as IAsyncEnumerable<Dataset>; serialize individual Dataset documents
Round-trip a complete DICOM file representation DicomFile APIs Not applicable; Native DICOM XML represents a dataset
Keep large values outside the document BulkDataURI, IBulkDataConverter, and synchronous or asynchronous loaders BulkData, IBulkDataConverter, and synchronous or asynchronous loaders

Strings are convenient for short-lived in-memory transformations. Streams fit files, network responses, compression layers, and other established .NET components. Pipes allow serialization and deserialization to participate directly in producer/consumer flows while the application retains control of flushing, completion, cancellation, and buffer thresholds. JSON asynchronous enumeration is useful when a DICOM JSON array should be produced or consumed one dataset at a time.

Bulk Data handling is independent of the selected I/O shape. An IBulkDataConverter can write selected element values as external references. When deserializing XML or JSON that contains or may contain Bulk Data references, explicitly set BulkDataLoader in the serializer options. If the serializer encounters a Bulk Data reference without a configured loader, it throws MedicalApiException. DefaultBulkDataLoader.Instance is available for unauthenticated file, http, and https references, but it is not selected implicitly.

An IBulkDataLoader supplies referenced values synchronously. For asynchronous deserialization, prefer an IAsyncBulkDataLoader so the data source can use asynchronous I/O and observe the operation’s cancellation token. DefaultBulkDataLoader implements IAsyncBulkDataLoader. These extension points let an application choose the storage policy, authentication model, buffering strategy, and concurrency appropriate for its environment.

Custom IAsyncBulkDataLoader implementations provide Register(string uri) as well as GetData and GetDataAsync. Registration records a reference for later retrieval; a loader that needs no preparation can leave Register empty. Asynchronous loading may resolve different references concurrently, so shared loader state must support concurrent calls. Returned asynchronous memory may be retained and modified by the element and must remain valid while it is in use.

Both option types implement IDicomSerializerOptions and expose DeferValueInitialization, which defaults to false. By default, referenced values are initialized before a dataset is returned or yielded. Set this option to true when the metadata must be parsed before referenced data is available, then explicitly initialize the affected elements before reading their values. This does not remove the requirement to configure a Bulk Data loader. The format-specific pages show the initialization methods and their lifetime rules.

Summary

Use the simplest API that preserves the behavior your application needs:

  • Choose strings for small, local transformations and debugging.
  • Choose streams for files and general-purpose synchronous or asynchronous I/O.
  • Choose PipeReader and PipeWriter for pipeline-based applications and explicit backpressure control.
  • Choose JSON IAsyncEnumerable<Dataset?> APIs when dataset collections should be handled incrementally.
  • Explicitly configure a Bulk Data loader before deserializing input that contains or may contain external references.
  • Prefer IAsyncBulkDataLoader for asynchronous deserialization; use DefaultBulkDataLoader.Instance when its supported URI schemes and unauthenticated access fit the application.
  • Enable DeferValueInitialization only when the application will explicitly initialize referenced element values after parsing.

See the format-specific pages for complete examples and ownership rules:

DICOM Error Handling and Exceptions DICOM Networking