SmartFTP is a fantastic FTP application which handles syncing files very effectively. This means that when you upload your entire website, SmartFTP will automatically detect changes and only upload what is required (instead of overwriting all of the files like some FTP applications do). For each project at TheFARM we have build scripts which run and create a time stamped ZIP package for each deployment environment with all of the necessary files formatted appropriately for each. Our deployment process then involves unzipping the contents of this file, opening up SmartFTP, connecting to the deployment destination and transfering all of the deployment files up (which SmartFTP synchronizes for us).

I thought it would be much more efficient if we automated this process. So we did some investigation and it turns out the SmartFTP conveniently has an API! So we decided to see if we could write a PowerShell script to use the SmartFTP api to automagically transfer/sync all of our deployment files in our Zip package to the necessary FTP site and with a bit of trial and error we managed to do it! Now, I’m not PowerShell expert or anything, and in fact this was my very first PowerShell script ever written so I’m sure this could all be done a bit better, but it works! I’m not going to go into detail about the SmartFTP api or how to write PowerShell stuff because this script will work with some basic requirements:

• You need both PowerShell and SmartFTP installed
• Currently this only supports the standard FTP protocol, but if you need SFTP, etc… you can just change the $fav variable’s ‘Protocol’ property
• The parameters, in this order are:
• destination
• the IP address, or host of your FTP server
• user
• the username used to login to the FTP server
• password
• the password used to login to the FTP server
• path
• The FTP path of where you want your files to go on your FTP server
• port
• The FTP port to use, default is 21
• source
• The source folder to copy to the FTP site, if not specified, uses the current directory that the PowerShell script is run from

Example usage:

FTPSync.ps1 123.123.123.123 MyUserName MyPassword 21 “C:\MyWebsiteFolder” “/websites/MyWebsite”

or you can just double click on the ps1 file and it will prompt you for these details.

So without further adieu, here’s the script!

#requires -version 2.0

# Define inputs
param (
    [parameter(Mandatory=$true)]    
    [string]
    $dest,
    [parameter(Mandatory=$true)]
    [string]
    $user,
    [parameter(Mandatory=$true)]
    [string]
    $pass,
    [parameter(Mandatory=$true)]
    [ValidatePattern('\d+')]
    [int]
    $port = 21,
    [parameter(Mandatory=$false)]
    [ValidateScript({ Test-Path -Path $_ -PathType Container })]
    [string]
    $source,
    [parameter(Mandatory=$true)]
    [ValidatePattern('\/+')]
    [string]
    $path
)

# get current folder
$currFolder = (Get-Location -PSProvider FileSystem).ProviderPath;
# set current folder
[Environment]::CurrentDirectory=$currFolder;
# if the source isn't set, then use the current folder
if ($source = "") {
    $source = $currFolder;
}

Write-Host "------------------------------------------------------" -foregroundcolor yellow -backgroundcolor black
Write-Host("{0, -20}{1,20}" -f "Destination", $dest);
Write-Host("{0, -20}{1,20}" -f "User", $user);
Write-Host("{0, -20}{1,20}" -f "Pass", "********");
Write-Host("{0, -20}{1,20}" -f "Port", $port);
Write-Host "";
Write-Host "Source:";
Write-Host $source;
Write-Host "";
Write-Host "Path";
Write-Host $path;
Write-Host "------------------------------------------------------" -foregroundcolor yellow -backgroundcolor black

# Create application
$smartFTP = New-Object -comObject SmartFTP.Application;
$smartFTP.Visible = [bool]0;
$smartFTP.CloseAll();

# create temp favorite item
$fav = $smartFTP.CreateObject("sfFavorites.FavoriteItem");
$fav.Name = $user + " @ " + $dest + " (temp favorite by cmdInterface)";
# 1 = FTP standard protocol
$fav.Protocol = 1;
$fav.Host = $dest;
$fav.Port = $port;
$fav.Path = $path;
$fav.Username = $user;
$fav.Password = $pass;
# forces it not to be saved
$fav.Virtual = "true";

# Add temporary favorite to SmartFTPs FavoriteManager
$favMgr = $smartFTP.FavoritesManager;
$rootFolder = $favMgr.RootFolder;
$rootFolder.AddItem($fav);

