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 |