The easiest approach is to build the package visually in the package designer, save it and then simply use the console to read it and generate the installation zip like:

get-package "powershell console.xml" `
  | Export-Package -FileName "PowerShell Console.zip" -Zip

That’s fine in most cases but if you have some more complex scenarios or want to generate some custom packages – you might want to generate packages directly in PowerShell.

To Create a Package you simply use:

$package = new-package "Test Package";

Now that you have that package you might want to add some files and items to it.

Let’s add for example our item templates by querying the master database and creating a dynamic item source:

$TemplatesSource = get-childitem "master:/templates/Cognifide" `
  | New-ItemSource "Cognifide Templates";

And subsequently add it to our new package:

$package.Sources.Add($TemplatesSource);

While that by itself is fairly useful, the really cool part is that you have a full flexibility of PowerShell at your disposal when you create a source with static items. Let’s say you want to add all items of template “Article Template” that reside anywhere under your “home” node … now that would require quite a bit of clicking in the Package Designer, but is trivial with the PowerShell Console:

$ArticlesSource = get-childitem master:/content/home/about-us/* -recurse `
  | where-object { $_.TemplateName -match "ArticleTemplate" } `
  | New-ExplicitItemSource "Cognifide Articles";

$package.Sources.Add($ArticlesSource);

You can specify any automation or filter you can think of to your Get-ChildItem, and you really don’t have to skimp on the number of data sources – after all you can re-generate your package at any time!

Similarly you can do this to the files on disk. Let’s say – you want to add all .aspx, .ascx and .ashx files, just to make sure your deployment features all the latest code and for the sake of this example let’s assume your UI elements are located in the Layouts folder under your web application:

$LayoutsPath = $AppPath+"layouts\*"
$Layouts = get-childitem $LayoutsPath -include "*.as?x" -recurse -force `
  | New-ExplicitFileSource "My Layouts";
$package.Sources.Add($Layouts);

Easy enough… now let’s add everything that is within the bin folder as a dynamic file source:

$BinFolder = New-FileSource "Bin Folder" -Root "/bin"
$package.Sources.Add($BinFolder);

That is it really… you may want to specify your package metadata which you would do like:

$package.Metadata.Author = "Auto generated " + `
  [DateTime]::Now.ToShortDateString();
$package.Metadata.Comment = "Isn't it cool?!";
$package.Metadata.Publisher = "Cognifide";

and then save it for later opening in package designer:

$package | Export-Package -FileName "test package.xml"

alternatively you can open such package as specified earlier

get-package "test package.xml"

if you ever wanted to add more sources to it or export as a zip file to be imported with the assets in your target environment:

$package | Export-Package -FileName "test package.zip" -Zip

… now on your target machine you need to upload your package to the Data\Packages folder. But then to install it all it takes is:

Import-Package "test package.zip"

Obviously all of it can be hooked to ribbon, context items, or be scheduled… but I get ahead of myself…

So how does it all relate to continuous deployment?

All of this can be completely automated, all you need to do is create a Script item as described in one of my previous posts and call the PowerShell execution URL referencing your script from your CruiseControl server or whichever continuous integration product you use in a fashion similar to:

http://myhost/Console/Layouts/PowerShellResults.aspx?scriptId={1680E211-BD28-49BE-82FB-DA7232814C62}&scriptDb=web

You need to deal with the fact that you are most probably not logged in with your continuous delivery environment – in this case probably best approach is to use the web database or the script item my turn out to be unavailable to you and the script will not execute.

Now in your source environment your script will create the package and upload it to an FTP server (there is plenty of ways to do this from PowerShell… you can find a couple of samples on Stack Overflow) and subsequently call a second part of the script on the target server.

On the Target server – a complementary script will be executed in the similar fashion – by the originating server and if you don’t have direct access to the file on the FTP server you’ve just uploaded – you can download it and import the package.

Now if you integrate the script with a ribbon in Content Editor on the source server (like described in the previous post) you can have a one-click-deployment solution on your dev machine, but then the REALLY cool part would be to integrate it with the context menu (as described in this post) and be able to push parts of the site to production with a single click! Not to mention your nightlies can really be nightlies if you do it using the scheduled tasks integration.

The goal for this week: Context Scripts

Context scripts are the first step to break the scripting out of the admin realm and into the editor’s space. Those scripts will still be written by admins and developers but the goal is for them to be usable by the authors. The goal for those scripts can be as trivial as e.g. syndicating all the great functionality little plugins like this Unpublish button by Ted in one place and then mix and match them to your liking.

Some of the important bits:

• Context scripts are something that is visible to users on “Scripts” page.
• Scripts can be exposed to everyone or just the groups of your liking… you define it in the script.
• Scripts are grouped in collections that are defined in *.psepi files that you drop into your application folder

How do I define a script collection?

Each script collection is defined within a single .psepi file. A sample script can look as follows:

<?xml version="1.0"?>
<ContextScriptCollection>
  <Title>Statistics Scripts</Title>
  <Description>This is a sample script collection allows for calculating some interesting stats for the branch you're in.</Description>
  <Scripts>
    <ContextScript>
      <Title>Author Statistics</Title>
      <Description>Click to Learn more about how many pages under this one were created by which authors.</Description>
      <Script>get-childitem -recurse | Group-Object  ChangedBy | Sort count -descending | format-table -property count, name</Script>
        <Icon>/App_Themes/Default/Images/Tools/AddUser.gif</Icon>
        <Warning>This script only calculates statistics so it does not really need a warning but let’s show it anyway. Do you want to calculate them?</Warning>
      <Groups>
        <string>WebAdmins</string>
        <string>Administrators</string>
      </Groups>
    </ContextScript>
  </Scripts>
</ContextScriptCollection>

What does each of the tags mean?

• Title & Description on ContextScriptCollection are going to appear at the top of the list for the collection – pretty self explanatory.
• Scripts is a container for ContentScript tags, it can contain any number of them.
• Each ContentScript tag represent a single script, where Title is what will appear on the button that the user will click to execute the script.
• Script tag contains the script body – this is where you put the code that will get executed
• Icon is a URL to an image that will appear on the button left of the button title.
• Warning tag contains a question that will get presented to the user before the script will be executed. This tag can be omitted in which case no warning will be shown. A rule of thumb would be that you should show a warning before a long running scripts and scripts that modify content so a user can back away from a mistakenly pressed button.
• Groups tag contains the list of groups that will have the right to see the script. if that tag is empty, all users will see the script. If you define at least one group, you need to define all groups that you want to see the button.

What does “Context” in Context scripts mean?

Basically since we cannot show the editor a console and let them navigate to the page (for various reasons, like complexity and potential destructive powers ) The scripting environment will put your script “in the current page” before releasing control to your script, which in essence is equivalent to typing before your script.

cd MyCMSDrive:\
cd /path/to/my/page/

That means that your script can get access to the page the user is currently on simply by using the “get-item .” command or enumerate its children by use of “get-childitem” etc. in the case of the script above it calculates author statistics for the branch it is executed in. Pretty cool, huh? ;)

Additionally I’ve realized in the process of duplicating/extending the functionality of Ted’s plugin that modifying standard EPiServer properties is not necessarily very intuitive, hence I’ve created a few macros to help me with the scripting exercises. While I still need to call “CreateWritableClone” I’ve simplified the saving of a page by defining the “Save-Page” function and created a Get-CurrentPage as an alias to “get-item .”. So a following script unpublishes the current page:

Get-CurrentPage | foreach-object {
$writable = $_.CreateWritableClone();
$writable.StopPublish = [DateTime]::Now;
Save-Page($writable);
}

While this one unpublishes all of its children

get-childitem -recurse | foreach-object {
$writable = $_.CreateWritableClone();
$writable.StopPublish = [DateTime]::Now;
Save-Page($writable);
}

Notice the subtle difference in the script and the major difference in the effect? Pure PowerShell magic!

To be honest I was amused to find out that during the whole process I’ve still not broken the CMS 5 compatibility, but I don’t expect it to stay this way in the future.

Also at this moment you can add and remove the *.psepi files at any moment as the files are parsed on every request, if that proves to be a problem in the future, caching will get introduced. At this moment I don’t find it a problem as it only happens in edit mode.

[Download & Enjoy]

Includes 2 bonus script collections!

How to install?

Extract the DLL form the ZIP file into the BIN folder of your web application to install the plugin. Remove the DLL to uninstall it.

All constructive feedback appreciated!

Disclaimer – Responsibility: With great powers comes great responsibility – this tool can do a lot of harm to a lot of content in a very short time – backup your system before using the plugin! I will not be held responsible for any use of it. Test your scripts on your development server first! Test on an exact copy of production before running scripts on production content.

Disclaimer – Security: While the tool requires a membership in either the “WebAdmin” or “Administrators” group, to execute, protect it with a <location> entry in web.config, to add another layer of security especially if your administration UI is exposed to the public. Manage your group memberships & rights responsibly!

For that to work, apart from the overall big blocks to be in place and working seamlessly (which is the absolute minimum required) – you need to be VERY attentive to details.

What happens when user enters a place in the system where they are not usually required to work, are they properly guided? What do they see if they click on a little link somewhere in the corner? Does every image has an Alt text attached to it? Do your buttons have tooltips? Do the users have alternate views on all content? Do the system communicates abnormal states in a descriptive way and guides the user towards the solution? Is the UI logically laid out? Did you REALLY think what property should go on which tab? Have you setup the property names in a way that they make sense to non programmer? Do they have descriptions?

Part of the job we do is help sometimes troubled EPiServer customers get their solution built elsewhere or in-house to work, and I seem to be noticing some patterns which we have addressed in Cognifide as being bad practices. Many of those stem from the lack of research of the content served being done in the discovery phase.

Discovery phase? What’s that?

It seems that a great deal of projects does not seem to be well thought out in many aspects. When you look at the solution, It feels like a developer just got some templates and ran with them. Once the front end matches what the html templates outline, the solution is pushed to production and forgotten by the design/development agency and the poor customer is struggling with it for years trying to improve the ever degrading performance and fighting the CMS UI that’s been thrown together in a rush. Possibly aggravating in the process and rebuilding it again and again.

You need to realize that once your site goes to production, the trouble begins for your customer, not ends.

Understand your content, please

A very basic tendency for a lot of them is storing all the content of one type under a single tree node. or a very basic hierarchy. But:

• What is the volume of content in the start?
• Have you talked to the client about the maintenance of the content?
• How do they plan to store older content?
  • Are they archiving it?
  • Do they plan to serve it to general while archived?
  • Is the old content actively browsed on the CMS side?
• What is the volume increase over time?
• What is the profile of the content? Is it a catalogue? Chronological news library?
• Is there a taxonomy in place?
• How often and which content is being modified?

EPiServer shows pages in a tree, and while we have observed the CMS performance improving over time there are some basic scenarios that the hierarchy structure will never be able to deal with efficiently if not well thought out.

So your potential edge case scenarios might be that the customer has:

1. 10 000 articles that need to be migrated for the site to go live, but they only plan to add 2-3 a month,
2. They might be starting fresh but they plan to add 20 to 30 articles a day!

How do you deal with those?

Obviously the worst thing you can do is to put them all under the “Articles” node. The customer will be frustrated to no end! Both you and the CMS reputation gets damaged while they try to do any basic thing in the CMS.

In the first case you need to work with the client to dissolve them into the hierarchy that’s granular enough to leave you with the 20-50 articles per node tops. Dividing it into 10 categories of roughly 1000 items won’t do! If the page names are meaningful, you may attempt to create a structure based on the first and second letter of the articles. This works best for directories of people or places.

The second case is probably going to happen to you when you will be working with any kind of news site, be that intranet of sorts or a news agency, TV portal or an information broker. In which case, it seems to be making the most sense to put the content into a chronological structure. Have a node for each year, month (and day if needed) there is an article.

AUTOMATE!

When a user writes an article that is supposed to fit into your content plan, move it into the proper node automatically. In the first case, move it to the proper category or based on the page title move it around to the proper place in the catalogue. In the chronological plan, move it to the day or month node upon creation. If a new node needs to be created for it – that’s your responsibility to do it. Organize the content for the user or you will be in a world of pain sooner than you expect!

Those tasks are easily automated by hooking into the page save and create events. Your customer will love you for it.

Naturally you don’t necessarily have to have a single plan on a given site. A site can have both branches with news-like plan and directory-like sub trees.

The base line is – you need to plan it ahead, and you need to learn about the content profile.

Distinction with a difference

You need to realize the distinction between the content and the presentation of it. Don’t try to cram the content into the browsing structure. Separation of concerns should not be limited to code organization. Separate concerns in the content structure as well.

Have the user trip designed around the best SEO practices. The hub pages should make sense from the visitor’s perspective. DON’T try to put your articles under it just because the hub page browses them. this may work for a little tiny sites but then again, those are not the sites that you will run into troubles because it basically means your customer is barely ever touching them.

Have your content stored in a separate branch and reach out for it with a tag set that is related to the hub page.

Build a logical taxonomy and stick to it!

That basically means – treat your content equally no matter where it’s stored – preferably having it tagged with a high performance framework like the Faceted Navigation Framework published by Cognifide some time ago or make it Lucene.Net based. You can try to use the EPiServer built in categories. We have had limited success with it and the performance of FindPagesWithCriteria (which we have effectively banned from our arsenal) but I was told the performance in that front have improved greatly in the latest EPiServer CMS release.

Regardless – don’t rely on the page hierarchy structure to select the content, it doesn’t matter where it is, the metadata is what should be driving the content stream. You can hand pick your navigation links, fine, but article lists, news, announcements, events, treat it as a single content stream. Use a taxonomy to divide it into categories and you will be much happier in the long run as you will gain much more flexibility to reorganize the structure and move the content around when its profile changes later.

Using the EPiServer CMS for nearly 4 years now, those are the basic principles we have come to establish.

I wonder what are your practices? Where do you think our practices do or do not fit your design philosophy? Is there anything we could do better? Do you have practices regarding content planning? How do you analyze the content to make the best plan for it?

• The bounds factor – proper use of Enum type guarantee that the selected value will fall within the constraints of the allowed value set.
• The ability to treat Enums as flags (and compound them into flag sets) as well as a one-of selector.
• The ease of use and potentially complete separation of the “Enum value” from the underlying machine type representation that ensures the most efficient memory usage.

Surprisingly enough EPiServer as it stands right now does not have an easy facility to turn Enums into properties. To give credit where credit is due, the EPiServer framework provides a nice surrogate that mimic that behaviour to a degree. The relevant property types are:

• PropertyAppSettingsMultiple  – which “creates check boxes with options that are defined in the AppSettings section in web.config. The name of the property should match the key for the app setting.”
• PropertyAppSettings  – which “creates a drop down list with options that are defined in the AppSettings section in web.config. The name of the property should match the key for the app setting.”

You quickly realize though that the properties have some limitations that makes their use a bit less compelling:

• The properties are not strongly typed
• The property entry in AppSettings section has to have the name that matches the property name on the page.
• It’s rather poorly documented, Other than relating to this blog entry or Erik’s post documenting it I could not find any other examples on how to use them. (but then again, who needs docs really when we have Reflector)
• You cannot have the very same property duplicated on the page since you can only have a single property of a given name per page. So you need to have multiple entries in AppSettings that match the name of each of those properties on your pages. I know… semantics but still…
• You are working on strings rather than enums (Did i mention it’s not type safe?)
• The values in the AppSettings are stored in a somewhat DLS-y manner (consecutive options are separated from each other with the ‘|’ character, the name and the value are separated with a ‘;’, for example: <add key = "RegionId" value="First Option;Option1|Default Option;Option2|Disabled Option;Option3" /> ) and I have had on an occasion entered a string there that caused the server to crash.
• The values are not translatable, or at least I could not find how to do it and any Reflector digging rendered no results either.

The solution to the problem:

The solution that the blog post describes is:

• Type safe
• Supports UI localization
• Easy to use in your custom implementation
• Flexible in allowing you to switch between the Enum being multi-choice or a single choice solution
• fully defined in the code – no need to modify web,config.

All you need to do to create your own custom Enum property is declare it.

using Cognifide.EPiserverControls.EnumDropDown;

[PageDefinitionTypePlugIn(DisplayName = "Sample Enum Property")]
public class SampleProperty : PropertyEnumSelector<MySampleEnum>
{
}

That’s it, really!

Now if you want to customize it; obviously you need to provide the information for the property to work with. But let’s stop for a while and think, where does that information belong?

• The property should worry about the mechanics of editing and the tediousness of persistence of the edited value, it clearly is not the place to specify the link between the Enum type and its human friendly drop down text.
• Web.config is for settings, not for describing content types and definitely not to enforce the property names.
• So where should the metadata around your Enum type be? How about we put it around the Enum type itself?

[Flags]
public enum MySampleEnum
{
  [ValueVisualisation(Name="First Option", LanguageKey="/enum/first")]
  Option1,

  [ValueVisualisation(Name="Default Option", Selected=true, LanguageKey="/enum/second")]
  Option2,

  [ValueVisualisation(Name="Disabled Option", Enabled=false, LanguageKey="/enum/disabled")]
  Option3,

  [ValueVisualisation(Name="Hidden Option", Hide=true, LanguageKey="/enum/hidden")]
  Option4,

  [ValueVisualisation(Name="Fifth Option", LanguageKey="/enum/fifth")]
  Option5,

}

What does all that do?

The property using an Enum described this way will look the following way in EPiServer:

Let’s get into the what’s happened here as there’s more than catches the eye.

As you can see the enum values are named like they are in the attributes describing them, Default option is selected just like you could have expected by looking at the Selected=true in its attribute. The Enabled=false in the Disabled option results in an option that cannot be changed. The unchangeable option can be both unselected or selected by default. You may want to disable some deprecated options but still show them in the UI as a legacy but for some reason you might not want users to be able to change their value. Option4 is clearly missing, which is intended and specified by the Hide=true, as you might want to hide options that have been removed form the UI and on the same time you don’t want to loose compatibility with a legacy API that uses the option.

Also There is one thing about the first option on the list – it’s translated! The mechanism to specify the translation is based on the standard EPiServer localization files that you can find in the “lang” folder in your typical EPiServer installation. The Translation for the property looks like the following

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<languages>
  <language name="English" id="en">
    <enum>
      <first>First Option Translated EN</first>
    </enum>
  </language>    
</languages>

so you see the value will take its translation key from the LanguageKey="/enum/first".

Ok, so we have the PropertyAppSettingsMultiple replacement, but what about PropertyAppSettings?

So here I reach the place where I am not 100% certain whether I took the proper path but I am sure I will hear about it if I didn’t :) The place where the property determines if it’s supposed to allow for multi selection or not is whether the Enum is marked with the [Flags] attribute. Obviously Flags mean that the property is a form of a bit flag and should be able to allow the user to flip the bits independently rather than being the “one-of” type. So once you remove the [Flags] form your enum you’re going to see it rendered the following way:

But hey, it’s not a one way trip, if you decide that you want the enum rendered in another type of property and force the opposite behaviour you can always override it in the derived property like follows:

    [PageDefinitionTypePlugIn(DisplayName = "Sample Enum Property Checklist")]
    public class SamplePropertyChecklist : PropertyEnumSelector<MySampleEnum>
    {
        static SamplePropertyChecklist()
        {
            MultiSelectEnum = true;
        }
    }

so even if you think my usage of [Flags] is faulty, the damage can be undone :)

Ok, but what about the enums that we have no control over – like enums form libraries. Obviously cannot retrofit attributes into them. Well, true but we still can have all of the control over the property.

Let’s assume for a moment that this is our legacy enum:

public enum MySampleLegacyEnum
{
  Option1,
  Option2,
  Option3,
  Option4,
  Option5,
}

You can just do nothing and simply use it in the property but the UI will display the not so nice Option1… names. That can be easily fixed – Again, specifying translation is the easiest way of achieving that goal. An xml for that enum would look like follows:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<languages>
  <language name="English" id="en">
    <MySampleLegacyEnum>
      <Option1>First Option</Option1>
      <Option2>Default Option</Option2>
      <Option3>Disabled Option</Option3>
      <Option4>Hidden Option</Option4>
      <Option5>Fifth Option</Option5>
    </MySampleLegacyEnum>
  </language>  
</languages>

The default values can be added by retrofitting the “DefaultValues” list with the elements that you want selected in the scenario where the property is first displayed for editing. You can also modify the inherited AvailableItems list to set the rest of the properties otherwise adjustable by the attributes.

Following is a sample of such retrofitted rules to match our original attribute-defined-enum.

[PageDefinitionTypePlugIn(DisplayName = "Sample Legacy Enum Property")]
public class SampleProperty : PropertyEnumSelector<MySampleLegacyEnum>
{
    static SampleProperty()
    {
        MultiSelectEnum = true;

        // Make Option2 a default selected value
        DefaultValues.Add(MySampleLegacyEnum.Option2.ToString());
        AvailableItems.Where(p => p.Value == MySampleLegacyEnum.Option2.ToString()).First().Selected = true;

        //Disable selection of Option3
        AvailableItems.Where(p => p.Value == MySampleLegacyEnum.Option3.ToString()).First().Enabled = false;

        //Remove hidden Option4
        AvailableItems.RemoveAll(p => p.Value == MySampleLegacyEnum.Option4.ToString());
    }
}

The [code for the EnumProperty] as well as [the compiled binaries] are available as Open Source and you can incorporate it in your projects as long as the Cognifide namespace is used for the code.

What do you think? Is that going to be useful for you?

Register for the Domain Driven Design that is platform-neutral and in fact, Eric gives .NET and Java versions of the courses.

More on Eric & DDD:
http://skillsmatter.com/course/design-architecture/domain-driven-design
http://skillsmatter.com/podcast/design-architecture/domain-driven-design
http://www.infoq.com/interviews/domain-driven-design-eric-evans

• HTML Code copy -Absolute must for any blogging .Net developer
• WatiN – Web applications testing in .Net – sounds like it might be THE framework for testing our web GUIs
• Visual Studio Add-Ins Every Developer Should Download Now
• Microsoft Visual Studio Extensibility Contest Winners
• Introduction to GhostDoc – really funny tool that needs to be looked at – might be useful…. moderately. Definitely genuine.
• CodeKeep – THE repository for storing and sharing code snippets
• Visual Studio Power toys pack installer
• Christopher Bennage lists some nice and worth mentioning tools as well
• Seems like an interesting sanbox for some cool development ideas
• FX Cop
• NCoverExplorer – test coverage tool
• This is not really a .Net stuff biut rather an IE Addon but a great one at that!