Retrieve content items

Xperience by Kentico provides the ContentRetriever API as the primary and recommended approach for retrieving reusable content.

The ContentRetriever API works with:

• Generated content type classes – classes generated by the system that allow you to work with content type fields using strongly-typed objects. These classes also allow access to all general data (title, ID, GUID, creation date, publish date, etc.) as well.
• Custom data transfer objects (advanced use case) – using custom DTOs grants you control over the mapping logic. See Custom model mapping. Note that some Xperience APIs that work with content items expect certain system fields to be present in the model and will not work as expected otherwise.

For more information about content querying and available parametrization, see ContentRetriever API and Reference - ContentRetriever API.

Retrieve content items

To retrieve content items, use the IContentRetriever service from the Kentico.Content.Web.Mvc namespace. This service provides built-in caching, optimized performance, and simplified content retrieval with generated classes for individual content types. The generated content type classes allow you to work with strongly typed objects and easily access their fields.

The ContentRetriever API provides several methods for different content retrieval scenarios:

• RetrieveContent – for retrieving items of a single content type
• RetrieveContentOfContentTypes – for retrieving items of multiple content types
• RetrieveContentOfReusableSchemas – for retrieving items using reusable field schemas
• RetrieveContentByGuids – for retrieving specific items by their GUIDs

Each method uses its corresponding parameter class (RetrieveContentParameters, RetrieveContentOfContentTypesParameters, etc.) to configure retrieval behavior.

For a detailed overview of the available methods and their parameters, see Reference - ContentRetriever API.

// Services obtained via dependency injection
private readonly IContentRetriever contentRetriever;

private async Task SampleRetrieval()
{
    // Retrieves 3 banners with linked items
    var banners = await contentRetriever.RetrieveContent<Banner>(
        new RetrieveContentParameters
        { 
            LinkedItemsMaxLevel = 1
        },
        query => query.TopN(3),
        new RetrievalCacheSettings(cacheItemNameSuffix:
                                    $"{nameof(RetrieveContentQueryParameters.TopN)}|3"));

    // Accesses the content item data
    foreach (Banner item in banners)
    {
        // Accesses content type fields
        string header = item.BannerHeaderText;

        // Accesses system fields
        VersionStatus status = item.SystemFields.ContentItemCommonDataVersionStatus;
    }
}

For scenarios requiring advanced query customization, you can use the content item query API with ContentItemQueryBuilder and IContentQueryExecutor.

Filter content items based on tags

You can limit the retrieval to only content items with specified tags tags using the additionalQueryConfiguration parameter with the WhereContainsTags method:

// A collection of tags, e.g., obtained from a Tag selector
IEnumerable<Guid> tagIdentifiers;

var banners = await contentRetriever.RetrieveContent<Banner>(
    query => query.WhereContainsTags("SomeTaxonomy", tagIdentifiers),
    new RetrievalCacheSettings(cacheItemNameSuffix:
                                    $"{nameof(WhereParameters.WhereContainsTags)}|SomeTaxonomy|tagIdentifiers"));

You can also create a TagCollection object and pass it as an argument of the WhereContainsTags method. The TagCollection object then represents a collection of all tags specified as the input and any tags that are children of the specified tags. This is useful when you need to retrieve all items that belong in a subtree of a taxonomy.

// A collection of tags, e.g., obtained from a Tag selector
IEnumerable<Guid> tagIdentifiers;
var tagCollection = await TagCollection.Create(tagIdentifiers);

var articles = await contentRetriever.RetrieveContent<ArticlePage>(
    query => query.WhereContainsTags("SomeTaxonomy", tagCollection),
    new RetrievalCacheSettings(cacheItemNameSuffix:
        $"{nameof(WhereParameters.WhereContainsTags)}|SomeTaxonomy|Collection"));

The retrieval API is designed to work with data from the Tag selector editing component, which is a collection of identifiers (IEnumerable<Guid>).

• To convert a collection of identifiers to a collection of tags, you can use the RetrieveTags method of the ITaxonomyRetriever interface.

  C#

  RetrieveTags

  Copy

  
    // Service obtained via dependency injection
    private readonly ITaxonomyRetriever taxonomyRetriever;
  
    // A collection of tag GUIDs
    IEnumerable<Guid> tagIdentifiers;
  
    // Retrieves a collection of Tag objects
    IEnumerable<Tag> tags = await taxonomyRetriever.RetrieveTags(tagIdentifiers, "en");
    