# Get the transfer queue
$queue = $smartFTP.TransferQueue;
# stop the queue if it isn't already
if ($queue.State -ne 1) { $queue.Stop(); } # Stopped = 1
# clear the queue
foreach($item in $queue.Items) { $queue.RemoveItem($item); }
# set the thread count for the queue
$queue.MaxWorkers = 20;
#enable logging
$queue.Log = "true";
$queue.LogFolder = $currFolder + "\\LOG";

# create new transfer item
$newItem = $smartFTP.CreateObject("sfTransferQueue.TransferQueueItem");
# set the item as a folder and copy operation, 
$newItem.type = 2;  #FOLDER = 2 
$newItem.Operation = 1; #COPY = 1

# Set the source
$newItem.Source.type = 1;  #LOCAL = 1
$newItem.Source.Path = $source;

# Set the destination
$newItem.Destination.type = 2; #REMOTE = 2
$newItem.Destination.Path = $path;
$newItem.Destination.FavoriteIdAsString = $fav.IdAsString; #links up to our connection favorite

# and finally add it
$queue.AddItemTail($newItem);

Write-Host "STARTING" -foregroundcolor yellow -backgroundcolor black;

$queue.Start();

while ($queue.Items.Count -ne 0) { 
    Write-Host "Processing...bytes transfered: " $queue.TransferredBytes;
    Start-Sleep -s 2; #wait 2 seconds
}

# store the total bytes
$totalBytes = $queue.TransferredBytes;

# cleanup smartftp app
$queue.Quit();
$smartFTP.Exit();

# parse logs

# regex to find "[DATE/TIME] STOR FILENAME
# which indicates a file transfer
$regex = new-object System.Text.RegularExpressions.Regex("\[[\w\-\:]*?\]\sSTOR\s(.+?)\[",,[System.Text.RegularExpressions.RegexOptions]::SingleLine);
$totalFiles = 0;
Write-Host "Files Transfered" -foregroundcolor cyan -backgroundcolor black
Get-ChildItem $queue.LogFolder -include *.log -Recurse | foreach ($_) { 
    $currFile = Get-Content $_.fullname;
    $match = $regex.Matches($currFile);    
    if ($match.Count -gt 0) {        
        foreach($m in $match) { Write-Host $m.Groups[1]; } 
        $totalFiles++;
    }
    remove-item $_.fullname -Force -Recurse ;
}

Write-Host "COMPLETED (total bytes: " $totalBytes ", total files: )" $totalFiles -foregroundcolor cyan -backgroundcolor black;

"------------------------------------------------------"

# cleanup COM
Remove-Variable smartFTP

A few times I’ve seen questions posted on the Umbraco forums which ask how to deal with case insensitivity text with Examine, and it’s also something that we’ve had to handle a few times within our own company.

Here’s a scenario:

• You have a site search
• You use examine
• You want to show the results looking exactly the same as it was before it went into Examine

If you’re running a standard install you’ll notice that the content always ends up lowercased!

This is a bit of a problem, page titles will be lowercase, body content will be lowercase, etc. Part of this will be due to a mistake in Examine, part of it is due to the design of Lucene.

In this article I’ll have a look at what you need to do to make it work as you’d expect.

First, some background

Before we dive directly into what to do to fix it you really should understand what is happening. If you don’t care feel free to skip over this bit though :P.

Searching is a tricky thing, and when searching the statement Examine == examine = false; To get around this searching is best done in a case insensitive manner. To make this work Examine did a forced lowercase of the content before it was pushed into Lucene.Net. This was to ensure that everything was exactly the same when it was searched against.
In hindsight this is not really a great idea, it really should be the responsibility of the Lucene Analyzer to handle this for you.

Many of the common Lucene.Net analyzers actually do automatic lowercasing of content, these analysers are:

• StandardAnalyzer
• StopAnalyzer
• SimpleAnalyzer

So if you’re using the standard Examine config you’ll find yourself using the StandardAnalyzer and still have your content lowercased.

This means that there’s no need to Lucene to concern itself about case sensitivity when searching, everything is parsed by the analyzer (field terms and queries) and you’ll get more matches.

So how do I get around this?

Now that we’ve seen why all your content is generally lower case, how can we work with it in the original format and display it back to the UI?

Well we need some way in which we can have the field data stored without the analyzer screwing around with it.

Note: This doesn’t need to be done if you’re using an analyzer which doesn’t have a LowerCaseTokenizer or LowercaseFilter. If you’re using a different analyzer, like KeywordAnalyzer then this post wont cover what you’re after (since the KeywordAnalyzer isn’t lowercasing, you’re actually using an out-dated version of Examine, I recommend you grab the latest release :)). More information on Analyzers can be found at http://www.aaron-powell.com/lucene-analyzer

Luckily we’ve got some hooks into Examine to allow us to do what we need here, it’s in the form of an event on the Examine.LuceneEngine.Providers.LuceneIndexer, called DocumentWriting. Note that this event is on the LuceneIndexer, not the BaseIndexProvider. This event is Lucene.Net specific and not logical on the base class which is agnostic of any other framework.

What we can do with this event is interact directly with Lucene.Net while Examine is working with it.
You’ll need to have a bit of an understanding of how to work with a Lucene.Net Document (and for that I’d recommend having a read of this article from me: http://www.aaron-powell.com/documents-in-lucene-net), cuz what you’re able to do is play with Lucene.Net… Feel the power!

So we can attach the event handler the same way as you would do any other event in Umbraco, using an Action Handler:

public class UmbracoEvents : ApplicationBase
{
	public UmbracoEvents()
        {
            var indexer = (LuceneIndexer)ExamineManager.Instance.IndexProviderCollection["DefaultIndexer"];

            indexer.DocumentWriting +=new System.EventHandler(indexer_DocumentWriting);
        }
}

To do this we’ve got to cast the indexer so we’ve got the Lucene version to work with, then we’re attaching to our event handler. Let’s have a look at the event handler

void indexer_DocumentWriting(object sender, DocumentWritingEventArgs e)
{
	//grab out lucene document from the event arguments
	var doc = e.Document;

	//the e.Fields dictionary is all the fields which are about to be inserted into Lucene.Net
	//we'll grab out the "bodyContent" one, if there is one to be indexed
	if(e.Fields.ContainsKey("bodyContent")) 
	{
		string content = e.Fields["bodyContent"];
		//Give the field a name which you'll be able to easily remember
		//also, we're telling Lucene to just put this data in, nothing more
		doc.Add(new Field("__bodyContent", content, Field.Store.YES, Field.Index.NOT_ANALYZED));
	}
}

And that’s how you can push data in. I’d recommend that you do a conditional check to ensure that the property you’re looking for does exist in the Fields property of the event args, unless you’re 100% sure that it appears on all the objects which you’re indexing.

Lastly we need to display that on the UI, well it’s easy, rather accessing the bodyContent property of the SearchResults, use the __bodyContent and you’ll get your unanalyzed version.

Conclusion

Here we’ve looked at how we can use the Examine events to interact with the Lucene.Net Document. We’ve decided that we want to push in unanalyzed text, but you could use this idea to really tweak your Lucene.Net document. But really playing with the Document is not recommended unless you *really* know what you’re doing ;).

I’ve been asked this question a few times, how do you implement pagination in your Examine search results.

Well a fun-fact is that Lucene doesn’t have really good way to do this, it just involves skipping to the point that you want to get the results from.

Thanks to .NET and LINQ we have extension methods which handles that nicely, Skip and Take, and since that the search results are IEnumerable underneath they can be used. But there’s one problem, doing this will result in a bit of a performance hit, as your initial Skip would hydrate a bunch of entities from the underlying Lucene store, which is where you loose performance.

So we implemented our own version of Skip! So you can just use Skip and Take as standard, and they’ll be evaluated without loosing performance.

Here’s the code:

int pageNumber = string.IsNullOrEmpty(Request.QueryString["pageNum"]) ? 0 : int.Parse(Request.QueryString["pageNum"]);
int pageSize = 10; //this could be a config value or something

/* serach snipped */

var results = searcher.Search(...);

//And we'll just set a repeater with the results
Repeater.DataSource = results.Skip(pageNumber * pageSize).Take(pageSize);
Repeater.DataBind();

It's just that easy.

Now that Examine is able to be used by a wider audience than Umbraco understanding how search works is possibly a bit more important ;).

So today while answering a question on the Umbraco forum I thought that what I was going on about is something that more people might want to hear about. And really, I do like the sound of my own (virtual) voice…

Understanding Lucene.Net from Examine

For this I’m going to be looking at the Lucene.Net implementation of Examine, and this is agnostic of whether you’re using UmbracoExamine or Examine.LuceneEngine.

To get started you should familiarize yourself a bit with the Lucene Query Parser Syntax, as that’s what we’re using internally to get the data back from Lucene.Net.

Also, we’re going to be working with the Fluent API for Examine, so fell free to read up on that here and here. With Examine we’ve made it easy to see what the Lucene query you’re building up is as you’re working with the Fluent API, in fact if you to a .ToString() call on the ISearchCriteria instance you’ll be able to see what you’re search query looks like (we’ve also got some other information in the result of that method call too).

So you can see what’s been generated, let’s build a query and dissect it:

var criteria = searcher.CreateSearchCriteria(IndexTypes.Content);
criteria = criteria.NodeName("Hello").And().NodeTypeAlias("world").Compile();

Console.WriteLine(criteria.ToString()); //+(+nodeName:Hello +nodeTypeAlias:world) +__IndexType:content

So this is what we've got, a total of three conditions… But wait, there’s only two conditions that I entered right?

Not quite, Examine has some smarts built into it around what you’re searching on and it’ll add that restriction on your behalf. This is so you don’t get results back from a different index type in your query. Note: If you don’t specify the IndexType then this condition wont be added for your.

Also, to ensure that all your entered queries don’t get killed by the IndexType (a problem in earlier Examine builds) we combine everything you enter into a GroupedAnd statement.

Let’s have a look at the parts we did request, and how they are comprised:

+nodeName:Hello +nodeTypeAlias:world

Ok, so what we've got here is our two conditions which we've added using Examine. Each is an AND (or in Lucene terminology SHOULD) and this is denoted by the +. Next we have a field name, in this case either nodeName or nodeTypeAlias. Youl’ll notice back in our Fluent API query we actually generated all of that using the build in methods, rather than having to use more magic strings. Next there is a : to indicate where the field name ends. Lastly we have the term which we’re going to search against, either Hello or world.

So essentially it’s built up of BOOLEAN_OPERATION&FieldName:Term (the & is so it’s slightly readable).

Conclusion

This was a brief look at how the Fluent API for Examine will turn your typed query into a Lucene query that is then searching.

With this knowledge you should be better able to design complex queries, use mixed conditionals and just plain go crazy.

During CodeGarden 2010 a few people were asking how to use Examine to index and search on data from any data source such as custom database tables, etc… Previously, the only way to do this was to override the Umbraco Examine indexing provider, remove the Umbraco functionality embedded in there, and then do a lot of coding yourself.  …But now there’s some great news! As of now you can use all of the Examine goodness with it’s embedded Lucene.Net with any data source and you can do it VERY easily.

Some things you need to know about the new version:

1. I haven’t made a release version of this yet as it still needs some more testing, though we are putting this into a production site next week.
2. If you want to try this, currently you’ll need to get the latest source from Examine @ CodePlex
3. If you are using a previous version of Examine, there’s a few breaking changes as some of the class structures have been moved, however you config file should still work as is… HOWEVER, you should update your config file to reflect the new one with the new class names
4. There is now 3 DLLs, not just 2:
   • Examine.DLL
     • Still pretty much the same… contains the abstraction layer
   • Examine.LuceneEngine.DLL
     • The new DLL to use to work with data that is not Umbraco specific
   • UmbracoExamine.DLL
     • The DLL that the Umbraco providers are in

Ok, now on to the good stuff. First, I’ve added a demo project to this post which you can download HERE. This project is a simple console app that contains a sample XML data file that has 5 records in it. Here’s what the app does:

1. This re-indexes all data
2. Searches the index for node id 1
3. Ensures one record is found in the index
4. Updates the dateUpdated time stamp for the data record
5. Re-indexes the record with node id 1’

So assuming that you have some custom data like a custom database table, xml file, or whatever, there’s really only 3 things that you need to do to get Examine indexing your custom data:

