Documentation – DICOMweb

10-Net: Standard Services

Mon, 01 Jan 0001 00:00:00 +0000

Standard services and provider contracts

Standard handlers are the simplest server starting point when their persistence contracts fit your application. They implement transaction validation, DICOM search matching and projection, response formatting, and relevant workflow rules. They do not install a database, archive, renderer, or subscription store. Implement the provider interfaces against your own infrastructure. Asynchronous provider I/O methods accept a cancellation token; forward it to backend I/O and stop asynchronous enumeration when cancellation is requested. Synchronous capability methods such as GetResponseMediaTypes do not take a token.

Register on DicomWebApplication.CreateBuilder() or use the matching DicomWebAspNetCoreBuilder.AddStandard...() method. The latter resolves providers from each ASP.NET Core application scope. DicomWebStandardServiceOptions.MaximumSearchResults defaults to 1000 and must be positive. It caps results returned by the standard search engines even when a request asks for more. A request’s limit and offset still control its page; backend candidates must be in stable order so repeated pages are meaningful.

Registration	Required provider	Optional provider	Transactions supplied
`AddStandardStudiesService`	`IDicomWebStudiesProvider`, `IDicomWebRepresentationProvider` in the current source	Options	Study, series, and instance search, store, metadata, DICOM and bulk/frame retrieval, plus WADO-URI DICOM retrieval. Rendered routes, including WADO-URI rendered retrieval and thumbnails, depend on declared representation media types. The standard handler does not implement MPR or 3D volume rendering.
`AddStandardWorklistService`	`IDicomWebWorkitemProvider`	`IDicomWebSubscriptionProvider`, options	Create, retrieve, update, change state, search; cancellation request, subscriptions, and notification connection when subscriptions are supplied; filtered subscription routes when the provider declares support
`AddStandardStorageCommitmentService`	`IDicomWebStorageCommitmentProvider`	—	Request and check result
`AddStandardModalityWorklistService`	`IDicomWebModalityWorklistProvider`	Options	Search scheduled procedure steps
`AddStandardModalityPerformedProcedureStepService`	`IDicomWebMppsProvider`	—	Create, update, retrieve performed procedure steps
`AddStandardNonPatientInstanceService`	`IDicomWebNonPatientInstanceProvider`	Options	Search, store, retrieve non-patient instances

The current AddStandardStudiesService source dereferences representations.SupportedMediaTypes during registration. Supply a representation provider, even if its supported media type map is empty. Its default RetrieveAsync can render simple JPEG frames; controls such as viewport, window, and ICC profile, and whole multi-frame rendering require an application renderer. Advertise only combinations your provider can produce.

The current standard representation handler throws NotSupportedException for every MPR and 3D volume-rendering transaction, even if its provider declares a media type. Do not advertise those transaction keys with the standard handler. A replacement custom handler can implement a selected transaction; it must supply its own rendering and response policy. An uncaught NotSupportedException follows the host exception pipeline rather than becoming a DICOMweb error response.

Search providers

IDicomWebStudiesProvider.FindCandidatesAsync, IDicomWebWorkitemProvider.FindCandidatesAsync, IDicomWebModalityWorklistProvider.FindCandidatesAsync, and IDicomWebNonPatientInstanceProvider.FindCandidatesAsync return possible matches, one dataset per resource at DicomWebSearchContext.Level, in stable order. The context also gives the URI’s parent Resource and compiled Plan. A backend may return a superset. The standard engine applies final Plan.Matches, Plan.Project, offset, and limit; filtering a true match out in the backend cannot be repaired by that final pass. Plan.IncludedAttributes and IncludeAllAttributes describe projection, while Offset and Limit describe requested pagination.

Do not apply Plan.Offset or Plan.Limit to the provider’s candidate stream: the standard engine applies them after matching, so backend pagination would skip or truncate results again. Keep attributes needed for matching in each candidate until that pass has run. MaximumSearchResults bounds the response size; it does not bound how many candidates are read. The engine enumerates the full candidate stream to count remaining matches and adds a Warning response header when more results are available. Push supported matching predicates into the backend to reduce that work without discarding true matches.

Plan.Filter is a DicomWebSearchFilter. Its Matches property exposes the predicate tree to use when translating a search into a database query. All nodes in one match collection must succeed against the same dataset. An empty collection matches every dataset.

Match node	Meaning at the current dataset scope
`DicomWebSearchMatch`	Base type for a node; `Tag` identifies the attribute examined at this scope.
`DicomWebCriterionMatch`	Applies its `Criterion` to that attribute. `DicomWebSearchCriterion.Attribute` retains the full `DicomWebAttributePath`, `Kind` identifies the matching rule, and `Values` contains decoded matching values.
`DicomWebSequenceMatch`	Requires at least one item of the sequence identified by `Tag` to satisfy all its `ItemMatches`. Nested sequence nodes apply the same rule recursively. A missing attribute, a non-sequence attribute, or a sequence with no matching item fails this node.

For example, the search keys RequestAttributesSequence.ScheduledProcedureStepID=STEP and RequestAttributesSequence.RequestedProcedureID=PROCEDURE produce one sequence node with two criterion nodes:

RequestAttributesSequence: at least one item must satisfy both
  ScheduledProcedureStepID = STEP
  RequestedProcedureID = PROCEDURE

A sequence containing (STEP, OTHER) in one item and (OTHER, PROCEDURE) in another does not match. A sequence containing (STEP, PROCEDURE) in one item does match. A database translation therefore needs one correlated existence check for the sequence item, with both conditions inside it; separate existence checks could select different items.

Enumerating Plan.Filter directly yields a flat sequence of DicomWebSearchCriterion values from the tree. This is useful for inspecting attribute paths and selecting safe backend predicates, but it does not expose the sequence nodes or their item scopes. Use Filter.Matches and DicomWebSequenceMatch.ItemMatches when preserving those scopes in a backend query. If the backend cannot reproduce a matching rule, return a broader candidate set and let Plan.Matches make the final decision. The library’s final matcher is authoritative.

Search provider examples

The following provider is complete for a read-only, empty modality worklist. Replace its enumeration with a stable backend query when scheduled steps exist:

public sealed class EmptyModalityWorklist : Aspose.Medical.Dicom.Web.Providers.IDicomWebModalityWorklistProvider
{
    public async System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.Dataset> FindCandidatesAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebSearchContext search,
        [System.Runtime.CompilerServices.EnumeratorCancellation] System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        await System.Threading.Tasks.Task.CompletedTask;
        yield break;
    }
}

For Studies, this small in-memory archive demonstrates all three required storage methods. It keeps caller-provided DicomFile objects in process memory and loses them on restart. Replace it with durable storage and database-backed candidate selection for a real service:

public sealed class InMemoryStudies : Aspose.Medical.Dicom.Web.Providers.IDicomWebStudiesProvider
{
    private readonly System.Collections.Concurrent.ConcurrentDictionary<string, Aspose.Medical.Dicom.DicomFile> files = new();

    public System.Threading.Tasks.ValueTask<Aspose.Medical.Dicom.Web.Providers.DicomWebStoreInstanceResult> StoreAsync(
        Aspose.Medical.Dicom.DicomFile instance, System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        string uid = ReadUid(instance.Dataset, Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID);
        bool added = files.TryAdd(uid, instance);
        Aspose.Medical.Dicom.Web.Providers.DicomWebStoreInstanceResult result = new()
        {
            Outcome = added ? Aspose.Medical.Dicom.Web.Providers.DicomWebStoreOutcome.Stored
                            : Aspose.Medical.Dicom.Web.Providers.DicomWebStoreOutcome.Failed
        };
        return System.Threading.Tasks.ValueTask.FromResult(result);
    }

    public async System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.DicomFile> RetrieveAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebResourceIdentifier resource,
        [System.Runtime.CompilerServices.EnumeratorCancellation] System.Threading.CancellationToken cancellationToken = default)
    {
        foreach (Aspose.Medical.Dicom.DicomFile file in Select(resource))
        {
            cancellationToken.ThrowIfCancellationRequested();
            yield return file;
        }
        await System.Threading.Tasks.Task.CompletedTask;
    }

    public async System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.Dataset> FindCandidatesAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebSearchContext search,
        [System.Runtime.CompilerServices.EnumeratorCancellation] System.Threading.CancellationToken cancellationToken = default)
    {
        System.Collections.Generic.HashSet<string> seen = new();
        foreach (Aspose.Medical.Dicom.DicomFile file in Select(search.Resource))
        {
            cancellationToken.ThrowIfCancellationRequested();
            Aspose.Medical.Dicom.Dataset dataset = file.Dataset;
            string study = ReadUid(dataset, Aspose.Medical.Dicom.Tags.Tag.StudyInstanceUID);
            string series = ReadUid(dataset, Aspose.Medical.Dicom.Tags.Tag.SeriesInstanceUID);
            string instance = ReadUid(dataset, Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID);
            string key = search.Level switch
            {
                Aspose.Medical.Dicom.Web.Providers.DicomWebSearchLevel.Study => study,
                Aspose.Medical.Dicom.Web.Providers.DicomWebSearchLevel.Series => study + "/" + series,
                _ => study + "/" + series + "/" + instance
            };
            if (seen.Add(key))
                yield return dataset;
        }
        await System.Threading.Tasks.Task.CompletedTask;
    }

    private System.Collections.Generic.IEnumerable<Aspose.Medical.Dicom.DicomFile> Select(
        Aspose.Medical.Dicom.Web.Providers.DicomWebResourceIdentifier resource)
    {
        string? study = resource.StudyInstanceUid;
        string? series = resource.SeriesInstanceUid;
        string? instance = resource.SopInstanceUid;
        System.Collections.Generic.List<Aspose.Medical.Dicom.DicomFile> selected = new();
        foreach (Aspose.Medical.Dicom.DicomFile file in files.Values)
        {
            if (!string.IsNullOrEmpty(study) && ReadUid(file.Dataset, Aspose.Medical.Dicom.Tags.Tag.StudyInstanceUID) != study)
                continue;
            if (!string.IsNullOrEmpty(series) && ReadUid(file.Dataset, Aspose.Medical.Dicom.Tags.Tag.SeriesInstanceUID) != series)
                continue;
            if (!string.IsNullOrEmpty(instance) && ReadUid(file.Dataset, Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID) != instance)
                continue;
            selected.Add(file);
        }
        selected.Sort((left, right) =>
        {
            string leftKey = ReadUid(left.Dataset, Aspose.Medical.Dicom.Tags.Tag.StudyInstanceUID) + "/" +
                             ReadUid(left.Dataset, Aspose.Medical.Dicom.Tags.Tag.SeriesInstanceUID) + "/" +
                             ReadUid(left.Dataset, Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID);
            string rightKey = ReadUid(right.Dataset, Aspose.Medical.Dicom.Tags.Tag.StudyInstanceUID) + "/" +
                              ReadUid(right.Dataset, Aspose.Medical.Dicom.Tags.Tag.SeriesInstanceUID) + "/" +
                              ReadUid(right.Dataset, Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID);
            return System.StringComparer.Ordinal.Compare(leftKey, rightKey);
        });
        return selected;
    }

    private static string ReadUid(Aspose.Medical.Dicom.Dataset dataset, Aspose.Medical.Dicom.Tags.Tag tag) =>
        dataset.GetSingleValueOrDefault(tag, string.Empty) ?? string.Empty;
}

public sealed class NoRenderedRepresentations : Aspose.Medical.Dicom.Web.Providers.IDicomWebRepresentationProvider
{
    public System.Collections.Immutable.ImmutableDictionary<Aspose.Medical.Dicom.Web.DicomWebTransaction,
        System.Collections.Immutable.ImmutableArray<string>> SupportedMediaTypes { get; } =
        ImmutableDictionary<DicomWebTransaction,
            ImmutableArray<string>>.Empty;

    public System.Collections.Immutable.ImmutableArray<string> GetResponseMediaTypes(
        Aspose.Medical.Dicom.Web.Providers.DicomWebRepresentationRequest request) => [];
}

Aspose.Medical.Dicom.Web.DicomWebApplication application =
    DicomWebApplication.CreateBuilder()
        .AddStandardStudiesService(new InMemoryStudies(), new NoRenderedRepresentations())
        .Build();

In ASP.NET Core, register both provider interfaces in DI and call the adapter builder’s AddStandardStudiesService(). An empty representation declaration leaves application-specific rendered routes out of capabilities. The example returns one instance dataset as the study/series candidate; an archive should construct level-appropriate datasets and consistent search attributes rather than rely on this simplification.

Persistence and representation contracts

Interface	Members and application obligation
`IDicomWebStudiesProvider`	`FindCandidatesAsync` supplies study/series/instance candidates; `StoreAsync(DicomFile)` persists one validated Part 10 instance and returns `DicomWebStoreInstanceResult`; `RetrieveAsync(DicomWebResourceIdentifier)` streams files in stable study/series/instance order. The resource carries optional Study, Series, and SOP Instance UIDs.
`IDicomWebRepresentationProvider`	`SupportedMediaTypes` declares transaction to single-part media types. `GetResponseMediaTypes(DicomWebRepresentationRequest)` reports what a particular request can produce. `RetrieveAsync(request, selectMediaType, token)` returns `DicomWebRepresentationResult` with selected media type, headers, and ordered `DicomWebEncodedRepresentation` items. A delegate selects among offered media types before encoding. The application performs multipart packaging.
`IDicomWebNonPatientInstanceProvider`	`FindCandidatesAsync` supplies category-specific candidates; `StoreAsync(category, DicomFile)` reports each store outcome; `RetrieveAsync(category, sopInstanceUid)` returns the file or `null`.
`IDicomWebWorkitemProvider`	`FindCandidatesAsync` supplies UPS candidates; `GetAsync(uid)` returns `DicomWebVersionedDataset` or `null`; `TryCreateAsync` atomically creates an unused UID; `TryReplaceAsync(uid, expectedRevision, completeReplacement)` atomically changes exactly that revision. Return `false` on conflict. Persist the dataset and opaque revision consistently.
`IDicomWebMppsProvider`	The same `GetAsync`, atomic `TryCreateAsync`, and revision-checked `TryReplaceAsync` pattern for performed procedure steps. The engine validates MPPS state; the provider supplies durable atomic storage.
`IDicomWebStorageCommitmentProvider`	`TryRequestAsync(transactionUid, IReadOnlyList<DicomWebSopReference>)` atomically records a new request and returns its pending or final `DicomWebStorageCommitment`, or `null` on UID collision. `GetAsync` returns the current state/result or `null` for an unknown UID. Safekeeping decisions belong to the backend.
`IDicomWebSubscriptionProvider`	`SupportsFilteredWorklistSubscriptions` controls filtered routes. `UpsertAsync`, `RemoveAsync`, and `SuspendAsync` maintain subscription state; `ResolveRequestingAeTitleAsync` maps host identity when needed. `PublishAsync`, `QueueAsync`, and `PublishStatusAsync` enqueue Event Report datasets; `OpenNotificationsAsync` streams them in delivery order for a requester. The provider owns retention, recipient matching, and delivery semantics.

Provider value type	Meaning
`DicomWebStoreInstanceResult` / `DicomWebStoreOutcome`	`Outcome` is `Stored`, `Warning`, or `Failed`. Optional `Reason` is a DICOM warning or failure code; `RetrieveUri` is an absolute retrieval URI; `CoercedAttributes` is one Original Attributes Sequence item describing changes made before storage. These values contribute to the per-instance STOW response.
`DicomWebVersionedDataset`	Stored `Dataset` with a backend-defined opaque `Revision`; change it on replacement so UPS/MPPS compare-and-replace is atomic.
`DicomWebStorageCommitment` / `DicomWebStorageCommitmentState`	`State` is `Pending`, `Complete`, or `Gone`; `CommittedInstances`, `FailedInstances`, and optional `RetryAfter` describe the result and polling delay. `DicomWebSopReference` carries SOP Class/Instance UIDs, optional Study/Series UIDs, and optional failure reason.
`DicomWebSubscription`	Required `Subscriber`, optional `WorkitemUid` and compiled `Filter`, plus deletion-lock and suspension flags.
`DicomWebSubscriptionUpdateResult` / `DicomWebSubscriptionUpdateOutcome`	`Outcome`, `IsDeletionLockGranted` (default `true`), and `InitialWorkitemUids` report the atomic subscription change and initial State Reports to queue.
`DicomWebRepresentationRequest` / `DicomWebRepresentationResult`	Request, selected `Instances`, and one-based `Frames`; response single-part `MediaType`, ordered encoded `Items`, and early `Headers`. Each `DicomWebEncodedRepresentation` carries content, required `ContentLocation`, and optional part headers.

Do not share mutable datasets across concurrent requests without your own synchronization. DicomWebWorklistEventPublisher can create and publish the UPS SCP restart and optional going-down status reports through the subscription provider (PublishRestartedAsync and PublishGoingDownAsync); the provider still queues and delivers them.

Store results and partial success

Return Stored or Warning only when the individual instance has been stored; Warning reports a stored instance that needs a warning, such as attribute coercion. Return Failed for an expected per-instance rejection so the handler can include it in the response and continue with other instances. Supply the applicable Reason; omitted warning and failure codes default to 0xB000 and 0xC000, respectively. An exception aborts normal response construction. Earlier successful provider calls are not rolled back by the standard handler, including when a later payload cannot be parsed.

Store result	Studies standard handler	Non-Patient Instance standard handler
Every instance stored without warnings	`200 OK`	`200 OK`
At least one stored instance, with warnings or failures	`202 Accepted`	`200 OK`
All instances failed	`409 Conflict`	`409 Conflict`

Inspect the response dataset even after a successful HTTP status. ReferencedSOPSequence identifies stored instances and their optional WarningReason; FailedSOPSequence identifies rejected instances and their FailureReason. The typed client’s StoreInstancesResult.Response contains that dataset for successful HTTP responses. For an all-failed 409, use the DicomWebClientException response diagnostics or the raw client response described in the client guide. A Studies request restricted to one study reports a mismatched Study Instance UID as a failed instance with reason 0xA900 before calling the provider.

The ASP.NET Core equivalent for the example is services.AddScoped<IDicomWebModalityWorklistProvider, EmptyModalityWorklist>() plus services.AddDicomWeb().AddStandardModalityWorklistService(); see the complete application. The standard engine can be combined with a custom replacement for a single transaction; see custom handlers.

For complete provider examples beyond Studies and Modality Worklist, continue with UPS and MPPS workflows, storage commitment and non-patient instances, and representation production.

10-Net: Worklist and Procedure Step Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Worklist and procedure step workflows

UPS Worklist and Modality Performed Procedure Step (MPPS) handlers validate their respective DICOM state transitions. Your provider must store a complete dataset and an opaque revision together. TryReplaceAsync must compare the expected revision and replace the dataset atomically; returning false lets the standard handler retry or report a conflict. UPS additionally needs stable search candidates. The following process-local store implements both contracts so the comparison is visible. Register different instances for the two services; it does not persist data across restarts.

public sealed class InMemoryWorkflowDatasets :
    Aspose.Medical.Dicom.Web.Providers.IDicomWebWorkitemProvider,
    Aspose.Medical.Dicom.Web.Providers.IDicomWebMppsProvider
{
    private readonly object gate = new();
    private readonly System.Collections.Generic.Dictionary<string,
        Aspose.Medical.Dicom.Web.Providers.DicomWebVersionedDataset> items =
        new(System.StringComparer.Ordinal);
    private long nextRevision;

    public async System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.Dataset> FindCandidatesAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebSearchContext search,
        [System.Runtime.CompilerServices.EnumeratorCancellation] System.Threading.CancellationToken cancellationToken = default)
    {
        System.Collections.Generic.List<Aspose.Medical.Dicom.Dataset> snapshot;
        lock (gate)
        {
            snapshot = new();
            System.Collections.Generic.List<string> uids = new(items.Keys);
            uids.Sort(System.StringComparer.Ordinal);
            foreach (string uid in uids)
                snapshot.Add(new Aspose.Medical.Dicom.Dataset(items[uid].Dataset));
        }
        foreach (Aspose.Medical.Dicom.Dataset candidate in snapshot)
        {
            cancellationToken.ThrowIfCancellationRequested();
            yield return candidate;
        }
        await System.Threading.Tasks.Task.CompletedTask;
    }

    public System.Threading.Tasks.ValueTask<Aspose.Medical.Dicom.Web.Providers.DicomWebVersionedDataset?> GetAsync(
        string uid, System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
        {
            Aspose.Medical.Dicom.Web.Providers.DicomWebVersionedDataset? result =
                items.TryGetValue(uid, out DicomWebVersionedDataset? stored)
                    ? new() { Dataset = new(stored.Dataset), Revision = stored.Revision }
                    : null;
            return System.Threading.Tasks.ValueTask.FromResult(result);
        }
    }

    public System.Threading.Tasks.ValueTask<bool> TryCreateAsync(
        string uid, Aspose.Medical.Dicom.Dataset dataset,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
        {
            if (items.ContainsKey(uid))
                return System.Threading.Tasks.ValueTask.FromResult(false);
            items.Add(uid, new() { Dataset = new(dataset), Revision = (++nextRevision).ToString(System.Globalization.CultureInfo.InvariantCulture) });
            return System.Threading.Tasks.ValueTask.FromResult(true);
        }
    }

    public System.Threading.Tasks.ValueTask<bool> TryReplaceAsync(
        string uid, string expectedRevision, Aspose.Medical.Dicom.Dataset replacement,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
        {
            if (!items.TryGetValue(uid, out Aspose.Medical.Dicom.Web.Providers.DicomWebVersionedDataset? current) ||
                !System.StringComparer.Ordinal.Equals(current.Revision, expectedRevision))
                return System.Threading.Tasks.ValueTask.FromResult(false);
            items[uid] = new() { Dataset = new(replacement), Revision = (++nextRevision).ToString(System.Globalization.CultureInfo.InvariantCulture) };
            return System.Threading.Tasks.ValueTask.FromResult(true);
        }
    }
}

The lock makes creation and revision replacement atomic within this one process. The Dataset copy constructor clones elements, including nested sequence datasets, when storing and retrieving a value. This keeps caller mutations from changing stored state before TryReplaceAsync. A real backend must provide the same guarantee across all of its workers. The search snapshot is ordered by UID; the standard engine applies final DICOM matching, projection, and pagination.

UPS subscriptions and notification delivery

IDicomWebSubscriptionProvider owns subscription state and the event queues. This small example supports worklist subscriptions made before workitems are created. It declines workitem and filtered subscriptions; it has no authenticated identity mapping, persistence, replay, or late-subscriber initial reports. Those are application policies to implement when needed. Because this provider cannot resolve an authenticated AE Title, supply the requester query parameter for Change Workitem State and Request Workitem Cancellation.

public sealed class InMemoryWorklistSubscriptions :
    Aspose.Medical.Dicom.Web.Providers.IDicomWebSubscriptionProvider
{
    private readonly object gate = new();
    private readonly System.Collections.Generic.Dictionary<string, Aspose.Medical.Dicom.Web.Providers.DicomWebSubscription> subscriptions =
        new(System.StringComparer.Ordinal);
    private readonly System.Collections.Generic.Dictionary<string, System.Threading.Channels.Channel<Aspose.Medical.Dicom.Dataset>> queues =
        new(System.StringComparer.Ordinal);

    public bool SupportsFilteredWorklistSubscriptions => false;

    public System.Threading.Tasks.ValueTask<Aspose.Medical.Dicom.Web.Providers.DicomWebSubscriptionUpdateResult> UpsertAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebSubscription subscription,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
        {
            if (subscription.WorkitemUid is not null || subscription.Filter is not null)
                return System.Threading.Tasks.ValueTask.FromResult(new Aspose.Medical.Dicom.Web.Providers.DicomWebSubscriptionUpdateResult
                {
                    Outcome = Aspose.Medical.Dicom.Web.Providers.DicomWebSubscriptionUpdateOutcome.Forbidden
                });
            subscriptions[subscription.Subscriber] = subscription;
            GetQueue(subscription.Subscriber);
            return System.Threading.Tasks.ValueTask.FromResult(new Aspose.Medical.Dicom.Web.Providers.DicomWebSubscriptionUpdateResult
            {
                Outcome = Aspose.Medical.Dicom.Web.Providers.DicomWebSubscriptionUpdateOutcome.Applied,
                InitialWorkitemUids = []
            });
        }
    }

    public System.Threading.Tasks.ValueTask<bool> RemoveAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebSubscription subscription,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        if (subscription.WorkitemUid is not null || subscription.Filter is not null)
            return System.Threading.Tasks.ValueTask.FromResult(false);
        lock (gate)
            return System.Threading.Tasks.ValueTask.FromResult(subscriptions.Remove(subscription.Subscriber));
    }

    public System.Threading.Tasks.ValueTask<bool> SuspendAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebSubscription subscription,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
        {
            if (!subscriptions.TryGetValue(subscription.Subscriber, out Aspose.Medical.Dicom.Web.Providers.DicomWebSubscription? current))
                return System.Threading.Tasks.ValueTask.FromResult(false);
            subscriptions[subscription.Subscriber] = new()
            {
                Subscriber = current.Subscriber,
                WorkitemUid = current.WorkitemUid,
                Filter = current.Filter,
                HasDeletionLock = current.HasDeletionLock,
                IsSuspended = true
            };
            return System.Threading.Tasks.ValueTask.FromResult(true);
        }
    }

    public System.Threading.Tasks.ValueTask<string?> ResolveRequestingAeTitleAsync(
        Aspose.Medical.Dicom.Web.DicomWebRequest request,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        return System.Threading.Tasks.ValueTask.FromResult<string?>(null);
    }

    public System.Threading.Tasks.ValueTask PublishAsync(
        string workitemUid, Aspose.Medical.Dicom.Dataset eventReport,
        System.Threading.CancellationToken cancellationToken = default)
        => PublishToSubscribersAsync(eventReport, cancellationToken);

    public System.Threading.Tasks.ValueTask QueueAsync(
        string subscriber, Aspose.Medical.Dicom.Dataset eventReport,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
            GetQueue(subscriber).Writer.TryWrite(new Aspose.Medical.Dicom.Dataset(eventReport));
        return System.Threading.Tasks.ValueTask.CompletedTask;
    }

    public System.Threading.Tasks.ValueTask PublishStatusAsync(
        Aspose.Medical.Dicom.Dataset eventReport,
        System.Threading.CancellationToken cancellationToken = default)
        => PublishToSubscribersAsync(eventReport, cancellationToken);

    public System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.Dataset> OpenNotificationsAsync(
        string requester, System.Threading.CancellationToken cancellationToken = default)
    {
        lock (gate)
            return GetQueue(requester).Reader.ReadAllAsync(cancellationToken);
    }

    private System.Threading.Tasks.ValueTask PublishToSubscribersAsync(
        Aspose.Medical.Dicom.Dataset eventReport, System.Threading.CancellationToken cancellationToken)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
            foreach (Aspose.Medical.Dicom.Web.Providers.DicomWebSubscription subscription in subscriptions.Values)
                if (!subscription.IsSuspended)
                    GetQueue(subscription.Subscriber).Writer.TryWrite(new Aspose.Medical.Dicom.Dataset(eventReport));
        return System.Threading.Tasks.ValueTask.CompletedTask;
    }

    private System.Threading.Channels.Channel<Aspose.Medical.Dicom.Dataset> GetQueue(string subscriber)
    {
        if (!queues.TryGetValue(subscriber, out System.Threading.Channels.Channel<Aspose.Medical.Dicom.Dataset>? queue))
        {
            queue = System.Threading.Channels.Channel.CreateUnbounded<Aspose.Medical.Dicom.Dataset>();
            queues.Add(subscriber, queue);
        }
        return queue;
    }
}

QueueAsync is direct delivery to one subscriber; PublishAsync selects subscriptions for a workitem; PublishStatusAsync carries an SCP lifecycle report. The sample treats every active worklist subscription as matching. When a subscriber enrolls after workitems already exist, calculate InitialWorkitemUids as part of the atomic UpsertAsync change and provide those initial State Reports. For a filtered subscription, apply its compiled Filter to candidate workitems. Store queues durably if notifications must survive process restart. DicomWebWorklistEventPublisher.PublishRestartedAsync and PublishGoingDownAsync create status reports and call this provider’s PublishStatusAsync.

Each queued report is cloned so mutations by one receiver cannot change another subscriber’s report. This sample uses unbounded in-memory queues, retains unread reports after unsubscribe, and removes an event when a receiver reads it. It has no delivery acknowledgment or replay after a failed send. Use one notification connection per requester with this implementation; concurrent readers for the same requester would consume different reports from its shared queue. A production provider must choose queue capacity, retention, and reconnect behavior appropriate to its delivery requirements.

The standard handler persists a workitem change before calling the subscription provider to publish its reports. These calls do not share a library-managed transaction. If publication fails, the stored change may already be visible; retrieve the workitem before retrying a failed operation and provide a durable recovery policy for notifications that could not be queued.

Register the providers with the hosting-neutral builder; ASP.NET Core uses the corresponding DI registrations and AddStandardWorklistService():

InMemoryWorkflowDatasets workitems = new();
InMemoryWorklistSubscriptions subscriptions = new();
Aspose.Medical.Dicom.Web.DicomWebApplication application =
    DicomWebApplication.CreateBuilder()
        .AddStandardWorklistService(workitems, subscriptions)
        .Build();

With that service exposed under /dicomweb, the following client subscribes to the worklist, creates a scheduled workitem, changes its state, and receives reports until that workitem reaches IN PROGRESS. Creation also publishes a State Report, so the first queued report is not necessarily the requested state change. Use valid UIDs assigned by your application, and place UseWebSockets before mapping the ASP.NET Core endpoint.

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });

await client.Worklist.SubscribeWorklistAsync("VIEWER_AE");
await using Aspose.Medical.Dicom.Web.DicomWebNotificationConnection connection =
    await client.ConnectNotificationsAsync("VIEWER_AE");

Aspose.Medical.Dicom.Dataset workitem = [];
workitem.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID, "1.2.840.1");
workitem.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.ProcedureStepState, "SCHEDULED");
workitem.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.TransactionUID, string.Empty);
workitem.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.InputReadinessState, "READY");
Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.CreateWorkitemResult> created =
    await client.Worklist.CreateAsync(workitem);

Aspose.Medical.Dicom.Dataset stateChange = [];
stateChange.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.ProcedureStepState, "IN PROGRESS");
stateChange.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.TransactionUID, "1.2.840.2");
Aspose.Medical.Dicom.Web.DicomWebRequestOptions changeOptions = new()
{
    Query = Aspose.Medical.Dicom.Web.DicomWebQueryParameters.Parse("requester=MODALITY_AE")
};
await client.Worklist.ChangeStateAsync(created.Value.WorkitemUid, stateChange, changeOptions);

using System.Threading.CancellationTokenSource wait = new(System.TimeSpan.FromSeconds(30));
while (await connection.ReceiveAsync(wait.Token) is Aspose.Medical.Dicom.Dataset report)
{
    string affectedUid = report.GetSingleValueOrDefault(Aspose.Medical.Dicom.Tags.Tag.AffectedSOPInstanceUID, string.Empty);
    string state = report.GetSingleValueOrDefault(Aspose.Medical.Dicom.Tags.Tag.ProcedureStepState, string.Empty);
    if (affectedUid == created.Value.WorkitemUid && state == "IN PROGRESS")
    {
        System.Console.WriteLine(state);
        break;
    }
}

The timeout is only for this example’s wait for an event. A canceled receive or invalid event aborts the connection; dispose it and call ConnectNotificationsAsync again before receiving more reports. A production consumer should continue receiving until close or its own cancellation and decide how to process or persist each report. The typed ChangeStateAsync(workitemUid, WorkitemState.InProgress, transactionUid) overload builds the payload; use the dataset overload when you also need request options such as the explicit requester shown here.

UPS updates and final states

The standard worklist service accepts SCHEDULED → IN PROGRESS → COMPLETED or CANCELED. The transition to IN PROGRESS establishes the Transaction UID that owns subsequent updates and final-state transitions. Repeating an already completed or canceled state with its owning Transaction UID succeeds. Disallowed transitions to IN PROGRESS, COMPLETED, or CANCELED return HTTP 409; unsupported target states or invalid Transaction UIDs return HTTP 400.

For UpdateAsync, a scheduled workitem must have no transaction query parameter and no TransactionUID attribute in the update payload. An in-progress workitem requires exactly one transaction query parameter and a TransactionUID payload attribute, both equal to the stored Transaction UID. Completed and canceled workitems cannot be updated.

An update must omit ProcedureStepState, SOPInstanceUID, SOPClassUID, PatientName, PatientID, PatientBirthDate, PatientSex, AdmissionID, IssuerOfAdmissionIDSequence, AdmittingDiagnosesDescription, AdmittingDiagnosesCodeSequence, ReferencedRequestSequence, and ReplacedProcedureStepSequence. Including any of these attributes returns HTTP 400, even if its value is unchanged. Change the state through ChangeStateAsync.

Before requesting a final state, use UpdateAsync to store its required attributes in the workitem. The state-change payload supplies the requested state and Transaction UID; it does not merge other attributes into the stored dataset.

Final state	Required stored attributes
`COMPLETED`	Exactly one item in `UnifiedProcedureStepPerformedProcedureSequence`. That item must contain nonempty `PerformedStationNameCodeSequence` and `PerformedWorkitemCodeSequence`, populated `PerformedProcedureStepStartDateTime` and `PerformedProcedureStepEndDateTime`, and an `OutputInformationSequence`, which may be empty.
`CANCELED`	Exactly one item in `ProcedureStepProgressInformationSequence`. That item must contain a nonempty `ProcedureStepDiscontinuationReasonCodeSequence`. The handler fills a missing or blank `ProcedureStepCancellationDateTime` in this item when changing the state.

Each item in these required code sequences needs CodeMeaning and a code value (CodeValue, LongCodeValue, or URNCodeValue). CodeValue and LongCodeValue also require CodingSchemeDesignator.

MPPS uses the same revision contract

Pass a different InMemoryWorkflowDatasets instance to AddStandardModalityPerformedProcedureStepService. The standard MPPS handler checks the procedure step state and required attributes, while the provider supplies atomic storage. This client creates an in-progress step, retrieves it, updates its description, and completes it. The empty values and sequences illustrate required attributes that may be empty; supply real patient, scheduling, and performed-series details when they are available.

InMemoryWorkflowDatasets procedureSteps = new();
Aspose.Medical.Dicom.Web.DicomWebApplication mppsApplication =
    DicomWebApplication.CreateBuilder()
        .AddStandardModalityPerformedProcedureStepService(procedureSteps)
        .Build();

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Dataset scheduled = [];
scheduled.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.StudyInstanceUID, "1.2.840.100");
scheduled.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.ReferencedStudySequence, []));
scheduled.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.AccessionNumber, string.Empty);
scheduled.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.RequestedProcedureID, string.Empty);
scheduled.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.RequestedProcedureDescription, string.Empty);
scheduled.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.ScheduledProcedureStepID, string.Empty);
scheduled.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.ScheduledProcedureStepDescription, string.Empty);
scheduled.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.ScheduledProtocolCodeSequence, []));

Aspose.Medical.Dicom.Dataset initial = [];
initial.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.ScheduledStepAttributesSequence, [scheduled]));
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PatientName, string.Empty);
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PatientID, string.Empty);
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PatientBirthDate, string.Empty);
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PatientSex, string.Empty);
initial.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.ReferencedPatientSequence, []));
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepID, "STEP-1");
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedStationAETitle, "MODALITY_AE");
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedStationName, string.Empty);
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedLocation, string.Empty);
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepStartDate, "20260925");
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepStartTime, "110000");
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepStatus, "IN PROGRESS");
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepDescription, string.Empty);
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureTypeDescription, string.Empty);
initial.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.ProcedureCodeSequence, []));
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepEndDate, string.Empty);
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepEndTime, string.Empty);
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.Modality, "CT");
initial.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.StudyID, string.Empty);
initial.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.PerformedProtocolCodeSequence, []));
initial.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.PerformedSeriesSequence, []));
await client.ModalityPerformedProcedureSteps.CreateAsync("1.2.840.3", initial);

Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.RetrieveModalityPerformedProcedureStepResult> current =
    await client.ModalityPerformedProcedureSteps.RetrieveAsync("1.2.840.3");
Aspose.Medical.Dicom.Dataset changes = [];
changes.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepDescription, "Acquisition reviewed");
Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.UpdateModalityPerformedProcedureStepResult> updated =
    await client.ModalityPerformedProcedureSteps.UpdateAsync("1.2.840.3", changes);
System.Console.WriteLine(updated.Value.StatusReport?.Count ?? current.Value.ProcedureStep.Count);

Aspose.Medical.Dicom.Dataset series = [];
series.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformingPhysicianName, string.Empty);
series.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.ProtocolName, "HEAD");
series.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.OperatorsName, string.Empty);
series.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.SeriesInstanceUID, "1.2.840.100.1");
series.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.SeriesDescription, string.Empty);
series.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.RetrieveAETitle, string.Empty);
series.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.ReferencedImageSequence, []));
series.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.ReferencedNonImageCompositeSOPInstanceSequence, []));
Aspose.Medical.Dicom.Dataset completed = [];
completed.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepStatus, "COMPLETED");
completed.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepEndDate, "20260925");
completed.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PerformedProcedureStepEndTime, "120000");
completed.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(Aspose.Medical.Dicom.Tags.Tag.PerformedSeriesSequence, [series]));
await client.ModalityPerformedProcedureSteps.UpdateAsync("1.2.840.3", completed);

The standard handler validates the initial and final attributes and prevents an invalid state transition. Use identifiers and values from the actual performed procedure in an application.

10-Net: Storage Commitment and Non-Patient Instances

Mon, 01 Jan 0001 00:00:00 +0000

Storage commitment and non-patient instances

These services have different backend obligations. Storage Commitment records a request and reports a later safekeeping decision; accepting a request does not itself commit an instance. Non-Patient Instance storage groups DICOM files by one of the standardized category paths in DicomWebRouteCatalog.NonPatientInstanceCategories. The standard handlers validate the HTTP and DICOM envelopes, while providers supply persistence, candidate order, and actual outcomes.

A pending storage commitment request

This process-local provider illustrates the two-method contract and the transition from Pending to Complete. CompleteFromArchive stands for a call made after an archive has determined which instances are safe; this example has no archive and does not make that decision itself. A real implementation must persist requests and results and make duplicate Transaction UID detection atomic across workers.

public sealed class InMemoryCommitments :
    Aspose.Medical.Dicom.Web.Providers.IDicomWebStorageCommitmentProvider
{
    private readonly object gate = new();
    private readonly System.Collections.Generic.Dictionary<string,
        Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitment> results =
        new(System.StringComparer.Ordinal);
    private readonly System.Collections.Generic.Dictionary<string,
        System.Collections.Immutable.ImmutableArray<Aspose.Medical.Dicom.Web.Providers.DicomWebSopReference>> requested =
        new(System.StringComparer.Ordinal);

    public System.Threading.Tasks.ValueTask<Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitment?> TryRequestAsync(
        string transactionUid,
        System.Collections.Generic.IReadOnlyList<Aspose.Medical.Dicom.Web.Providers.DicomWebSopReference> instances,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
        {
            if (results.ContainsKey(transactionUid))
                return System.Threading.Tasks.ValueTask.FromResult<Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitment?>(null);
            Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitment pending = new()
            {
                State = Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitmentState.Pending,
                RetryAfter = System.TimeSpan.FromSeconds(10)
            };
            results.Add(transactionUid, pending);
            requested.Add(transactionUid, [.. instances]);
            return System.Threading.Tasks.ValueTask.FromResult<Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitment?>(pending);
        }
    }

    public System.Threading.Tasks.ValueTask<Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitment?> GetAsync(
        string transactionUid, System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
        {
            results.TryGetValue(transactionUid, out Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitment? result);
            return System.Threading.Tasks.ValueTask.FromResult(result);
        }
    }

    public void CompleteFromArchive(
        string transactionUid,
        System.Collections.Immutable.ImmutableArray<Aspose.Medical.Dicom.Web.Providers.DicomWebSopReference> committed,
        System.Collections.Immutable.ImmutableArray<Aspose.Medical.Dicom.Web.Providers.DicomWebSopReference> failed)
    {
        lock (gate)
        {
            if (!results.ContainsKey(transactionUid))
                throw new System.Collections.Generic.KeyNotFoundException(transactionUid);
            results[transactionUid] = new()
            {
                State = Aspose.Medical.Dicom.Web.Providers.DicomWebStorageCommitmentState.Complete,
                CommittedInstances = committed,
                FailedInstances = failed
            };
        }
    }

    public System.Collections.Immutable.ImmutableArray<Aspose.Medical.Dicom.Web.Providers.DicomWebSopReference> GetRequestedInstances(
        string transactionUid)
    {
        lock (gate)
            return requested[transactionUid];
    }
}

Register new InMemoryCommitments() with AddStandardStorageCommitmentService on the hosting-neutral builder, or register IDicomWebStorageCommitmentProvider in ASP.NET Core DI and call its matching AddStandard... method. An archive worker can read GetRequestedInstances(transactionUid), check safekeeping, then call CompleteFromArchive with the committed and failed references. Return Gone when a previously retained result has expired; return null from GetAsync only for a transaction that is unknown. The provider supplies RetryAfter for pending responses and failure reasons on individual DicomWebSopReference values.

Pending produces 202 Accepted without a report; the optional RetryAfter becomes a Retry-After header in seconds. Complete produces 200 OK with the committed and failed references, even when some or all instances could not be committed. Completion therefore means that the decision is available. Check the report before treating any instance as committed. Preserve Study and Series UIDs from each request reference when populating a hierarchical result; the handler groups those references into the corresponding study/series sequences. A duplicate Transaction UID returns 409 Conflict; checking an unknown transaction returns 404 Not Found, and checking a Gone result returns 410 Gone.

This client example requests commitment for one already stored SOP Instance and checks the result. It reads the pending state without assuming that a later poll will already be complete:

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Dataset reference = [];
reference.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.ReferencedSOPClassUID,
                      Aspose.Medical.Dicom.Uid.CTImageStorage.Code);
reference.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.ReferencedSOPInstanceUID, "1.2.840.10");
Aspose.Medical.Dicom.Dataset request = [];
request.AddOrUpdate(new Aspose.Medical.Dicom.Elements.Sequence(
    Aspose.Medical.Dicom.Tags.Tag.ReferencedSOPSequence, [reference]));

Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.RequestStorageCommitmentResult> accepted =
    await client.StorageCommitment.RequestAsync("1.2.840.11", request);
if (accepted.Value.IsPending)
{
    Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.CheckStorageCommitmentResult> checkedResult =
        await client.StorageCommitment.CheckResultAsync("1.2.840.11");
    System.Console.WriteLine(checkedResult.Value.IsPending ? "Still pending" : "Report available");
}

Read accepted.Value.Report when the initial request completes immediately, or checkedResult.Value.Report after a completed check. For the flat SOP-reference request above, successful instances are in ReferencedSOPSequence and failed instances are in FailedSOPSequence, with FailureReason on each failed item. Hierarchical requests use ReferencedStudySequence and FailedStudySequence with nested series and SOP references. Schedule further checks using the response’s Retry-After header when present and your application’s cancellation and retry policy; the client does not poll automatically.

Non-patient instance storage

This in-memory provider separates categories and returns stable candidate order. It stores the supplied file reference, so callers must not mutate a stored file after the call. It loses all data on restart; a real provider should use durable storage and category/UID indexes.

public sealed class InMemoryNonPatientInstances :
    Aspose.Medical.Dicom.Web.Providers.IDicomWebNonPatientInstanceProvider
{
    private readonly object gate = new();
    private readonly System.Collections.Generic.Dictionary<(string Category, string Uid), Aspose.Medical.Dicom.DicomFile> files = new();

    public async System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.Dataset> FindCandidatesAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebSearchContext search,
        [System.Runtime.CompilerServices.EnumeratorCancellation] System.Threading.CancellationToken cancellationToken = default)
    {
        string category = search.Resource.NonPatientInstanceCategory ?? string.Empty;
        System.Collections.Generic.List<Aspose.Medical.Dicom.Dataset> snapshot;
        lock (gate)
        {
            snapshot = new();
            System.Collections.Generic.List<string> uids = new();
            foreach ((string Category, string Uid) key in files.Keys)
                if (key.Category == category)
                    uids.Add(key.Uid);
            uids.Sort(System.StringComparer.Ordinal);
            foreach (string uid in uids)
                snapshot.Add(new Aspose.Medical.Dicom.Dataset(files[(category, uid)].Dataset));
        }
        foreach (Aspose.Medical.Dicom.Dataset candidate in snapshot)
        {
            cancellationToken.ThrowIfCancellationRequested();
            yield return candidate;
        }
        await System.Threading.Tasks.Task.CompletedTask;
    }

    public System.Threading.Tasks.ValueTask<Aspose.Medical.Dicom.Web.Providers.DicomWebStoreInstanceResult> StoreAsync(
        string category, Aspose.Medical.Dicom.DicomFile instance,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        string uid = instance.Dataset.GetSingleValue<string>(Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID);
        lock (gate)
        {
            bool added = files.TryAdd((category, uid), instance);
            Aspose.Medical.Dicom.Web.Providers.DicomWebStoreInstanceResult outcome = new()
            {
                Outcome = added ? Aspose.Medical.Dicom.Web.Providers.DicomWebStoreOutcome.Stored
                                : Aspose.Medical.Dicom.Web.Providers.DicomWebStoreOutcome.Failed
            };
            return System.Threading.Tasks.ValueTask.FromResult(outcome);
        }
    }

    public System.Threading.Tasks.ValueTask<Aspose.Medical.Dicom.DicomFile?> RetrieveAsync(
        string category, string sopInstanceUid,
        System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        lock (gate)
        {
            files.TryGetValue((category, sopInstanceUid), out Aspose.Medical.Dicom.DicomFile? file);
            return System.Threading.Tasks.ValueTask.FromResult(file);
        }
    }
}

StoreAsync(category, instance) reports an outcome for each validated file. The single-instance route checks the target UID before calling the provider. FindCandidatesAsync may return a superset; the standard search handler performs final matching and projection. The following client stores and retrieves a protocol-approval instance. The file shown contains only a few attributes to keep the transport example small; a real SOP Instance must satisfy its SOP Class requirements.

A Non-Patient Instance store returns 200 OK when any instance was stored, including a mixed success/failure result. Inspect stored.Value.Response for both ReferencedSOPSequence and FailedSOPSequence; the HTTP status alone cannot establish that every instance was stored. The store result table also explains warning and failure reasons and the all-failed response.

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Dataset dataset = [];
dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.SOPClassUID,
                    Aspose.Medical.Dicom.Uid.ProtocolApprovalStorage.Code);
dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID, "1.2.840.12");
dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.ContentLabel, "APPROVAL");
Aspose.Medical.Dicom.DicomFile file = new(dataset);
Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.StoreInstancesResult> stored =
    await client.NonPatientInstances.StoreAsync("protocol-approvals", file);
System.Console.WriteLine(stored.Response.StatusCode);
Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.RetrieveNonPatientInstanceResult> retrieved =
    await client.NonPatientInstances.RetrieveAsync("protocol-approvals", "1.2.840.12");
System.Console.WriteLine(retrieved.Value.File.Dataset.Count);
await using Aspose.Medical.Dicom.Web.DicomWebClientStream<Aspose.Medical.Dicom.Dataset> matches =
    await client.NonPatientInstances.SearchAsync("protocol-approvals",
        new DicomWebSearchOptions
        {
            MatchingParameters =
            [
                new Aspose.Medical.Dicom.Web.DicomWebQueryParameter("ContentLabel", "APPROVAL")
            ]
        });
await foreach (Aspose.Medical.Dicom.Dataset match in matches)
    System.Console.WriteLine(match.Count);

To run the two server providers through ASP.NET Core, register IDicomWebStorageCommitmentProvider and IDicomWebNonPatientInstanceProvider in DI, call AddDicomWeb().AddStandardStorageCommitmentService().AddStandardNonPatientInstanceService(), and map the endpoint. The registration creates handlers; it does not install an archive.

10-Net: Custom Handlers

Mon, 01 Jan 0001 00:00:00 +0000

Custom transaction handlers

Use a custom handler when the standard engine’s validation, persistence boundary, or response policy does not fit a transaction. The application still selects the standard route, validates its request envelope, and dispatches a typed message. This includes route and query validation, request Content-Type checks, and required Accept presence; the custom handler chooses and produces the response representation. Your handler implements IRequestHandler<DicomWebRequest<TTransaction>, DicomWebApplicationResult> and returns either an HTTP DicomWebResponse or, for a WebSocket transaction, a DicomWebNotificationSession. The typed wrapper’s Request exposes the resolved DicomWebRequest; its Route and PathParameters are available after dispatch resolution. A handler reads the forward-only Body through ReadDatasetAsync, ReadDatasetsAsync, ReadDicomFileAsync, or ReadDicomFilesAsync as appropriate, and honors the cancellation token.

The same modality worklist search can be supplied by the standard provider or by a complete replacement handler. This custom implementation returns an empty result in the accepted DICOM JSON or multipart XML representation and does not use the standard matching engine:

public sealed class EmptyWorklistHandler :
    Aspose.Medical.Communication.Messages.IRequestHandler<
        Aspose.Medical.Dicom.Web.DicomWebRequest<Aspose.Medical.Dicom.Web.Transactions.SearchModalityScheduledProcedureSteps>,
        Aspose.Medical.Dicom.Web.DicomWebApplicationResult>
{
    public System.Threading.Tasks.ValueTask<Aspose.Medical.Dicom.Web.DicomWebApplicationResult> Handle(
        Aspose.Medical.Dicom.Web.DicomWebRequest<Aspose.Medical.Dicom.Web.Transactions.SearchModalityScheduledProcedureSteps> message,
        System.Threading.CancellationToken cancellationToken)
    {
        cancellationToken.ThrowIfCancellationRequested();
        Aspose.Medical.Dicom.Web.DicomWebRequest request = message.Request;
        // HttpRequestHeaders parses the Accept list, including quoted parameters and q values.
        using System.Net.Http.HttpRequestMessage acceptParser = new();
        acceptParser.Headers.TryAddWithoutValidation(
            "Accept", request.Headers.GetCommaSeparatedValue("Accept") ?? string.Empty);
        System.Net.Http.Headers.MediaTypeHeaderValue? selected = null;
        double bestQuality = 0;
        string[] responseMediaTypes =
        [
            Aspose.Medical.Dicom.Web.DicomWebMediaTypes.ApplicationDicomJson,
            Aspose.Medical.Dicom.Web.DicomWebMediaTypes.MultipartRelatedDicomXml
        ];
        foreach (string offeredText in responseMediaTypes)
        {
            System.Net.Http.Headers.MediaTypeHeaderValue offered =
                System.Net.Http.Headers.MediaTypeHeaderValue.Parse(offeredText);
            int controllingSpecificity = -1;
            int controllingParameterCount = -1;
            double offeredQuality = 0;
            foreach (System.Net.Http.Headers.MediaTypeWithQualityHeaderValue range in acceptParser.Headers.Accept)
            {
                int specificity = MatchSpecificity(range, offered, out int parameterCount);
                if (specificity < 0)
                    continue;

                if (specificity > controllingSpecificity ||
                    (specificity == controllingSpecificity && parameterCount > controllingParameterCount))
                {
                    controllingSpecificity = specificity;
                    controllingParameterCount = parameterCount;
                    offeredQuality = range.Quality ?? 1;
                }
            }
            if (offeredQuality > bestQuality)
            {
                selected = offered;
                bestQuality = offeredQuality;
            }
        }
        if (selected is null)
            return System.Threading.Tasks.ValueTask.FromResult<Aspose.Medical.Dicom.Web.DicomWebApplicationResult>(
                new Aspose.Medical.Dicom.Web.DicomWebResponse(System.Net.HttpStatusCode.NotAcceptable));

        Aspose.Medical.Dicom.Web.DicomWebContent content =
            DicomWebContent.FromDatasets(EmptyResults(), selected);
        Aspose.Medical.Dicom.Web.DicomWebApplicationResult result =
            DicomWebResponse.Ok(content);
        return System.Threading.Tasks.ValueTask.FromResult(result);
    }

    // Returns -1 when the Accept range does not cover the offered media type;
    // otherwise 0 for */*, 1 for type/*, or 2 for a full media type.
    private static int MatchSpecificity(
        System.Net.Http.Headers.MediaTypeWithQualityHeaderValue range,
        System.Net.Http.Headers.MediaTypeHeaderValue offered,
        out int parameterCount)
    {
        parameterCount = 0;
        string[] rangeParts = (range.MediaType ?? string.Empty).Split('/');
        string[] offeredParts = (offered.MediaType ?? string.Empty).Split('/');
        if (rangeParts.Length != 2 || offeredParts.Length != 2)
            return -1;
        bool matchesAllTypes = rangeParts[0] == "*" && rangeParts[1] == "*";
        bool matchesAllSubTypes = rangeParts[1] == "*";
        if ((!matchesAllTypes && !rangeParts[0].Equals(offeredParts[0], System.StringComparison.OrdinalIgnoreCase)) ||
            (!matchesAllSubTypes && !rangeParts[1].Equals(offeredParts[1], System.StringComparison.OrdinalIgnoreCase)))
            return -1;

        // Every parameter of the range except q must be present in the offered media type.
        foreach (System.Net.Http.Headers.NameValueHeaderValue parameter in range.Parameters)
        {
            if (parameter.Name.Equals("q", System.StringComparison.OrdinalIgnoreCase))
                continue;
            bool found = false;
            foreach (System.Net.Http.Headers.NameValueHeaderValue offeredParameter in offered.Parameters)
            {
                if (offeredParameter.Name.Equals(parameter.Name, System.StringComparison.OrdinalIgnoreCase) &&
                    string.Equals(offeredParameter.Value?.Trim('"'), parameter.Value?.Trim('"'),
                        System.StringComparison.OrdinalIgnoreCase))
                {
                    found = true;
                    break;
                }
            }
            if (!found)
                return -1;
            parameterCount++;
        }
        return matchesAllTypes ? 0 : matchesAllSubTypes ? 1 : 2;
    }

    private static async System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.Dataset> EmptyResults()
    {
        await System.Threading.Tasks.Task.CompletedTask;
        yield break;
    }
}

The handler offers the two response envelopes it produces: a DICOM JSON array or multipart XML. DicomWebContent.FromDatasets packages XML collections as multipart content, so the handler does not offer bare application/dicom+xml and then change the selected envelope while writing. It selects each offered representation’s quality from its most specific matching Accept range before comparing the offers. An explicit q=0 exclusion therefore takes precedence over a positive wildcard, as required by HTTP Accept precedence. It also distinguishes application/dicom+json from application/json. The example covers header media-type selection; a production replacement must also implement the DICOMweb negotiation query controls and character-set policy it accepts. The standard engine already owns those policies for its transactions.

On the hosting-neutral builder, call AddSingletonHandler(new EmptyWorklistHandler()) for a stateless, thread-safe instance. AddHandlerFactory<TTransaction>(factory) creates a handler for a dispatch when it needs request-specific state. Use<TTransaction>(behavior) and Use<TTransaction>(factory) add typed Communication pipeline behaviors; Use(IOpenRequestBehaviorFactory) adds an open request behavior. A shared instance must be safe for concurrent requests. On the ASP.NET Core builder, AddHandler<TTransaction,THandler>(ServiceLifetime) and AddHandlerFactory<TTransaction,TFactory>(ServiceLifetime) register the implementation in dependency injection; AddOpenRequestBehavior<TFactory>(ServiceLifetime) registers an open behavior factory. The default lifetime is Scoped.

Decision	Standard handler with provider	Custom handler
Route and envelope validation	Library	Library
DICOM matching, search projection, pagination	Library	Application
Transaction-specific validation and response semantics	Library	Application
Persistence, search candidates, rendering, workflow backend	Application provider	Application handler and its dependencies
Typical choice	Built-in behavior fits the application	A transaction needs different semantics or an existing service abstraction

Registrations can be combined. A later handler registration for the same transaction replaces its earlier handler; other standard transactions remain. Register the standard service first, then the selected replacement. There is no replacement for the built-in RetrieveCapabilities handler. Enable and Disable operate on routes and generated capabilities; a route without a handler is omitted when Build() snapshots the configuration. Build() returns a configured application; later builder changes do not retroactively change it.

10-Net: Representations and Streaming

Mon, 01 Jan 0001 00:00:00 +0000

Representations and streaming

A DICOMweb route determines which request and response representations are possible. The client’s AcceptedMediaTypes becomes an HTTP Accept preference; the server selects among the route’s media types and, for rendered retrieval, the provider’s declared media types. DicomWebMediaTypes supplies constants for Part 10 DICOM, DICOM JSON, Native DICOM Model XML, multipart, bulk octet streams, and common rendered formats. Content-Type describes the representation actually returned. A multipart response has its own media type and individual part headers, including Content-Location where supplied. The server may return 406 Not Acceptable when it cannot supply an acceptable representation.

DICOM transfer syntax and metadata

For Part 10 retrieval through the Studies service, a transfer-syntax parameter can request a specific transfer syntax. Without that parameter, the standard Studies engine writes Explicit VR Little Endian. It can transcode to supported syntaxes; it does not promise that every syntax is available. transfer-syntax=* permits each returned file to retain its stored syntax, except Implicit VR Little Endian and Explicit VR Big Endian, which are converted to Explicit VR Little Endian. For uncompressed octet-stream bulk data, the standard engine may transcode encapsulated pixel data before writing frames. Rendered retrieval does not accept a transfer-syntax parameter. Inspect the returned Content-Type, multipart part headers, and file metadata to identify the negotiated representation.

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
string syntax = Aspose.Medical.Dicom.TransferSyntax.DeflatedExplicitVrLittleEndian.Uid.Code;
Aspose.Medical.Dicom.Web.DicomWebRetrieveOptions options = new()
{
    AcceptedMediaTypes = [$"{Aspose.Medical.Dicom.Web.DicomWebMediaTypes.ApplicationDicom}; transfer-syntax={syntax}"]
};
Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.RetrieveInstanceResult> result =
    await client.Studies.RetrieveInstanceAsync("1.2.3", "1.2.3.4", "1.2.3.4.5", options);
System.Console.WriteLine(result.Value.File.MetaInfo.TransferSyntax);

Use DicomWebRetrieveOptions for metadata too. AcceptedMediaTypes = [DicomWebMediaTypes.ApplicationDicomJson] asks for DICOM JSON; MultipartRelatedDicomXml requests a multipart Native DICOM Model XML collection where the route allows one. Metadata can contain external Bulk Data references. Configure DicomWebClientOptions.BulkDataLoader when your application needs to resolve those references while parsing; do not assume a particular invocation time for the loader.

For study or series retrieval, the typed client returns a one-pass DicomWebClientStream<DicomFile> and handles multipart Part 10 parsing. The lower-level DicomWebClientResponse.ReadDicomFilesAsync accepts single-part or multipart DICOM, while ReadDicomFileAsync accepts only one single-part application/dicom body. Neither file reader parses arbitrary octet-stream frame or bulk-data parts.

Studies.RetrieveInstanceAsync accepts single-part or multipart DICOM but requires exactly one file in the response. Keep its accepted representations to Part 10 DICOM; use the raw frame or bulk-data operations for octet-stream representations. WADO-URI DICOM retrieval uses the single-part file reader. Non-patient instance retrieval accepts single-part DICOM or metadata and constructs a DicomFile from the parsed metadata when that representation is selected. See the payload reader contracts.

The current typed NonPatientInstances.RetrieveAsync helper cannot consume multipart Part 10 responses, although the server route supports them. For that representation, send a raw RetrieveNonPatientInstance transaction through SendAsync and consume the response with ReadDicomFilesAsync.

Declare a JPEG representation

IDicomWebRepresentationProvider.SupportedMediaTypes controls which rendered transaction/media-type combinations are registered and advertised. GetResponseMediaTypes can narrow the choices for a particular request. This provider declares only instance JPEG rendering; it relies on the interface’s default RetrieveAsync, which renders a single-frame instance as JPEG and honors quality. Viewport, window, ICC profile processing, whole multi-frame rendering, and other output formats require an implementation of RetrieveAsync. MPR and 3D need a custom transaction handler because the bundled standard handler does not implement them.

public sealed class JpegInstanceRepresentations :
    Aspose.Medical.Dicom.Web.Providers.IDicomWebRepresentationProvider
{
    public System.Collections.Immutable.ImmutableDictionary<Aspose.Medical.Dicom.Web.DicomWebTransaction,
        System.Collections.Immutable.ImmutableArray<string>> SupportedMediaTypes { get; } =
        ImmutableDictionary<DicomWebTransaction,
            ImmutableArray<string>>.Empty.Add(
                Aspose.Medical.Dicom.Web.Transactions.RetrieveRenderedInstance.Instance,
                [DicomWebMediaTypes.ImageJpeg]);

    public System.Collections.Immutable.ImmutableArray<string> GetResponseMediaTypes(
        Aspose.Medical.Dicom.Web.Providers.DicomWebRepresentationRequest request) =>
        [Aspose.Medical.Dicom.Web.DicomWebMediaTypes.ImageJpeg];
}

Register new JpegInstanceRepresentations() alongside an IDicomWebStudiesProvider with AddStandardStudiesService. The default renderer obtains the stored file through the Studies provider; the application still supplies that storage. Do not declare PNG, GIF, or another transaction unless your provider’s RetrieveAsync actually produces it. The chosen output’s MediaType, ordered Items, ContentLocation, and optional headers are the contract between a custom representation provider and the standard response packager.

When overriding RetrieveAsync, call its selectMediaType callback with the single-part types you can produce before encoding the output. DicomWebRepresentationResult.MediaType and each DicomWebEncodedRepresentation.Content.ContentType must match a choice obtained from that callback, and the first item’s type must match the result’s MediaType. Return at least one item; a single-part response requires exactly one. Each item contains its encoded resource bytes and resource ContentLocation; the standard handler supplies multipart framing when negotiated. Keep data captured by an item’s DicomWebContent writer available until response writing finishes.

The corresponding client call supplies quality and streams the returned bytes directly to a destination. The destination file is illustrative; use a path and access policy appropriate for your application.

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Web.DicomWebRenderOptions render = new()
{
    AcceptedMediaTypes = [Aspose.Medical.Dicom.Web.DicomWebMediaTypes.ImageJpeg],
    Quality = 80
};
await using Aspose.Medical.Dicom.Web.DicomWebClientResponse image =
    await client.Studies.RetrieveRenderedInstanceAsync("1.2.3", "1.2.3.4", "1.2.3.4.5", render);
image.EnsureSuccessStatusCode();
await using System.IO.FileStream output = File.Create("instance.jpg");
await image.ContentReader.CopyToAsync(output);

Rendering controls

Set DicomWebRenderOptions properties to decoded values; the client escapes them when constructing the query. The following formats apply to the common controls on rendered Studies resources. Null scalar properties and an empty Annotation array omit those controls.

Property	Format and accepted values
`Quality`	Integer from 1 through 100 for lossy image quality.
`Viewport`	`"width,height"` or `"width,height,sourceX,sourceY,sourceWidth,sourceHeight"`. Output dimensions are positive integers. Each of the four source-region values is a decimal number or an empty component that requests its default. For example, `"512,512,,,256,256"` omits the source origin.
`Window`	`"center,width,function"`. Center is a decimal number; width is positive. Function is `linear`, `linear-exact`, or `sigmoid`; `linear` requires width of at least 1. For example, `"40,400,linear"`.
`IccProfile`	One or a comma-separated list of the lowercase tokens `no`, `yes`, `srgb`, `adobergb`, `rommrgb`, and `displayp3`.
`Annotation`	Keywords such as `"patient"` and `"technique"`. Each keyword starts with an ASCII letter and then contains only ASCII letters, digits, underscores, or hyphens. Array entries become repeated `annotation` parameters; comma-separated keywords are also accepted. The renderer determines which annotations it supports.
`AdditionalParameters`	Ordered `DicomWebQueryParameter` values for other rendering controls or extensions. Their meaning and support depend on the requested transaction and renderer.

Thumbnail transactions accept only the two-component viewport, such as "128,128"; a source-region viewport is invalid. Their parsed rendering controls ignore quality, window, ICC profile, and annotations. Set only the thumbnail viewport and representation preferences when using these options for a thumbnail request.

The server’s representation provider must implement the requested controls. The default JPEG implementation above supports quality, rejects viewport and window overrides or ICC processing, and reports unsupported annotations in a Warning header. The following request therefore requires a provider that implements these controls:

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Web.DicomWebRenderOptions render = new()
{
    AcceptedMediaTypes = [Aspose.Medical.Dicom.Web.DicomWebMediaTypes.ImageJpeg],
    Quality = 85,
    Viewport = "512,512",
    Window = "40,400,linear",
    IccProfile = "srgb",
    Annotation = ["patient", "technique"]
};
await using Aspose.Medical.Dicom.Web.DicomWebClientResponse image =
    await client.Studies.RetrieveRenderedInstanceAsync("1.2.3", "1.2.3.4", "1.2.3.4.5", render);
image.EnsureSuccessStatusCode();
await using System.IO.FileStream output = File.Create("windowed-instance.jpg");
await image.ContentReader.CopyToAsync(output);

Bulk data, frames, and multipart bodies

RetrieveBulkDataAsync takes a decoded path relative to the configured Studies service root. For a root of https://example.org/dicomweb/, "bulkdata/1.2.3/1.2.3.4/1.2.3.4.5/7FE00010" addresses Pixel Data through the standard provider. Pass query parameters through DicomWebRetrieveOptions.Query. An absolute BulkDataURI is not resolved by this method: convert a reference under the same service root to its relative path, or retrieve an external URI with an application-configured HTTP transport. For external references encountered while parsing metadata, supply an IAsyncBulkDataLoader through DicomWebClientOptions.BulkDataLoader.

The standard provider resolves bulkdata/{study}/{series}/{instance}/{attributePath}. The attribute path contains zero or more sequence-tag/item-index pairs followed by the value’s tag. Sequence item indices are zero-based: 0040A730/0/00420011 identifies Encapsulated Document in the first Content Sequence item. Use the references returned in metadata when available. Malformed tag/index paths produce 400 Bad Request; a missing sequence, item, or element produces 404 Not Found, and an element whose VR has no Bulk Data representation produces 406 Not Acceptable.

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
await using Aspose.Medical.Dicom.Web.DicomWebClientResponse bulk =
    await client.Studies.RetrieveBulkDataAsync("bulkdata/1.2.3/1.2.3.4/1.2.3.4.5/7FE00010",
        new DicomWebRetrieveOptions
        {
            AcceptedMediaTypes = [Aspose.Medical.Dicom.Web.DicomWebMediaTypes.MultipartRelatedOctetStream]
        });
bulk.EnsureSuccessStatusCode();
System.Console.WriteLine(bulk.ContentType);
await using System.IO.FileStream output = File.Create("bulk.multipart");
await bulk.ContentReader.CopyToAsync(output);

Bulk-data and frame methods return a raw DicomWebClientResponse because their response can be binary or multipart and the caller must choose how to consume it. Frame numbers in RetrieveFramesAsync are one-based, and the collection must be nonempty with no duplicates. The next example preserves the entire multipart response, including its boundaries and part headers, as received. An application that needs individual frames must parse the multipart body using a suitable multipart reader; the DICOM Part 10 readers above are for files, not frame bytes.

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Web.DicomWebRetrieveOptions options = new()
{
    AcceptedMediaTypes = [Aspose.Medical.Dicom.Web.DicomWebMediaTypes.MultipartRelatedOctetStream]
};
await using Aspose.Medical.Dicom.Web.DicomWebClientResponse frames =
    await client.Studies.RetrieveFramesAsync("1.2.3", "1.2.3.4", "1.2.3.4.5", [1, 2], options);
frames.EnsureSuccessStatusCode();
System.Console.WriteLine(frames.ContentType);
await using System.IO.FileStream output = File.Create("frames.multipart");
await frames.ContentReader.CopyToAsync(output);

DicomWebContent supplies the reverse direction for request or custom response bodies. FromDataset defaults to DICOM JSON, FromDatasets writes a JSON array or XML multipart collection, and FromDicomFiles streams a multipart Part 10 sequence. FromBytes retains the supplied memory until writing finishes; keep it unchanged. WriteToAsync accepts a Stream or PipeWriter. A host must keep services and source data alive until the write completes, even if a handler has already returned its result.

The following sends two files without constructing one combined byte array. It assumes two existing valid Part 10 files at the supplied paths:

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Web.DicomWebContent content =
    DicomWebContent.FromDicomFiles(ReadFilesAsync(["first.dcm", "second.dcm"]));
Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.StoreInstancesResult> stored =
    await client.Studies.StoreAsync(content);
System.Console.WriteLine(stored.Value.Response.Count);

static async System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.DicomFile> ReadFilesAsync(
    System.Collections.Generic.IEnumerable<string> paths,
    [System.Runtime.CompilerServices.EnumeratorCancellation] System.Threading.CancellationToken cancellationToken = default)
{
    foreach (string path in paths)
    {
        cancellationToken.ThrowIfCancellationRequested();
        yield return await Aspose.Medical.Dicom.DicomFile.OpenAsync(path, cancellationToken: cancellationToken);
    }
}

10-Net: Hosting-Neutral Integration

Mon, 01 Jan 0001 00:00:00 +0000

Hosting-neutral integration

DicomWebApplication has no socket, HTTP listener, or dependency-injection requirement. Build it once with standard and/or custom handlers, then give each inbound request a DicomWebRequest whose Path is relative to the DICOMweb service root. The host owns HTTP parsing, authentication, authorization, header and query extraction, request body lifetime, and cancellation. ProcessAsync resolves a route, attaches route values, validates the DICOMweb envelope, dispatches the transaction, and returns a DicomWebApplicationResult.

The following adapter shows the complete public request boundary for a host that already has an HTTP request stream. It does not assume an ASP.NET Core request object:

public static async System.Threading.Tasks.ValueTask<(
    Aspose.Medical.Dicom.Web.DicomWebApplicationResult Result,
    Aspose.Medical.Dicom.Web.DicomWebPayloadReader Payload)> DispatchAsync(
    Aspose.Medical.Dicom.Web.DicomWebApplication application,
    string method,
    string relativePath,
    string? rawQuery,
    System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, System.Collections.Generic.IEnumerable<string>>> headers,
    System.IO.Stream requestBody,
    System.Uri serviceBaseUri,
    bool isWebSocketRequest,
    System.Threading.CancellationToken requestAborted)
{
    Aspose.Medical.Dicom.Web.DicomWebHeaders fields = new(headers.Select(header =>
        System.Collections.Generic.KeyValuePair.Create(
            header.Key, System.Collections.Immutable.ImmutableArray.CreateRange(header.Value))));
    System.Net.Http.Headers.MediaTypeHeaderValue? contentType =
        MediaTypeHeaderValue.TryParse(
            fields.GetFirstOrDefault("Content-Type"), out MediaTypeHeaderValue? parsed)
            ? parsed : null;
    System.IO.Pipelines.PipeReader pipe = PipeReader.Create(
        requestBody, new StreamPipeReaderOptions(leaveOpen: true));
    Aspose.Medical.Dicom.Web.DicomWebPayloadReader payload =
        new(pipe, false, contentType, null);
    try
    {
        Aspose.Medical.Dicom.Web.DicomWebRequest request = new()
        {
            Method = method,
            Path = relativePath,
            Query = Aspose.Medical.Dicom.Web.DicomWebQueryParameters.Parse(rawQuery),
            Headers = fields,
            Body = payload,
            ServiceBaseUri = serviceBaseUri,
            IsWebSocketRequest = isWebSocketRequest
        };
        Aspose.Medical.Dicom.Web.DicomWebApplicationResult result =
            await application.ProcessAsync(request, requestAborted);
        return (result, payload);
    }
    catch
    {
        await payload.DisposeAsync();
        throw;
    }
}

rawQuery may include the leading ?; use / for relativePath when the request targets the service root. Supply the absolute service base URI used to build links in results; pass the host’s abort token. The example passes no custom bulk-data loader. To resolve external bulk-data references in incoming metadata, pass an Aspose.Medical.Dicom.Serialization.IAsyncBulkDataLoader as the payload reader’s fourth constructor argument.

DicomWebPayloadReader is forward-only; leaveOpen: false completes its pipe on disposal while StreamPipeReaderOptions(leaveOpen: true) leaves the host-owned stream open. The caller must dispose the returned Payload after writing the Result, because response content may be lazy. Keep any needed request services alive until writing or notification enumeration ends.

