Create your own package fragment installer

When installing a package, you may need to ensure some additional requirements to be met and / or some additional operations performed. You can do this by using your own package fragment installer.

There are two abstract classes for this:

• BasePackageFragmentInstaller
• BasePackageFragmentUninstaller

Each class has the Validate method you need to implement. This is where you should check for prerequisites on the website etc before installing or uninstalling something.

Besides, BasePackageFragmentInstaller has the Install method and BasePackageFragmentUninstaller - the Uninstall method, which you should implement, too. This is where you add your installing and uninstalling code respectively.

Please note that the Validate method is called before Install or Uninstall method.

If your package fragment installer is configurable via install.xml, learn how to read its configuration programmatically. If you need information about the package being installed, find out how to get it in your code.

Creating a fragment installer

To create a custom fragment installer:

1. Create a class library project in Visual Studio.
2. Add a reference to Composite.dll.
3. Create a installer class and inherit it from the abstract class BasePackageFragmentInstaller.
4. Implement the  BasePackageFragmentInstaller class. This will add two methods:
   1. Validate: Add your validating code here
   2. Install: Add your installing code here

For simplicity's sake we will only add a logging information to these two methods in the sample below:

using System;
using System.Collections.Generic;
using Composite.Core; // logging
using Composite.Core.PackageSystem.PackageFragmentInstallers;


namespace Demo
{
    public class FancyPackageFragmentInstaller : BasePackageFragmentInstaller
    {
        public override IEnumerable<System.Xml.Linq.XElement> Install()
        {
            Log.LogInformation("Fancy Installer", "Installing a package");
			// installation code goes here
            yield break;
        }

        public override IEnumerable<Composite.Core.PackageSystem.PackageFragmentValidationResult> Validate()
        {
            Log.LogInformation("Fancy Installer", "Validating the installation requirements");
			// validation code goes here
            yield break;
        }
    }
}

You can extend this code adding the logic you need making use, among other things, of C1 CMS API. For example, in your Validate method, you can make sure that some data types should be created or check for a specific package of a specific version to have been already installed in C1 CMS.

If necessary, create your own fragment uninstaller:

1. Create a unistaller class and inherit it from the abstract class BasePackageFragmentUninstaller.
2. Implement the  BasePackageFragmentUninstaller class. This will add two methods:
   1. Validate: Add your validating code here
   2. Uninstall: Add your uninstalling code here

Again, for he simplicity's sake we will add a logging information to these two methods:

using System;
using System.Collections.Generic;
using Composite.Core; // logging
using Composite.Core.PackageSystem.PackageFragmentInstallers;


namespace Demo
{
	public class FancyPackageFragmentUninstaller : BasePackageFragmentUninstaller
    {
        public override void Uninstall()
        {
            Log.LogInformation("Fancy Installer", "Uninstalling a package");
			// uninstallation code goes here
        }

        public override IEnumerable<Composite.Core.PackageSystem.PackageFragmentValidationResult> Validate()
        {
            Log.LogInformation("Fancy Installer", "Validating the uninstallation requirements");
			// validation code goes here
            yield break;
        }
    }

}

Finally, build the project.

Using a fragment installer

To add the custom fragment installer to a CMS Package, you need to:

1. Add the installer DLL to the package
2. Add a step in the package's install.xml to pre-load this DLL.
3. Add a step in install.xml that calls the fragment installer.

We assume that our custom package fragment installer is called "Demo.FancyPackageFragmentInstaller" contained in the assembly called "FancyInstaller".

1. Create the folder /Bin in the package (if the former doesn't exist).
2. Copy your FancyInstaller.dll in there.
3. Edit install.xml.
4. Within the mi:PackageFragmentInstallerBinaries element, add the path to DLL:
   
   

   <mi:PackageFragmentInstallerBinaries>
   	<mi:Add path="~\Bin\FancyInstaller.dll" />
   </mi:PackageFragmentInstallerBinaries>

5. Within the mi:PackageFragmentInstallers element, add the installer and uninstaller types:
   
   

   <mi:PackageFragmentInstallers>
   	<mi:Add 
   		installerType="Demo.FancyPackageFragmentInstaller, FancyInstaller" 
   		uninstallerType="Demo.FancyPackageFragmentUninstaller, FancyInstaller" />
   </mi:PackageFragmentInstallers>

6. Save the changes in the package (repack it).

(Download the sample package with Demo.FancyPackageFragmentInstaller.)

Installing the package

You can install the package locally.

When the package with our simplistic fragment installer is installed, two logging messages will appear in the log.

Likewise, you'll see two logging messages when uninstalling the package.