• To convert a collection of Tag objects to a collection of identifiers, you can use the Select LINQ method.

  C#

  Select LINQ method

  Copy

  
    // A collection of Tag objects
    IEnumerable<Tag> tags;
  
    // Retrieves a collection of tag identifiers
    IEnumerable<Guid> tagIdentifiers = tags.Select(tag => tag.Identifier);
    

// A collection of tags, e.g., obtained from a Tag selector
IEnumerable<Guid> tagIdentifiers;

var banners = await contentRetriever.RetrieveContent<Banner>(

    query => query.Where(where =>
        where.WhereContainsTags("SomeTaxonomy",
                    new List<Guid> { tagIdentifiers.ElementAt(0) })
             .And()
             .WhereContainsTags("SomeTaxonomy",
                    new List<Guid> { tagIdentifiers.ElementAt(1) })),
    new RetrievalCacheSettings(cacheItemNameSuffix: 
                                    $"{nameof(WhereParameters.Where)}|MultipleTags|tagIdentifiers"));

Retrieve content items from smart folders

Smart folders give content editors the power to select a specific set of content items. This is achieved by configuring filter conditions, such as “items published in the last 7 days”, “items with the Acme tag”, etc.

For smart folders with dynamic content delivery enabled, you can use IContentRetriever with the additionalQueryConfiguration parameter and the InSmartFolder parametrization method to retrieve the content items that match a folder’s filter conditions. You can then display or otherwise use the retrieved items in your application. This allows content editors to control which items are delivered directly in the Content hub UI, without needing to adjust the code.

The InSmartFolder method requires you to specify the smart folder by its ID, GUID or code name identifier. To get the identifier, we recommend using fields with the Smart folder selector UI form component. The smart folder selector is supported in the following scenarios:

• Fields with the Smart folder data type, added to the content types used for reusable content items or website channel pages, or to reusable field schemas.
• Properties of Page Builder components, such as widgets, decorated by theSmartFolderSelectorComponent attribute.

As smart folders can contain multiple content types, you can retrieve content either via the:

• RetrieveContentOfContentTypes method with a list of content types you want to retrieve from the smart folder
• RetrieveContentOfReusableSchemas method with a shared reusable schema implemented by the content types you want to retrieve from the smart folder

// A list of content types available in the smart folder
var contentTypes = new[] { ArticlePage.CONTENT_TYPE_NAME, BlogPage.CONTENT_TYPE_NAME };

var smartFolderGuid = model?.Properties?.SmartFolderSelectorField.Identifier ?? Guid.Empty;

var contentItems = await contentRetriever.RetrieveContentOfContentTypes<IContentItemFieldsSource>(
    contentTypes,
    RetrieveContentOfContentTypesParameters.Default,
    query => query.InSmartFolder(smartFolderGuid)
                   .OrderBy(new OrderByColumn("ContentItemCommonDataLastPublishedWhen", OrderDirection.Descending))
                   .TopN(5),
    new RetrievalCacheSettings(cacheItemNameSuffix:
        $"{nameof(RetrieveContentQueryParameters.InSmartFolder)}|{smartFolderGuid}|{nameof(RetrieveContentOfContentTypesQueryParameters.OrderBy)}|{nameof(OrderByColumn)}|{nameof(RetrieveContentQueryParameters.TopN)}|5"));

Setting the order and maximum number of retrieved items is not part of the options configured for the smart folder in the administration UI. If required, control these parameters using the OrderBy and TopN query parametrization.

The InSmartFolder parametrization causes the query to return an empty result if the specified smart folder:

• Doesn’t exist
• Doesn’t have dynamic content delivery enabled
• Has invalid filter conditions (for example if a tag saved in the Taxonomy filter option was later deleted)

Using multiple InSmartFolders calls in a single query is not supported and results in an exception.

var smartFolderGuid = model?.Properties?.SmartFolderSelectorField.Identifier ?? Guid.Empty;

