Introducing the Marker Kentico Business Library (MKB)

Posted by: admin | Technical | 05.02.2010

Marker Kentico Business Library

Marker Kentico Busi­ness Library

Marker have created a complete busi­ness layer facade for work­ing across the kentico docu­ment apis. Why would we do such a crazy thing? Well, we found that on larger and more complex web appli­ca­tions that we had a certain amount of trou­ble with the stan­dard approach.

When you use custom docu­ment types in Kentico, your rows are either returned as a CMS.TreeEngine.TreeNode or a System.Data.DataRow depend­ing on what part of the api you are using. So the first main driver for our busi­ness layer was to be able to have a busi­ness entity class that mapped directly to a custom docu­ment type in Kentico. This means we know exactly  how a partic­u­lar docu­ment type is repre­sented in our appli­ca­tion and know exactly what prop­er­ties it has.

Also, you have differ­ent apis depend­ing on whether or not you are using workflow/versioning or not.  All of the recom­mended devel­op­ment arti­cles within the Kentico docu­men­ta­tion gener­ally assume you are work­ing with published docu­ments on your site which might not always be the case.

It should be noted that this approach is really for aspx template advo­cates look­ing to get the maxi­mum control and perfor­mance from Kentico. This approach is likely overkill for smaller sites and is not applic­a­ble for the portal engine approach.

This arti­cle will focus on the basics of creat­ing an entity class mapping to your custom docu­ment type and using the generic repos­i­tory to perform some stan­dard oper­a­tions. There’s a lot of func­tion­al­ity in the MKB library beyond what is shown here and we doubt there is anything you can do with the kentico docu­ment api that you can’t do more easily and cleanly with the MKB library, if there is, let us know!

This library works against v5 with the 5.0.5 hot fix applied only. Just drop it in your bin folder and off you go..

Let’s create our first docu­ment entity class…

You can see a sample entity below which maps to a custom docu­ment type in our appli­ca­tion. You will need to create this for each custom docu­ment type in your appli­ca­tion. Note that we are currently work­ing on code gener­a­tion which will auto­mat­i­cally gener­ate these classes for you against the Kentico data­base. We think this would be a great feature to have within Kentico itself at some point.

Make sure you entity class inher­its from the Docu­mentEn­tity class (Marker.Kentico.Business.Entities.DocumentEntity). This class includes all the core fields for a kentico docu­ment instance.

Next, you should apply a special table attribute. The table attribute allows you to set the class name (maps to kentico docu­ment type’s class name) and default alias path (the default alias path which forms the basis of all data access for the entity by default). In addi­tion (not shown below) there is the possi­bil­ity of setting the default site code (default site code for all data access for the entity by default if required with multi site solu­tions and also a default wild­card alias key (for auto­mat­i­cally load­ing the entity based on a wild­card alias. If you don’t set this it’s the name of the entity lower­cased, in this case ‘supplier’).

Next, apply special field attrib­utes for each prop­erty you want to map to a kentico docu­ment type. Note that your prop­erty names can be differ­ent from the under­ly­ing field if you want, and you can specific the nature of the bind­ing (read, insert, update, all) as required.

This is all that is required to start using MKB, create a simply entity and move on to the next step, where the fun begins!

using Marker.Kentico.Business.Attributes;
using Marker.Kentico.Business.Enumeration;
using Marker.Kentico.Business.Entitie;
using Marker.Kentico.Business.Attributes;
using Marker.Kentico.Business.Enumerations;
using Marker.Kentico.Business.Entities;

    public class Supplier : DocumentEntity
    {

        private string _companyName = string.Empty;

        public Supplier()
        { }

        [Field("CustomerCode", FieldBindingType.All)]
        public string CustomerCode { get; set; }

        [Field("CompanyName", FieldBindingType.All)]
        public string CompanyName {
            get { return _companyName; }
            set
            {
                _companyName = value;
                this.DocumentName = value;
            }
        }

        [Field("ImageThumb", FieldBindingType.All)]
        public Guid ImageThumb { get; set; }

        [Field("Url", FieldBindingType.All)]
        public string Url { get; set; }

        [Field("Address", FieldBindingType.All)]
        public string Address { get; set; }

        [Field("Phone", FieldBindingType.All)]
        public string Phone { get; set; }

    }

Let’s work with our enti­ties using the docu­ment repository…

All you need to do is to put a using state­ment to the enti­ties and repos­i­tory namespaces

using Marker.Kentico.Business.Repository;
using Marker.Kentico.Business.Entities;

Then you can retrieve a strongly typed repos­i­tory to work with your supplier enti­ties as follows. This retrieves a single­ton instance of the repos­i­tory class, it could also be created using depen­dency injec­tion if preferred, but this is the simplest api to be offered.

var repository = RepositoryFactory<DocumentRepository<Supplier>>.Instance;

Once you have your repos­i­tory you can then load enti­ties or get the current entity (if it is a supplier other­wise it will be null)

Supplier supplier = repository.Load(string aliasPath);
Supplier supplier = repository.GetCurrent();

Here are some other thigns you can do…

Saving and Deleting

Just update your entity’s prop­er­ties and call the save method

supplier.Url = "http://newurl.com";
repository.Save(supplier);

Dele­tion is just as easy: 

repository.Delete(supplier.DocumentID);

Custom Query Support with Paging!

You can see below that our repsi­tory enables query­ing with paging support (return­ing the total results)

var searchCriteria = new QueryFindCriteria();
searchCriteria.QueryName = "FindSuppliers"; // set the query name here
searchCriteria.SelectOnlyPublished = false; // let's include unpublished nodes
searchCriteria.Take = 10; // take 10 rows
searchCriteria.Skip = 10; // start at row 11
int totalCount = 0;
List<Supplier> suppliers = repository.Find(searchCriteria, out totalCount);

To support this you must be running SQL 2005 or above and simply struc­ture your query as follows.

WITH AllResults AS
(

-- core paged query should go in here

select SupplierView.*, Row_Number() over (order by ##ORDERBY## as RowIndex
FROM View_SMS_Supplier_Joined as SupplierView
##WHERE##
)

SELECT (SELECT COUNT(NodeID) FROM AllResults ) As TotalResults, *
FROM AllResults
WHERE RowIndex > @skip AND RowIndex <= (@skip + @take)

Crite­ria objects (not overloads)

You will likely have noticed that Kentico has dozens of over­loads for it’s core meth­ods. MKB gets round this by having a limited number of over­loads with crite­ria objects that contain prop­er­ties with sensi­ble defaults for all core operations.

For exam­ple, the QueryFind­Cri­te­ria mentioned above has the follow­ing properties.

  • Site­Name (defaults to current site)
  • Culture­Code
  • Where
  • TopN
  • Selec­tOn­ly­Pub­lished
  • OrderBy
  • CheckUser­Per­mis­sions
  • Query­Name
  • Para­me­ters

And there is a simpler TreeFind­Cri­te­ria accepted as an over­load to the Find method on any repos­i­tory with these properties:

  • Site­Name (defaults to current site)
  • Culture­Code
  • Where
  • TopN
  • Selec­tOn­ly­Pub­lished
  • OrderBy
  • CheckUser­Per­mis­sions
  • Alias­Path
  • CombineWith­De­fault­Cul­ture
  • MaxRel­a­tiveLevel
  • Select­Lat­estVer­sion — allows you to work with latest version of docu­ment under work­flow, no need to change your api!

We hope you can see how much simpler this is as you just need to set the prop­er­ties you expl­citly need for any query rather than being forced to use a partic­u­lar overload.

Conclu­sion

We are shar­ing this library because we believe that it will be of value for kentico devel­op­ers and part­ners to assess and make use of. We hope that it will also be useful for Kentico them­selves who might consider the devel­op­ment of such an api to make it easier to work with Kentico.

This code base is provided as is and we recom­mend you use it for test­ing purposes at this stage (although we feel the api cover­age is pretty good). We’ll support and answer ques­tions as best we can. There’s lots not covered here that is offered with the library that i’ll cover in future posts if the inter­est is there!

Get the code!

We are provid­ing a debug compiled version of our busi­ness assem­bly to solicit feed­back on the apis offered. If there is suffi­cient inter­est we will release the code base on codeplex.

Down­load the latest version here: Marker.Kentico.Business.v3

11 Responses to “Introducing the Marker Kentico Business Library (MKB)”

  1. Rick February 9th, 2010 @ 9:31 am

    Very inter­est­ing… I’ve been mulling on some­thing very simi­lar. I espe­cially like the server-side paging (ROW_NUMBER) stuff. Have you consid­ered imple­ment­ing SQL cache depen­den­cies as well?

  2. Michiel February 9th, 2010 @ 10:33 am

    Great work, thanks so much for shar­ing it!

    I have been work­ing on some­thing like this as well. In fact, I started from the oppo­site side, I now have auto-generated strongly typed classes based on custom docu­ment types (using a build provider). I haven’t had the time to develop a clean repos­i­tory and query­ing API. I mate­ri­al­ize these objects only for the current node.

    I really feel that Kentico under­de­liv­ers on their API, and I see no signs that they will deliver a clean API in the _near_ future (5.x time­line). It seems that ASPX devel­op­ers for Kentico are not the major­ity (but much more vocal on the user­voice site), thus it’s not the most impor­tant feature for them to develop.

    Just out of curios­ity, how are you unit test­ing this library? Do you use an exam­ple site, and roll back after running the tests? And how long did it take you to develop this library?

    Thanks for post­ing this!

  3. Keith Patton February 9th, 2010 @ 10:47 am

    Hi Michiel,
    I think that if Kentico are truly posi­tion­ing Kentico CMS as an enter­prise offer­ing then they will have to provide a much better set of apis moving forwards, i don’t think the Portal Engine approach is for every­one. You only have to look at Share­Point to see that there is a lot of devel­op­ment work required behind the scenes to make things easier for users, and i don’t think the portal engine approach is enough.

    Our test­ing has so far been rather limited to using aspx pages against each method of the repos­i­to­ries. It is defi­nitely some­thing we would like some help with if we decided to open source.

    Would you be inter­ested in look­ing at the code? Perhaps if you like the repos­i­tory apprach etc. you could maybe inte­grate your build provider and we could get code gener­a­tion added in?

    Thanks for the feedback

  4. Keith Patton February 9th, 2010 @ 10:48 am

    Hi Rick,
    Thanks for the feed­back. haven’t got as far as cache depen­den­cies on the sql side as yet. I’d need to do a bit more research on that to ensure it wouldn’t conflict with anythign kentico is doing on the caching side but inter­est­ing idea.

  5. Justin February 10th, 2010 @ 4:47 am

    Down­load­ing it now and look­ing forward to check­ing it out. Our team is also in the ASPX camp. As our projects increase in complex­ity, I am on the look­out for ways to work smarter.

  6. Keith February 10th, 2010 @ 9:10 am

    great, let me know how you get on..

  7. The Guru February 11th, 2010 @ 11:36 pm

    This is a really great idea. When we use custom docu­ment types (which is frequently!) we create a Custo­mOb­ject­In­fo­Provider and a Custo­mOb­ject­Info class that allows you to create a new CustomObjectInfo(DataRow dr) by simply pass­ing a DataRow to it, the same way Kentico handles it’s own docu­ment types.
    What would be great is an appli­ca­tion that could create these classes and the docu­ment type in Kentico CMS, we’ve thought about it a couple of times while going through the pain of writ­ing providers.
    Great job.

  8. Michiel February 21st, 2010 @ 5:51 am

    I have done a few tests with the library and so far I’m impressed. But auto­matic gener­a­tion of the docu­ment entity classes (using a Build Provider for instance) is a must.

    Another improve­ment is to auto­mat­i­cally make prop­er­ties that repre­sent docu­ments or attach­ments into enti­ties as well. Kentico just stores a guid for those, so in our Build Provider we gener­ate classes with prop­er­ties of type Attach­ment or Docu­ment. So given a docu­ment type with a field that stores attach­ments, we can write code like this:

    for(Attachment a in Document.Model.Downloads) {
    // a.Url
    // a.Filename
    // a.Size
    }

    Where Attach­ment is a custom class that encap­su­lates an attach­ment in Kentico, Document.Model is a prop­erty on our custom TemplatePage class (derives from System.Web.UI.Page) and its Down­loads prop­erty would be auto­mat­i­cally gener­ated to be of type List based on the field defi­n­i­tion of the docu­ment type in Kentico. As you can see we sepa­rate Docu­ment (base prop­er­ties that all docu­ments have) and the Model (extra fields defined by the docu­ment type). I saw it as a 1-to-1 rela­tion­ship between those two, not neces­sar­ily as a single type.

    But what we have is read-only, just in order to ease template devel­op­ment. It’s also limited to stronly typed access to the current docu­ment for a template, with no repos­i­tory to find other objects.

    Regard­ing open sourc­ing this library. I don’t think there is such a strong commu­nity of Kentico devel­op­ers. But if you do release it on Code­plex or some­thing like that, I would be will­ing to devote some of my time to a Build Provider (but no guar­an­tees, it would depend of time being available).

    Has Kentico shown any inter­est in adopt­ing the library?

    Thanks again for shar­ing, great job!

  9. Keith February 24th, 2010 @ 11:17 am

    I have done a few tests with the library and so far I’m impressed. But auto­matic gener­a­tion of the docu­ment entity classes (using a Build Provider for instance) is a must.

    Keith > Well, yes. We haven’t found it too much of a prob­lem hand craftign the enti­ties ourselves. I agree it will be a nice solu­tion and we are part way there so it will come in a future release.

    Another improve­ment is to auto­mat­i­cally make prop­er­ties that repre­sent docu­ments or attach­ments into enti­ties as well. Kentico just stores a guid for those, so in our Build Provider we gener­ate classes with prop­er­ties of type Attach­ment or Document.

    KP > We opted to keep things simple with the Guid. You can load an Attach­ment, option­ally includ­ing the binary via the Attach­men­tRepos­i­tory. This is consis­tent with us not attempt­ing to have object prop­er­ties at all as that leads into more complex­ity than we are able to handle at this time. For exam­ple Kentico doesn’t really support the notion of foreign keys or many to many doc types explic­itly. We tend to just store the ids and then if we really want to, we create extra meth­ods on the specific entity’s repos­i­tory to return the objects or collec­tions that we need. Obvi­ously some­thing like Linq for SQL/Entities would do this auto­mat­i­cally, but we haven’t found the need as yet.

    Regard­ing open sourc­ing this library. I don’t think there is such a strong commu­nity of Kentico devel­op­ers. But if you do release it on Code­plex or some­thing like that, I would be will­ing to devote some of my time to a Build Provider (but no guar­an­tees, it would depend of time being available).

    KP > We’ll prob­a­bly release it with the next major version which will have code gener­a­tion capabilities.

    Has Kentico shown any inter­est in adopt­ing the library?

    KP > Nope. I orig­i­nally shared it with them and they said that most kentico users/developers would not find the need for some­thign so advanced. I think Martin the CTO liked some of the approaches and i genuinely hope it informs how they tackle things in 5.5 and beyond

  10. Michiel March 5th, 2010 @ 9:40 am

    Hey, thanks for your answers! I’m look­ing forward to a new release with a build provider.

  11. Bruce May 20th, 2010 @ 3:45 am

    I have done a few tests with the library and so far I’m impressed. But auto­matic gener­a­tion of the docu­ment entity classes (using a Build Provider for instance) is a must.

    Keith > Well, yes. We haven’t found it too much of a prob­lem hand craftign the enti­ties ourselves. I agree it will be a nice solu­tion and we are part way there so it will come in a future release.

    Another improve­ment is to auto­mat­i­cally make prop­er­ties that repre­sent docu­ments or attach­ments into enti­ties as well. Kentico just stores a guid for those, so in our Build Provider we gener­ate classes with prop­er­ties of type Attach­ment or Document.

    KP > We opted to keep things simple with the Guid. You can load an Attach­ment, option­ally includ­ing the binary via the Attach­men­tRepos­i­tory. This is consis­tent with us not attempt­ing to have object prop­er­ties at all as that leads into more complex­ity than we are able to handle at this time. For exam­ple Kentico doesn’t really support the notion of foreign keys or many to many doc types explic­itly. We tend to just store the ids and then if we really want to, we create extra meth­ods on the specific entity’s repos­i­tory to return the objects or collec­tions that we need. Obvi­ously some­thing like Linq for SQL/Entities would do this auto­mat­i­cally, but we haven’t found the need as yet.

    Regard­ing open sourc­ing this library. I don’t think there is such a strong commu­nity of Kentico devel­op­ers. But if you do release it on Code­plex or some­thing like that, I would be will­ing to devote some of my time to a Build Provider (but no guar­an­tees, it would depend of time being available).

    KP > We’ll prob­a­bly release it with the next major version which will have code gener­a­tion capabilities.

    Has Kentico shown any inter­est in adopt­ing the library?

    KP > Nope. I orig­i­nally shared it with them and they said that most kentico users/developers would not find the need for some­thign so advanced. I think Martin the CTO liked some of the approaches and i genuinely hope it informs how they tackle things in 5.5 and beyond

Leave a Reply

About Marker

Marker is a full service digi­tal agency, which means we help you with your strat­egy (we’ve been doing this stuff for nearly a decade), execu­tion and ongo­ing campaign manage­ment.

We’ve got devel­op­ers, design­ers and online marketers, not to mention our project manage­ment and strat­egy capability.

Contact us for a chat.

How can we help?