Client Operations

Client operation reference

The operation group types are DicomWebCapabilitiesOperations, DicomWebUriOperations, DicomWebStudiesOperations, DicomWebWorklistOperations, DicomWebStorageCommitmentOperations, DicomWebModalityWorklistOperations, DicomWebModalityPerformedProcedureStepOperations, and DicomWebNonPatientInstanceOperations.

All methods below are members of the operation group exposed by DicomWebClient. They accept a final optional CancellationToken. A search returns a one-pass DicomWebClientStream<Dataset>; a multi-instance DICOM retrieval returns DicomWebClientStream<DicomFile>. A raw DicomWebClientResponse must be disposed. Other operations return DicomWebClientResult<T> (or DicomWebClientResult for subscription changes), with HTTP metadata and a consumed value. See client lifetime and error handling.

Group	Methods	Input and result distinction
Capabilities	RetrieveAsync	Accepts DicomWebRetrieveOptions; returns a raw JSON or WADL response.
Uri	RetrieveDicomInstanceAsync, RetrieveRenderedInstanceAsync	Both use study, series, and SOP Instance UIDs; DICOM retrieval materializes RetrieveUriDicomInstanceResult.File. Rendered retrieval requires a concrete non-DICOM contentType and returns raw content. See the WADO-URI example.
ModalityWorklist	SearchAsync	Accepts DicomWebSearchOptions; streams scheduled procedure step datasets.
StorageCommitment	RequestAsync, CheckResultAsync	Request takes a transaction UID and Dataset or DicomWebContent; check takes that UID. Both return IsPending and optional Report.
ModalityPerformedProcedureSteps	CreateAsync, UpdateAsync, RetrieveAsync	Create/update take MPPS UID and either Dataset or DicomWebContent; retrieve takes UID. Mutation results contain optional status reports; retrieve returns ProcedureStep.
NonPatientInstances	SearchAsync, StoreAsync, RetrieveAsync	All take category. Store accepts a single file, synchronous or asynchronous file sequence, or content; a single-instance route additionally takes instanceUid and a file or content. Search streams datasets; store returns the STOW report; retrieve materializes a file.

Studies

Scope	Methods	Result
All studies	SearchAsync, SearchSeriesAsync, SearchInstancesAsync	Dataset streams at the requested level.
Store	StoreAsync and StoreStudyAsync	StoreAsync addresses the Studies root; StoreStudyAsync additionally takes the target Study UID. Each accepts one DicomFile, IEnumerable<DicomFile>, IAsyncEnumerable<DicomFile>, or DicomWebContent, and returns StoreInstancesResult.Response.
Study	RetrieveStudyAsync, RetrieveStudyMetadataAsync, RetrieveRenderedStudyAsync, RetrieveRenderedMprStudyAsync, RetrieveRendered3DStudyAsync, RetrieveStudyThumbnailAsync, RetrieveStudyBulkDataAsync, RetrieveStudyPixelDataAsync, SearchSeriesAsync(studyUid), SearchInstancesAsync(studyUid)	DICOM file stream, metadata/search dataset stream, or raw representation response as named.
Series	RetrieveSeriesAsync, RetrieveSeriesMetadataAsync, RetrieveRenderedSeriesAsync, RetrieveRenderedMprSeriesAsync, RetrieveRendered3DSeriesAsync, RetrieveSeriesThumbnailAsync, RetrieveSeriesBulkDataAsync, RetrieveSeriesPixelDataAsync, SearchInstancesAsync(studyUid, seriesUid)	Takes Study and Series UIDs. DICOM/metadata methods stream files/datasets; representations are raw responses.
Instance	RetrieveInstanceAsync, RetrieveInstanceMetadataAsync, RetrieveRenderedInstanceAsync, RetrieveRenderedMprInstanceAsync, RetrieveRendered3DInstanceAsync, RetrieveInstanceThumbnailAsync, RetrieveInstanceBulkDataAsync, RetrieveInstancePixelDataAsync	Takes Study, Series, and SOP Instance UIDs. DICOM retrieval returns RetrieveInstanceResult.File; metadata streams datasets; representations are raw responses.
Frames	RetrieveFramesAsync, RetrieveRenderedFramesAsync, RetrieveRenderedMprFramesAsync, RetrieveRendered3DFramesAsync, RetrieveFrameThumbnailAsync	Takes the three UIDs and a nonempty IReadOnlyCollection<int> of distinct, one-based frame numbers; returns a raw response.
Bulk data path	RetrieveBulkDataAsync	Takes a path relative to the configured Studies service root, such as "bulkdata/1.2.3/1.2.3.4/1.2.3.4.5/7FE00010", and returns a raw response. It does not resolve an arbitrary absolute BulkDataURI; see bulk-data paths and external references.

DicomWebSearchOptions applies to every search. DICOM and metadata retrieval methods use DicomWebRetrieveOptions. Rendered, MPR, 3D, and thumbnail methods use DicomWebRenderOptions; bulk, pixel, and unrendered frame retrieval use DicomWebRetrieveOptions. These methods send standard transactions; remote availability depends on the server’s capabilities, provider, and representation media types.

UPS Worklist

Task	Methods and overloads	Value
Create/search/retrieve	CreateAsync(Dataset or DicomWebContent), SearchAsync, RetrieveAsync(workitemUid)	Created UID and optional status report, dataset stream, or retrieved workitem.
Update	UpdateAsync(workitemUid, Dataset), UpdateAsync(workitemUid, transactionUid, Dataset), UpdateAsync(workitemUid, DicomWebContent)	Optional status report. The transaction UID overload addresses a claimed workitem.
Change state	ChangeStateAsync(workitemUid, Dataset), ChangeStateAsync(workitemUid, DicomWebContent), ChangeStateAsync(workitemUid, WorkitemState, transactionUid)	ChangeWorkitemStateResult; the typed overload constructs the state-change content.
Request cancellation	RequestCancellationAsync overloads take a workitem UID plus optional requester and either a Dataset, DicomWebContent, or no explicit payload	Optional status report. The requester overload identifies the requesting AE Title.
Workitem subscription	SubscribeWorkitemAsync, UnsubscribeWorkitemAsync	Workitem UID and subscriber AE Title; HTTP outcome.
Worklist subscription	SubscribeWorklistAsync, UnsubscribeWorklistAsync, SuspendWorklistSubscriptionAsync	Subscriber AE Title; HTTP outcome.
Filtered worklist subscription	SubscribeFilteredWorklistAsync, UnsubscribeFilteredWorklistAsync, SuspendFilteredWorklistSubscriptionAsync	Subscriber AE Title; requires server-side filtered-subscription support.
Notification connection	ConnectNotificationsAsync	Requester AE Title, optional ClientWebSocketOptions callback, and token; returns a disposable connection.

The root client also offers ConnectNotificationsAsync, with the same connection contract. Body-operation overloads accept DicomWebRequestOptions, except ChangeStateAsync(workitemUid, WorkitemState, transactionUid, cancellationToken). Use a Dataset or DicomWebContent state-change overload when you need additional headers or query parameters. Retrieve operations accept DicomWebRetrieveOptions. DicomWebClient.SendAsync remains available when a high-level operation does not expose the response body exactly as your application needs.

Typed result values

StoreInstancesResult.Response is the STOW response dataset. RetrieveInstanceResult.File, RetrieveUriDicomInstanceResult.File, and RetrieveNonPatientInstanceResult.File hold a DicomFile. Non-patient instance retrieval can construct that file from a metadata response, so its presence does not mean the server sent Part 10 bytes. CreateWorkitemResult has the assigned WorkitemUid and an optional StatusReport; RetrieveWorkitemResult.Workitem holds the workitem dataset. UpdateWorkitemResult and RequestWorkitemCancellationResult carry optional status reports, while ChangeWorkitemStateResult indicates a successful state change. RequestStorageCommitmentResult and CheckStorageCommitmentResult expose IsPending and an optional Report. CreateModalityPerformedProcedureStepResult and UpdateModalityPerformedProcedureStepResult carry optional status reports; RetrieveModalityPerformedProcedureStepResult.ProcedureStep holds the retrieved dataset.