OpenWrap Shell

#The OpenWrap shell (o.exe)

Introduction

The shell is responsible for finding a bootstrap class in a package that will handle the actual execution of commands, optionally downloading missing packages as needed.

To do this, the shell scans the current directory and it's parents for a child directory containing .wrap files. When one is found, the shell attemps to locate the openwrap package. If you re-use the bootstrapper, you can specify your own entry-point package by name.

The shell will then resolve any dependent packages, and select whatever latest version of each is specified. It's important to note that the shell ignores any dependency version identifiers and always picks the latest version.

Once all packages are loaded, assemblies in each of the scanned folders will be scanned for a type with a name ending in Runner containing one of two methods.

The first is a static method named Main and accepting an IDictionary<string,object> that describes the current environment (location of the system repository, current directory, command line and bootstrapped packages). This is what OpenWrap 1.1 uses.

The second is a static method also called Main, but accepting an array of strings and returning an int. This is what OpenWrap 1.0 used, and is no longer the recommended entrypoint to use. In this mode, the shell also tries to locate a SetSystemRepositoryPath static method taking the full path to the system repository path (as defined by the -SystemRepositoryPath input, see below).

As part of this loading process, all assemblies in the dependency chain will be pre-loaded in the LoadFrom context.

The Main method (1.1 and above)

The Main method of the bootstrapper receives an IDictionary<string,object> containing all the environment information needed for proper initializations.

Those are the values currently passed by the environment:

• openwrap.syspath string legacy the system repository path (by default `%LOCALAPPDATA%\openwrap\wraps). OpenWrap >= 2.0.3 does not support redirecting that folder and probably won't until 2.1.
• openwrap.sysroot string (openwrap-shell > 2.1.1) the location of OpenWrap's system installation (by default '%LOCALAPPDATA%\openwrap)
• openwrap.cd string the current directory
• openwrap.shell.commandline string the full command line that was passed to the openwrap shell
• openwrap.shell.assemblies IEnumerable<string> the full paths of all assemblies located and pre-loaded by the shell
• openwrap.shell.version string The version of the shell used to load the
• openwrap.shell.args IEnumerable<string> the list of arguments the shell has already consumed

Shell 1.0 behavior

The behavior of the first version of the shell is important to describe if you're going to have packages being bootstrapped from both the old (1.0) and the new (1.1) version of the shell.

In the 1.0 times, the shell is not scanning for dependent assemblies, and only knows about legacy method signatures (static int Main(string[] args)).

Furthermore, the method itself will only be found in an assembly that has the same name as the first package name passed to the BootstrapRunner constructor.

This means that if you use the 1.0 shell to launch code, and you construct the BootstrapRunner instance with a package name of mycompany-myEntrypoint, the assembly will need to be named mycompany-myEntrypoint.dll.

Return status codes

The shell returns certain status codes that can help you diagnose the reason for a failure.

• Zero or above: the command completed
• -1: An unknown error occurred while running the command (usually an unhandled exception)
• -10: Unknown command
• -50: The command returned an error
• -100: An unknown error occurred while installing the shell
• -200: No entrypoint found
• -250: A new version of the shell is required to run the entrypoint package.

Shell inputs

The OpenWrap shell lets you specify certain command inputs.

-InstallHref http://server.com

Specifies the name of the server used for retrieving initial packages at installation time.

-SystemRepositoryPath c:\path\to\systemrepository

legacy Specifies the system repository to use. Usually used for testing the behavior of the shell without uninstalling your system repository. Versions of the shell > 2.1.1 will not accept that parameter anymore.

-SystemPath c:\path\to\sysroot

Path where OpenWrap stores all its data.

-ProxyHref http://proxy:port

The shell normally uses the system-defined proxy to install itself. If you need a custom proxy, you can use the ProxyHref input to change the proxy address.

-ProxyUsername username (or DOMAIN\username)

The username to use for the proxy. If missing, the credentials for the current user are used.

ProxyPassword password

The password to use for the proxy.

-ShellInstall (None|Install|UseCurrent)

Specifies what to do if the shell is not installed. Accepts the following value:

• None: Does nothing and uses the current executable
• Install: Installs the shell to the default location
• UseCurrent: Uses the shell from the current location and registers it.

-ShellPanic

This is when your system repository has a version of OpenWrap that stopped working and you want to force a redownload and an overwrite of any package you have in your system repository. Use for when things go bad.

-UseSystemVersion

Enables the system repository version of OpenWrap to be used instead of the project repository (if present).