After dispatch, set HTTP status from DicomWebResponse.StatusCode, copy Headers, set Content-Type and optional length from Content, then await Content.WriteToAsync on the host response stream. For DicomWebNotificationSession, apply handshake headers, accept the WebSocket, and send each dataset in Notifications as one DICOM JSON text message. Status/header/WebSocket APIs belong to the selected host. For a concrete HTTP and WebSocket adapter, use ASP.NET Core integration. If ProcessAsync cannot resolve a path, it returns a not-found response; a known path with a different method returns method-not-allowed. Protocol, DICOM validation, JSON, and XML parsing failures are converted to error responses where caught by ProcessAsync. Other exceptions can propagate to the host, which should apply its normal exception policy.

10-Net: ASP.NET Core Integration

Mon, 01 Jan 0001 00:00:00 +0000

ASP.NET Core integration

Reference the local Aspose.Medical.Dicom.Web.AspNetCore project or its matching package and the main Aspose.Medical assembly. The checked-out integration project targets .NET 10 and references Microsoft.AspNetCore.App. AddDicomWeb() registers a scoped hosting-neutral application and returns DicomWebAspNetCoreBuilder. Its overload accepts an Action<DicomWebAspNetCoreOptions>. ConfigureApplication(Action<DicomWebApplicationBuilder>) applies route and behavior changes whenever a scoped application is built.

Complete minimal application: standard handler

This Program.cs is a working read-only MWL-RS server with an intentionally empty in-memory worklist. It demonstrates the complete provider contract and responds to search requests without installing persistence:

Microsoft.AspNetCore.Builder.WebApplicationBuilder builder =
    WebApplication.CreateBuilder(args);
Microsoft.Extensions.DependencyInjection.ServiceCollectionServiceExtensions.AddScoped<
    Aspose.Medical.Dicom.Web.Providers.IDicomWebModalityWorklistProvider,
    EmptyModalityWorklist>(builder.Services);
Aspose.Medical.Dicom.Web.DicomWebServiceCollectionExtensions.AddDicomWeb(builder.Services)
    .AddStandardModalityWorklistService();

Microsoft.AspNetCore.Builder.WebApplication app = builder.Build();
Aspose.Medical.Dicom.Web.DicomWebEndpointRouteBuilderExtensions.MapDicomWeb(app, "/dicomweb");
await app.RunAsync();

public sealed class EmptyModalityWorklist : Aspose.Medical.Dicom.Web.Providers.IDicomWebModalityWorklistProvider
{
    public async System.Collections.Generic.IAsyncEnumerable<Aspose.Medical.Dicom.Dataset> FindCandidatesAsync(
        Aspose.Medical.Dicom.Web.Providers.DicomWebSearchContext search,
        [System.Runtime.CompilerServices.EnumeratorCancellation] System.Threading.CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        await System.Threading.Tasks.Task.CompletedTask;
        yield break;
    }
}

For a real worklist, query the backend in stable order from FindCandidatesAsync; the library performs final matching and projection. The equivalent hosting-neutral setup is DicomWebApplication.CreateBuilder().AddStandardModalityWorklistService(new EmptyModalityWorklist()).Build().

To expose Studies instead, use the complete InMemoryStudies and NoRenderedRepresentations classes in standard services and replace the worklist registrations above with:

Microsoft.Extensions.DependencyInjection.ServiceCollectionServiceExtensions.AddSingleton<
    Aspose.Medical.Dicom.Web.Providers.IDicomWebStudiesProvider,
    InMemoryStudies>(builder.Services);
Microsoft.Extensions.DependencyInjection.ServiceCollectionServiceExtensions.AddSingleton<
    Aspose.Medical.Dicom.Web.Providers.IDicomWebRepresentationProvider,
    NoRenderedRepresentations>(builder.Services);
Aspose.Medical.Dicom.Web.DicomWebServiceCollectionExtensions.AddDicomWeb(builder.Services)
    .AddStandardStudiesService();

The singleton in-memory archive survives request scopes for the lifetime of this demo process. Use application-managed persistence and an appropriate DI lifetime in a real service.

Complete custom handler for the same transaction

Replace the provider registration and standard registration above with this DI registration, and use EmptyWorklistHandler from custom handlers:

Aspose.Medical.Dicom.Web.DicomWebServiceCollectionExtensions.AddDicomWeb(builder.Services)
    .AddHandler<Aspose.Medical.Dicom.Web.Transactions.SearchModalityScheduledProcedureSteps,
                EmptyWorklistHandler>();

AddHandler<TTransaction,THandler> and AddHandlerFactory<TTransaction,TFactory> accept a ServiceLifetime (default Scoped); AddOpenRequestBehavior<TFactory> registers a Communication pipeline behavior factory. ConfigureApplication can additionally enable/disable services or add hosting-neutral behaviors. A scoped DicomWebApplication is built from registration callbacks using the request scope’s services. Use a handler factory when a new handler instance is required for each dispatch. A directly registered DI handler is resolved when its application scope is constructed. A later registration for the same transaction replaces the earlier one; register the standard service first when replacing only one of its transactions. Standard provider methods are also resolved from that scope.

Endpoint mapping and transport

MapDicomWeb(pattern) resolves the scoped application from request services. MapDicomWeb(pattern, application) uses the explicitly built immutable application. Both map the root and all resource paths beneath a static service-root path, such as /dicomweb, and return an IEndpointConventionBuilder so endpoint conventions can be applied to the group. The relative DICOMweb resource path excludes the service root. The base URI used for result links includes the request scheme, host, path base, and mapped root; configure ASP.NET Core forwarded headers in the host before relying on proxy-supplied origin values. The route group and host’s middleware supply ordinary ASP.NET Core endpoint features.

The adapter parses ordered query parameters and headers, wraps HttpRequest.BodyReader in a DicomWebPayloadReader, resolves an optional IAsyncBulkDataLoader from request services, passes RequestAborted to ProcessAsync, and writes status, response headers, Content-Type, optional Content-Length, and content to HttpResponse.BodyWriter. The adapter disposes its payload reader without completing the host-owned request pipe. A malformed query string receives HTTP 400. DicomWebResponse content writing may stream after handler completion, so scoped providers and request services must remain valid for the entire response. Exceptions not converted into an application response follow the host’s exception handling pipeline.

DicomWebAspNetCoreOptions.NotificationCloseTimeout defaults to 5 seconds and must be positive. It limits waiting for the peer to complete the WebSocket close handshake after server notification enumeration finishes. It does not configure ASP.NET Core request-body, WebSocket, authentication, or response timeouts.

Notification WebSockets and host policy

When UPS notifications are registered, call the host’s WebSocket middleware and map the DICOMweb endpoints in the usual ASP.NET Core pipeline. A DicomWebNotificationSession supplies handshake headers and ordered event-report datasets. The adapter accepts the WebSocket, writes each dataset as one DICOM JSON text message, and initiates a close handshake after the sequence ends. Request abortion cancels enumeration and transmission. The host must provide authenticated requester identity and appropriate authorization; it also owns CORS, TLS, forwarded headers, upload limits, and WebSocket policy. CORS does not restrict WebSocket origins; configure the host’s WebSocket origin policy separately. IDicomWebSubscriptionProvider owns subscription persistence and notification queues.

Place the middleware before the DICOMweb endpoint when using notification connections:

Microsoft.AspNetCore.Builder.WebSocketMiddlewareExtensions.UseWebSockets(app);
Aspose.Medical.Dicom.Web.DicomWebEndpointRouteBuilderExtensions.MapDicomWeb(app, "/dicomweb");

An explicitly built application can be mapped without AddDicomWeb:

Aspose.Medical.Dicom.Web.DicomWebApplication application =
    DicomWebApplication.CreateBuilder()
        .AddStandardModalityWorklistService(new EmptyModalityWorklist())
        .Build();
Aspose.Medical.Dicom.Web.DicomWebEndpointRouteBuilderExtensions.MapDicomWeb(app, "/dicomweb", application);

In that form the caller owns the application and its provider lifetimes. Use the DI form when request-scoped dependencies are required.

10-Net: DICOMweb Client

Mon, 01 Jan 0001 00:00:00 +0000

DICOMweb client

DicomWebClient is an HTTP user agent independent of the server application in this library. Give it an application-configured HttpClient and DicomWebClientOptions with an absolute BaseUri pointing at the remote service root. The client does not own or dispose the HttpClient. Configure authentication, TLS, proxy, redirects, and connection pooling on that transport. ServiceBaseUris can override roots by DicomWebService when a deployment splits services across paths or origins. BulkDataLoader supplies external metadata Bulk Data resolution; MaxNotificationMessageBytes defaults to 16 MiB.

Option	Default and valid values	Effect
`BaseUri`	Required absolute HTTP or HTTPS URI	Default root for every operation group.
`ServiceBaseUris`	Empty immutable dictionary; each override must be an absolute HTTP or HTTPS URI	Overrides one `DicomWebService` root.
`MaxNotificationMessageBytes`	16 MiB; positive integer	Rejects larger incoming WebSocket event reports.
`BulkDataLoader`	`null`	Optional `IAsyncBulkDataLoader` used while parsing external metadata Bulk Data.

Supply service roots without query strings or fragments. The client appends each standard resource path to the selected root and escapes route and query values; pass those values decoded. A root of https://example.org/dicomweb/ produces a Studies search at https://example.org/dicomweb/studies, while WADO-URI sends its identifying query parameters to the root itself.

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });

await using Aspose.Medical.Dicom.Web.DicomWebClientStream<Aspose.Medical.Dicom.Dataset> studies =
    await client.Studies.SearchAsync(new DicomWebSearchOptions { Limit = 20 });
await foreach (Aspose.Medical.Dicom.Dataset study in studies)
    System.Console.WriteLine(study.Count);

DicomWebSearchOptions supplies ordered matching parameters, included fields, Limit, Offset, fuzzy, empty-value, and multiple-value matching flags, accepted media types, and extra headers. Null option values omit the corresponding query control. Searches return DicomWebClientStream<Dataset>, which owns a live response, can be enumerated once, and should be disposed even if enumeration stops early. DicomWebRetrieveOptions carries accepted media types, extra query parameters, and headers. DicomWebRenderOptions adds quality (1–100), viewport, window, ICC profile, annotation tokens, and additional parameters; see rendering control formats and thumbnail differences. DicomWebRequestOptions carries query parameters and headers for body operations. An empty AcceptedMediaTypes uses the transaction default; do not set both it and an explicit Accept header.

Set MatchingParameters to repeated, decoded DicomWebQueryParameter values. IncludeFields requests additional projected attributes; EmptyValueMatching, FuzzyMatching, and MultipleValueMatching are nullable so an omitted value leaves the server default in place. The provider receives a compiled search plan and the standard engine performs final DICOM matching:

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Web.DicomWebSearchOptions options = new()
{
    MatchingParameters = [new Aspose.Medical.Dicom.Web.DicomWebQueryParameter("PatientName", "SMITH*")],
    IncludeFields = ["StudyDate", "PatientID"],
    FuzzyMatching = false,
    EmptyValueMatching = false,
    MultipleValueMatching = false,
    Limit = 20,
    Offset = 0
};
await using Aspose.Medical.Dicom.Web.DicomWebClientStream<Aspose.Medical.Dicom.Dataset> matches =
    await client.Studies.SearchAsync(options);
await foreach (Aspose.Medical.Dicom.Dataset study in matches)
    System.Console.WriteLine(study.Count);

When explicitly including a private data attribute in a standard study, series, instance, or workitem search, also supply a matching parameter for its Private Creator attribute. The creator must identify the same private block and, for a nested attribute, have the same sequence path. The standard service rejects an included private data attribute without its corresponding creator match. This requirement does not apply to including the Private Creator attribute itself.

Operation groups and results

