Создание расширений для Small Basic

Общие требования

Компилятор Small Basic разработан таким образом, что он позволяет подключать любые внешние библиотеки расширений от сторонних разработчиков. Эти библиотеки могут быть написаны практически на любом языке программирования, поддерживающем MS .Net Framework версии 4.5 и новее,  и скомпилированы в dll-сборку MS .Net. Существует несколько обязательных правил, которые необходимо выполнять для того, чтобы компилятор Small Basic смог идентифицировать созданные объекты как «объекты» Small Basic.

• Тип объекта должен быть объявлен статическим (static)
• Тип объекта должен быть оформлен как SmallBasicTypeAttribute
• Свойства (параметры) объекта должны иметь тип Microsoft.SmallBasic.Library.Primitive
• Все входные и выходные параметры для методов должны иметь тип Microsoft.SmallBasic.Library.Primitive
• Все события должны быть типа Microsoft.SmallBasic.Library.SmallBasicCallback

После выполнения этих условий вы можете скомпилировать сборку в  виде dll-библиотеки и поместить ее в папку «lib» в папке установки Small Basic. Например, если Small Basic был установлен на вашем диске «С:», а ваша библиотека называлась «myextensions», вам нужно поместить файл myextensions.dll в папку «C:\Program Files\Microsoft\Small Basic\lib».

При желании вы можете включить XML-документацию в ваш проект и скопировать полученный xml-файл вместе с файлом библиотеки. Это автоматически активирует текст справки в области справки Intellisense и подсказки в редакторе.

Пример расширения на C #

Вот пример расширения MyExtensions, написанного на C #, которое представляет объект «Settings»,  позволяющий пользователям хранить и извлекать пары имя-значение, специфичные для программы.

using System.Collections.Generic;
using System.IO;
using System.Reflection;
using System.Runtime.Serialization.Formatters;
using System.Runtime.Serialization.Formatters.Binary;
using Microsoft.SmallBasic.Library;
namespace MyExtensions

{
    /// <summary>

/// The Settings library consists of helpers that allow programs to store and retrieve user settings.

/// </summary>

[SmallBasicType]

public static class Settings

{

static Primitive _filePath = new Primitive();

/// <summary>

/// Gets the file path for the settings file.

/// </summary>

public static Primitive FilePath

{

get

{

if (string.IsNullOrEmpty(_filePath))

{

_filePath = Path.ChangeExtension(Assembly.GetEntryAssembly().Location, ".settings");

}

return _filePath;

}

}

 

/// <summary>

/// Gets the value for the setting identified by the specified name.

/// </summary>

/// <param name="name">

/// The Name of the setting.

/// </param>

/// <returns>

/// The Value of the setting.

/// </returns>

public static Primitive GetValue(Primitive name)

{

if (System.IO.File.Exists(FilePath))

{

using (Stream stream = System.IO.File.Open(FilePath, FileMode.Open))

{

Dictionary<string, string> contents = ReadContents(stream);

if (contents.ContainsKey (name))

{return contents[name];}

}

}

return "";

}

 

/// <summary>

/// Sets a value for a setting identified by the specified name.

/// </summary>

/// <param name="name">

/// The Name of the setting.

/// </param>

/// <param name="value">

/// The Value of the setting.

/// </param>

public static void SetValue(Primitive name, Primitive value)

{

Dictionary<string, string> contents = null;

if (System.IO.File.Exists(FilePath))

{

using (Stream stream = System.IO.File.Open(FilePath, FileMode.Open))

{

contents = ReadContents(stream);

}

}

else

{

contents = new Dictionary<string, string>();

}

contents[name] = value;

using (Stream stream = System.IO.File.Open(FilePath, FileMode.Create))

{

WriteContents(stream, contents);

}

}

 

static Dictionary<string, string> ReadContents(Stream stream)

{

BinaryFormatter formatter = new BinaryFormatter();

formatter.AssemblyFormat = FormatterAssemblyStyle.Simple;

return (Dictionary<string, string>)formatter.Deserialize(stream);

}

 

static void WriteContents(Stream stream, Dictionary<string, string> map)

{

BinaryFormatter formatter = new BinaryFormatter();

formatter.AssemblyFormat = FormatterAssemblyStyle.Simple;

formatter.Serialize(stream, map);

}

}

}

Английский оригинал статьи: https://docs.microsoft.com/ru-ru/archive/blogs/smallbasic/extending-small-basic

---

Создание расширения с помощью Microsoft Visual Basic .NET

Создание расширения

1. Откройте Visual Basic и нажмите «Создать новый проект»
2. Выберите тип проекта — «Библиотека классов» и назовите его «MyFirstExtension»
3. После загрузки проекта удалите весь код класса Class1 и вставьте следующий код:

Imports System

Imports Microsoft.SmallBasic.Library

Imports System.Threading

Imports System.IO

<SmallBasicType()> _

Public Module FirstModule

Public Function ShowMessage(ByVal MsgTxt As Primitive) As Primitive

MsgBox(MsgTxt.ToString)

End Function

End Module

4. Откройте обозреватель решений, щелкните правой кнопкой мыши на «MyFirstExtension» и перейдите к пункту «Добавить ссылку».
5. После того, как диалоговое окно откроется, нажмите на вкладку «Обзор» и перейдите в папку Small Basic и нажмите «SmallBasicLibrary.dll». После этого все ошибки долшны исчезнуть.
   

Сборка

Чтобы расширение работало в Small Basic, нам нужно изменить Target Framework на .NET 3.5 (для Small Basic 1.0) или .NET 4.5 (для Small Basic 1.1), или .NET 4.8 (для Small Basic 1.2 и новее).

1. Нажмите на кнопку Сохранить в верхней части экрана
2. Перейдите в Проекты > Свойства MyFirstExtension
3. Нажмите на вкладку «Компиляция»
4. Нажмите «Дополнительные параметры компиляции» внизу
5. Нажмите на раскрывающееся меню «Target Framework» и выберите .NET 3.5 (или .NET 4.5 или .NET 4.8)
6. Нажмите «ОК» и когда появится диалоговое окно, нажмите «Да»
7. Вы можете открыть расширение, открыв обозреватель решений и дважды щелкнув «Class1.VB»
8. Теперь, создайте .dll, перейдя в верхнюю часть экрана и нажав Build > Build MyFirstExtension
9. Это создаст .dll файл в папке «bin> Release» вашего проекта
10. Перейдите к файлу «bin > Release» в проводнике и скопируйте файлы «SmallBasicLibrary.dll» и «SmallBasicLibrary.xml» в папку «lib» в папке установки MS Small Basic:
    
    1. Откройте папку Small Basic и создайте папку «lib», если ее там еще нет
    2. Откройте папку «lib» и скопируйте в неё ваши файлы «SmallBasicLibrary.dll» и «SmallBasicLibrary.xml»
11. Закройте приложение Small Basic, если оно было запущено, и снова откройте его
12. Теперь все, что вам нужно сделать, чтобы использовать расширение, это ввести в FirstModule.ShowMessage («YourMessageBoxTextHere»)

Идём дальше

Чтобы реализовать больший функционал для FirstModule, все, что вам нужно сделать, это добавить в класс больше функций. Если вам нужно получить какие-либо переменные от пользователя, просто разделите ByVal YOURVARIABLE запятыми. Если вам нужно вернуть значение функции, просто поставьте return перед ней так:

Public Function NetOpen() As Primitive

Return My.Computer.Network.IsAvailable

End Function

Английский оригинал статьи: https://social.technet.microsoft.com/wiki/contents/articles/13340.small-basic-how-to-create-an-extension-using-vb-net.aspx

---

Создание расширения с помощью Microsoft Visual C#

Введение

Microsoft Small Basic, хотя и является хорошим языком программирования для начинающих, всё-таки довольно ограничен в возможностях, однако, если вам действительно необходим функционал, которого нет изначально в Small Basic, и это вас ограничивает, вы можете написать свою собственную библиотеку расширения. Вы также можете написать бтблиотеку расширения просто для того, чтобы помочь сообществу Small Basic, опубликовав её в интернете.