1. Create your own ISimpleDataService
   • There is only 1 method to implement: IEnumerable<SimpleDataSet> GetAllData(string indexType)
   • This is the method that Examine will call to re-index your data
   • A SimpleDataSet is a simple object containing a Dictionary<string, string> and a IndexedNode object (which consists of a Node Id and a Node Type)
   • For example, if you had a database row, your SimpleDataSet object for the row would be the dictionary of the rows values, it’s node id and type … easy.
2. Use the ToExamineXml() extension method to re-index individual nodes/records
   • Examine relies on data being in the same XML structure as Umbraco (which we might change in version 2 sometime in the future… like next year) so we need to transform simple data into the XML structure. We’ve made this quite easy for you; all you have to do is get the data from your custom data source into a Dictionary<string, string> object and use this extension method to pass the xml structure in to Examine’s ReIndexNode method.
   • For example: ExamineManager.Instance.ReIndexNode(dataSet.ToExamineXml(dataSet["Id"], "CustomData"), "CustomData");  where dataSet is a Dictionary<string, string> .
3. Update your Examine config to use the new SimpleDataIndexer index provider and the new LuceneSearcher search provider

If you’re not using Umbraco at all, then you’ll only need to have the 2 Examine DLLs which don’t reference the Umbraco DLLs whatsoever so everything is decoupled.

I’d recommend downloading the demo app and running it as it will show you everything you need to know on how to get Examine running with custom data. However, i know that people just like to see code in blog posts, so here’s the config for the demo app:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>

  <configSections>
    <section name="Examine" type="Examine.Config.ExamineSettings, Examine"/>
    <section name="ExamineLuceneIndexSets" 
             type="Examine.LuceneEngine.Config.IndexSets, Examine.LuceneEngine"/>
  </configSections>

  <Examine>
    <ExamineIndexProviders>
      <providers>

        <!-- 
        Define the indexer for our custom data.
        Since we're only indexing one type of data, there's 
        only 1 indexType specified: 'CustomData', however
        if you have more than one type of index (i.e. Media, Content) 
        then you just need to list them as a comma seperated list without spaces.
        
        The dataService is how Examine queries whatever data source you have, 
        in this case it's a custom data service defined in this project.
        A custom data service only has to implement one method... very easy.        
        -->
        <add name="CustomIndexer"
             type="Examine.LuceneEngine.Providers.SimpleDataIndexer, 
                Examine.LuceneEngine"
             dataService="ExamineDemo.CustomDataService, ExamineDemo"
             indexTypes="CustomData"
             runAsync="false"/>

      </providers>
    </ExamineIndexProviders>
    <ExamineSearchProviders defaultProvider="CustomSearcher">
      <providers>
     
        <!-- 
        A search provider that can query a lucene index, no other 
        work is required here 
        -->
        <add name="CustomSearcher"
             type="Examine.LuceneEngine.Providers.LuceneSearcher, 
                Examine.LuceneEngine" />

      </providers>
    </ExamineSearchProviders>
  </Examine>

  <ExamineLuceneIndexSets>

    <!-- Create an index set to hold the data for our index -->
    <IndexSet SetName="CustomIndexSet" 
              IndexPath="App_Data\CustomIndexSet">
      <IndexUserFields>        
        <add Name="name" />
        <add Name="description" />
        <add Name="dateUpdated" />
      </IndexUserFields>
    </IndexSet>
    
  </ExamineLuceneIndexSets>

</configuration>

TheFARM is currently looking for a talented and passionate senior .Net developer. Someone that has a minimum of 4 years ASP.Net development experience, stays up to date with the latest technologies, and actually loves to program. Skill set should include:

• Expert knowledge of .Net from v2 up to v4
• Experience with common patterns and practices including Dependency Injection
• JavaScript, JQuery, AJAX, and everything else to do with client side web programming… yes, you’ll still have to write some CSS and HTML
• ASP.Net MVC 2+
• We are an Umbraco CMS development agency so if you’ve used it before, it would be of huge benefit, otherwise be prepared for extensive training
• … and lots, lots more ;)

If you think you would be suitable for this role, we would love to hear from you! Please email us your CV/Resume to: Work@thefarmdigital.com.au

The uComponents project for Umbraco is coming along rather nicely! So far there are 13 new data types created and a few extensions, hopefully soon we’ll have a package ready to go. In the meantime, I thought I’d share a nice little code snippet that we’re using this throughout uComponents that allows you to add embedded resources to ClientDependency. It’s pretty easy and works perfectly with Umbraco 4.5 or any other site you have running ClientDependency. This will ensure that embedded resources (JavaScript or CSS) are added to the ClientDependency combined scripts/styles and also compressed and cached.

First, I’ll show you how to register your embedded resources using our extension method class (for a Control object):

this.AddResourceToClientDependency(
    "DataTypesForUmbraco.Controls.Shared.Resources.PrevalueEditor.css", 
    ClientDependency.Core.ClientDependencyType.Css);

The above code assumes:

• The class that you are consuming the code inherits from System.Web.UI.Control
• That your embedded resource’s path is: DataTypesForUmbraco.Controls.Shared.Resources.PrevalueEditor.css
  • If you don’t know about embedded resources, or know how they work, you should read: Working With Embedded Resources in ASP.Net
• That your embedded resource is a CSS type

Pretty easy right!! Well, the only thing missing is that you’ll need to add our extension method class to your project which looks like this:

/// 

/// Extension methods for embedded resources
/// 
public static class ResourceExtensions
{

    /// 

    /// Adds an embedded resource to the ClientDependency output by name
    /// 
    /// 
    /// 
    /// 
    public static void AddResourceToClientDependency(this Control ctl, string resourceName, ClientDependencyType type)
    {
        //get the urls for the embedded resources           
        var resourceUrl = ctl.Page.ClientScript.GetWebResourceUrl(ctl.GetType(), resourceName);

        //add the resources to client dependency
        ClientDependencyLoader.Instance.RegisterDependency(resourceUrl, type);
    }

    /// 

    /// Adds an embedded resource to the ClientDependency output by name and priority
    /// 
    /// 
    /// 
    /// 
    public static void AddResourceToClientDependency(this Control ctl, string resourceName, ClientDependencyType type, int priority)
    {
        //get the urls for the embedded resources           
        var resourceUrl = ctl.Page.ClientScript.GetWebResourceUrl(ctl.GetType(), resourceName);

        //add the resources to client dependency
        ClientDependencyLoader.Instance.RegisterDependency(priority, resourceUrl, type);
    }

}

So basically, if you have a Control, you can register your embedded resources in ClientDependency with one line of code… sweeeeet.

When working with Macros in Umbraco there’s always the decision of what type to go with, are you going with XSLT, a .NET user control, a .NET class or maybe a DLR script?

Here’s a few guidelines which we use at TheFARM to do macros.

Please note – although Shannon and myself are both on the Umbraco core team this is the opinion of us and does not necessarily reflect that of the Umbraco core team.

Choosing the right type

Umbraco supports several different ways which you can create a macro:

• XSLT
• .NET User Control
• .NET Custom Control
• DLR languages such as IronPython or IronRuby

Choosing the right tool for the job comes down to what you're trying to do with your macro. Generally speaking you'll be writing a macro that is either a XSLT or a .NET User Control. We currently don't use the DLR languages so using IronPython or IronRuby as the macro type isn't done (but if you can put forth a good case as to why we should we're happy to hear it!) and it's not often that you're going to require a macro which loads up a .NET control which is just a class (such as a CompositeControl or WebControl).

In fact in all the years I’ve been working with Umbraco I’ve never used a .NET Custom Control. In fact I’ve hardly ever had a need to create custom .NET server controls in all the time which I have work with ASP.NET.

When to use XSLT

XSLT is a powerful but miss-understood language and using it in Umbraco can be a really good idea or a really bad idea. XSLT is great for interacting with the Umbraco content cache, as the cache stores all the data as XML, which obviously XML is great at working with. When working purely with the XML cache it can be really fast.
But XSLT can become slow if you start introducing .NET into the mix. This can be in the form of XSLT Extensions, or embedded C# code in your XSLT file.
Here's a few rules as to when XSLT is the probably right way to go:

• Are you building a navigation system
  • Navigation systems such as breadcrumbs, top or page-based navigations should always be done in XSLT
• Are you repeating content under the current node or something contextual from the current node
  • If you're building something like a news article listing outputting with XSLT is often faster as the data is contextual
• Is the number of lines going to be small
  • XSLT can be hard to read (well, XPath really) and once you start getting long XSLT files with multiple templates it can be very hard to follow where you're going in the file

• Are you likely to debug
  • Yes you can debug XSLT. No it's not as nice an experience as debugging .NET
• Do you have to write an XSLT extension
  • If you have to write an XSLT extension that means that you need some .NET which has functionality too complex to express in XSLT. Try not to mix technologies
• Do you need to get nodes with a XPath selector like //node
  • If you're using //node then you're looking at the XML file as a whole, so chances are you don't really know where your data is. This means you're having to process the whole XML file to find what you want, resulting in potentially slow code and scalability problems

Essentially what it comes down to is that XSLT is great if you're working with transforming the data for just the data to display on the UI, remember XSLT stands for Extensible Stylesheet Language Template Transformations ;).

When to use .NET

.NET is what we're most familiar with, so coding .NET seems the right thing to do, but despite popular belief .NET isn't the be all and end all when it comes to programming. .NET has a lot of advantages over the other macro types, but it can also introduce its own problems particularly around performance.
Here's a few rules as to when .NET User Controls are probably the right way to go:

• You're working with FADS
• You're interacting with an external data source
  • UI should never directly access the data source
• You have business rules around the data
  • Business rules don't have to be just external data reliant, they can be around the content too. Business rules can be generally expressed easier in .NET
• You plan to unit test
  • This is kind of the same as the business rules point, but if you're writing business rules you should be unit testing them and unit testing XSLT is very hard

• You need fine-grade control over the markup generated
  • Some .NET server controls have their own markup rules around them and outputting simple things can often be tricky (like menus or lists of data)

Macros vs Registered User Controls

When creating a .NET User Control you need to make a decision about whether you want to have it as a macro or whether you just register is as per normal in the Master Page. The general rule is that you shouldn't make something into a macro unless you need to pass data into it from the current Umbraco page, or you need to have the content editors place it anywhere they want.
Often a macro needs to have data passed into it from Umbraco, this could be a property which is set on the current page. This is an idea opportunity to use a Macro rather than just registering the user control as when Umbraco is processing the template and finding the macros it will assign any of these properties. This can save you from writing code to retrieve the value yourself.
The other reason is that you may want content editors to control where a macro is placed within a site. This can be handy for things such as Contact forms or news listings. By giving editors this freedom they can better control what pages do what in their site. But with great power comes great responsibility. If you're allowing macros to be inserts from the WYSIWYG editor (and this is applicable for XSLT macros as well as .NET) things can break so be sure to handle unexpected usage. A good rule of thumb is that a macro should only be allowable in the WYSIWYG editor if you know it can't break anything (design, functionality, etc).
Using a plain control registration though does have its own advantages. If you register the control yourself it will be faster as there is no dynamic creation of the user control instance from the Umbraco request, this is all handled via the ASP.NET runtime. It can also give you greater flexibility if you want to use features such as Dependency Injection, as you're running in the ASP.NET life cycle entirely, not being injected into the page from an outside source.
Our preference is to have controls registered in templates for .NET components.

Conclusion

Hopefully this simple set of guidelines will give you a bit of an insight into how we at TheFARM go about our Umbraco development.

A few people were asking for the source code from my Examine presentation at CodeGarden, so here it is. I’m not going to go in to all of the details of this site or the Examine config as it’s pretty simple. However, i will give you a very quick run down of it and if you attended CodeGarden and my presentation, you’d probably already know this.

The Umbraco config for this demo site is simple: A search form, a couple of search result pages with different templates (results using XSLT extensions, results to query media using the FluentAPI, custom results using the FluentAPI). Then there’s the content: 5 very simple nodes consisting of a text field and a numeric field and a miniature blog with some posts and comments.

I’ve included all of the source files and a backup of the database that it was running on. The source files are left in the same state as we left the demo during the presentation. So to get it up and running, just restore the database to your MS SQL server, update your web.config, and put the project files into IIS (or open the solution in Visual Studio).

Download here

A few people had asked during CodeGarden 2010 if I would post up the slide deck for my Examine presentation, so here it is. There’s not a heap of information in there since i think people would have soaked up most of the info during the examples and coding demos but it’s posted here regardless and hopefully it helps a few people.

I’ve included a PDF version (link at the bottom) and also the image version below (if you’re too lazy to download it :)