Retrieving a complete DICOM study lets your application process its instances without requesting each one separately. With Aspose.Medical for .NET, you can use a Study Instance UID to retrieve the study through DICOMweb and work with the returned DICOM files in C#.

This tutorial shows how to configure a DICOMweb client, retrieve all instances of a study, and print the SOP Instance UID of each returned file. The example processes the response asynchronously and does not save files to disk.

Retrieve DICOM Files with Aspose.Medical for .NET

Aspose.Medical for .NET provides a DICOMweb client for communicating with compatible servers. Study retrieval uses WADO-RS, the DICOMweb service for retrieving DICOM resources.

The RetrieveStudyAsync method returns a DicomWebClientStream<DicomFile>. Each item represents a DICOM Part 10 file from the study. The client handles the multipart response parsing, so you can focus on processing the returned instances.

For details about response formats, see the representations and streaming documentation.

Prerequisites

Before running the example, prepare:

  • A C# console application targeting a framework supported by your Aspose.Medical package.
  • An Aspose.Medical version that includes the DICOMweb APIs used below.
  • A reachable DICOMweb server that supports study retrieval.
  • The Study Instance UID of an existing study on that server.
  • Any authentication required by the server.

Install the package in your project directory:

dotnet add package Aspose.Medical

You can also install it through Visual Studio’s NuGet Package Manager. See the Aspose.Medical downloads page for package information.

How to Retrieve All Instances of a DICOM Study in C#

To retrieve a DICOM study, follow these steps:

  1. Create an HttpClient for the HTTP requests.
  2. Set DicomWebClientOptions.BaseUri to your server’s DICOMweb service URL.
  3. Create a DicomWebClient using the HTTP client and options.
  4. Pass the Study Instance UID to client.Studies.RetrieveStudyAsync.
  5. Use await foreach to process each returned DicomFile.
  6. Read the SOP Instance UID from the file’s dataset.

Add the following code to Program.cs:

using System.Net.Http;
using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Web;

HttpClient httpClient = new HttpClient();
DicomWebClientOptions options = new DicomWebClientOptions
{
    BaseUri = new System.Uri("https://dicom.example.com/dicomweb")
};
DicomWebClient client = new DicomWebClient(httpClient, options);

string studyUid = "1.2.840.113619.2.55.3.604688119";

// Retrieve the study as DICOM Part 10 files
await using DicomWebClientStream<DicomFile> files = await client.Studies.RetrieveStudyAsync(studyUid);

await foreach (DicomFile file in files)
{
    string sopInstanceUid = file.Dataset.GetValue<string>(
        Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID, 0);
    System.Console.WriteLine($"Retrieved instance: {sopInstanceUid}");
}

Replace https://dicom.example.com/dicomweb with your server’s actual DICOMweb base URL. Replace studyUid with a Study Instance UID available on that server. The supplied address and UID are placeholders, so the example requires these changes before it can retrieve data.

If the server requires authentication, configure the HttpClient according to its requirements before sending the request. The DicomWebClient does not take ownership of that HTTP client; your application manages its lifetime.

Understand the Retrieval and Processing Steps

Select the study by its Study Instance UID

The studyUid argument identifies the study to retrieve. You do not need to provide a Series Instance UID or a separate SOP Instance UID for every file.

The RetrieveStudyAsync API reference documents optional retrieval settings and a cancellation token in addition to the required study UID.

Process the returned files asynchronously

The await foreach loop enumerates the returned files. Place your per-instance processing inside this loop rather than collecting every file into a list first.

The response is a one-pass stream. If you need another pass through the instances, design your application to retain the required results or make another retrieval request. Keep the await using declaration so the stream is disposed when its scope ends.

Read each SOP Instance UID

Inside the loop, file.Dataset.GetValue<string>(Tag.SOPInstanceUID, 0) reads the first value of the SOP Instance UID element. This identifier belongs to the individual instance, whereas the Study Instance UID selects the study containing those instances.

The example prints each identifier to the console. It does not render images, create an archive, or write .dcm files to a local folder.

Expected Output

After a successful retrieval, the console displays one line for each returned instance. For example:

Retrieved instance: 1.2.3.4.5.1
Retrieved instance: 1.2.3.4.5.2
Retrieved instance: 1.2.3.4.5.3

These identifiers are illustrative. The actual values and number of lines depend on the selected study and the server response.

Troubleshoot Study Retrieval

If retrieval fails, check the DICOMweb base URL, the study UID, and the credentials used by your HTTP client. Confirm that the server supports retrieving the study as DICOM files.

Handle errors around both the retrieval call and the asynchronous loop: a streamed response can fail while your application is enumerating it. For longer operations, review the method’s cancellation parameter and configure the HTTP client’s timeout for your application.

If the code does not recognize DicomWebClient or RetrieveStudyAsync, check the installed package version against the current API reference.

Conclusion

In this guide, you have learned how to retrieve all instances of a DICOM study in C# using Aspose.Medical for .NET. By processing the returned files asynchronously, you can read each instance’s SOP Instance UID and extend the example to handle the DICOM data your application needs.

Use the loop as the starting point for your own per-instance processing, then test it with a known study on your DICOMweb server. The DICOMweb client guide covers related search, storage, and retrieval operations.

Frequently Asked Questions

Can I retrieve a study without knowing every instance UID?

Yes. RetrieveStudyAsync takes the Study Instance UID and retrieves all instances in that study. You do not need to list their individual UIDs in the request.

Does this example download DICOM files to a folder?

It retrieves DICOM files over HTTP as DicomFile objects, but it does not save them to disk. The loop only reads and prints their SOP Instance UIDs.

How can I retrieve only the study metadata?

Use RetrieveStudyMetadataAsync when you need metadata for the study’s instances. It returns a stream of Dataset objects rather than a stream of DICOM files.