Чтобы написать расширение для Small Basic, вам нужно будет выбрать для этого CLR-совместимый язык (https://en.wikipedia.org/wiki/List_of_CLI_languages). В этом руководстве будет использоваться Microsoft C#, однако, существует большой выбор языков программирования, совместимых с CLR, которые можно использовать для написания расширений Small Basic. В этом руководстве предполагается, что вы хорошо понимаете, как использовать MS Visual Studio, являеющееся наиболее предпочтительной средой разработки для CLR, и в частности, для создания расширений MS Small Basic. Это руководство написано применительно к версии Microsoft Visual Studio 2012 Professional.

Настройка вашего проекта

Перед настройкой проекта проверьте вашу версию MS Small Basic, поскольку разные рерсии Small Basic работают на разных версиях MS .Net Framework. Следуйте инструкциям в соответствии с установленной у вас версией.

Так как Small Basic 1.0 создан для .NET Framework версии 3.5 с пакетом обновления 1 (SP1), то он не будет совместим с расширениями, созданными для других версий. Вам необходимо создать библиотеку классов (поскольку вне Small Basic «расширения» обычно называются библиотеками объектов (классов), или просто «библиотеками»). Вам нужно выбрать «.NET Framework 3.5» из выпадающего списка в верхней части окна «Новый проект», и затем выбрать «Библиотеку классов», как показано ниже.

Small Basic версии 1.1 и старше построены на MS .Net Framework 4.5 (4.8), поэтому следуйте приведенным выше инструкциям, но выберите «.Net Framework 4.5» вместо «.Net Framework 3.5».

Независимо от версии, вам также нужно добавить ссылку на SmallBasicLibrary.dll, который находится внутри каталога, в который вы установили MS Small Basic. Нам нужна эта библиотека, потому что она позволяет нам помечать классы атрибутом, который делает их видимыми в IDE Small Basic. После того, как вы добавили ссылку, вам также надо включить пространство имен в свой файл кода.

Создание вашего расширения

Содержимое вашего файла кода должно быть похоже на текст, который показан здесь:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using Microsoft.SmallBasic.Library;

 

namespace Small_Basic_Extension_Tutorial

{

public class Class1

{

}

}

Поскольку Small Basic не знает областей видимости или экземпляров класса, мы должны пометить наш класс как статический, и нам нужно дать ему атрибут, который идентифицирует его как класс для использования в Small Basic. Каждый член нашего класса также должен быть объявлен как статический. Именно поэтому рекомендуется вместо того, чтобы писать код прямо в класс Small Basic, писать его в отдельный класс, использующий типы C#, а затем просто писать обертку над этими классами для класса Small Basic. Однако этот учебник не будет использовать обертку и мы будем писать код прямо в класс Small Basic:

[SmallBasicType]

public static class ExampleExtension

Одним из ограничений MS Small Basic является тот факт, что в нем нет явных объявлений типов: у вас есть только один тип данных, Primitive, который представляет как числовые, так и текстовые значения. Это означает, что наши функции и свойства должны принимать и возвращать значения типа Primitive. Это не должно быть проблемой, так как многие типы в C# неявно преобразуются в тип Primitive.

Прежде чем мы продолжим, нам также надо создать файл XML для описания классов, функций и свойств в нашем расширении. MS Visual Studio может сделать это автоматически. Все, что вам нужно сделать, это зайти в свойства вашего проекта, перейти на вкладку «Build» и установить флажок рядом с «XML документация». Это позволит MS Visual Studio автоматически создавать файл документации XML с использованием предоставленной вами информации.

Чтобы предоставить информацию для этого XML-файла, вам необходимо создать специальный комментарий, используя три косые черты (///) перед самим элементом, для которого вы хотите добавить описание. После трёх косых черт вы можете вводить описание объекта. Оно будет автоматически записано в файл XML-документации, который вы затем cможете распространять вместе с вашим расширением. Когда вы набираете три косых черты перед объектом, который будет содержать комментарий в документации, вы должны увидите текст, подобный этому:

/// <summary>

/// This is the class we will be using for our example extension.

/// </summary>

[SmallBasicType]

public static class ExampleExtension

{

}

После заполнения поля подсказки эта подсказка будет отображаться в окне IntelliSense в IDE Small Basic, когда пользователь выбирает этот класс. Существует множество различных тегов полей подсказки, которые будут появляться в зависимости от того, для чего вы создаете комментарий. Позже вы увидите, что теги для параметров для функций появятся при документировании функций, которые вы создаёте. Есть еще один тег, который не будет отображаться и требует ввода, это тег <example>. Этот тег можно использовать для демонстрации примера кода с использованием вашей функции.

Теперь мы создадим функцию, которую будем использовать в качестве примера. Эта функция будет довольно простой и будет возводить число в указанную степень. Некоторое осложнение возникает из-за того, что мы не используем встроенные типы C#, но мы можем легко идентифицировать тип данных в типе Primitive, который мы хотим использовать. Код для этой функции приведен ниже, и вы должны поместить его в единственный класс ExampleExtension в вашем файле кода, приведенном выше.

Вот сам код функуии:

public static Primitive ToPower(Primitive _base, Primitive index)

{

double _base_ = double.Parse(_base.ToString());

int _index = int.Parse(index.ToString());

double _base_copy = _base_;

for (int i = 0; i < _index; i++)

_base_copy *= _base;

return (Primitive)_base_copy;

}

Здесь мы преобразовали первый Primitive в число двойной точности, представляющее собой число с плавающей запятой с точностью до 14 знаков после запятой, а второй Primitive преобразовали в целое число. Второе должно быть целым числом, потому что показатель степени для используемой функции должен быть целым. Затем мы делаем копию основания, так как нам нужна одна переменная для умножения и одна переменная — для хранения результата.

Для повторного умножения мы используем цикл for. Как только счетчик цикла станет равным заданной степени, цикл for завершится. После этого мы использовали преобразование в стиле C для преобразования числа двойной точности обратно в Primitive. Хотя это может работать без преобразования, хорошей практикой является преобразование возвращаемого вами значения в тип возвращаемый нашей функцией. Чтобы завершить работу над функцией, давайте добавим к ней комментарий для документации. Для этого примера я написал следующий текст комментария:

/// <summary>

/// Raises a number to the specified power.

/// </summary>

/// <param name="_base">The number to be raised.</param>

/// <param name="index">The power to raise the number to.</param>

/// <returns>The specified number raised to the specified power.</returns>

/// <example>ExampleExtension.ToPower(2, 2)</example>

public static Primitive ToPower(Primitive _base, Primitive index)

Прежде чем мы протестируем наше первое расширение в Small Basic, давайте создадим еще два свойства. Свойства полезны тем, что они позволяют хранить как информацию, которая редактируется пользователем, так и информацию, которую пользователь не может редактировать. Чтобы создать свойство, мы должны использовать методы доступа get и set. Использование только метода доступа get позволит нам установить постоянное значение для нашего свойства, а используя метод доступа set, мы сможем изменять его значение. Соответствующий код приведен ниже:

/// <summary>

/// The username of the current logged-on user. This is a read-only property.

/// </summary>

public static Primitive CurrentUsername

{

get

{

return (Primitive)Environment.UserName;

}

}

private static Primitive _UserEditableValue = (Primitive)null;

/// <summary>

/// A user-editable property.

/// </summary>

public static Primitive UserEditableValue

{

set { _UserEditableValue = value; }

get { return _UserEditableValue; }

}

/// <summary>

/// A user-editable property that has been implemented differently.

/// </summary>

public static Primitive ShorterUserEditableValue

{

get;

set;

}

Здесть также используется более короткий способ использования методов доступа get и set, который не требует использования скрытой переменной. Второй метод предпочтителен для редактируемых пользователем свойств, если только вам не нужно делать что-то иное, чем просто установить значение свойства.

Компиляция вашего расширения

Все, что нам осталось до того, как мы протестируем наше новое расширение, это скомпилировать наш код. MS Visual Studio по умолчанию имеет две конфигурации, которые мы можем использовать при компиляции нашего кода. Это «Debug» и «Release». Если вы готовы выпустить ваше расширение, вы должны скомпилировать его с помощью конфигурации «Release». Это оптимизирует код и удалит из него много ненужной информации, добавляемой отладчиком. Чтобы изменить текущую конфигурацию, перейдите в меню «Сборка», а затем в «Диспетчер конфигурации» внизу. Затем вы можете изменить конфигурацию вашего проекта, как показано ниже.

Как только вы изменили конфигурацию, просто нажмите клавишу F6 на клавиатуре или выберите в меню пункт «Сборка». Это скомпилирует ваш проект, создав файлы DLL и XML, которые надо добавить в папку «lib» в папке «Small Basic». Чтобы получить эти файлы, вы можете открыть обозреватель решений в Visual Studio, щелкнуть правой кнопкой мыши имя проекта и выбрать «Открыть в проводнике», чтобы открыть папку, в которой находятся ваши файлы, с помощью проводника Windows. Затем вы можете перемещаться по папкам «bin» и «Release», чтобы найти ваши файлы. Обратите внимание, что вам также нужно будет проверить опцию «XML-файл документации» в свойствах вашего проекта при переключении на конфигурацию Release, так как она была настроена только для конфигурации отладки.

Тестирование нового расширения

Чтобы протестировать ваше расширение, нужно переместить его и его XML-файл (вы не должны перемещать SmallBasicLibrary.dll или XML-файл в папку lib) в папку «lib» в папке Small Basic, где хранятся расширения MS Small Basic. Обратите внимание, что вам, вероятно, потребуется разрешение администратора (или права администратора) для перемещения файлов в эту папку, которая обычно находится внутри папки «Program Files (x86)» для 64-разрядных версий Windows, или просто «Program Files» для 32-разрядных версий Windows.

Теперь вы должны запустить Small Basic и ввести имя класса ExampleExtension, — вы увидите его описание в окне IntelliSense. Если вы не видите его в окне IntelliSense, проверьте, пометили ли вы его или его дочерние элементы как статические, и дали ли вы ему атрибут SmallBasicType. Однако, если вы не допустили ошибок, вы должны увидеть нечто подобное:

Распространение вашего расширения

Как только вы закончите разработку своего расширения, вы можете начать его распространение. Если у вас нет собственного веб-сайта, на котором вы можете разместить файлы расширения, вы можете воспользоваться существующими веб-сайтами для размещения своего расширения. Это, например, GitHub (https://github.com/), который содержит Git-репозитории, которые предоставляют целый ряд функций управления версиями; или Sourceforge (http://www.sourceforge.net/), популярный веб-сайт для проектов, который позволяет использовать репозитории Git, SVN или Mercurial; и, наконец, CodePlex (http://www.codeplex.com/), веб-сайт Microsoft, созданный для проектов с открытым исходным кодом.

Вы также можете выбрать лицензию для распространения вашего расширения под. Лицензия определяет, что конечный пользователь может и не может делать с вашим исходным кодом. Популярные лицензии с открытым исходным кодом включают в себя лицензию MIT (Массачусетский технологический институт), GPL (GNU Public License), лицензию Mozilla и многие другие. Важно, чтобы вы прочитали тексты лицензий, прежде чем выбирать их, и убедились, что вы знаете, что может сделать конечный пользователь. Если вы не хотите использовать какую-либо из этих лицензий, существует также возможность создания собственной лицензии. Перед написанием собственной лицензии рекомендуется ознакомиться с некоторыми юридическими концепциями.

Английский оригинал статьи: https://social.technet.microsoft.com/wiki/contents/articles/14025.small-basic-how-to-create-an-extension-using-c.aspx

Поделиться: