en-US/about_Rivet_Plugins.help.txt
|
TOPIC
about_Rivet_Plugins SHORT DESCRIPTION Explains the Rivet plug-in system LONG DESCRIPTION Rivet plug-ins allow users to modify migration operations or perform other work before and after an operation is applied to a database. 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. There are two plug-in points: before an operation is applied to a database and after an operation is applied to a database. 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.') To enable plug-ins, you need to configure Rivet so it knows where to look for them. Set the `plug-insRoot` option to the directory path where you want to put your plug-ins. For example, { "SqlServerName": "example.com\Rivet", "DatabasesRoot": "Databases", "PluginsRoot": "Tools\\Rivet\\Plugins" } Paths in rivet.json files are relative to the rivet.json file. See `about_Rivet_Configuration` for more information. Once you've defined your plug-ins directory, you create the plug-in scripts. To run code *before* an operation is applied to database, create a `Start-MigrationOperation.ps1` script in your plug-ins directory. It should look like this: function Start-MigrationOperation { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [Rivet.Migration] # The migration the operation is part of. $Migration, [Parameter(Mandatory=$true)] [Rivet.Operation] # The operation which is about to be applied. $Operation ) Set-StrictMode -Version 'Latest' # Your plug-in logic goes here. } To run code *after* an operation is applied to a database, create a `Complete-MigrationOperation.ps1` script in your plug-ins directory. It should look like this: function Complete-MigrationOperation { [CmdletBinding()] param( [Parameter(Mandatory=$true)] [Rivet.Migration] # The migration the operation is part of. $Migration, [Parameter(Mandatory=$true)] [Rivet.Operation] # The operation which was just applied. $Operation ) Set-StrictMode -Version 'Latest' # Your plug-in logic goes here. } Rivet ships with some sample plug-ins. Look in the `Extras` directory. Each plug-in should have two parameters: the first is a `Rivet.Migration` object representing the migration getting run. The second is a `Rivet.Operation` object representing the specific operation getting run. Each plug-in will get called for each operation in a migration. You'll get the same migration object for each operation in that migration. Each operation in Rivet is represented by a unique C# object that you can modify. You can't remove operations from being run. Instead, throw an exception to reject the operation. You are allowed to run additional operations and/or return additional C# operation objects. See the sample plug-ins in the Extras directory that ships with Rivet. SEE ALSO about_Rivet about_Rivet_Configuration about_Rivet_Intellisense about_Rivet_Migrations |