en-US/about_Rivet_Plugins.help.txt

TOPIC
    about_Rivet_Plugins
 
SHORT DESCRIPTION
    Explains the Rivet plug-in system.
 
LONG DESCRIPTION
 
    ## Why Plugins?
 
    Rivet plug-ins allow users to modify migration operations or perform other
    work when Rivet loads them from your migration scripts. You can also write
    your own operatons. Examples include:
 
     * Validating that all tables/columns have descriptions.
     * Automatically adding created and last updated columns to each new table.
     * Validating that any raw SQL doesn't include a `USE` statement.
     * Preventing certain operations from being used, e.g. `Rename-Column`.
     * Customizing constraint and index names.
      
    Plugins and custom operations should be packaged into one or more PowerShell
    modules. Use the "PluginPaths" configuration option in your rivet.json file
    to tell Rivet where it can find these modules. It imports the modules using
    the `Import-Module` cmdlet. If you want to import the modules, set the
    "PluginModules" setting to a list of modules that contain your plug-ins. If
    the modules listed in "PluginModules" aren't loaded when Rivet runs, Rivet
    will fail with an error.
 
    To create custom operations, export them from your PowerShell module.
 
    To create custom plugins, create a function and add the `Rivet.Plugin`
    attribute to that function. The constructor for that attribute takes in the
    event to which your plugin will respond.
 
    Rivet ships with a sample PowerShell module that contains plug-ins that you
    can use as a basis for writing your own. See the `RivetSamples` directory.
 
    ## Events
 
    Rivet has these events:
 
    * BeforeOperationLoad
    * AfterOperationLoad
    * AfterMigrationLoad
 
    ### BeforeOperationLoad
 
    #### Overview
 
    The `BeforeOperationLoad` event occurs before each operation is loaded from
    your migration script. Use this event to modify your operation before it is
    executed against your database, or to return custom operations you want to
    run *before* a specific operation.
 
    It gets passed two parameters: `Migration`, which is the migration object
    currently being loaded and `Operation`, the operation that is about to
    be loaded (i.e. saved into Rivet's internal store for later execution).
 
    Plugins that respond to this event *must* have `Migration` and `Operation`
    parameters.
 
    #### Example
 
    This code demonstrates an empty plugin that responds to the
    `BeforeOperationLoad` event.
 
        function Invoke-MyPlugin
        {
            [CmdletBinding()]
            [Rivet.Plugin([Rivet.Events]::BeforeOperationLoad)]
            param(
                [Parameter(Mandatory)]
                [Rivet.Migration]$Migration,
 
                [Parameter(Mandatory)]
                [Rivet.Operations.Operation]$Operation
            )
 
            # Do stuff.
        }
 
    ### AfterOperationLoad
 
    #### Overview
 
    The `AfterOperationLoad` event occurs after an operation is loaded and saved
    to Rivet's internal store for later execution. Use this event to modify the
    operation before it gets applied, or to add additional operations that you
    want to run *after* a specific operation.
 
    These plugins get passed two parameters `Migration`, which is the migration
    object currently being loaded and `Operation`, the operation that just got
    loaded.
 
    Plugins that respond to this event *must* have `Migration` and `Operation`
    parameters.
 
    #### Example
 
    This code demonstrates an empty plugin that responds to the
    `AfterOperationLoad` event.
 
        function Invoke-MyPlugin
        {
            [CmdletBinding()]
            [Rivet.Plugin([Rivet.Events]::AfterOperationLoad)]
            param(
                [Parameter(Mandatory)]
                [Rivet.Migration]$Migration,
 
                [Parameter(Mandatory)]
                [Rivet.Operations.Operation]$Operation
            )
 
            # Do stuff.
        }
 
    ### AfterMigrationLoad
 
    #### Overview
 
    The `AfterMigrationLoad` event occurs after all operations in a migration
    have been applied, but before the transaction has been commited. Use this
    event for any validations that require a fully loaded migration.
 
    These plugins get passed the `Migration` parameter which is the migration
    object currently being loaded.
 
    Plugins that respond to this event *must* have the `Migration` parameter.
 
    #### Example
 
    This code demonstrates an empty plugin that responds to the
    `AfterMigrationLoad` event.
 
        function Invoke-MyPlugin
        {
            [CmdletBinding()]
            [Rivet.Plugin([Rivet.Events]::AfterMigrationLoad)]
            param(
                [Parameter(Mandatory)]
                [Rivet.Migration]$Migration
            )
 
            # Do stuff.
        }
 
    ## Cancelling a Migration
 
    In order to cancel a migration, a plug-in *must throw an exception*. For
    example,
 
        throw ('Operation is invalid: all tables are required to specify a description. Use the -Description parameter to document this table''s purpose.')
     
    ## Loading Your Plug-ins
 
    Use Rivet's `PluginPaths` setting (in your rivet.json file) to tell Rivet
    where it can find the module(s) that contain your plug-ins. When Rivet runs,
    it will run `Import-Module` on each of these paths. Make sure each path
    points to a directory, .psd1 file, or .psm1 file.
 
        {
            "SqlServerName": ".",
            "DatabasesRoot": "Databases",
            "PluginsPath": "Tools\\Rivet\\RivetSamples"
        }
 
    The paths should be relative to the rivet.json file. Wildcards are
    supported.
 
     
SEE ALSO
    about_Rivet
    about_Rivet_Configuration
    about_Rivet_Intellisense
    about_Rivet_Migrations