var articleItems = await contentRetriever.RetrieveContent<ArticlePage>(
    RetrieveContentParameters.Default,
    query => query.InSmartFolder(smartFolderGuid),
    new RetrievalCacheSettings(
        cacheItemNameSuffix: $"{nameof(RetrieveContentQueryParameters.InSmartFolder)}|{smartFolderGuid}|{nameof(ContentTypesQueryParameters.OfContentType)}|ArticlePage"));

Smart folder content and language fallbacks

Language fallbacks are not used when retrieving content items from a smart folder in a specific language.

For example, if you have Spanish configured to fall back to English, and you retrieve content from a smart folder in Spanish, items are not included if their Spanish language variant doesn’t fulfill the folder’s filter conditions (even if their English variant does).

Cache data retrieved from smart folders

Caching the data of retrieved content items is recommended in most cases. However, smart folder conditions are set in the administration UI by content editors and are evaluated dynamically. Items move in and out of smart folders as their content and metadata changes. This makes it challenging to ensure that cached data does not become outdated.

The most practical approach is to set a reasonable short expiration time for cached data that is retrieved from a smart folder, depending on how often your project’s content editors adjust content items and smart folder filter criteria.

In scenarios where you are retrieving one specific content type, you can also set a cache dependency on all items of the given content type, which ensures that the cache is cleared whenever any items of the type are updated.

// IContentRetriever with custom cache settings
var cacheSettings = new RetrievalCacheSettings(
    cacheItemNameSuffix: $"SmartFolder|{smartFolderGuid}",
    cacheExpiration: TimeSpan.FromMinutes(5));

var contentItems = await contentRetriever.RetrieveContentOfContentTypes<IContentItemFieldsSource>(
    new[] { "Sample.Type" },
    new RetrieveContentOfContentTypesParameters
    {
        WorkspaceNames = new[] { "MainContent" }
    },
    query => query.InSmartFolder(smartFolderGuid)
                    .OrderBy(new OrderByColumn("ContentItemCommonDataLastPublishedWhen", OrderDirection.Descending))
                    .TopN(5),
    cacheSettings);

Content item security

Content items can be secured to allow access only for authenticated users. By default, the IContentRetriever doesn’t include secured content items in the query results. You can change this behavior by setting the IncludeSecuredItems property of the RetrieveContentParameters object to true.

// Services obtained via dependency injection
private readonly IContentRetriever contentRetriever;

// Information about whether to include secured items in the query execution passed from the caller
public async Task ContentItemRetrieval(bool includeSecuredItems)
{
    // Retrieves banners, including secured items if specified
    var banners = await contentRetriever.RetrieveContent<Banner>(
        new RetrieveContentParameters 
        { 
            IncludeSecuredItems = includeSecuredItems
        });
}

The secured state of a retrieved content item is indicated by its item.SystemFields.ContentItemIsSecured property. You can use this property to display information to visitors accordingly.

For example, you can pass the content item’s ContentItemIsSecured property to a model and display an appropriate message to visitors. 

@model CompanyName.Models.MyModel

// In this case, 'ContentItemIsSecured' is mapped to the 'IsSecured' property of the view model 
@if (model.IsSecured && !User.Identity.IsAuthenticated)
{
    <p>
        Sign in to view this content.
    </p>
}

Both pages and content items use the same property to determine their security configuration. When working with collections of linked content items (provided, e.g., via a selection UI managed by the combined content selector UI form component), you can determine which content items are marked as secured via simple projection.

// Contains a collection of sample 'Clinic' content items - retrieval code omitted for brevity
var clinic = await GetMedicalClinics();

var securedClinics = clinics.Select(x => x.SystemFields.ContentItemIsSecured);

Content item names

There are several name fields related to each content item that represent various names used throughout the system:

• Code name – a unique identifier of the content item, used primarily in code. Code names are stored in the ContentItemName property of each content item.
• Display name – the name displayed for the item in the administration interface. Display names are not available via the API, use a Title field instead.
• Title field – a custom field that we recommend you to add to your content types. The Title field represents the name which is used when displaying the content item in the presentation layer.

Date and time fields

