XperienceCommunity.QueryExtensions 1.0.0-beta.1

Xperience Query Extensions

This package provides a set of extension methods for Kentico Xperience 13.0 DocumentQuery, MultiDocumentQuery, ObjectQuery, and IPageRetriever data access APIs.

Dependencies

This package is compatible with ASP.NET Core 3.1 → ASP.NET Core 5 applications or libraries integrated with Kentico Xperience 13.0.

How to Use?

1. Install the NuGet package in your ASP.NET Core project (or class library)

   dotnet add package XperienceCommunity.QueryExtensions
   

2. The extension methods are all in the Kentico.Content.Web.Mvc, CMS.DocumentEngine and CMS.DataEngine namespaces, so assuming you have the package installed you should see them appear in Intellisense.

Extension Method Examples

DocumentQuery

public void QueryDocument(Guid nodeGuid)
{
    var query = DocumentHelper.GetDocuments()
        .WhereNodeGUIDEquals(nodeGuid);
}

var query = DocumentHelper.GetDocuments()
    .OrderByNodeOrder();

var query = DocumentHelper.GetDocuments()
    .OrderByDescending(nameof(TreeNode.NodeID))
    .TopN(1)
    .DebugQuery();

/*
--- BEGIN [path\to\your\app\Program.cs] QUERY ---


DECLARE @DocumentCulture nvarchar(max) = N'en-US';

SELECT TOP 1 *
FROM View_CMS_Tree_Joined AS V WITH (NOLOCK, NOEXPAND) LEFT OUTER JOIN COM_SKU AS S WITH (NOLOCK) ON [V].[NodeSKUID] = [S].[SKUID]
WHERE [DocumentCulture] = @DocumentCulture
ORDER BY NodeID DESC


--- END [path\to\your\app\Program.cs] QUERY ---
*/

var query = DocumentHelper.GetDocuments()
    .OrderByDescending(nameof(TreeNode.NodeID))
    .TopN(1)
    .DebugQuery("Newest Document");

/*
--- BEGIN [Newest Document] QUERY ---


DECLARE @DocumentCulture nvarchar(max) = N'en-US';

SELECT TOP 1 *
FROM View_CMS_Tree_Joined AS V WITH (NOLOCK, NOEXPAND) LEFT OUTER JOIN COM_SKU AS S WITH (NOLOCK) ON [V].[NodeSKUID] = [S].[SKUID]
WHERE [DocumentCulture] = @DocumentCulture
ORDER BY NodeID DESC


--- END [Newest Document] QUERY ---
*/

public void QueryDatabase(ILogger logger)
{
    var query = DocumentHelper.GetDocuments()
        .OrderByDescending(nameof(TreeNode.NodeID))
        .TopN(1)
        .LogQuery(logger, "Logged Query");
}

public async Task QueryDatabase(CancellationToken token)
{
    List<TreeNode> pages = await DocumentHelper.GetDocuments()
        .TopN(5)
        .ToListAsync(token);
}

public async Task QueryDatabase(CancellationToken token)
{
    TreeNode? newestPage = await DocumentHelper.GetDocuments()
        .OrderByDescending(nameof(TreeNode.NodeID))
        .TopN(1)
        .FirstOrDefaultAsync(token);

    if (newestPage is null)
    {
        return;
    }

    // ...
}

ObjectQuery

var query = UserInfo.Provider.Get()
    .OrderByDescending(nameof(UserInfo.UserLastModified))
    .TopN(1)
    .DebugQuery();

/*
--- BEGIN [path\to\your\app\Program.cs] QUERY ---


SELECT TOP 1 *
FROM CMS_User
ORDER BY UserLastModified DESC


--- END [path\to\your\app\Program.cs] QUERY ---
*/

var query = UserInfo.Provider.Get()
    .OrderByDescending(nameof(UserInfo.UserLastModified))
    .TopN(1)
    .DebugQuery("User");

/*
--- QUERY [User] START ---


SELECT TOP 1 *
FROM CMS_User
ORDER BY UserLastModified DESC


--- QUERY [User] END ---
*/

public void QueryDatabase(ILogger logger)
{
    var query = UserInfo.Provider.Get()
        .OrderByDescending(nameof(UserInfo.UserLastModified))
        .TopN(1)
        .LogQuery(logger, "Logged User Query");
}

public async Task QueryDatabase(CancellationToken token)
{
    List<UserInfo> recentlyUpdatedUsers = await UserInfo.Provider.Get()
        .OrderByDesc(nameof(UserInfo.UserLastModified))
        .TopN(10)
        .ToListAsync(token);
}

public async Task QueryDatabase(CancellationToken token)
{
    UserInfo? user = await UserInfo.Provider.Get()
        .OrderByDesc(nameof(UserInfo.UserLastModified))
        .TopN(1)
        .FirstOrDefaultAsync(token);

    if (user is null)
    {
        return;
    }

    // ...
}

PageRetriever

int pageIndex = 3;
int pageSize = 10;

var result = await retriever.RetrievePagedAsync<TreeNode>(
    pageIndex,
    pageSize,
    q => q.OrderByNodeOrder(),
    cancellationToken: token);

int total = result.TotalRecords;
List<TreeNode> pages = result.Items;

TreeNode? page = await retriever.FirstOrDefaultAsync<TreeNode>(
    q => q.TopN(1),
    cancellationToken: token);

IEnumerable<Guid> nodeGuids = await retriever.SelectAsync<LandingPage>(
    landingPage => landingPage.NodeGUID,
    cancellationToken: token);

References

.NET

• Nullable reference types (C# reference)

Kentico Xperience

• Kentico Xperience 13 Beta 3 - New Data Access APIs
• Pages API Examples
• Retrieving pages in custom scenarios
• Improvements under the hood – Document and ObjectQuery enumeration without DataSets