Protocol and API Reference

Protocol and API reference

This checklist maps the public DICOMweb surface in the current source to this guide. Related overloads share an explanation. Transaction classes are singletons (Instance) used to select an operation, while DicomWebService identifies a family. DicomWebRoute describes a transaction’s method, relative path template, required/optional role, WebSocket flag, request and response media types, and default representation; BuildPath expands escaped route values. DicomWebApplicationBuilder.Enable/Disable accept either a service or transaction. RetrieveCapabilities cannot be disabled or replaced. DicomWebCapabilities.Routes is the built application’s immutable route snapshot; CreateContent(baseUri, accept) selects JSON or WADL content, or returns null when neither is acceptable.

Public API area	Guide section
DicomWebApplication, builder, typed request/result, routes, services, transactions, capabilities	Overview, hosting-neutral integration, custom handlers
All six AddStandard... registrations, eight provider interfaces, search plan and provider result models	Standard services, UPS and MPPS providers, other providers
AddDicomWeb, DicomWebAspNetCoreBuilder, options, both MapDicomWeb overloads	ASP.NET Core
DicomWebClient, eight operation groups, options, typed results, raw response, notifications	Client
DicomWebContent, DicomWebPayloadReader, headers, query, media types, multipart, rendering	This page, representations and streaming, and the client

Transaction families

The transaction classes under Aspose.Medical.Dicom.Web.Transactions include: capabilities; WADO-URI DICOM and rendered retrieval; Studies search at study, series, and instance levels; study and study-constrained storage; DICOM, metadata, bulk data, pixel data, frames, rendered, MPR, 3D, and thumbnail retrieval; UPS workitem create, search, retrieve, update, state change, cancellation, subscriptions, and notification opening; storage commitment request and check; modality scheduled procedure step search; MPPS create, update, retrieve; and non-patient instance search, store, and retrieve. The client operation groups map these families to methods. The standard registration table shows which server handlers are supplied and which need providers or declared representations.

Family	Public transaction keys
Common and URI	RetrieveCapabilities, RetrieveUriDicomInstance, RetrieveUriRenderedInstance
Studies search and store	SearchStudies, SearchStudySeries, SearchStudyInstances, SearchStudySeriesInstances, SearchSeries, SearchInstances, StoreInstances, StoreStudyInstances
Studies DICOM and metadata	RetrieveStudy, RetrieveSeries, RetrieveInstance, RetrieveStudyMetadata, RetrieveSeriesMetadata, RetrieveInstanceMetadata
Studies rendered and thumbnail	RetrieveRenderedStudy, RetrieveRenderedMprStudy, RetrieveRendered3DStudy, RetrieveStudyThumbnail, RetrieveRenderedSeries, RetrieveRenderedMprSeries, RetrieveRendered3DSeries, RetrieveSeriesThumbnail, RetrieveRenderedInstance, RetrieveRenderedMprInstance, RetrieveRendered3DInstance, RetrieveInstanceThumbnail, RetrieveRenderedFrames, RetrieveRenderedMprFrames, RetrieveRendered3DFrames, RetrieveFrameThumbnail
Studies bulk, pixel, and frames	RetrieveStudyBulkData, RetrieveStudyPixelData, RetrieveSeriesBulkData, RetrieveSeriesPixelData, RetrieveInstanceBulkData, RetrieveInstancePixelData, RetrieveFrames, RetrieveBulkData
UPS Worklist	CreateWorkitem, RetrieveWorkitem, UpdateWorkitem, ChangeWorkitemState, RequestWorkitemCancellation, SearchWorkitems, SubscribeWorkitem, UnsubscribeWorkitem, SubscribeWorklist, UnsubscribeWorklist, SuspendWorklistSubscription, SubscribeFilteredWorklist, UnsubscribeFilteredWorklist, SuspendFilteredWorklistSubscription, OpenNotificationConnection
Other services	SearchNonPatientInstances, StoreNonPatientInstances, RetrieveNonPatientInstance, StoreNonPatientInstance, RequestStorageCommitment, CheckStorageCommitment, SearchModalityScheduledProcedureSteps, CreateModalityPerformedProcedureStep, UpdateModalityPerformedProcedureStep, RetrieveModalityPerformedProcedureStep

DicomWebTransaction<TTransaction> is the typed dispatch key; DicomWebRequest<TTransaction> wraps the resolved DicomWebRequest. Custom handlers cannot invent arbitrary HTTP routes through the standard builder. DicomWebRouteCatalog.All lists the standard route inventory, Get(transaction) selects one descriptor, and TryResolve(method, path, query, out route, out values) resolves a request. NonPatientInstanceCategories lists supported category path names. DicomWebRequest requires Method, relative Path, and Body; it also carries Query, Headers, ServiceBaseUri, WebSocket flag, route, and PathParameters. GetSearchQuery/GetRenderingParameters expose validated request controls. Request body readers share one forward-only pipe.

Representations and transport values

