---
title: Displaying page attachments
related:
  - https://docs.kentico.com/13/developing-websites/generating-classes-for-xperience-objects.md
  - https://docs.kentico.com/13/managing-website-content/working-with-files/page-attachments.md
  - https://docs.kentico.com/13/developing-websites/defining-website-content-structure/managing-page-types/configuring-grouped-page-attachments.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

[Attachments](https://docs.kentico.com/13/managing-website-content/working-with-files/page-attachments.md) represent files, for example images or documents, tied directly to a page. Attachments can be stored in [page type](https://docs.kentico.com/13/developing-websites/defining-website-content-structure/managing-page-types.md) fields of the following [data types](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/reference-field-editor.md):

- **Attachments** – stores multiple attachments under a single page type field.
- **File** – stores a single page attachment.

and as [unsorted attachments](https://docs.kentico.com/13/managing-website-content/working-with-files/page-attachments/attaching-files-to-pages.md) tied directly to the page (_TreeNode_) object.

When working with page attachments in the API:

- Use the [IPageRetriever service](https://docs.kentico.com/13/custom-development/working-with-pages-in-the-api.md) to retrieve the desired pages. You can use [page type generators](https://docs.kentico.com/13/developing-websites/generating-classes-for-xperience-objects.md) to generate strongly typed representations of individual page types. The generated code uses the **DocumentAttachment** type (available in the _CMS.DocumentEngine_ namespace) for _File_ fields, and **IEnumerable** for _Attachments_ fields.
- Access page field attachments via the **Fields** property of the generated page type class. You can access various attachment properties, such as their name or MIME type.
- Access unsorted attachments via the **Attachments** property of the generated page type class.
- To generate URLs for page attachments, use the [IPageAttachmentUrlRetriever service](#getting-page-attachment-urls).

The following example illustrates how to access various page attachments of the _Article_ page type using its corresponding generated class:

```csharp title="Working with page attachments using generated page type code"

// Contains an instance of the IPageRetriever service (e.g., obtained via dependency injection)
private readonly IPageRetriever pageRetriever;

// Retrieves an article
Article article = pageRetriever.Retrieve<Article>(
                        query => query
                                .Path("Home/", PathTypeEnum.Single)
                                .TopN(1))
                                .FirstOrDefault();

// Accesses a property of an attachment stored in the article's 'Teaser' field (of the File data type)
string attachmentName = article.Fields.Teaser.AttachmentName;

// Iterates over attachments in the article's 'Images' field (of the Attachments data type)
foreach (DocumentAttachment image in article.Fields.Images)
{
    string imageMimeType = image.AttachmentMimeType;
}

// Iterates over unsorted attachments 
foreach (DocumentAttachment image in article.Attachments)
{
    string imageMimeType = image.AttachmentMimeType;
}  

```

## Getting page attachment URLs

To generate URLs for page attachments, use the **IPageAttachmentUrlRetriever** service (_Kentico.Content.Web.Mvc_ namespace) and its **Retrieve** method:

```csharp

// Contains an instance of the IPageAttachmentUrlRetriever  service (e.g., obtained via dependency injection)
private readonly IPageAttachmentUrlRetriever attachmentUrlRetriever;

// Contains a page from Xperience
// The Article class is a strongly typed representation of a custom 'Article' 
// page typed generated by the system (Page Types application -> edit a page type -> Code tab)
Article article;

// Resolves a URL for an attachment stored in the 'Attachment' field of the 'Article' page type
IPageAttachmentUrl attachmentUrl = attachmentUrlRetriever.Retrieve(article.Fields.Attachment);

```

The _Retrieve_ method returns an **IPageAttachmentUrl** object with the following properties:

- string **AbsoluteUrl** – the application absolute URL of the page attachment.
- string **RelativePath** – the application relative (starting with '_\~/_') permanent path to the file. For example: _\~/getattachment/0140bccc-9d47-41ea-94a9-ca5d35b2964c/sample\_image.jpg_. This format ensures that the image remains accessible if the file is renamed or moved to a different media library or directory on the file system.
- bool **IsImage** – a boolean flag stating whether the URL leads to an image file.
- NameValueCollection **QueryStringParameters** – a collection of query string parameters appended to the URL. See [Parameterizing attachment URLs](#parameterizing-attachment-urls).

> **Info:** **Special characters**
>
> The system replaces all special characters in file names with a '-' (hyphen). This includes characters that are not 0-9, a-z (Latin lower case 'a' to 'z'), '.' (full stop) or '\_' (underscore).

You can further adjust the URLs by calling various extension methods on the _IPageAttachmentUrl_ object. See [Parameterizing attachment URLs](#parameterizing-attachment-urls).

### Creating image variant URLs

To get URLs for [image variants](https://docs.kentico.com/13/developing-websites/managing-responsive-images/defining-image-variants.md) of page attachments, use the **WithVariant** extension method (_Kentico.Content.Web.Mvc_ namespace) on the _IPageAttachmentUrl_ object. Specify the image variant definition identifier as the method's parameter. The generated URLs are treated identically to URLs generated for standard attachments and can be [parameterized](#parameterizing-attachment-urls) the same way.

```csharp

IPageAttachmentUrl variantUrl = attachmentUrl.WithVariant("variantName");

```

### Parameterizing attachment URLs

You can further parameterize the retrieved attachment URLs via extension methods on the **IPageAttachmentUrl** object. The extension methods add query string parameters that change the URL behavior and allow you to customize the format of the files. The following extensions are available:

- **WithOptions** – used to provide additional configuration for the URL via a **FileUrlOptions** object. Using the object, you can specify:

  - _Content disposition_ – configured via the _AttachmentContentDisposition_ boolean property. Determines whether the file gets displayed inline (_false_) or requires some form of user action to download (_true_).

    ```csharp

    using Kentico.Content.Web.Mvc

    ...

    // Forces a download of the media file when its URL is accessed
    // The pageAttachmentUrl variable is an IPageAttachmentUrl object obtained via IPageAttachmentUrlRetriever
    IFileUrl attachmentUrlWithOptions = pageAttachmentUrl.WithOptions(new FileUrlOptions { AttachmentContentDisposition = true});

    ```
- **WithSizeConstraint** – used to resize image media files. You can resize image files via the  **SizeConstraint**  parameter of the method. Note, however, that this parameterization never upscales the image. The following image size constraints are available:
  - _SizeConstraint.Empty –_ leaves the image unchanged.
  - _SizeConstraint.Height(100)_ – resizes the image to the specified height (maintains aspect ratio).
  - _SizeConstraint.Width(100)_ – resizes the image to the specified width (maintains aspect ratio).
  - _SizeConstraint.MaxWidthOrHeight(100)_ – resizes the image so that its width and height do not exceed the specified value (maintains aspect ratio).
  - _SizeConstraint.Size(100, 120)_ – resizes the image to the specified width and height. Does not maintain aspect ratio.

    > **Info:** **Image resizing**
    >
    > - It is not possible to resize image files via the _SizeConstraint_ parameter when using **direct URLs**. This is caused by the fact that files accessed from direct URLs are handled directly by the hosting environment.
    > - Image resizing via the _SizeConstraint_ parameter is not supported for the SVG and WebP image formats.
    > - Resized images are not rendered by default on Linux deployments of ASP.NET Core live site projects. To add compatible image resizing functionality, developers need to apply [hotfix 13.0.107](https://devnet.kentico.com/download/hotfixes) or newer and install the [Kentico.Xperience.ImageProcessing.KX13](https://www.nuget.org/packages/Kentico.Xperience.ImageProcessing.KX13) NuGet package into the live site project.
    > - For ASP.NET Core projects, developers can provide their own image resizing functionality – implement `IImageProcessingService` and register the service using the `RegisterImplementation` attribute. Requires [hotfix 13.0.107](https://devnet.kentico.com/download/hotfixes) or newer.
    > - If the [Image file request protection](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-media-libraries/securing-media-libraries.md#image-file-request-protection) feature is enabled, any links to image file endpoints (i.e., `getattachment`) with resizing query parameters need to include a validation hash.