Developing modules, shell commands

Before going forward, some definitions:
  • Module is an assembly having a set of shell commands.
  • Shell command is a derived class of Comkarl.Restful.Shell.External.ShellCommand. A shell command is the target of a command text like hello-world @arg "Matías Fidemraizer". Callers will call your command using its command text which is mapped to your so-called class.

In order to continue reading, please be sure you have installed:
  • Visual Studio 2010 or later.
  • .NET Framework 4.0 or later.
  • Visual C# 4.0 or later.
  • Restful Framework Toolkit (go to this page download section!).

Your very first shell command!

Now open a Visual Studio instance, create a new project using "Restful Framework · Command module" template.

Once project generation finished, check if "Restful Sdk toolbar" is enabled (if it is disabled, enable it!).

In solution explorer go to Add new item and create one using Restful Framework · Command item template.

Ok, now you have created a basic shell command like this:

using Comkarl.Restful.Shell.External;

namespace SomeNamespace
     public sealed class VeryFirstCommand : Comkarl.Restful.Shell.External.ShellCommand
        public override void Execute(ShellResponse response)

This is the basic structure of a Restful Framework shell command:
  • A regular class declaration with ShellCommandNameAttribute giving a command name.
  • Regular class inherits ShellCommand from Comkarl.Restful.Shell.External.dll.
  • ShellCommand.Execute(ShellResponse) override.

So... ok, but what is next??

Just develop like any other C# and .NET project.

But, anyway, maybe you would like to know shell commands support input arguments and these are regular class properties using ShellCommandArgumentAttribute:

public string Text { get; set; }

Above code would mean that your very first shell command would be called this way from a client or other service:

very-first-command @text "my whole text"

Imagine you want to just return the text held by @text to the caller. You need to play with ShellResponse object given by ShellCommand.Execute method.

ShellResponse has a dynamic-typed Data property. You just need to set an object to this property:

response.Data = new { ResponseText = Text };

Since Restful Framework serializes ShellResponse into a standard JSON string, you do not need to do any further step to return @text argument text to the caller. So easy!.

Now try to build your Visual Studio project and open its Bin\Debug folder. In addition to project's assembly DLL and dependencies, you are going to find a ZIP file called the same way as your project name. This is the shell command module package generated during project build.

If you open it, you will find at least one file: project's assembly DLL.

Command module packages are the ones you will need if you want to install your command modules in Restful Framework cloud server!

Adding custom content and dependencies to command module package

Usually projects need satellite assemblies, dependencies, configuration files, data files, images.... And command module packages support packaging everything inside itself in a single file.

In the root of a project created with "Restful Framework · Command module" project template you are going to find a file called ModuleContents.config.

This file defines which files are going to be included in the command module package.

Steps for adding new files:
  1. Add a new XML item as child of ItemGroup like this: <ShellModuleContent Include="" />.
  2. Provide FULL physical path to the file as Include attribute value.
  3. Save ModuleContents.config file.
  4. Build project.

ModuleContents.config file is a Microsoft Build project file and it is called during Visual Studio command module project build, meaning you can use regular Microsoft Build syntax, properties and items in order to get directory paths to your project.

Currently because of some tooling limitations, module content must be placed in the target dir (for example, \Bin\Debug). *Be sure to set your file properties to "Build Action -> Copy always".

For example, a file called "MyPicture.jpg" in your command module project would be added this way:

<ShellModuleContent Include="$(TargetDir)MyPicture.jpg" />

Last edited Jul 22, 2012 at 3:17 PM by MFidemraizer, version 2


No comments yet.