---
title: Consumption
summary: How a consuming application references, constructs, calls, and disposes the proxy.
status: draft
owner: SAIF.Core documentation
last_reviewed: 2026-09-24
---

# Consumption

A consumer obtains document preview and distribution by holding a `DocumentServiceProxy` instance for the lifetime of `SAIF.Services.Utilities.Documents.DocumentService`, which is itself consumed by `SAIF.Services.Web.Proxies` and, through that library, by `SAIF.Services.Web.Proxies` consumers documented at [`SAIF.Services.Web.Proxies` overview](../../libraries/saif-services-web-proxies/overview.md), including several `DependencyMaps/SAIF.DependencyMaps.Web.*` Autofac registrations and the `PrintAPI` controllers.

## Reference style

| Field | Value |
| --- | --- |
| Mechanism | Service Reference (svcutil) |
| Declared in | `Services/SAIF.Services.Web.Proxies/Service References/Document/Reference.svcmap` |
| Generated artifacts | `Services/SAIF.Services.Web.Proxies/Service References/Document/Reference.cs` |
| Target framework | .NET Framework 4.6.2 |
| Regeneration command | Visual Studio "Update Service Reference" |

## Construction

```csharp
public DocumentServiceProxy(string serviceUrl)
{
    Enforce.ArgumentNotNullOrWhiteSpace(serviceUrl, nameof(serviceUrl));
    var binding = new BasicHttpBinding
    {
        MaxReceivedMessageSize = int.MaxValue,
        ReaderQuotas = new XmlDictionaryReaderQuotas { MaxArrayLength = int.MaxValue }
    };
    webService = new clsGenerateSoapClient(binding, new EndpointAddress(serviceUrl));
}
```

| Step | Requirement |
| --- | --- |
| Endpoint address | Constructor argument, resolved by `DocumentService` from `IEnvironmentService.GetConfigSetting("documentGeneratorServiceUrl")` |
| Binding | Constructed in code — `BasicHttpBinding` with `MaxReceivedMessageSize` and `ReaderQuotas.MaxArrayLength` raised to `int.MaxValue` |
| Credentials | None |
| Initialization | Single-constructor |

## Endpoint configuration

| Setting | Value | Source | Changeable without a rebuild |
| --- | --- | --- | --- |
| Endpoint address | `http://xpressionsdev:8000/wsDocuments/clsGenerate.asmx` (non-prod) / `http://xpressionsprod:8000/wsDocuments/clsGenerate.asmx` (prod) | `Services/SAIF.Services.WebApi/EnvironmentApi/App_Data/environments.xml` | Yes |
| Binding configuration | Constructed in code | `Services/SAIF.Services.Web.Proxies/DocumentServiceProxy.cs:22-29` | No |
| Security mode | None declared — `BasicHttpBinding()` default* | `DocumentServiceProxy.cs:23` | No |

The `app.config` `<client><endpoint name="clsGenerateSoap">` entry (`Services/SAIF.Services.Web.Proxies/app.config:59`, address `eexprod4`) is present but is not used at runtime, because the wrapper supplies an explicit `Binding` and `EndpointAddress` to the generated constructor.

## Resilience

| Concern | Finding | Configurable by consumer | Source | Tech debt |
| --- | --- | --- | --- | --- |
| Timeout | None configured — binding defaults apply | No | `DocumentServiceProxy.cs:22-29` | Yes |
| Retry | None configured | No | — | Yes |
| Circuit breaking | None configured | No | — | Yes |
| Thread safety | Not determined from source | — | — | No |
| Cancellation | Not supported — no cancellation on any of the six call sites | — | `DocumentServiceProxy.cs:37-146` | Yes |
| Message size limits | `MaxReceivedMessageSize` and `MaxArrayLength` raised to `int.MaxValue`; `ReaderQuotas.MaxStringContentLength` keeps the 8192 default* | Yes | `DocumentServiceProxy.cs:24-27` | Yes |

The message-size limits were raised to accommodate large rendered PDFs, but the timeouts were not raised alongside them, so a large document distribution can still time out under the default one-minute send timeout*.

## Disposal

| Aspect | Finding |
| --- | --- |
| Disposal performed | `Close()` |
| Faulted channel handled | No — a faulted channel throws from disposal and masks the original failure* |
| Wrapper responsibility | `DocumentServiceProxy` disposes the generated proxy |
| Source | `Services/SAIF.Services.Web.Proxies/DocumentServiceProxy.cs:217-225` |

```csharp
public void Dispose()
{
    webService.Close();
}
```

`DocumentService` instances constructed per request in `Services/SAIF.Services.WebApi/PrintAPI/Controllers/ReportsController.cs:30,61,92,110` and `HomeController.cs:24` are never disposed*, so the underlying `DocumentServiceProxy`/`clsGenerateSoapClient` chain is also left undisposed for those call paths.

## Error handling for consumers

| Failure | Surfaces as | Consumer action |
| --- | --- | --- |
| Service unreachable | `EndpointNotFoundException`† | None — propagates to `DocumentService`, then to controllers/services |
| SOAP fault returned | `FaultException`† | None — propagates unchanged |
| Timeout exceeded | `TimeoutException`† | None — propagates unchanged |
| Response larger than the message size limit | Not applicable — `MaxReceivedMessageSize` is raised to `int.MaxValue` | — |
| Empty or absent output message | `ArgumentNullException` from LINQ's `OrderBy` for `GetCategories`/`GetPackages`, or a `NullReferenceException` from `MapFaxMessage` when `faxInfo` is `null`* | None — unhandled |

## Usage examples

```csharp
// Preview a document package as a PDF
var pdfBytes = documentService.GeneratePdf(package, xml, profile);

// Distribute a document package by email and image import
documentService.DistributeDocument(docConfig, imageConfig, mailMessage, printConfig, deferredPrintConfig);
```

| Scenario | Operations used | Notes |
| --- | --- | --- |
| Preview a rendered document as PDF | `previewDocument` | Reached through `DocumentService.GenerateDocument`/`GeneratePdf` |
| List categories and packages for the caller's application | `categoriesForUser`, `documentsForCategory` | Reached through `DocumentService.GetCategories`/`GetPackages` |
| Distribute a document by print, email, fax, or imaging | `distributeDocument` | Reached through the four `DocumentService.DistributeDocument` overloads |

## Lifecycle guidance

| Question | Answer |
| --- | --- |
| Construct once or per call | Once per `DocumentService` instance, itself constructed per request in the `PrintAPI` controllers |
| Disposable | Yes (`IDisposable`) |
| Safe to share across threads | Not determined from source |

## Related documentation
- [Client index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Contract](contract.md)
- [Operation map](operation-map.md)
- [Client reference](reference.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `†` are derived from dependency library
> documentation via the Legends CLI. Statements marked with `*` were inferred
> from code structure or contextual evidence.

## Sources
- `Services/SAIF.Services.Web.Proxies/DocumentServiceProxy.cs`
- `Services/SAIF.Services/Utilities/Documents/DocumentService.cs`
- `Services/SAIF.Services.WebApi/PrintAPI/Controllers/ReportsController.cs`
- `Services/SAIF.Services.WebApi/PrintAPI/Controllers/HomeController.cs`