Template Building Blocks via .NET Assembly

After getting your hands on a CMS environment, you may want to work on a Tridion Template Building Blocks (TBB) created through an ASP.NET assembly from Visual Studio. For experienced Tridion developers and consultants, move along, there's nothing new or exciting here.

I surprised a fellow coworker when I confessed never having set this up before. SDL Tridion is so flexible there are several different ways of accomplishing the same task. The answer to many Tridion questions is a strange cocktail consisting of precedence, preference, and environment. Each customer is free to focus on the parts they like, which means Tridion users may end with a very useful, but small slice of the software's capabilities (e.g. you don't need a Linux setup if you're a Windows shop or in my case, XSLT component templates provide "enough" functionality). It also makes the consultant's job that much more fun, challenging, and exciting!

Option 1

Log in to the TridionWorld forum and ask.

Option 2

Read someone else's explanation. TBBs with .NET assemblies have been covered before, along with sample code (good stuff, visvabalaji aka "String Writer"). If you get bored with your typical object-oriented languages, put on your architect hat and try them in F#. Or try them pre-made. Fellow consultants at Building Blocks even follow Joel's Rules to bake them into their SDLC with continuous integration. When you're done checking out the other posts, you can even philosophize the pros and cons of TBB and if you're still not sure which TBB is what type, you can add some visual flair to your icons.

Option 3

Hack along with your Disruptive Innovator to prepare the TcmUploadAssembly program, create a .NET class library, update code, and then update the content management system (CMS). The following assumes you have Visual Studio installed on the same environments as the CMS.
Prepare TcmUploadAssembly (set up once)

1. Copy TcmUploadAssembly.exe from %TRIDION_HOME%\bin\client\ to a location of your choice. You can later move this to your Visual Studio solution folder to take advantage of a post-build event.
2. Create a.config.xml file with the following, updating the target URL to your CME's address. A sample copy is in the "client" folder above.
   

   <?xml version="1.0"?>
      <templateAssemblyUploadConfig>
         <targetURL>http://localhost/</targetURL>
         <userName />
         <password />
         <uploadPDB>true</uploadPDB>
      </templateAssemblyUploadConfig>
   

Create Class Library

1. Using Visual Studio 2010, create a C# Class Library. An appropriate folder name would match your organization, an existing namespace, or related functionality. For example my first project was "MyFirstTemplatingLibrary" and the one I used for this is "CreateAndBreakTemplates."
   
2. Right-click References in Solution explorer and add references to client libraries in:
   %TRIDION_HOME%\bin\client\
   
   
   Quick tip on getting a list of dlls (for making your next great tutorial): in a CMD prompt use "dir /b > list.txt" to output a directory's contents and save it to text file "list.txt." Bonus if you're a PowerShell or scripting wiz to convert the list of dlls into the C# using references at the top of your code.
3. Update .NET example class to extend ITemplate

• Above the class add: [TcmTemplateTitle("Add Date to Package")]
• After the class name add colon (:) followed by "ITemplate" to extend the ITemplate class.
• Add a Transform() function, for example, the following will almost add a date to the package when used in Template Builder:
  public void Transform(Engine engine, Package package)
     {
     var timeStamp = DateTime.Now.ToString("d MMM yyyy");
     package.PushItem("timeStamp", package.CreateHtmlItem(timeStamp));
     }

After getting the project setup and some sample code written, you'll need to get these dlls into the CMS using the TcmAssemblyUploader.

Update the CMS

Move your developed dlls into Tridion using the project's post-build event, manually through the command line, or through the Visual Studio Add-in. All three flavors rely on the TcmAssemblyUploader executable that comes with the Tridion installation.

1. If you feel like a .NET developer, add the following post-build event.
• Post-build event > Project {ProjectName}'s Properties (or right-click on Project in Solution Explorer)
• Add the following Post-build event command-line, changing "tcm:1-1-2" to the TCM id of a folder in your CMS (hover over it to get the number):
  "$(SolutionDir)\TcmUploadAssembly.exe" "$(SolutionDir)\config.xml" /verbose /folder:tcm:1-1-2 "$(TargetFileName)"
2. If you prefer a command prompt, manually run TcmUploadAssembly using the following syntax (if you're creatively lazy, consider making a .bat file)
   {path_to_exe}\TcmUploadassembly.exe {path_to_assembly} /targeturl:{CME_url_including_http} /folder:{tcm_id_of_folder}
3. Speaking of automation, check out the TcmUploadAssembly Visual Studio Add-on for your version of SDL Tridion: 
• R5.3 and 2009
• 2011

If everything works, you will see a successful build in Visual Studio and the TBB ready for use in the CMS. If you have a problem, start with basic systems checking:

• is there an obvious problem, syntax error, or error message
• are you missing a dll reference?
• is the solution the right version (software revision number, 64 vs 32-bit, etc) 
• can you test a simpler problem, can you go back to a known working solution

Debugging

After this setup can use your TBB as you would the existing default TBB. You can optionally attach Visual Studio to a process (run the modular Template Builder and select TcmTemplateDebugHost), so that running template building block will actually stop on break points selected in Visual Studio. See if you can find the typo in the same code above (hint: all the syntax is right, but one of the parameters returned unexpected results).

That's it! Create a class library, take a short trip through dll hell, and have your classes extend ITemplate. Once you load your assembly into Tridion, you can see the assembly name and individual TBBs based on each class you create. Mix-match-and play with these modular pieces to leverage a familiar interface and programming language.

I am on the cusp of moving back to level 3 as I find out what it really takes to work with TBBs!


Update: Updated the string for the date format but left the picture.