Client property	Operations	Result shape
`Capabilities`	`RetrieveAsync`	Raw `DicomWebClientResponse` for JSON or WADL capabilities
`Uri`	`RetrieveDicomInstanceAsync`, `RetrieveRenderedInstanceAsync`	Materialized `RetrieveUriDicomInstanceResult.File`, or raw rendered response
`Studies`	Study/series/instance search; `StoreAsync` and `StoreStudyAsync`; study/series/instance DICOM and metadata retrieval; bulk data, pixel data, frame retrieval; rendered, MPR, 3D, and thumbnail retrieval	Search/metadata `DicomWebClientStream<Dataset>`; study/series `DicomWebClientStream<DicomFile>`; single instance `RetrieveInstanceResult.File`; store `StoreInstancesResult.Response`; binary/rendered methods return raw responses
`Worklist`	Create, search, retrieve, update, change state, request cancellation, workitem/worklist/filtered-worklist subscription changes, `ConnectNotificationsAsync`	Workitem datasets, optional status reports, materialized outcomes, search stream, or notification connection
`StorageCommitment`	`RequestAsync`, `CheckResultAsync`	`IsPending` and optional `Report`
`ModalityWorklist`	`SearchAsync`	Dataset stream
`ModalityPerformedProcedureSteps`	`CreateAsync`, `UpdateAsync`, `RetrieveAsync`	Optional status report or retrieved procedure-step dataset
`NonPatientInstances`	`SearchAsync`, `StoreAsync`, `RetrieveAsync`	Dataset stream, STOW response dataset, or `RetrieveNonPatientInstanceResult.File`

The method overloads accept a typed Dataset or DicomFile for common requests and DicomWebContent for caller-controlled payloads. Studies and non-patient stores also accept synchronous or asynchronous file sequences where provided. StoreStudyAsync constrains the study in the URI. Worklist update and typed state-change overloads accept the transaction UID that identifies workflow ownership. Cancellation overloads with a requester argument instead identify the requesting AE Title. The results table describes the payload type; always inspect Response.StatusCode, headers, and the operation-specific value for partial or pending outcomes.

Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.RetrieveInstanceResult> instance =
    await client.Studies.RetrieveInstanceAsync("1.2.3", "1.2.3.4", "1.2.3.4.5");
Aspose.Medical.Dicom.DicomFile file = instance.Value.File;

Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.StoreInstancesResult> stored =
    await client.Studies.StoreAsync(file);
Aspose.Medical.Dicom.Dataset storeReport = stored.Value.Response;

For large study retrieval, use the one-pass stream instead of accumulating all files:

await using Aspose.Medical.Dicom.Web.DicomWebClientStream<Aspose.Medical.Dicom.DicomFile> files =
    await client.Studies.RetrieveStudyAsync("1.2.3");
await foreach (Aspose.Medical.Dicom.DicomFile item in files)
    System.Console.WriteLine(item.Dataset.Count);

The other service groups use the same client and result conventions. These calls use UIDs from an existing deployment:

await using Aspose.Medical.Dicom.Web.DicomWebClientStream<Aspose.Medical.Dicom.Dataset> scheduled =
    await client.ModalityWorklist.SearchAsync();
await foreach (Aspose.Medical.Dicom.Dataset step in scheduled)
    System.Console.WriteLine(step.Count);

Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.CheckStorageCommitmentResult> commitment =
    await client.StorageCommitment.CheckResultAsync("1.2.3.6");
if (commitment.Value.IsPending)
    System.Console.WriteLine("Check again later");

Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.RetrieveModalityPerformedProcedureStepResult> mpps =
    await client.ModalityPerformedProcedureSteps.RetrieveAsync("1.2.3.7");
Aspose.Medical.Dicom.Dataset procedureStep = mpps.Value.ProcedureStep;

Aspose.Medical.Dicom.Web.DicomWebClientResult<Aspose.Medical.Dicom.Web.Transactions.RetrieveNonPatientInstanceResult> palette =
    await client.NonPatientInstances.RetrieveAsync("color-palettes", "1.2.3.8");
Aspose.Medical.Dicom.DicomFile paletteFile = palette.Value.File;

await using Aspose.Medical.Dicom.Web.DicomWebClientResponse rendered =
    await client.Studies.RetrieveRenderedInstanceAsync("1.2.3", "1.2.3.4", "1.2.3.4.5");
rendered.EnsureSuccessStatusCode();

Read the raw rendered ContentReader or copy it to your output destination before disposing the response. The server must advertise and implement the requested representation. The client exposes MPR and 3D methods, but the bundled standard Studies handler currently throws NotSupportedException for those transactions; use a server with a custom implementation before calling them.

WADO-URI and separate service roots

Use ServiceBaseUris[DicomWebService.Uri] when WADO-URI has a different endpoint from the Studies service. The client adds requestType=WADO, the Study, Series, and SOP Instance UIDs, and contentType to the query. For rendered retrieval, provide a concrete non-DICOM contentType; do not use a wildcard. WADO-URI media types must not include transfer-syntax or charset parameters. This example retrieves both Part 10 and JPEG representations from an existing server:

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/"),
        ServiceBaseUris = System.Collections.Immutable.ImmutableDictionary<
            Aspose.Medical.Dicom.Web.DicomWebService, System.Uri>.Empty.Add(
                Aspose.Medical.Dicom.Web.DicomWebService.Uri,
                new System.Uri("https://example.org/wado/"))
    });
Aspose.Medical.Dicom.Web.DicomWebClientResult<
    Aspose.Medical.Dicom.Web.Transactions.RetrieveUriDicomInstanceResult> instance =
    await client.Uri.RetrieveDicomInstanceAsync("1.2.3", "1.2.3.4", "1.2.3.4.5");
System.Console.WriteLine(instance.Value.File.Dataset.Count);

await using Aspose.Medical.Dicom.Web.DicomWebClientResponse image =
    await client.Uri.RetrieveRenderedInstanceAsync("1.2.3", "1.2.3.4", "1.2.3.4.5",
        DicomWebMediaTypes.ImageJpeg,
        new DicomWebRenderOptions { Quality = 80 });
image.EnsureSuccessStatusCode();
await using System.IO.FileStream output = File.Create("wado-instance.jpg");
await image.ContentReader.CopyToAsync(output);

Raw requests and response ownership

SendAsync(DicomWebClientRequest, token) sends a standard DicomWebTransaction with route-template values, ordered query parameters, headers, and optional DicomWebContent. It returns DicomWebClientResponse; dispose it after reading. StatusCode, IsSuccessStatusCode, Headers, ContentType, and ContentReader expose the live HTTP outcome. EnsureSuccessStatusCode throws HttpRequestException on unsuccessful HTTP status. ReadDatasetAsync, ReadDatasetsAsync, ReadDicomFileAsync, and ReadDicomFilesAsync parse one semantic form from the same forward-only body. Do not mix these readers with direct ContentReader reads on one response. Typed, materialized DicomWebClientResult<T> owns a consumed value and Response metadata; its response body has already been closed. Raw rendered and binary retrievals leave response consumption to you.

Aspose.Medical.Dicom.Web.DicomWebClientRequest request =
    new(Aspose.Medical.Dicom.Web.Transactions.RetrieveCapabilities.Instance);
await using Aspose.Medical.Dicom.Web.DicomWebClientResponse response =
    await client.SendAsync(request);
response.EnsureSuccessStatusCode();
System.Console.WriteLine(response.ContentType);

DicomWebClientRequest.RouteValues fills the named segments in a standard route template. This direct request asks for one study’s metadata, names its route value explicitly, and consumes the raw response as a dataset sequence:

using System.Net.Http.HttpClient transport = new();
Aspose.Medical.Dicom.Web.DicomWebClient client = new(transport,
    new DicomWebClientOptions
    {
        BaseUri = new System.Uri("https://example.org/dicomweb/")
    });
Aspose.Medical.Dicom.Web.DicomWebClientRequest request =
    new(Aspose.Medical.Dicom.Web.Transactions.RetrieveStudyMetadata.Instance)
    {
        RouteValues = new System.Collections.Generic.Dictionary<string, string> { ["study"] = "1.2.3" },
        Headers = new Aspose.Medical.Dicom.Web.DicomWebHeaders(
            ("Accept", [Aspose.Medical.Dicom.Web.DicomWebMediaTypes.ApplicationDicomJson]))
    };
await using Aspose.Medical.Dicom.Web.DicomWebClientResponse response =
    await client.SendAsync(request);
await foreach (Aspose.Medical.Dicom.Dataset metadata in response.ReadDatasetsAsync())
    System.Console.WriteLine(metadata.Count);

See worklist and procedure step workflows, storage commitment and non-patient instances, and representations and streaming for service-specific requests and response consumption.

Failures and cancellation

Operations that return a materialized result or open a DicomWebClientStream<T> check the HTTP status before returning. On an unsuccessful HTTP status, they throw DicomWebClientException, which derives from HttpRequestException and exposes Response, a bounded ResponseBody, and IsResponseBodyComplete. The captured body can be incomplete if its limit is reached or reading fails; it is not necessarily a DICOM dataset. Transport failures and local input or payload validation can throw other exceptions.

Methods that return DicomWebClientResponse, including SendAsync and rendered or binary retrievals, leave HTTP status handling to the caller. Check IsSuccessStatusCode and read the raw body if you need error details, or call EnsureSuccessStatusCode to throw HttpRequestException. This raw path does not capture a DicomWebClientException.ResponseBody automatically. The semantic readers also require a successful status.

Cancellation must cover both opening a response and consuming its body:

Operation	Cancellation scope
Materialized result	Its operation token covers sending the request and parsing the result.
`DicomWebClientStream<T>`	The operation token covers sending and opening the response. Pass an enumeration token through `WithCancellation` or `GetAsyncEnumerator(token)` to cancel subsequent item reads.
Raw `DicomWebClientResponse`	The operation token covers sending and acquiring the response. Pass a token to the semantic reader or `ContentReader.CopyToAsync` when consuming the body.
Notification connection	The connection token covers the opening handshake. Each `ReceiveAsync` accepts its own receive token.

Dispose streamed and raw responses when reading ends or is canceled. A timeout for the whole download must remain active through body consumption; successfully opening a response does not mean that its payload has finished arriving.

Notifications

ConnectNotificationsAsync(requester, configure, token) on the client or Worklist opens the UPS WebSocket. Configure ClientWebSocketOptions when credentials or headers are needed. Dispose the connection after use. ReceiveAsync returns one parsed DICOM JSON event dataset or null after a close message; only one receive may be active. Binary, oversized, or malformed event messages fail. The server must have a subscription provider, an enabled notification route, and WebSocket hosting support.

State exposes the current System.Net.WebSockets.WebSocketState. Canceling a receive or failing to receive or parse an event aborts the connection. Dispose that connection and call ConnectNotificationsAsync again to resume receiving; another ReceiveAsync call on the aborted connection cannot resume the interrupted event. A normal close, indicated by null, also ends receiving on that connection.

await using Aspose.Medical.Dicom.Web.DicomWebNotificationConnection connection =
    await client.ConnectNotificationsAsync("READER");
Aspose.Medical.Dicom.Dataset? eventReport = await connection.ReceiveAsync();
if (eventReport is not null)
    System.Console.WriteLine(eventReport.Count);

10-Net: Client Operations

Mon, 01 Jan 0001 00:00:00 +0000

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.

10-Net: Protocol and API Reference

Mon, 01 Jan 0001 00:00:00 +0000

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.

Documentation – DICOMweb

10-Net: Standard Services

Standard services and provider contracts

Search providers

Compiled search filters

Search provider examples

Persistence and representation contracts

Store results and partial success

10-Net: Worklist and Procedure Step Workflows

Worklist and procedure step workflows

UPS subscriptions and notification delivery

UPS updates and final states

MPPS uses the same revision contract

10-Net: Storage Commitment and Non-Patient Instances

Storage commitment and non-patient instances

A pending storage commitment request

Non-patient instance storage

10-Net: Custom Handlers

Custom transaction handlers

10-Net: Representations and Streaming

Representations and streaming

DICOM transfer syntax and metadata

Declare a JPEG representation

Rendering controls

Bulk data, frames, and multipart bodies

10-Net: Hosting-Neutral Integration

Hosting-neutral integration

10-Net: ASP.NET Core Integration

ASP.NET Core integration

Complete minimal application: standard handler

Complete custom handler for the same transaction

Endpoint mapping and transport

Notification WebSockets and host policy

10-Net: DICOMweb Client

DICOMweb client

Operation groups and results

WADO-URI and separate service roots

Raw requests and response ownership

Failures and cancellation

Notifications

10-Net: Client Operations

Client operation reference

Studies

UPS Worklist

Typed result values

10-Net: Protocol and API Reference

Protocol and API reference

Transaction families

Representations and transport values

Payload readers

Headers and query parameters

Search and rendering controls

Failures and lifecycle