HiveSharp

Easy-peasy C# based scripting environment for your everyday tasks

Home | Download | Documentation | Donate

Scripting runtime reference

You can run any .NET 4.5 compatible code as part of HiveSharp modules in compliance with the execution rules and syntax extensions of CSScript. Consequently .NET Framework 4.5 is a requirement to install and run HiveSharp. It's preinstalled by default on Windows 8.0 and later versions, and can be installed via Windows Update or manually on Windows Vista and above.

Entry point methods

While support for C# code and libraries is extensive and all-encompassing in HiveSharp, there are certain restrictions specifically around the methods that serve as entry points and can be directly executed by HiveSharp. For a method to be an eligible entry point, it has to conform to the following rules:

Be contained in a public static class
Be public and static itself
Take only parameters of the supported types (see below), or none at all

There are no restrictions on contents of entry point methods or their return types, although a return type of bool will be directly interpreted as an indicator of success or failure of the respective method.

Internal methods in a module can have any valid C# signature. At the same time, as explained above, entry point methods can only have parameters of specific data types, if any. The supported entry point parameter data types are:

All built-in types with the exception of decimal, char and object
Enumerations, including those declared in the module itself

Metadata

In order to provide more information about objects in a module such as classes, methods or parameters, as well as modules themselves, you can use special attributes provided by the HiveSharp runtime. This extra metadata can be displayed in the HiveSharp UI to make script information more human-readable, as well as used by the HiveSharp engine to enforce constraints on arguments passed to methods. All attributes mentioned here can be found in the HiveSharp.Runtime namespace.

PublishAttribute, customarily appearing in code as simply Publish in accordance with the C# convention, allows you to attach a human readable title and description to an entity in the code and can be applied to a module (assembly), a class, a method or a parameter. The command line interface of HiveSharp will refuse to process any entities without this attribute unless supplied with the --allowUnpublished (--u) argument. You can find out more about the command line interface here.

namespace HiveSharp.Runtime
{
    [ AttributeUsage(AttributeTargets.Assembly | AttributeTargets.Module |
      AttributeTargets.Class | AttributeTargets.Method | AttributeTargets.Parameter) ]
    public class PublishAttribute : Attribute
    {
        public PublishAttribute() { }
        public PublishAttribute(string title, string description)
        {
            Title = title;
            Description = description;
        }

        public string Title { get; set; }
        public string Description { get; set; }
    }
}

ValuesAttribute (or Values for short) is applicable to parameters of entry point methods. It allows you to specify constraints on values that can be passed as an argument for a given parameter. HiveSharp will prevent execution of any entry point method if the arguments supplied are not conformant with declared constraints such as range, regex or a set of specific allowed values.

namespace HiveSharp.Runtime
{
    [AttributeUsage(AttributeTargets.Parameter)]
    public class ValuesAttribute : Attribute
    {
        public object[] Allowed { get; set; }
        public object[] Recommended { get; set; }
        public object Min { get; set; }
        public object Max { get; set; }
        public string Regex { get; set; }
    }
}

TagsAttribute (or Tags for short) is applicable to all the same entities as PublishAttribute, with the exception of parameters. It can be used to attach tags that can aid in searching, although it is currently ignored by the HiveSharp engine.

namespace HiveSharp.Runtime
{
    [ AttributeUsage(AttributeTargets.Assembly | AttributeTargets.Module |
      AttributeTargets.Class | AttributeTargets.Method) ]
    public class TagsAttribute : Attribute
    {
        public TagsAttribute() { }
        public TagsAttribute(params string[] tags)
        {
            Tags = tags;
        }

        public string[] Tags { get; set; }
    }
}

Back to Table of contents