DateTime fields and system properties of retrieved content items always have values in the time zone of the server where the application is running. If you wish to display values in a different time zone (e.g., in a website visitor’s local time), perform a time conversion using the standard .NET API.

Retrieve linked content items

To retrieve a list of content items linked to a page or another content item:

1. Retrieve the object representing the content item or page containing linked content items using IContentRetriever.
2. Retrieve linked content items by accessing content item fields of the retrieved object.

// Services obtained via dependency injection
private readonly IContentRetriever contentRetriever;

private async Task SampleContentQuery()
{    // Retrieves 3 banners with linked items (1 level deep)
    var banners = await contentRetriever.RetrieveContent<Banner>(
        new RetrieveContentParameters 
        { 
            LinkedItemsMaxLevel = 1
        },
        query => query.TopN(3),
        new RetrievalCacheSettings(cacheItemNameSuffix:
                                        $"{nameof(RetrieveContentQueryParameters.TopN)}|3"));

    // Accesses the content item data
    foreach (Banner item in banners)
    {
        // Accesses linked content item
        Image image = item.BannerBackgroundImage.FirstOrDefault();

        // Accesses content type fields of the linked item
        string description = image.ImageShortDescription;

        // Accesses system fields of the linked item
        VersionStatus status = image.SystemFields.ContentItemCommonDataVersionStatus;
    }
}

Retrieve assets

To retrieve information about an asset, like filename, file size, URL, or width and height (if available) from a content item that has an asset field:

1. Retrieve the object representing the content item or page containing linked content items using IContentRetriever.
2. Retrieve a ContentItemAsset object from the asset field and access its properties.
   • It is strongly recommended to use generated content type classes that allow you to work with content type fields using strongly-typed objects.

// Services obtained via dependency injection
private readonly IContentRetriever contentRetriever;

private async Task SampleContentQuery()
{
    // Retrieves 3 banners with linked items
    var banners = await contentRetriever.RetrieveContent<Banner>(
        new RetrieveContentParameters 
        { 
            LinkedItemsMaxLevel = 1
        },
        query => query.TopN(3),
        new RetrievalCacheSettings(cacheItemNameSuffix:
                                        $"{nameof(RetrieveContentQueryParameters.TopN)}|3"));

    // Accesses the content item data
    foreach (Banner item in banners)
    {
        // Accesses linked content item
        Image image = item.BannerBackgroundImage.FirstOrDefault();

        // Accesses the asset object in the ImageFile property of the Image content type
        ContentItemAsset asset = image.ImageFile;

        // Accesses the properties of the asset
        int? width = asset.Metadata.Width;
        int? height = asset.Metadata.Height;
        string extension = asset.Metadata.Extension;
        string url = asset.Url;
    }
}

Retrieve image variants

To retrieve a specific variant of an image asset:

1. Retrieve the ContentItemAsset object.
2. Access the properties of the image variant using its code name identifier.

// Retrieves a content item asset
// ...

// Accesses the asset object in the ImageFile property of the asset's content type
ContentItemAsset asset = myAsset.ImageFile;

// Accesses the properties of an image variant with the 'Hero' code name
if (asset.Metadata.Variants.ContainsKey("Hero")){
    int variantWidth = asset.Metadata.Variants["Hero"].Width;
    int variantHeight = asset.Metadata.Variants["Hero"].Height;
    string variantUrl = asset.VariantUrls["Hero"];
}

To display the retrieved image variant on a live site of a website channel application, you can also use the provided Tag Helpers.

Secured assets

Content item assets that are configured to require authentication return HTTP 403 (Forbidden) when requested by unauthenticated visitors. In such cases, consider displaying a placeholder teaser image instead. For example, a popular practice is to display a blurred teaser image overlaid with a lock icon.

Retrieve content items for preview

The IContentRetriever API automatically handles preview context, retrieving the appropriate content versions based on the current request context:

• For the live site, retrieves published versions according to security claims
• For preview and builders, retrieves the latest available version regardless of workflow state or security

You can use the IsForPreview parameter of the RetrievePagesParameters object to force either only preview or only live data.

var banners = await contentRetriever.RetrieveContent<Banner>(
    new RetrieveContentParameters
    {
        IsForPreview = true
    });