DicomWebMediaTypes names common DICOM, DICOM JSON, Native DICOM Model XML, multipart, octet-stream, image, video, text, WADL, and problem JSON representations. DicomWebContent combines a concrete media type, optional exact byte length, and DicomWebContentWriter. Omit the length when it is unknown; a supplied length must be non-negative and match the bytes written. The writer receives a destination PipeWriter and cancellation token. It must leave the destination open. WriteToAsync publishes the payload without completing a supplied pipe or closing a supplied stream.

Content factory	Representation
FromBytes	Supplied bytes with the selected media type; the memory must remain valid and unchanged until writing completes.
FromString	UTF-8 text; specify a matching character set in the media type when one is needed.
FromDataset	One DICOM JSON dataset object by default, or one Native DICOM Model XML document.
FromDatasets	A DICOM JSON array by default, or a multipart collection of Native DICOM Model XML documents.
FromDicomFile	One application/dicom Part 10 file.
FromDicomFiles	A multipart Part 10 sequence from an IAsyncEnumerable<DicomFile>.

Content may read or enumerate source data when the host writes it. Keep datasets, files, source memory, and services available until writing completes. A host must write DicomWebResponse.StatusCode, headers, content type, optional content length, and body, or upgrade a DicomWebNotificationSession.

Payload readers

DicomWebPayloadReader accepts a pipe, leaveOpen, parsed content type, and optional IAsyncBulkDataLoader. CreateEmpty supplies an empty body. Select the reader by both the representation and the expected number of datasets or files:

Payload-reader method	Accepted body and result
ReadDatasetAsync	One DICOM JSON dataset object, one Native DICOM Model XML document, or multipart content containing exactly one metadata dataset.
ReadDatasetsAsync	A DICOM JSON array, one XML document, or multipart metadata. JSON metadata parts contain arrays; XML metadata parts contain individual documents. Returns datasets in payload order.
ReadOptionalDatasetAsync	The same metadata forms as ReadDatasetAsync when bytes are present; an empty body produces an empty dataset even without a media type.
ReadDicomFileAsync	One single-part application/dicom payload.
ReadDicomFilesAsync	One single-part application/dicom file or a multipart sequence of Part 10 files. It does not parse raw frame or bulk-data bytes as files.

DicomWebClientResponse exposes the same four non-optional semantic readers and checks HTTP success before parsing. DicomWebRequest also exposes those readers, with one useful difference: its ReadDicomFileAsync accepts either a single-part file or a multipart body containing exactly one file. Zero or multiple files fail that request convenience method. Use the plural reader when the transaction permits several files.

All semantic readers and the raw pipe advance the same forward-only body; choose one consumption path. Keep the payload reader alive until reading or enumeration ends, and dispose it afterward. leaveOpen: false completes the supplied pipe on disposal; true leaves completion to its owner. Content location and part headers identify items in multipart responses created by the library.

Headers and query parameters

DicomWebHeaders is a case-insensitive read-only dictionary of multi-valued fields with Empty, ContainsKey, TryGetValue, GetFirstOrDefault, and GetCommaSeparatedValue. DicomWebQueryParameter is one named, optionally valueless item. Construct DicomWebQueryParameters from decoded names and values; Parse accepts an encoded query with or without its leading ?, and ToString escapes it without adding ?. A literal + is preserved when parsing, so it is not a substitute for an encoded space.

Query names are case-sensitive. Contains, GetValues, and GetFirstOrDefault use the exact name; order and repeated parameters are retained. GetUInt32 returns null when absent and rejects repeated, valueless, negative, or non-integer values. Malformed percent escapes and empty query components fail parsing. Preserve repeated query and header values until protocol validation rather than flattening them into one value.

Search and rendering controls

DicomWebSearchQuery and DicomWebRenderingParameters.Parse are the inbound validated views of search and rendering controls. DicomWebSearchPlan exposes Level, Filter, included attributes, IncludeAllAttributes, Offset, Limit, Matches, and Project. DicomWebSearchFilter.Matches contains the predicate tree of DicomWebSearchMatch nodes: a DicomWebCriterionMatch applies its Criterion at the current dataset scope, and a DicomWebSequenceMatch requires one sequence item to satisfy all its ItemMatches. All matches in a collection must succeed at the same scope. Directly enumerating DicomWebSearchFilter yields the flat criteria; use the tree when translating sequence conditions into backend queries. See the compiled search filter example.

DicomWebSearchCriterion exposes attribute path, match kind, and decoded values. DicomWebAttributePath.Tags runs from the outermost attribute to the matching attribute. DicomWebMatchKind identifies exact, wildcard, inclusive range, UID-list, empty, fuzzy Person Name, and multiple-value matching. Provider candidates should preserve stable ordering and the target level. MPR and 3D are transaction keys and client methods, but the bundled standard Studies handler does not implement their rendering. A custom handler is required for them.

Failures and lifecycle

DicomWebException carries an HTTP status for server-side transaction failures. The application converts it, FormatException, InvalidDataException, JSON/XML parse errors, and DICOM validation errors into responses; other exceptions can reach the host. A client should check status before consuming a raw body and dispose raw responses and one-pass streams. Cancellation propagates through request processing, payload writing, provider enumeration, client transmission, and notification receiving when the caller supplies a token. Ownership of provider storage, HttpClient, host request/response streams, and notification queues remains with the application or host that supplied them.