Why does Register-SitecoreInstallExtension appear to do nothing?

Question

I'm making my first attempt at extending SIF, and I don't seem to be able to register a new Task correctly. Can anyone suggest what I'm doing wrong here?

I've create a new script commandlet. It has the following contents:

function Invoke-SolrInstallTask
{
    [CmdletBinding(SupportsShouldProcess=$true)]
    param(
        [parameter(Mandatory=$true)]
        [string]$solrVersion = "6.6.2",

        #
        # more declarations
        #
    )

    PROCESS
    {
        #
        # Code for the task...
        #
    }
}

Export-ModuleMember -Function Invoke-SolrInstallTask

That file is saved as Invoke-SolrInstallTask.psm1 in my user's module folder at

C:\Users\<myUser>\Documents\WindowsPowerShell\Modules\Invoke-SolrInstallTask\

Calling

Import-Module Invoke-SolrInstallTask

appears to work, and a subsequent call to Get-Module shows that PowerShell has registered my function as a script:

If I try to run my commandlet directly it appears to work ok. So then I call:

Register-SitecoreInstallExtension Invoke-SolrInstallTask -As SolrInstall -Type Task

That generates no output.

I can see from the SIF that documentation that Get-SitecoreInstallExtension only returns references to standard tasks, unless you call it passing a configuration file.

My solr.json config file contains (amongst other stuff) a block that tries to use the custom task:

"Tasks" : {
    "PerformSolrInstall": {
        "Type": "SolrInstall",
        "Params": {
            "solrVersion": "[parameter('SolrVersion')]"
        }
    }
}

But despite that Get-SitecoreInstallExtension .\solr.json never returns any reference to my task:

And unsurprisingly, if I try to run that custom config I get an error:

I'm guessing there's some other bit of "how to register a custom task" that I've failed to find in the documentation. Any suggestions what it is?

Answer 1

It's a small thing which I'm hoping to have fixed soon so that things are a little clearer, sorry this isn't as straight-forward as it should be!

Calling Register-SitecoreInstallExtension outside of a running install does nothing as there is no context for it to operate in. The function actually sets information in a dictionary when the install itself imports the function.

I'll be addressing this in the next release by outputting an appropriate message rather than silence.

To actually enable functions to be registered correctly do the following:

1. Create your psm1 file (e.g. MySifExtensions.psm1)
2. For each function in there that you want SIF to use, call Register-SitecoreInstallExtension in the psm1
3. In the configuration, include the path to the module

So your MySifExtension.psm1 looks like this

function Invoke-SolrInstallTask{ <# implementation #> }
Register-SitecoreInstallExtension -Command Invoke-SolrInstallTask -As SolrInstall -Type Task

Then in your configuration file:

"Parameters" : {},
"Variables": {},
"Tasks": {},
"Modules" : [
  'path to module'
]

With the module path, either specify the full path or the path relative to the configuration file. If the module is available by name when calling Import-Module you can specify just the name of the module.

You can get embedded help on the topic of extending by running:

Get-help about_SitecoreInstallFramework_Extending -ShowWindow

Alternatively, check out the documentation on configuring and extending sif here: https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/90/Sitecore_Experience_Platform_90_Initial_Release.aspx#