Common API Classes

• The Sitecore Application Programming Interface (API) is

very extensive. It has to be. We use it ourselves to define
the Sitecore browser-based interfaces and the rest of the
Sitecore system. In fact, the API consists of more than 90
namespaces, each of which contains a number of classes,
which in turn contain a number of methods and attributes.

• Luckily, the average Sitecore web site developer does not

need to know the entire API to produce world-class web
sites. Knowledge of a handful of classes is enough to get
started. Once a developer understands these classes, it’s
easy to locate and understand any additional required
classes and methods using Visual Studio’s Intellisense
and Sitecore’s API Reference materials.
Sitecore.Context Holds information about the current state.

Sitecore.Configuration.Factory Provides access to information defined in the installation’s

web.config file.

Sitecore.Data.Database Provides access to the Items, Aliases, Templates, and other information
available in a Sitecore Database.

Sitecore.Data.Items.Item A language specific single version of an Item, usually retrieved directly from a
Database.

Sitecore.Data.Fields.* A collection of classes that represent the various Sitecore data types and
provide convenience functions for translating information out of its XML storage format.

Sitecore.SecurityModel.Domain Represents a Sitecore Domain, which contains Users, Roles, and

related information.

Sitecore.SecurityModel.UserItem Represents a Sitecore User. Provides access to User properties.

Sitecore.Globalization.Language Represents both web site and client languages.

Sitecore.Sites.SiteContext Represents a Sitecore site. Provides access to Site properties.

 The Sitecore.Context
• Most developers begin using the Sitecore API when
writing Layout or Sub layout code-behind or web
controls. Regardless of what the developer needs to do,
understanding how to complete the task starts with
understanding the context in which custom code
executes. The Sitecore runtime process runs as a part
of the .NET framework running on a web server, usually
Microsoft’s Internet Information Server (IIS). When IIS
serves a Sitecore web site, it passes HTTP requests to
the Sitecore process, which sends the requests to the
Sitecore HTTP Request Pipeline.
The HTTP Request Pipeline is a predefined series of
method calls which build up information about the current
environment and the current request, followed by a call to
another pipeline which builds a response to the request,
which, for most pages on a normal web site, is the Render
Layout Pipeline. Sitecore Pipelines are fully customizable.

The HTTP Request Pipeline includes many steps, and

many of these are devoted to interrogating the HTTP
request to gather information about the current request and
the web.config file to garnish information about the current
environment. This information is passed between steps
and ultimately to custom code-behind code or web controls
in the Sitecore.Context object.

Developers therefore often start custom code with calls to

the Sitecore.Context object to obtain a pointer to the
requested Sitecore Item, the current User, the Database
associated with the current web site, information about
 Sitecore.Data.Item requested_item = Sitecore.Context.Item;

string = Sitecore.Context.GetUserName( );

Sitecore.Context members

Database Gets the current database as a

Sitecore.Data.Database object

Device Gets the current security domain as a

Sitecore.SecurityModel.Domain object

Item Gets the requested Item as a

Sitecore.Data.Items.Item object. Can also
be used to set the current Item in the
context from a custom Pipeline step.
Language Gets the current language as a
Sitecore.Globalization.Language
object.
Site Gets the current Site as a
Sitecore.Sites.SiteContext object.
User Gets the current User as a
Sitecore.SecurityModel.UserItem
object.
GetDeviceName Gets the name of the current device.
GetDomainName Gets the name of the current
security domain.
GetUserName Gets the name of the current user.
 Sitecore.Configuration.Factory
• Although the Sitecore.Context object is very
useful, it is limited by the fact that it is focused
on the current request and the information
associated with it. In some cases, developers
need access to a different Database, Security
Domain, or even a different Sitecore Site. In
these cases, the Sitecore.Configuration.Factory
class comes in handy. This class encapsulates
the general information available in the
web.config file and provides methods that
provide access to this information.
GetDatabaseNames Returns an array of strings which
hold the names of the databases
defined for this installation.
GetDatabase Returns the named database as a
Sitecore.Data.Database object.
GetDomainNames Returns an array of strings which
hold the names of the domains
defined for this installation.
GetDomain Returns the named domain as a
Sitecore.SecurityModel.Domain
object.
GetSiteNames Returns an array of strings which
hold the names of the sites defined
for this installation.
GetSiteInfo Returns information about the named
site as a Sitecore.Web.SiteInfo object.
GetSite Returns the context associated with the
named site as a
Sitecore.Sites.SiteContext object.
 Item Related Classes
• Sitecore provides many classes which encapsulate both
the content and infrastructure associated with a Site.
Nearly all information stored by Sitecore is represented as
an Item, which can be seen as similar to a database
record. Some Items perform a specific function, such as
Templates (which describe Items) or UserItems (which
describe Users), others simply represent content managed
by Sitecore and displayed on the published web site.

• Regardless of their specific function or where they are

stored, Sitecore refers to the storage mechanism for Items
as a Database. The actual physical implementation of the
Database may vary and is described in more detail in the
Integrating External Data Sources article. Regardless of
the actual implementation of the storage, developers
retrieve Items, represented by the
Sitecore.Data.Items.Item class, via the
Sitecore.Data.Database class.
As mentioned earlier, Items are similar to database records.
Items contain Fields, which are similar to database table
columns. All Fields are stored as XML text, but the various
Sitecore data types use various formats and tags to
structure the information appropriately (for more information
related to the storage of each type, please refer to the Field
Reference article). Although it is always possible to extract
the raw XML text directly from an Item, Sitecore provides a
number of Field specific classes which parse the XML text
to provide details about the Field contents.
 Sitecore.Data.Database
A Database consists mainly of a collection of Items, but
also has associated Aliases, Indexes, Languages,
Masters, Properties, Templates, and more. This section
describes the most commonly used members
A "database" in Sitecore speak is a named data store for
Sitecore items.
Databases are defined in web.config using the
<database> element. Only databases defined below the
main <databases> element are considered valid.
The bare minimum for a database definition is:
<database id="myDB" singleInstance="true"
type="Sitecore.Data.Database, Sitecore.Kernel">
<param desc="name">$(id)</param>
</database>
This will define a database called 'myDB' that can be
accessed from within the Sitecore API in the following way:

Database database = Factory.GetDatabase("myDB");

MainUtil.Out("Got the database: " + database.Name);

The code will output the message:

Got the database: myDB

Note that all threads in the process will share a single

instance of the database object due to the attribute
'singleInstance' on the <database> element.
 Provides access to the Items in the Database. Items may be
Items accessed:
By Path:
Sitecore.Data.Items.Item myItem =
myDB.Items[“/sitecore/content/home/myitem”];

By GUID:

Sitecore.Data.ID myItemID = Sitecore.Data.ID.Parse(

"{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}");

myItem = Sitecore.Context.Database.Items[myItemID];

By GUID Path:

string myItemURI =
"/{11111111-1111-1111-1111-111111111111}"
+ "/{8374EDAF-2947-20C7-148B-20484EFFA87B}"
+ "/{38A98B93-39AB-983D-284A-39F87C938E84}"
+ "/{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}";
Languages An array of
Sitecore.Globalization.Language, which
represent the Languages supported by
Items in this Database.
Name The name of this database as a string.

Masters A collection of Master Items represented

as a Sitecore.Data.MasterRecords
object. Masters are used when creating
content Items in the Sitecore clients.
Templates A collection of Template Items
represented as a
Sitecore.Data.TemplateRecords object.
Templates define the Fields associated
with a specific Item.