Skip to content

Migrate a Screenplay model to a new version

A Screenplay major version can retire a form. The compiler does not keep the old form working for a while: it reports it as an error whose message names the replacement and the migration that writes it, for example run 'screenplay migrate --from 5 --to 6' (the slots-and-outlets step) to rewrite the model. The migration rewrites the files for you and tells you what it could not decide alone.

Terminal window
screenplay migrate shop --from 5
Migrating 3 files from Screenplay 5 to 6 (1 step: 5→6 slots-and-outlets)
orders.play
5:5 toolbar → toolbar + outlet actions of actions in toolbar
15:5 toolbar actions → outlet actions extends
shell.play
8:3 navigation topbar → outlet topbar of navigation + outlet topbarActions of actions
13:3 navigation sidebar → outlet sidebar of navigation
2 files rewritten · 0 need review · 0 refused

A file the migration does not change - here the third file - is compiled with the others and never written; it is listed only when it still needs review.

A file does not say which version it was written for, so --from is required. Migrations only move forward.

screenplay migrate <file.play|folder> --from <version> [--to <version>] [--dry-run] [--report <file>]

Option Meaning
<file.play|folder> A folder migrates every .play file beneath it as one application. A file migrates that file; the other files of its folder give it its place in the application and are compiled with it, unchanged.
--from <version> The version the files are written in, as a major: 5, 5.11 or v5.11.0 all mean 5. A model written for Screenplay 4 or earlier uses --from 5: no step starts before 5, and such a model writes slots, outlets, navigation regions and toolbars in the forms the 5 → 6 step reads. --from 4 is refused with a message that says so.
--to <version> The version to end at. Defaults to the version the compiler reads.
--dry-run Print what would change and write nothing.
--report <file> Also write the result as JSON: the steps, and for every file its outcome, changes, reviews and the compiler’s remaining errors and warnings, each with its line.
Exit code Meaning
0 Every file was migrated and compiles with the target version without errors.
2 A file needs review: the migration left something for you to decide, or the result still has compiler errors. Every change it could make is written.
1 The migration could not run: an invalid argument, no .play files, no chain of steps between the versions, or a file a step could not rewrite. A file that could not be rewritten is left as it was.

A rewritten file keeps its encoding, a byte order mark included, and its line endings, so the diff shows only the lines the migration changed. Each file is written beside itself first and then replaces the original, so a failed write never leaves half a file. If a file cannot be written, the command stops there, exits 1 and says which files it had already written and which it did not write.

Run it on a clean working tree and read the diff before committing, as with any generated change.

The migration never edits text with search and replace. Each step reads the file with the compiler - which still understands every retired form of the version it migrates from, and keeps what it read in the syntax tree while it reports the form - rewrites the syntax tree, and prints the changed declarations back with the printer. Only the lines a step changes are rewritten. Every other line stays as it was, byte for byte: comments, blank lines, alignment and the comment at the end of a rewritten line.

When the steps have run, the current compiler compiles the result and reports any errors and warnings with the file and line, so you see straight away what still needs attention. It reports what a normal compile reports, the checks that are on by default included - such as PLAY0533 for a State Change command nothing issues. A warning is reported but does not make a file need review; an error does.

Steps chain by version. Migrating from 5 to 7 would run the 5 → 6 step, then the 6 → 7 step, each reading the output of the one before. The runner refuses a gap (no step leaves a version on the way) and an overlap (two steps cover the same version) instead of guessing.

Screenplay: Migrate document migrates the open, saved .play document. It asks for the version the document is written in, runs the migration in the C# compiler over the same bridge as the C# repairs and checks, and replaces the editor text with the result. The change is an ordinary edit: review it, undo it, or save it. What changed and what needs review are written to the Screenplay migration output. The other files of the root are not touched.

The MCP server’s migrate tool takes from, an optional to and an optional root-relative document. It is read-only: it returns the same report as --report and, when you name a document, its migrated source for you to write. An agent can use it to migrate one document, check the reviews and the remaining diagnostics, and write the result through its usual file tools.

Screenplay 6 split what Screenplay 5 called outlets into two things. A slot is a region content is placed in. An outlet is a list of items a layout or template offers - buttons, filters, tabs, stats or destinations - that modules, features and screens change without copying the template. Run:

Terminal window
screenplay migrate <folder> --from 5 --to 6

A Screenplay 4 model migrates the same way, with --from 5.

The slots-and-outlets step rewrites:

Screenplay 5 Screenplay 6 Code
outlet <name> in a component slot <name> PLAY0890
destination outlet <name> in a contribution destination slot <name> PLAY0891
outlet <name> under a navigate to slot <name> PLAY0892
outlet <name> on a layout or template slot <name> PLAY0893
navigation topbar|sidebar on a layout or template outlet topbar|sidebar of navigation, its items as default items and its logo kept; its buttons move to a new outlet topbarActions|sidebarActions of actions PLAY0894
navigation topbar|sidebar extends|inherits|overrides on a module outlet topbar|sidebar extends|inherits|overrides, with its items; its buttons move to outlet topbarActions|sidebarActions with the same mode, the actions outlet the layout’s own region buttons moved to PLAY0894
<slot> contributes <Point> <slot> and outlet <Point> of navigation in <slot> PLAY0895
toolbar <name> on a feature or module outlet <name> extends, with its buttons PLAY0896
a template toolbar slot holding a toolbar <name> or buttons the toolbar slot and outlet <name> of actions in toolbar, its buttons as default items PLAY0026

It leaves for review, with the file and line:

  • A template slot that holds both items and something else, such as a component. The items move to the outlet; the rest stays under the slot, which still does not compile, so you can place it with a screen’s fits or remove it.
  • A toolbar item <name> action|navigate|dialog <Target>. An outlet holds buttons that name a slice; write it as button <name> title "…" slice <Slice> (or default in a template) or remove it.
  • A logo in a module’s navigation region. Only a layout declares the logo.
  • Buttons in a module’s navigation region when no layout in the same file offers outlet topbarActions|sidebarActions of actions. The buttons still move to that outlet, out of the navigation outlet; check that the layout offers it, or move them to the actions outlet it does offer.
  • A mode on a layout’s navigation region, and an outlet the template already declares under the same name.
  • A line in a navigation region that is neither an item, a button nor a logo.

Every sample as it was in Screenplay 5.11 migrates to warning-free Screenplay 6 with nothing to review; the specifications in Source/DotNET/Screenplay/Migrations hold the migration to that and to a before-and-after fixture for every row above.

Screenplay 6 also reports a State Change command nothing issues (PLAY0533) in every model check, without --check. A --check PLAY0533 or a validation gate that names it does not need changing: the code is still accepted and still selects input-surfaces, as it did in Screenplay 5. See Completeness checks.

The TypeScript compiler reports the Screenplay 5 forms with the same messages, but does not migrate: the migration runs in the C# compiler, behind the CLI, the MCP tool and the VS Code command.

A step is a class in the compiler that implements IScreenplayMigration and has a public parameterless constructor; the runner finds it by convention.

public class SlotsAndOutlets : IScreenplayMigration
{
public ScreenplayVersion From => 5;
public ScreenplayVersion To => 6;
public MigrationName Name => "slots-and-outlets";
public MigrationResult Apply(DocumentSyntax document)
{
// Read document.Syntax - retired forms included - and return the rewritten tree,
// a MigrationChange per change with the edits that print it, and a MigrationReview
// for anything an author has to decide.
}
}

A change carries edits that say which source lines the rewritten nodes replace: ReplaceLine, InsertAfterBlock, MoveBlock and RemoveLine. The runner prints the nodes and applies the edits, refusing two edits to one line. To run migrations from your own code, use ScreenplayMigrator: Plan(from, to) chains the steps, MigratePath and Migrate return a MigrationReport without writing anything.