Converting Older Canvas Screens

Canvas supports pre-compiled assemblies. These files are embedded within the screen or object to allow for faster load time. To support this feature the Canvas screen format has been modified and the screen version incremented.

Pre-v9.5 Canvas screens used a script format that is incompatible with Canvas v9.5. When you open a pre-v9.5 screen in Canvas v9.5 the application will convert the screen to an updated script format, and then permanently apply the new format when you save the screen in Canvas v9.5. In Canvas, a Script Change Pending message will warn you of the pending change. Older screens opened in Canvas View or Canvas View Lite will be converted on the fly, but not saved with the new format.

Script Change Pending dialog box

If you have a lot of older screens to convert, a CLI-based utility, CanvasFileConverter, is available to convert multiple Canvas screens to the updated script format.

Older screens are converted on the fly, but are limited to just the selected screen. If the selected screen includes Canvas objects or other nested screens that contain script, those will not be automatically converted during the open operation. To ensure all screens are converted, be sure to open any screen dependencies prior to opening the parent screen or use the bulk conversion utility, described below.

Custom Canvas Controls

Note the following about custom Canvas controls:

• If your older screen contains a custom Canvas control, the control assemblies must be compiled against the v9.5 Canvas binaries before attempting to convert the screen to the new script format. Any screen that makes use of a custom Canvas control will fail to convert if the control is not first updated to the latest version of Canvas.
• Depending on where the CanvasFileConverter is being executed, the custom control assemblies need to be placed in the same folder. While Canvas currently allows for the custom control assemblies to reside in custom folders or subfolders, the CanvasFileConverter requires that the control assemblies be located in the same directory—along with all the Canvas and CygNet support binaries, typically CygNet\Bin.

CanvasFileConverter Utility

A command-line-interface utility, CanvasFileConverter, is available to bulk convert multiple Canvas screens to the updated script format, and save a copy of the original files as a backup.

The CanvasFileConverter utility requires an input file that must be prepared in advanced of running the utility. The input file tells the utility the path to the file names of the screens to be converted. The input file can include a list of files, or a list of folders that contain the files. The utility supports converting files stored in a BSS, or in a local or network Windows file-system folder.

To bulk convert screens via command-line

1. Prepare the input file. See the parameters described below.
2. Open a Command Prompt window.
3. Navigate to the directory where the CanvasFileConverter application is installed.
4. Optional. Type canvasfileconverter and press Enter to see user assistance for the utility, for example:

   C:\CygNet\Bin>canvasfileconverter

5. Type the desired command(s) using the syntax described below.

Usage

CanvasFileConverter [-svc:<site.service>] [-files:<input file path> || -folders:<input file path>] [-topDirectoryOnly] [-backupPath:<path>]

 

Parameters

Some parameters require additional data; follow each parameter with :additional data. See Usage and the examples for each parameter for more information.

Parameter	Required	Description
-svc	no	Specify the name of the BSS hosting the files to be converted in site.service format. If no service is specified, the file or folder names are assumed to be in a local or network Windows file-system folder. Do not use slashes in the path, e.g., <site.service>\ or \\<site.service>\. Example CanvasFileConverter -svc:CYGNET.BSS -folders:C:\temp\InputFoldersBSS.txt
-files || -folders	yes	Specify the name of an input file containing file names or folder names. The format of the input file differs for files and folders, local or BSS-based: -files — For files, the input file lists the names of the individual .can and .cob files to be converted. -folders — For folders, the input file lists the names of the folders that contain the .can and .cob files to be converted. By default, all valid .can and .cob files within the specified folders and any related subfolders will be converted. See the -topDirectoryOnly parameter to limit folders. Also note: If specifying a path to local files or folders, a fully qualified path is required. If specifying a path to BSS-based files or folders, the name of the <site.service> is specified in the -svc parameter. Examples Input File Specifying Local Files CanvasFileConverter -files:C:\temp\InputFilesLocal.txt Input File Specifying Local Folders CanvasFileConverter -folders:C:\temp\InputFoldersLocal.txt Input File Specifying BSS-based Files CanvasFileConverter -svc:CYGNET.BSS -files:C:\temp\InputFilesBSS.txt Input File Specifying BSS-based Folders CanvasFileConverter -svc:CYGNET.BSS -folders:C:\temp\InputFoldersBSS.txt
-topDirectoryOnly	no	By default, the converter will recursively find all .can and .cob files in all subfolders specified in the -folders parameter. Include the -topDirectoryOnly parameter to limit conversion to only the directory specified. Example CanvasFileConverter -folders:C:\temp\InputFoldersLocal.txt -topDirectoryOnly
-backupPath	no	Specify a local path to a backup location for the original files that have been converted. Backups will never be written back to the hosting BLOB service. If a -backupPath is not specified, a new folder, named "Originals", will be created at the same path as specified in the -files or -folders parameter. Example CanvasFileConverter -files:C:\temp\InputFilesLocal.txt -backupPath:D:\CONVERTER\SCREENS\BACKUPS