Small Basic: Comment Créer une Extension en C# (fr-FR)
Introduction
Microsoft Small Basic, bien qu'il soit un très bon langage pour un débutant, devient très vite limité dés que l'on veut aller plus loin en programmation. Si vous sentez que vous être plutôt d'un niveau avancé en Small Basic, mais que vous vous sentez également limité par le langage, vous pouvez avoir envie d'écrire une extension. Vous pouvez également vouloir écrire une extension simplement pour aider la Communauté Small Basic en étendant les possibilités à sa disposition.
Pour écrire une extension pour Small Basic, nous devons choisir un langage compatible CLR pour l'écrire. Ce tutoriel va utiliser le langage Microsoft C#, mais il existe grande variété (en-US) de langages compatible avec la CLR utilisée pour écrire une extension Small Basic (et nous avons également un tutoriel pour écrire une extension en Visual Basic.NET ici). Ce tutoriel par du principe que vous avez familier avec Visual Studio, qui est l'environnement privilégié pour le développement pour la CLR. Ce tutoriel utilise Microsoft Visual Studio 2013 Professional (mais fonctionne de la même manière avec Visual Studio 2013 Community).
Configurer le Projet Visual Studio
Avant de configurer le projet, vérifiez la version de votre Small Basic, car les différentes versions ne sont pas compilée sur le même Framework .Net. Suivez les instructions en fonction de la version installée :
Small Basic 1.0 est compilée pour la version 3.5 SP1 du Framework .Net, et n'est pas compatible avec les extensions des autres versions. Vous devrons créer une Bibliothèque de Classes (les extensions Small Basic sont référencées comme des bibliothèques). Nous devons sélectionner ".NET Framework 3.5" depuis la liste déroulante en haut de la boite de dialogue "Nouveau projet", et sélectionner le type de projet "Bibliothèque de classe" comme indiqué ce-dessous.
Small Basic 1.1 est compilée avec le Framework .Net 4.5, donc suivez les mêmes instructions que précédemment mais en sélectionnant ".Net Framework 4.5" au lieu de ".Net Framework 3.5".
Quelque soit la version, nous avons également besoin d'ajouter une référence à SmallBasicLibrary.dll, qui se trouve dans le dossier où vous avez installé Small Basic. Nous avons besoin de cette librairie car elle est utilisée pour nous permettre de marquer nos classes avec un attribut permettant à l'EDI Small Basic de les reconnaître. Une fois la référence ajoutée, nous devons inclure l'espace de nom dans notre fichier.
Programmer Notre Extension
Notre fichier doit ressembler à quelque chose comme ce qui suit.
01.using System;
02.using System.Collections.Generic;
03.using System.Linq;
04.using System.Text;
05.using Microsoft.SmallBasic.Library;
06.
07.namespace SmallBasicExtensionTutoriel
08.{
09. public class Class1
10. {
11. }
12.}
Comme Small Basic ne gère aucun principe de portée ou d'instance, nous devons définir notre classe comme statique (static), et nous devons lui affecter l'attribut qui va l'identifier comme une classe que Small Basic va pouvoir utiliser. Chaque membre de votre classe doit également être déclaré comme statique. A ce stade il est recommandé, plutôt que d'écrire votre code directement dans la classe Small Basic, d'écrire une classe séparée qui utilise les types C#, et ensuite d'écrire un simple wrapper (encapsuleur) de ces classes dans la classe Small Basic. En revanche, ce tutoriel n'utilisera pas de wrapper, et on écrira directement notre code dans la classe Small Basic.
1.[SmallBasicType]
2.public static class ExampleExtension
Une des limitation de Small Basic est le fait qu'il ne possède pas de déclaration de type explicite : nous avons qu'un seul type de donnée, Primitive, qui représente aussi bien les valeurs numériques que les valeurs texte. Cela signifie que nos fonctions et propriétés doivent retourner une valeur de type Primitive. Ce ne devrait pas poser de problème, car la plupart des types C# seront converti automatiquement en type Primitive.
Avant de continuer, nous allons besoin de générer un fichier XML pour décrire la classe, les fonctions et les propriétés dans notre extension. Visual Studio peut le faire automatiquement pour nous. Tout ce que nous devons faire est de se rendre dans les propriétés de notre projet, aller dans l'onglet "Générer" et cocher la case a coté de "Fichier de documentation XML". Cette option va générer un fichier de documentation XML en utilisant les informations que nous allons fournir.
Pour fournir les informations à ce fichier, nous devons créer un commentaire en utilisant trois barres obliques ou slash (///) au dessus de l'item dont nous voulons ajouter un commentaire, et ensuite il suffit de remplir les valeurs. Elles seront automatiquement écrites dans le fichier de documentation, que nous pourrons alors distribuer avec notre extension. Quand nous tapons trois slashes sur un objet qui peut recevoir un commentaire de documentation, nous voyons un texte similaire à ceci.
1./// <summary>
2./// C'est la classe que nous allons utiliser pour notre exemple d'extension.
3./// </summary>
4.[SmallBasicType]
5.public static class ExampleExtension
6.{
7.}
Nous avons rempli le résumé (summary), et ce résumé sera désormais affiché dans l'EDI Small Basic lorsque l'utilisateur sélectionne cette classe dans la fenêtre de l'IntelliSense. Il existe une variété de tags qui peuvent apparaître en fonction de l'élément sur lequel nous créons un commentaire. Nous verrons plus tard les tags pour les paramètres de fonction qui apparaissent lorsque nous documentons la fonction que nous venons de créer. Un tag que nous pouvons voir maintenant, est le tag <example>. Ce tag peut être utilisé pour fournir un exemple de code pour notre fonction.
Nous allons créer la fonction que nous allons utiliser comme exemple. Cette fonction va être très basic, et va simplement élevé un nombre à une puissance spécifiée. Une légère complication va se poser à nous car nous n'allons pas utiliser les types C#, mais nous pouvons facilement analyser un Primitive vers le type que nous voulons utiliser. Le code de cette fonction ce trouve ci-dessous, et nous devons le placer dans la seule classe de notre fichier source, notée ExampleExtension précédemment.
01.public static Primitive ToPower(Primitive _base, Primitive index)
02.{
03. double _base_ = double.Parse(_base.ToString());
04. int _index = int.Parse(index.ToString());
05.
06. double _base_copy = _base_;
07.
08. for (int i = 0; i < _index; i++)
09. _base_copy *= _base;
10.
11. return (Primitive)_base_copy;
12.}
Nous avons converti le premier Primitive en double, qui est un nombre à virgule flottante d'une précision de 14 décimales, et nous avons converti le second en entier. Le second paramètre doit être un entier car nous ne pouvons pas élever à une puissance avec des décimales. Ensuite nous faisons une copie de notre double, car nous avons besoin d'une copie à multiplier et une copie pour stocker le résultat.
Pour boucler afin d'élever le nombre une seule puissance à la fois, nous avons utiliser une boucle For. Nous avons créer un autre entier pour cela. Une fois que notre second entier est égal à la puissance demandée, la boucle For s'arrête. Ensuite nous utiliser la conversion style C pour convertir le double en Primitive. Malgré que cela fonctionne sans la conversion, c'est une bonne pratique de convertir la valeur que nous devons retourner dans le type de retour de la fonction. Pour terminer la fonction, nous ajoutons un commentaire de documentation. Pour cet exemple, nous écrirons le texte suivant pour notre documentation.
1./// <summary>
2./// Elève un nombre à la puissance spécifiée.
3./// </summary>
4./// <param name="_base">Le nombre à élever.</param>
5./// <param name="index">La puissance dans laquelle élever le nombre.</param>
6./// <returns>Le nombre spécifié élevé à la puissance spécifiée.</returns>
7./// <example>ExampleExtension.ToPower(2, 2)</example>
8.public static Primitive ToPower(Primitive _base, Primitive index)
Avant de tester notre extension dans Small Basic, nous allons créer deux propriétés. Les propriétés sont utiles car elles permettent soit d'enregistrer des informations qui sont modifiables par l'utilisateur, soit de fournir des informations qui ne sont pas modifiables par l'utilisateur. Pour créer une propriété nous devons utiliser les accesseurs et set. Utiliser uniquement l'accesseur get nous permet de définir une valeur constante à notre propriété, et utiliser l'accesseur set nous permet d'autoriser l'utilisateur de la modifier. Nous allons utiliser le code qui suit pour ces deux propriétés. Les commentaires de documentations sont inclus.
01./// <summary>
02./// Le nom de l'utilisateur actuellement connecté. C'est une propriété en lecture seule.
03./// </summary>
04.public static Primitive CurrentUsername
05.{
06. get
07. {
08. return (Primitive)Environment.UserName;
09. }
10.}
11.
12.private static Primitive _UserEditableValue = (Primitive)null;
13./// <summary>
14./// Une propriété modifiable par l'utilisateur.
15./// </summary>
16.public static Primitive UserEditableValue
17.{
18. set { _UserEditableValue = value; }
19. get { return _UserEditableValue; }
20.}
21.
22./// <summary>
23./// Une propriété modifiable par l'utilisateur qui est implémentée différemment.
24./// </summary>
25.public static Primitive ShorterUserEditableValue
26.{
27. get;
28. set;
29.}
Est également inclus l'utilisation des accesseurs get et set de manière plus courte, qui ne nécessite pas d'utiliser une variable privée. La seconde méthode est préférée pour les propriétés modifiables si on a pas besoin de faire autre chose que de stocker la valeur de la propriété.
Compiler Notre Code
Ce qu'il nous reste à faire avant de tester notre extension et de compiler notre code. Visual Studio, par défaut, possède deux configurations qui peuvent être utilisées pour compiler notre code. Il y a Debug et Release. Quand nous sommes prêts à distribuer notre extension, nous devons compiler en utilisant la configuration Release. Elle optimise le code et retire tout un ensemble de code inutilisé qui est ajouté par le débogueur. Pour changer notre configuration en cours, se rendre dans le menu "Générer" et choisir "Gestionnaire de configurations..." tout à la fin du menu. Nous pouvons changer la configuration de notre projet comme ceci.
Une fois que nous avons changé la configuration, appuyer sur la touche F6 . Ceci va compiler notre projet, créer la DLL et les fichiers XML qui nous devrons ajouter au dossier "lib" dans le dossier du Small Basic. Pour obtenir ces fichiers, se rendre dans l'Explorateur de Solution, faire un clic droit sur le nom du projet est sélectionner "Ouvrir le dossier dans l'Explorateur de fichiers", qui va ouvrir le dossier où se trouve vos fichier dans l'Explorateur Windows. On navigue dans les dossiers "bin" et "Release" pour obtenir nos fichiers compilés. A noter que nous devons également cocher l'option "Fichier de documentation XML" dans les propriétés du projet lorsque nous basculons dans la configuration Release, car il n'est coché que pour la configuration Debug.
Testons notre Extension
Pour tester notre extension, nous devons la déplacer avec son fichier XML (de pas déplacer la SmallBasicLibrary.dll) le dossier "lib" du Small Basic, qui est l'endroit où les extensions doivent se trouver pour le Small Basic. A noter que vous devez avoir les droits d'administrateur pour déplacer les fichiers dans ce dossier, qui se trouve généralement dans "Program Files (x86)" pour les Windows 64 bits, et "Program Files" pour les Windows 32 bits.
Nous pouvons maintenant lancer Small Basic et taper le nom de notre classe qui s'appelle ExampleExtension, et voir la fenêtre IntelliSense. Si vous ne la vouez pas dans la fenêtre IntelliSense, vous devez vérifier que vous l'avez marquée comme statique, ainsi que ces membres enfants, ainsi que vous lui avez défini l'attribut SmallBasicType. Si vous n'avez pas fait d'erreurs, dans ce cas, vous devez voir quelque chose de similaire à ceci.
Distribuer Notre Extension
Une fois que nous avons terminé de développer notre extension, nous pouvons commencer à la distribuer. A moins que vous n'ayez un site web ou votre propre serveur où vous pouvez héberger un téléchargement, il y a plusieurs sites web où vous pouvez héberger votre extension. Ces sites inclus GitHub, qui fourni des dépôts Git permettant de gérer une multitude de versions; il y a Sourceforge, un site web populaire pour les projets permettant l'utilisation de dépôts Git, SVN, ou Mercurial; et pour finir il y a CodePlex, un site web Microsoft pour l'hébergement de projets open source.
Nous pourrons également choisir une licence sous laquelle distribuer notre extension. Une licence indique ce qu'un utilisateur final peut ou ne peut pas faire avec notre code. Dans les licences populaires on trouve la licence MIT (Massachusetts Institute of Technology), la GPL (La licence GNU Public), la licence Mozilla, et bien d'autres. Il est important de lire le texte de la licence avant de la choisir, pour être sûr que cous comprenez ce que l'utilisateur final peut faire. Si vous ne souhaitez pas utiliser l'une de ces licences, il y a l'option de créer votre propre licence. Il est recommander de bien comprendre certains concepts juridiques avant d'écrire votre propre licence.
Voir Aussi
Autres Langues
- Article original : Small Basic: How to Create an Extension Using C#