Anatomy of an Umbraco package


I shall use the “Zip upload” package by Tim Geyssens in order to illustrate how I understand a package is put together and wired up in Umbraco. First of all, download the package and look inside the zip file. Then look in the folder “54928f6f-5b64-48fc-9128-864dde7d16f3” which should contain the following files:

  • Nibble.Umb.ZipUpload.dll
  • package.xml
  • zipupload.ascx
  • zipUpload.config

Nibble.Umb.ZipUpload.dll

This file contains all of the “logic” for the application. This file does all the processing needed on the server side.

package.xml

I believe this is generated by Umbraco when creating a new package and isn’t something one should be concerned about too much.

zipupload.ascx

This contains the presentational elements of the application.

zipUpload.config

Contains configuration setting used the application.

The example above contains a very specific case but in general an Umbraco package will contain a .dll file, a presentation file e.g. aspx, a package.xml file and other optional files e.g. a config file.

Now, when such a package is installed, what I have so far found to happen is that, the package.xml is copied into a sub-folder with a GUID like name within the App_Data folder. Moreover, two config files are modified namely \App_Data\packages\installed\installedPackages.config and \config\Dashboard.config.

In the first file, the following got inserted within the “packages” section

<package id=”1″ version=”1.0″ url=”” name=”Zip Upload” folder=”e519344a-a1fe-4239-9271-d65a088c77dc” packagepath=”” repositoryGuid=”” packageGuid=”” hasUpdate=”False”>
<author url=”http://www.nibble.be”>Tim Geyssens</author>
<readme><![CDATA[Small dashboardcontrol that allows to upload a zip file to the media section of umbraco. All files in the zip get created as media items.]]></readme>
<actions>
<Action runat=”install” alias=”addDashboardSection” dashboardAlias=”MyDashboardSection”>
<section>
<areas>
<area>media</area>
</areas>
<tab caption=”Zip Upload”>
<control>/usercontrols/zipupload.ascx</control>
</tab>
</section>
</Action>
</actions>
<datatypes>
</datatypes>
<content nodeId=”” loadChildNodes=”False”>
</content>
<templates>
</templates>
<stylesheets>
</stylesheets>
<documenttypes>
</documenttypes>
<macros>
</macros>
<files>
<file>/bin/Nibble.Umb.ZipUpload.dll</file>
<file>/config/zipUpload.config</file>
<file>/usercontrols/zipupload.ascx</file>
</files>
<languages>
</languages>
<dictionaryitems>
</dictionaryitems>
<loadcontrol>
</loadcontrol>
</package>

<package id=”1″ version=”1.0″ url=”” name=”Zip Upload” folder=”e519344a-a1fe-4239-9271-d65a088c77dc” packagepath=”” repositoryGuid=”” packageGuid=”” hasUpdate=”False”>    <license url=”http://www.opensource.org/licenses/mit-license.php”>MIT license</license>    <author url=”http://www.nibble.be”>Tim Geyssens</author>    <readme><![CDATA[Small dashboardcontrol that allows to upload a zip file to the media section of umbraco. All files in the zip get created as media items.]]></readme>    <actions>      <Action runat=”install” alias=”addDashboardSection” dashboardAlias=”MyDashboardSection”>        <section>          <areas>            <area>media</area>          </areas>          <tab caption=”Zip Upload”>            <control>/usercontrols/zipupload.ascx</control>          </tab>        </section>      </Action>    </actions>    <datatypes>    </datatypes>    <content nodeId=”” loadChildNodes=”False”>    </content>    <templates>    </templates>    <stylesheets>    </stylesheets>    <documenttypes>    </documenttypes>    <macros>    </macros>    <files>      <file>/bin/Nibble.Umb.ZipUpload.dll</file>      <file>/config/zipUpload.config</file>      <file>/usercontrols/zipupload.ascx</file>    </files>    <languages>    </languages>    <dictionaryitems>    </dictionaryitems>    <loadcontrol>    </loadcontrol>  </package>

while in the second config file the following was added into the “dashboard” section

<section>

<areas>

<area>media</area>

</areas>

<tab caption=”Zip Upload”>

<control>/usercontrols/zipupload.ascx</control>

</tab>

</section>

The latter XML is presumably populated because in package.xml, there is a section which is as follows:

<Actions>

<Action runat=”install” alias=”addDashboardSection” dashboardAlias=”MyDashboardSection”>

<section>

<areas>

<area>media</area>

</areas>

<tab caption=”Zip Upload”>

<control>/usercontrols/zipupload.ascx</control>

</tab>

</section>

</Action>

</Actions>

When the application is uninstalled, the added package section in the first config file is deleted but the section within the dashboard nodes remains. Hence, that is why when after the uninstallation of the application, there is the following error message:

Could not load control: ‘/usercontrols/zipupload.ascx’. 
Error message: System.Web.HttpException (0x80004005): The file ‘/usercontrols/zipupload.ascx’ does not exist. at System.Web.Compilation.BuildManager.GetVPathBuildResultInternal(VirtualPath virtualPath, Boolean noBuild, Boolean allowCrossApp, Boolean allowBuildInPrecompile, Boolean throwIfNotFound, Boolean ensureIsUpToDate) at System.Web.Compilation.BuildManager.GetVPathBuildResultWithNoAssert(HttpContext context, VirtualPath virtualPath, Boolean noBuild, Boolean allowCrossApp, Boolean allowBuildInPrecompile, Boolean throwIfNotFound, Boolean ensureIsUpToDate) at System.Web.Compilation.BuildManager.GetVPathBuildResult(HttpContext context, VirtualPath virtualPath, Boolean noBuild, Boolean allowCrossApp, Boolean allowBuildInPrecompile, Boolean ensureIsUpToDate) at System.Web.UI.TemplateControl.LoadControl(VirtualPath virtualPath) at umbraco.cms.presentation.dashboard.OnInit(EventArgs e)

when clicking on the “Media” folder within the “Media” section. Hence deleting the “offending”

<section>

<areas>

<area>media</area>

</areas>

<tab caption=”Zip Upload”>

<control>/usercontrols/zipupload.ascx</control>

</tab>

</section>

code causes the error to disappear.

I am only starting to unravel how Umbraco deals with the packages and I might be totally wrong but I’ll try to edit and add any information I find out.

Two files which might be of interests are createdPackages.config and installedPackages.config found in \App_Data\packages and they should be self-explanatory :).

Advertisements
Tagged with:
Posted in package, Umbraco blogs

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: