Getting at the files in an Umbraco package

Jan 12th
2012

What files are in that Umbraco package

As described in my earlier posts we at Twins Solutions, aim for a development environment, that enables automatic creation of deployment artifacts (the files we need to deploy to the server to make thewebsite run). With this aim in mind handling normal Umbraco packages can be a challenge.

Normally an Umbraco package, is added to a website by adding it through the package manager in the Developers section of Umbraco. And until we (maybe) get support for Umbraco packages created as Nuget Packages (it isn't in the roadmap yet), adding an Umbraco package to an Umbraco website is a question of adding the package to a running Umbraco website using the package manager in the Umbraco backend.

There's several drawbacks to using this method.

First: Adding the package using this method, doesn't reveal immediately which files are added to the website, and given the non-existent standards regarding placement of package files, it can be something of a hunt-and-peck experience finding and including all the added files in the VS project. And as you know; unless these files is included in the project they will not be included in the build and deploy proces.

Second: This proces cannot be easily replicated, which means that next time we're adding the same package to another project, we'll have to go through the same proces, as last time. Only this time we might have some kind of file list written down the last time, we did the install.

Third: If we're using TFS as our CVS, we have to be aware of any existing files the installer might try to modify during the package installation, and check these files out before we do the package installation. If we don't do this, the installation might fail since files in the CVS (like web.config for instance) are write protected, when they are not checked out. Even worse the installation might fail silently if the package developer didn't predict this situation, and code his package installation procedure to handle this posssibility.

How to amend this situation

First of all, if you open the zip file containing the package files you are actually able to see the files in the package. This can give you and idea of which files are in the package. Only trouble is that all the files of the package is placed in the root of the zip-file.

To see where the different files is supposed to be placed, and possibly also the real filenames (in some packages the files in the root of the zip-file all have guids for filenames), you need to inspect the file called package.xml. Among other things, this file contains information of the actual name of the files in the root of zip-file, and you can use this information to determine which files is there and where they're supposed to end up.

This can help you find these files. But now we're here, why not just extract the files and add them to the VS project yourself? You could do that - or you could use this little Powershell script I've created that puts the files in the package in their right places using the information in the package.xml file.

function global:Build-UmbracoPackage {
    param($packageFile='.\package.xml')
    [xml]$filesInXml = Get-Content $packageFile
    $filesInXml.umbPackage.files.file | ForEach-Object {
        [string]$guidName = $_.guid
        [string]$newPath = $_.orgPath
        [string]$newName = $_.orgName
        $newPath = $newPath -Replace "/", "\"
        Write-Host ".\$guidName -> .$newPath\$newName"
        if (-not (Test-Path ".$newPath")) {
            md ".$newPath"
        }
        if (-not ($newPath -eq "\")) {
            Copy-Item -Path ".\$guidName" -Destination ".$newPath\$newName"
            Remove-Item -Path ".\$guidName"
        }
    }
}
Set-Alias umbpack Build-UmbracoPackage

About this script: First of all it depends on the zip-file being unpacked into a directory and the command/function is supposed to be run from a powershell command prompt while located in this directory. Second; it is made available by adding this snippet to your profile script before starting the powershell command prompt. Your profile script is usually located in c:\Users\yourname\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 but you can determine where the script is located by typing $profile in a powershell command prompt.

And once this has been run you can actually take the contents of the folders and turn it into your own nuget-package if you want to.

What haven't we handled yet?

At this time we haven't handled the fact that some packages actually does more than just copy files into your Umbraco installation. Some packages actually run custom code, maybe to add some lines to a config file somewhere, or create special database tables using a SQL script.

So in order to get all the way to the goal we have to do some more work. But how we can handle that is a subject for another blog post.