Home » Customization » Put Sitecore to Work for You: Build Custom Task Agents

Put Sitecore to Work for You: Build Custom Task Agents

Sitecore Technology MVP 2016
Sitecore MVP 2015
Sitecore MVP 2014

Enter your email address to follow this blog and receive notifications of new posts by email.

How many times have you seen some manual process and thought to yourself how much easier your life would be easier if that process were automated?

Custom Sitecore task agents could be of assistance on achieving some automation in Sitecore.

Last night, I built a custom task agent that deletes “expired” items from the recycle bin in all three Sitecore databases — items that have been sitting in the recycle bin after a specified number of days.

I came up with this idea after remembering an instance I had seen in the past where there were so many items in the recycle bin, finding an item to restore would be more difficult than finding a needle in a haystack.

Using .NET reflector, I looked at how Sitecore.Tasks.UrlAgent in Sitecore.Kernel.dll was coded to see if I had to do anything special when building my agent — an example would be ascertaining whether I needed to inherit from a custom base class — and also looked at code in Sitecore.Shell.Applications.Archives.RecycleBin.RecycleBinPage in Sitecore.Client.dll coupled with Sitecore.Shell.Framework.Commands.Archives.Delete in Sitecore.Kernel.dll to figure out how to permanently delete items in the recycle bin.

After doing my research in those two assemblies, I came up with this custom task agent:

using System;
using System.Collections.Generic;
using System.Linq;

using Sitecore.Configuration;
using Sitecore.Data;
using Sitecore.Data.Archiving;
using Sitecore.Diagnostics;

namespace Sitecore.Sandbox.Tasks
    public class RecycleBinCleanupAgent
        private const string ArchiveName = "recyclebin";
        private static readonly char[] Delimiters = new char[] { ',', '|' };

        public IEnumerable<string> DatabaseNames { get; set; }

        private IEnumerable<Database> _Databases;
        private IEnumerable<Database> Databases
                if (_Databases == null)
                    _Databases = GetDatabases();

                return _Databases;

        public int NumberOfDaysUntilExpiration { get; set; }

        public bool Enabled { get; set; }

        public bool LogActivity { get; set; }

        public RecycleBinCleanupAgent(string databases)

        private void SetDatabases(string databases)
            Assert.ArgumentNotNullOrEmpty(databases, "databases");
            DatabaseNames = databases.Split(Delimiters, StringSplitOptions.RemoveEmptyEntries).Select(database => database.Trim()).ToList();

        public void Run()
            if (Enabled)
        private void RemoveEntriesInAllDatabases()
            DateTime expired = GetExpiredDateTime();

            if (expired == DateTime.MinValue)

            foreach (Database database in Databases)
                RemoveEntries(database, expired);

        private DateTime GetExpiredDateTime()
            if (NumberOfDaysUntilExpiration > 0)
                return DateTime.Now.AddDays(-1 * NumberOfDaysUntilExpiration).ToUniversalTime();

            return DateTime.MinValue;

        private void RemoveEntries(Database database, DateTime expired)
            int deletedEntriesCount = RemoveEntries(GetArchive(database), expired);
            LogInfo(deletedEntriesCount, database.Name);

        private static int RemoveEntries(Archive archive, DateTime expired)
            IEnumerable<ArchiveEntry> archiveEntries = GetAllEntries(archive);
            int deletedEntriesCount = 0;

            foreach (ArchiveEntry archiveEntry in archiveEntries)
                if (ShouldDeleteEntry(archiveEntry, expired))

            return deletedEntriesCount;

        private static IEnumerable<ArchiveEntry> GetAllEntries(Archive archive)
            Assert.ArgumentNotNull(archive, "archive");
            return archive.GetEntries(0, archive.GetEntryCount()); ;

        private static bool ShouldDeleteEntry(ArchiveEntry archiveEntry, DateTime expired)
            Assert.ArgumentNotNull(archiveEntry, "archiveEntry");
            Assert.ArgumentCondition(expired > DateTime.MinValue, "expired", "expired must be set!");
            return archiveEntry.ArchiveDate <= expired;

        private static ArchiveQuery CreateNewArchiveQuery(ArchiveEntry archiveEntry)
            Assert.ArgumentNotNull(archiveEntry, "archiveEntry");
            return CreateNewArchiveQuery(archiveEntry.ArchivalId);

        private static ArchiveQuery CreateNewArchiveQuery(Guid archivalId)
            Assert.ArgumentCondition(archivalId != Guid.Empty, "archivalId", "archivalId must be set!");
            return new ArchiveQuery { ArchivalId = archivalId };

        private void LogInfo(int deletedEntriesCount, string databaseName)
            bool canLogInfo = LogActivity
                              && deletedEntriesCount > 0 
                              && !string.IsNullOrEmpty(databaseName);

            if (canLogInfo)
                Log.Info(CreateNewLogEntry(deletedEntriesCount, databaseName, ArchiveName), this);

        private static string CreateNewLogEntry(int expiredEntryCount, string databaseName, string archiveName)
            return string.Format("{0} expired archive entries permanently deleted (database: {1}, archive: {2})", expiredEntryCount, databaseName, archiveName);

        private IEnumerable<Database> GetDatabases()
            if (DatabaseNames != null)
                return DatabaseNames.Select(database => Factory.GetDatabase(database)).ToList();

            return new List<Database>();

        private static Archive GetArchive(Database database)
            Assert.ArgumentNotNull(database, "database");
            return ArchiveManager.GetArchive(ArchiveName, database);

Basically, it loops over all recycle bin archived entries in all specified databases after an allotted time interval — the time interval and target databases are set in a patch config file you will see below — and removes an entry when its archival date is older than the minimum expiration date — a date I derive from the NumberOfDaysUntilExpiration setting:

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
      <agent type="Sitecore.Sandbox.Tasks.RecycleBinCleanupAgent, Sitecore.Sandbox" method="Run" interval="01:00:00">
        <param desc="databases">core, master, web</param>

I had 89 items in my master database’s recycle bin before my task agent ran:


I walked away for a bit to watch some television, eat dinner, and surf Twitter for a bit, and phone my brother. I then returned to see the following in my Sitecore log:


I went into the recycle bin in my master database, and saw there were 5 items left after my task agent executed:


As you can see, my custom task agent deleted expired recycle bin items as designed. 🙂



  1. […] the spirit of my post on putting Sitecore to work for you, I built the following Sitecore agent (check out John […]

  2. wensveen says:

    Works like a charm! I also like the nice and clean output to the log.
    Thanks a lot.

    • wensveen says:

      I forgot to mention: The ArchiveQuery class is deprecated, so I changed that part (line 98) to “archive.RemoveEntries(new ID(archiveEntry.ArchivalId));”

  3. Arjunan says:

    Hi Sir, your blog is very nice and sitecore developers ca learn a lot from this blog.Thanks for posting nice articles and sharing your experience. Thanks a lot 🙂

    • Thanks for that!

      Btw, there is no need to call me sir — I’m just an ordinary bloke who likes to share Sitecore knowledge.



  4. Frederik says:

    Thanks for sharing, this is exactly what I needed. I also encountered the ‘obsolete’ warning on ArchiveQuery, but someone already commented on that.


Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: