By watching that video I started to search what he used and then stumbled on the official fable elmish repository, but also I found out an another one which is more to my liking and it was SAFE Stack (SAFE stands for Saturn Azure Fable and Elmish). A nice article have been written not long ago by Isaac Abhrams (MSDN Link), so I won’t try to repeat what he already wrote.

In this article, we will simply explore how to create your first application.

Why is it so interesting

Basically, if we use the SAFE Stack, everything is more or less working together. You write your back-end in F#, your front-end in F# and then you can share domain objects and basic functions between the two since all is compiled (or transpiled depending where you look at). If you run all within VS Code, it’s going to be a nice experience since you can save in back or front and then see the new results on the interface (back-end needs a page refresh in such a case or a new call to the server).

When putting breakpoints in the F# file, you can debug your front or backend directly. Also, if you know React JS and it’s plugin in Chrome, you know that you have a time machine for your front-end. It’s also working out of the box, so it’s great to debug or receive an “how to reproduce” script.

Requirements

• NodeJs
• Yarn
• Dotnet Core 3.1
• Crome with Redux extension (Didn’t work with Brave Browser due to some linking from VS Code)

More details at https://safe-stack.github.io/docs/quickstart/

Let’s install SAFE Stack

We’re in March 2020 and it’s .Net Core 3.1 era.

Add a new template to your dotnet new

This will allow you to scaffold template project. The project being quite active, I suggest you to update once in a while by retyping the same command. It will download the latest version while re-installing. (It’s based on a NuGet template package which you can follow).

dotnet new -i SAFE.Template

Create a new folder and then scaffold a first app

Details on command line arguments at https://safe-stack.github.io/docs/template-overview/

dotnet new SAFE --layout fulma-cover --deploy docker

Restore the whole app (takes a bit of time)

dotnet tool restore

Run without VS Code (No nice debugging experience)

Use the following to see if all is working as expected (Takes time on the first launch since it downloads everything).

dotnet fake build --target run

Run within VS Code (Integrated and nice experience)

Open VS Code in the current folder code .. If the extension required to run are not installed it will pop-up the following message. Simply agree

Once installed, if not already go on the debug icon on the left menu bar and look at the targets:

Click on Debug SAFE App. This will start both front-end and back-end server and watch/attach process in VS Code. This will allow to do live debug. After you click and wait, you should have 2 process attached

If you look at your source code from the F# view (default it after you have installed the plugin and opened a folder with FS files). You will see that you have only a few files, while in reality you have many. Simply go in the folder view to see everything. You will also see there’s a shared folder with a file. That file is shared through the FSProj file.

Default view after starting the application

Application created, let’s explore quickly the files

Front-end

All the front-end is build using react/redux. Since it’s the case and it’s quite nice, you can use the time machine to play around.

The code to generate the UX is something that looks like bellow:

let containerBox (model : Model) (dispatch : Msg -> unit) =
    Box.box' [ ]
        [ Field.div [ Field.IsGrouped ]
            [ Control.p [ Control.IsExpanded ]
                [ Input.text
                    [ Input.Disabled true
                      Input.Value (show model) ] ]
              Control.p [ ]
                [ Button.a
                    [ Button.Color IsPrimary
                      Button.OnClick (fun _ -> dispatch Increment) ]
                    [ str "+" ] ]
              Control.p [ ]
                [ Button.a
                    [ Button.Color IsPrimary
                      Button.OnClick (fun _ -> dispatch Decrement) ]
                    [ str "-" ] ] ] ]

Most of the UX is created using Fulma functions (Control.p, Field.div, etc.). In case you would like to have a line break, you could add a line with br []. It’s not because it’s using most likely Fulma that you cannot use the Fable.React.Standard html controls.

The first [] are for the style (class and stuff like that) and the second [] is the content.

The default project put all within one file, but nothing does not allow you to split across multiple file. Even the tutorial SAFE-Dojo is built using a bit more separation of concerns.

Back-end

Like the front-end, I would have loved to have a better separation within the template scaffolding. Right now, only one file is created and it’s up to you to know what to do.

Since the back-end is built around Saturn and Giraffe, you can see at the doc to understand more how to split your files (Which I highly recommend).

Otherwise, for the back-end, it’s the usual. You use your code and favorite libraries. Don’t forget that you can share some logic and types between your back and front.

Next step

I will try to come back on this, but, it will be about moving the file around and going a bit deeper with a bigger scenario. At the moment, the samples on the website are not all up to date and you might experience some issue by running them. That being said, enjoy playing around until the next post.

Thank you for reading!

Ordering of the filters within Dotnet Core

Basically, most of the time we want to add some behavior within the ActionFilter area. But when it comes to authorization, the best is to stop the entire pipeline as soon as possible. That’s where the IAuthorizationFilter comes into play.

Sample of creating an IAuthorizationFilter

The IAuthorizationFilter only require us one method to implement (i.e.: OnAuthorization). There is also no need of doing any dependency injection for such attribute in order to activate it. The following code is only an example doing nothing special, but you should grasp the idea.

    public sealed class SpecialAuthorizeAttribute : Attribute, IAuthorizationFilter  // or IAsyncAuthorizationFilter  ...
    {
        private const string HEADER_SPECIAL_STUFF = "specialHeaderStuff";

        public void OnAuthorization(AuthorizationFilterContext context)
        {
            if (context != null)
            {
                var authCode = context.HttpContext.Request.Headers[HEADER_SPECIAL_STUFF];
                // Write your logic here.
                if (string.IsNullOrEmpty(authCode))
                {
                    context.Result = new UnauthorizedObjectResult($"{HEADER_SPECIAL_STUFF} is required");
                    return;
                }

                if (!authCode.Equals("IAmValid"))
                {
                    context.Result = new UnauthorizedObjectResult($"{HEADER_SPECIAL_STUFF} is invalid");
                    return;
                }

                // ===== if you're here, it's a success =====
                // DO STUFF
                //
                // ===== you can also use registered services =====
                // var someService = context.HttpContext.RequestServices.GetService<ISomeService>();
            }
        }
    }

Sample of using our custom IAuthorizationFilter

The following code is based on a new WebApi project.

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{

    // GET api/values/5
    [SpecialAuthorize]
    [HttpGet("{id}")]
    public ActionResult<string> Get(int id)
    {
        return "value";
    }

    // ... other stuff
}

In order to execute, you can simply do a HTTP call using Curl.

nordes@Something:~$ curl https://localhost:5001/api/values/1 --insecure && echo ''
specialHeaderStuff is required
nordes@Something:~$ curl https://localhost:5001/api/values/1 -H 'specialHeaderStuff:IAmInvalid' --insecure && echo ''
specialHeaderStuff is invalid
nordes@Something:~$ curl https://localhost:5001/api/values/1 -H 'specialHeaderStuff:IAmValid' --insecure && echo ''
value

As you can see, when I use a Valid value, it is accepted and then process the Controller-Action. The attribute could also be put on the Controller and in such case will apply that rule to every actions.

Conclusion

As you can see, it’s not something complex to do. What you should ask yourself is if you need to use it? In my case, I had to use it for specific scenario, but most people will probably simply use the policy over the official Authorize attribute given by the framework.

In this article, we will talk about how to call the libgio (GSettings especially) from our Dotnet application. Obviously, this will work only from Linux having the library. People familiar with Linux/Gnome GUI already knows about the libgio by using C or C++, but what about using C#?

In case you want to know more about libgio, I recommend you to go on the Gnome Developer site and as extra resource you can also go on their blog post about the topic (First Step with GSettings). I will repeat myself later, but, the GSettings links configuration to your session using the DBUS session. If you don’t have any session, you will be able to read the default value, but not to modify them.

What are we going to experiment?

We will simply try to get the GSettings and set a new value. It means that we will be using only 3 API’s our of many. The full name of the library being used is libgio-2.0.so and those 3 API’s are:

• g_settings_new : This will attach to the schema
• g_settings_get_int : This will get the value
• g_settings_set_int : This will set the new value

As you can see, the GSettings is a database containing the key-value pairs of strongly typed documents. What is really under the hood for the schema is XML files. The XML is then compiled and the system will be using binary data instead of XML. The normal emplacement for the schemas is in /usr/share/glib-2.0/schemas. Some details about how to create your own schema (Python) can be found on that blog. In case you don’t want to have to specify the path on each request on your custom schema, simply update it by specifying the path directly in the schema element.

In the case you want to test using the command line, you can use the gsettings –help. In case you play in your subsystem (Windows10), you might want to install libglib2.0-bine and dconf-gsettings-backend.

Example of gsettings file for your application

The example bellow, is purely fictional, but if you wish you can look to existing schema available in /usr/share/glib-2.0/schemas/. If the path is part of the schema element, you won’t need to write the path at every request. Also note that the GSettings set won’t work if your dbus is not started for your user. The dbus bridge your settings with your current session.

<schemalist>
  <enum id="com.honosoft.sample.enum">
    <value nick="off" value="1"/>
    <value nick="warming" value="2"/>
    <value nick="on" value="3"/>
  </enum>

  <schema path="/usr/share/glib-2.0/schemas/" id="com.honosoft.sample">
 
    <key type="b" name="my-flag-is-active">
      <default>false</default>
      <summary>I am a boolean flag</summary>
      <description>A description of your boolean</description>
    </key>
    <key type="i" name="threshold">
        <range min="1" max="100"/>
        <default>50</default>
        <summary>Some threshold</summary>
        <description>Some threshold from 1 to 100 about something</description>
    </key>
 
    <key name="list-prime-numbers" type="ai">
      <default>[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43]</default>
      <summary>Some numbers</summary>
      <description>
        List of numbers
      </description>
    </key>
 
    <key name="list-my-pets" type="as">
        <default>['Captain', 'Scrooge', 'Mana', 'Saturn', 'Brutal']</default>
        <summary>Some array of strings</summary>
        <description>List my pet(s) name</description>
    </key>
 
    <key name="current-state" enum="com.honosoft.sample.enum">
        <default>'off'</default>
        <summary>display a state of my application</summary>
        <description>Using the enum allow only a few values pre-defined</description>
    </key>

    <child name="best-book" schema="com.honosoft.sample.book"/>
  </schema>
 
  <schema path="/usr/share/glib-2.0/schemas/" id="com.honosoft.sample.book">
      <key name="title" type="s">
          <default>'Clean Code'</default>
          <summary>Define the book title</summary>
      </key>
      <key name="author" type="s">
          <default>'Robert C. Martin'</default>
          <summary>Define the author name</summary>
      </key>
  </schema>
</schemalist>

After putting your file in the /usr/share/glib-2.0/schemas/ , you need to compile it. To compile and make it available, you have to execute glib-compile-schemas /usr/share/glib-2.0/schemas/ After, you will be able to access the key-value-pair. Note that the command exists simply for debugging purpose. More details can be found on that article.

How do we call such library from C# (Dotnet)

It’s not as complex as you might think. There’s some gotcha, and if you have C/C++ knowledge it will help you to understand those (such as void pointers).

In Dotnet, we have the attribute DllImports which consists of doing the link between the “dll” (or compiled C/C++ .so) and the framework. The best practice for that would be to create a layer of abstraction over the layer mapping such commands. Here’s the 3 command that we will be using mapped in C# using the attribute:

[DllImport("libgio-2.0.so", EntryPoint = "g_settings_new")]
public static extern IntPtr New(string schema);

[DllImport("libgio-2.0.so", EntryPoint = "g_settings_get_int")]
public static extern int GetInt(IntPtr settings, string key);

[DllImport("libgio-2.0.so", EntryPoint = "g_settings_set_int")]
public static extern bool SetInt(IntPtr settings, string key, int value);

As you can see, the IntPtr is a reference to the GSettings schema.

Let’s experiment the whole process

1. Request to the user what schema to retrieve
2. Request to the user what key (int key) to retrieve from the schema
3. Get the int value from the schema + key
4. Request the user to give a new value
5. Set or store the new value

class Program
{
    static void Main(string[] args)
    {
        Console.Write("Schema to look: ");
        var gsettingsSchema = Console.ReadLine();
        Console.Write("Key to look: ");
        var gsettingsKey = Console.ReadLine();

        var gsettings = DemoBindings.GSettings.New(gsettingsSchema);
        var result = DemoBindings.Bindings.GSettings.GetInt(gsettings, gsettingsKey);
        Console.WriteLine($"Value is: {result}");
        Console.Write("Please give me a new value to set: ");
        var newValue = Console.ReadLine();

        var intValue = int.Parse(newValue); // No validation, but you should ;)
        var success = DemoBindings.GSettings.SetInt(gsettings, gsettingsKey, intValue);
        Console.WriteLine($"The new value was set with {success ? string.Empty : "no "} success")
        Console.ReadKey();
    }
}

What does it mean for you?

In the eventually you would write an application that runs in the background triggering some event on the display, you could take advantage of the applications settings (listen even to those) and then maybe trigger some actions. For example:

• Toggle the display of a virtual keyboard on a touch screen.
• Get the current session details (windows)

I hope you’ve enjoyed, even if this is a really short blog.

Let’s consider that you have a touch panel where you would like to handle everything by yourself (touch, move, etc.). How in the world would you get the touch event?

Probably, if you never played around that low in the system, you probably don’t know. Interestingly, there’s the HID (Human Interface Devices). Most of the documentation is available if you search from your favorite engine. What you really want to know, is the binary data structure, once you have that, the fun can begin. In the case you can’t get any description anywhere, I guess the best choice is to do some reverse engineering (not recommended).

In this article we will only analyse a touch event generating a lot of binary data. I don’t want to cover the entire touch/move/etc of the binary data.

Let’s take the touch screen “touch” click event (KeyPress/Release)

Find the Screen Input Device

Within Linux system, there’s plenty of command in order to find your devices. The device files are usually located within the /dev/…. folder. In the past, we used to have all the existing device in the world in that folder. Nowadays, we simply have the bare minimum and that’s great. Most of the devices, if not all, are documented in the Linus repository. There’s many way to retrieve more details or at least the input device of your choice (touch panel).

One of those method consist in looking in all the USB (/proc/bus/usb/devices) or Input devices (/proc/bus/input/devices) in your system. The touch panel is usually linked to an “Event[1..5]” device.

An alternative is to configure your display to point towards your X-Server and then use the xinput command. If you fail to execute that command, it’s either not installed or you simply forgot to set your environment variable DISPLAY.

xinput --list

Second alternative. Without installing anything, you can use the device manager and look directly in the database and find your touch screen. The command for such a case is udevadm and of course you are required to run this as a root (sudo).

# Give all the devices available on your system. If you have a lot of
# devices connected, consider making the output redirected into a file.
# e.g.: udevadm info --export-db > myFile.txt
udevadm info --export-db 

An another alternative, just in case, is to simply look in the special folder “/dev/input/by-id” and “/dev/input/by-path“. The first give the currently connected device with input capabilities. So if you connect or disconnect an input device, you should be able to see it there. By doing a “ls -l” you will see which event file it’s using since it’s creating a symbolic link to it. For example in this output the event1 is my touchscreen:

myroot@mymachine:/dev/input/by-path# ls -l
total 0
lrwxrwxrwx 1 nobody nogroup 9 Mar  6 08:54 pci-0000:00:14.0-usb-0:13.1:1.1-event -> ../event1
lrwxrwxrwx 1 nobody nogroup 9 Mar  7 23:55 pci-0000:00:14.0-usb-0:13.4.2:1.0-event-kbd -> ../event2

Normally, from here, you know which device file correspond to your device. You might even have more details if you used the udevadm.

Read the binary content

Devices files are the raw data file. In order to be able to do something, you need to stream it as you would do for a TCP/UDP/File data. The structure of the content is structured following the driver rules. For example, the Keyboard and Mouse and a few other devices are considered as well known devices and are well documented all over the internet. You can even go directly in the Unix source code in order to see the .h file.

Let’s create a simple loop receiving the binary content while you touch the panel and then let’s output that raw data using an hex string.

public void ReadDeviceStream(CancellationToken stoppingToken) 
{
  // Use the device file
  var targetFile = new FileInfo("/dev/inputs/event1");

  // Open a stream
  using (FileStream fs = targetFile.Open(FileMode.Open, FileAccess.Read, FileShare.ReadWrite))
  {
    stoppingToken.Register(() => fs?.Close());
    int blockId = 1;

    // A big buffer, for simplicity purpose and to receive the entire touch report. We should use
    // the proper buffer size based on the event size. Note that we could also
    // use the binary reader
    var buffer = new byte[1024];

    // Read until the token gets cancelled
    while (!stoppingToken.IsCancellationRequested && fs.Read(buffer) > 0)
    {
      ShowBinaryContent(blockId, buffer);
      blockId++;
    }
  }
}

public void ShowBinaryContent(int blockId, byte[] buffer)
{
  Console.WriteLine($"Block #{blockId}");
  Console.WriteLine(BitConverter.ToString(bytes)); // Hex format: AB-1D...
  Console.WriteLine(string.Empty);
}

How to interpret the data

The result of the previous small program is displayed here

// Block #1
59-9A-74-5C-00-00-00-00-9C-C7-04-00-00-00-00-00-03-00-39-00-03-01-00-00-
59-9A-74-5C-00-00-00-00-9C-C7-04-00-00-00-00-00-03-00-35-00-31-01-00-00-
59-9A-74-5C-00-00-00-00-9C-C7-04-00-00-00-00-00-03-00-36-00-E8-01-00-00-
59-9A-74-5C-00-00-00-00-9C-C7-04-00-00-00-00-00-01-00-4A-01-01-00-00-00-
59-9A-74-5C-00-00-00-00-9C-C7-04-00-00-00-00-00-03-00-00-00-31-01-00-00-
59-9A-74-5C-00-00-00-00-9C-C7-04-00-00-00-00-00-03-00-01-00-E8-01-00-00-
59-9A-74-5C-00-00-00-00-9C-C7-04-00-00-00-00-00-04-00-05-00-00-00-00-00-
59-9A-74-5C-00-00-00-00-9C-C7-04-00-00-00-00-00-00-00-00-00-00-00-00-00

// Block #2
59-9A-74-5C-00-00-00-00-6F-40-05-00-00-00-00-00-03-00-35-00-2C-01-00-00-
59-9A-74-5C-00-00-00-00-6F-40-05-00-00-00-00-00-03-00-00-00-2C-01-00-00-
59-9A-74-5C-00-00-00-00-6F-40-05-00-00-00-00-00-04-00-05-00-10-27-00-00-
59-9A-74-5C-00-00-00-00-6F-40-05-00-00-00-00-00-00-00-00-00-00-00-00-00
            
// Block #3
59-9A-74-5C-00-00-00-00-5D-96-05-00-00-00-00-00-04-00-05-00-20-4E-00-00-
59-9A-74-5C-00-00-00-00-5D-96-05-00-00-00-00-00-00-00-00-00-00-00-00-00

// Block #4
59-9A-74-5C-00-00-00-00-7D-9A-05-00-00-00-00-00-03-00-39-00-FF-FF-FF-FF-
59-9A-74-5C-00-00-00-00-7D-9A-05-00-00-00-00-00-01-00-4A-01-00-00-00-00-
59-9A-74-5C-00-00-00-00-7D-9A-05-00-00-00-00-00-04-00-05-00-30-75-00-00-
59-9A-74-5C-00-00-00-00-7D-9A-05-00-00-00-00-00-00-00-00-00-00-00-00-00

As you can see, we receive many events at the same time and each block contains their own timestamp (few first bytes on each lines). A block here contains more than one instruction. For example, it tells you where you pushed and if it was a push event or release. Let’s focus on the data looking like the Block #1.

public static void Main()
	{
		// Release
		 var binaryStrings = 
		 new [] { "E3-00-75-5C-00-00-00-00-3F-72-09-00-00-00-00-00-03-00-39-00-0C-01-00-00",
                "E3-00-75-5C-00-00-00-00-3F-72-09-00-00-00-00-00-03-00-35-00-51-01-00-00",
                "E3-00-75-5C-00-00-00-00-3F-72-09-00-00-00-00-00-03-00-36-00-93-01-00-00",
                "E3-00-75-5C-00-00-00-00-3F-72-09-00-00-00-00-00-01-00-4A-01-01-00-00-00",
                "E3-00-75-5C-00-00-00-00-3F-72-09-00-00-00-00-00-03-00-00-00-51-01-00-00",
                "E3-00-75-5C-00-00-00-00-3F-72-09-00-00-00-00-00-03-00-01-00-93-01-00-00",
                "E3-00-75-5C-00-00-00-00-3F-72-09-00-00-00-00-00-04-00-05-00-00-00-00-00",
                "E3-00-75-5C-00-00-00-00-3F-72-09-00-00-00-00-00-00-00-00-00-00-00-00-00"};

		foreach (var bs in binaryStrings) {
			byte[] data = bs.Split('-').Select(b => Convert.ToByte(b, 16)).ToArray();

			Console.Write($"[Sec: {BitConverter.ToUInt32(data, 0)}]");
			Console.Write($"\t[USec: {BitConverter.ToUInt32(data, 8)}]");
			Console.Write($"\t[Type: {BitConverter.ToUInt16(data, 16)}]");
			Console.Write($"\t[Code: {BitConverter.ToUInt16(data, 18)}]");
			Console.Write($"\t[Value: {BitConverter.ToInt32(data, 20)}]");
			Console.WriteLine();
		}
	}
		/*
Ref: https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h
Ref: https://www.kernel.org/doc/Documentation/input/event-codes.txt

[Sec: 1551171811]    [USec: 619071]    [Type: 3 EV_ABS]    [Code: 57 ABS_MT_TRACKING_ID]    [Value: 268]  Unique ID of initiated contact
[Sec: 1551171811]    [USec: 619071]    [Type: 3 EV_ABS]    [Code: 53 ABS_MT_POSITION_X]    [Value: 337] Center X touch position 
[Sec: 1551171811]    [USec: 619071]    [Type: 3 EV_ABS]    [Code: 54 ABS_MT_POSITION_Y]    [Value: 403] Center Y touch position
[Sec: 1551171811]    [USec: 619071]    [Type: 1 EV_KEY]    [Code: 330 BTN_TOUCH]    [Value: 1] 
[Sec: 1551171811]    [USec: 619071]    [Type: 3 EV_ABS]    [Code: 0 ABS_X]    [Value: 337] 
[Sec: 1551171811]    [USec: 619071]    [Type: 3 EV_ABS]    [Code: 1 ABS_Y]    [Value: 403]
[Sec: 1551171811]    [USec: 619071]    [Type: 4 EV_MSC]    [Code: 5 MSC_TIMESTAMP]    [Value: 0] 
[Sec: 1551171811]    [USec: 619071]    [Type: 0 EV_SYN]    [Code: 0 SYN_REPORT]    [Value: 0] Indicate the batch is completed and we can proceed
		*/

All the documentation about the types, code, etc. is available from source of Linux (https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h).

The structure look like the following (4bit):

(C lang)

struct input_event {
	struct timeval time; // 2 unsigned uint32 or uint64
	unsigned short type; // 4 bit
	unsigned short code; // 4 bit
	unsigned int value;
};

The official documentation can be found at https://www.kernel.org/doc/Documentation/input/input.txt under the section 3.2.4 evdev and we can read the following:

The event codes are the same on all architectures and are hardware independent.

https://www.kernel.org/doc/Documentation/input/input.txt

How should we test?

It looks obvious, but in windows you might not be able to test/debug. You need a Linux system (Not subsystem). Since I use a touch panel with Linux, I simply logged the event output while I was experimenting the touch panel. I then replayed that same data while writing UT (TDD). After your TDD passes and that your event gets out as expected, you can then have the desired flow within your application. If you’ve never experimented, know that you can do remote debugging from Visual Studio (or code) to a Linux host. It works well and you might be able to debug more easily.

Existing library to support you

Here we go directly in the raw content, however, there’s a NuGet package that might help you realize what you need. As discussed in the beginning of the article, the HID is the keyword you want to look for, for such development. I haven’t played that much with the following library, but you should definitely use it in case you want to manage the devices from Dotnet. That library is OS agnostics and does not really care if you are on Windows, Linux or MacOS.

• NuGet Library: https://www.nuget.org/packages/HidSharp/
• GitHub Page: https://github.com/directhex/hidsharp

The only issue with that library is the lack of documentation. The best is to read the code itself or simply code everything by yourself.

What are we building?

The example will be simple and will be doing the following:

• Take JSON input
• Transform that JSON into an object (In this case, an object containing a dictionary)
• Pass through all the items from the dictionary and match the key against an enum which will be used to generate code
• Use reflection on the dictionary key enum (if it exists) and create a new special object with the dictionary value
• Print out the generated data using JSON prettify option

Building block #1 – JSON input

The JSON input will be quite simple, it will be an object containing a simple dictionary.

{ "MyDictionary": { "Key1": 1, "Key2": 2, "Key3": 3.1416 } }

Building block #2 – Basic objects structure

We now know the JSON structure, so let’s create our basic objects. Here we go a bit further than simply creating objects, we also create the Attribute which will be used during the “Reflection”.

class SampleObject
{
    public Dictionary<string, decimal> MyDictionary { get; set; }
}

public class CustomAttribute : Attribute
{
    public string CustomValue { get; set; }

    public CustomAttribute(string customValue)
    {
        CustomValue = customValue;
    }
}

 enum MyDictionarySpecialKeys
 {
     [Custom("Simple Value")]
     Key1,
     [Custom("Another Simple Value")]
     Key3
 }

 class MySpecialItem
 {
     public string Special { get; set; }
     public string OriginalKey { get; set; }
     public string Value { get; set; }
 }

Dive in the reflection

Now that we have all the basic object, let’s talk about the Reflection. I will not repeat what you can find on the MSDN, but rather show you directly a possible usage. The Reflection, as the name indicate, can go and read through the assembly and see how the objects are made and give you useful information. Recently, I used it in order to take a JSON configuration (appsettings section) and then generate code to be executed in the background based on that. I will not explain further that application.

Let’s begin, we will be taking our “Attribute” from the enum value and use the value provided. Then from that, instead of simply returning a simple string, let’s return a new Object. In this implementation, I will be using an extension method for simplicity. The same could be done using a simple method.

public static class CustomAttributeExtension
{
    internal static MySpecialItem GenerateEvent(this MyDictionarySpecialKeys myKey, decimal val)
    {
        // Get the member from the Enum
        var memberInfo = typeof(MyDictionarySpecialKeys)
            .GetMember(myKey.ToString())
            .FirstOrDefault();

        // If the enum member exists, then let's get the attribute
        if (memberInfo != null)
        {
            var attr = (CustomAttribute)memberInfo
                    .GetCustomAttributes(typeof(CustomAttribute), false)
                    .FirstOrDefault();

            if (attr == null)
            {
                // Should skip, if not exists
                return null;
            }

            // If enum contains the attribute let's create an object
            return new MySpecialItem
            {
                Special = attr.CustomValue,
                OriginalKey = myKey.ToString(),
                Value = val.ToString(CultureInfo.InvariantCulture)
            };
        }

        // Should skip
        return null;
    }
}

Let’s put all together in a program

If we take all of what we’ve done so far and put this into a program. We will have a JSON having 3 items in a dictionary. However, that dictionary will have only two entries mapped on the strongly typed enum. From that enum, the two enum members will be decorated with a custom attribute giving a special extra meaning to the value.

That put into code will give you something like this:

public class Program
{
    public static void Main()
    {
        var jsonInputSample = "{ \"MyDictionary\": { \"Key1\": 1, \"Key2\": 2, \"Key3\": 3.1416 } }";
        Console.WriteLine($"Input: {jsonInputSample}");

        var deserializedObject = JsonConvert.DeserializeObject<SampleObject>(jsonInputSample);
        var generatedSpecialItems = new List<MySpecialItem>();

        Console.WriteLine();
        Console.WriteLine("Content of [MyDictionary]:");

        foreach (var dictionaryItem in deserializedObject.MyDictionary)
        {
            Console.WriteLine($"\tDictionary [Key: {dictionaryItem.Key}] [Value: {dictionaryItem.Value}]");
            if (Enum.TryParse(dictionaryItem.Key, true, out MyDictionarySpecialKeys specialKey)
                && Enum.IsDefined(typeof(MyDictionarySpecialKeys), specialKey))
            {
                var specialItem = specialKey.GenerateEvent(dictionaryItem.Value);

                if (specialItem != null)
                {
                    generatedSpecialItems.Add(specialItem);
                }
            }
        }

        Console.WriteLine();
        Console.WriteLine("Result (Could be special items to be inserted in a DB):");
        Console.WriteLine("-----------------------------------------");
        Console.WriteLine(JsonConvert.SerializeObject(generatedSpecialItems, Formatting.Indented));
        Console.WriteLine("-----------------------------------------");
        Console.WriteLine("Completed");
        // Console.ReadKey(); // If you wish to wait when you run from Visual Studio and not command line.
    }
}

And the output result will be:

Input: { "MyDictionary": { "Key1": 1, "Key2": 2, "Key3": 3.1416 } }

Content of [MyDictionary]:
        Dictionary [Key: Key1] [Value: 1]
        Dictionary [Key: Key2] [Value: 2]
        Dictionary [Key: Key3] [Value: 3.1416]

Result (Events to be created):
-----------------------------------------
[
  {
    "Special": "Simple Value",
    "OriginalKey": "Key1",
    "Value": "1"
  },
  {
    "Special": "Another Simple Value",
    "OriginalKey": "Key3",
    "Value": "3.1416"
  }
]
-----------------------------------------
Completed

A complete example of a standalone project can be found on Github (https://github.com/Nordes/HoNoSoFt.PushChartToConfluence.Sample).

Introduction

Like I said, we will have an application serving some charts using the Canvas (HTML5) technology. We will then resize, take a snapshot and then transmit this file to our backend server. Then it will connect to confluence, look at the existing attachments and if it exists it will update using a comment or in the case where the file does not exists, we will be posting a new file. It is nice to update the file, but why not add the file (image) to the page if it is not already there.

Proposal using a chart

Note that we’re going to add the chart, but the same flow could be used to also update some comment/text. As long as you are familiar with html syntax, you should be able to do something good.

Pre-requisites before starting

1. If you already have a confluence server or follow the official installation guide from Confluence, skip to #3 (Create a small application)
2. For the docker users, let’s go towards the evaluation “just because”
   1. docker pull atlassian/confluence-server:latest
      1. About 700mo
   2. While it download, you can start by requesting a KEY
      1. https://my.atlassian.com/license/evaluation
      2. Select a Confluence server license and keep that page open until the docker image is ready.
   3. Start the docker image
      • Command: docker run -v $volume$:/var/atlassian/application-data/confluence --name="confluence" -d -p 8090:8090 -p 8091:8091 atlassian/confluence-server
        • $volume$: C:/demo/your/confluence/home
      • Open site: http://localhost:8090/
   4. During installation, fetch the Server ID and input it in the evaluation page.
      1. Follow the instructions
         1. Select trial
         2. Get the Server ID
         3. Go on your atlassian page already open and paste it
         4. Generate your key
         5. Copy/paste your key in the form within the confluence page
         6. Click next (wait a little) and voilà
         7. Setup a user or two and then let’s start
3. Create a small application with ChartJs (or use the one built in the previous post )

Back-End

In the back-end, we will first be receiving the image to at least test our local upload between front-end and back-end. After, we will start integrating the Confluence connexion.

Dotnet ImagesController: Receive Images (Part 1)

Within Dotnet Core, we can receive files or forms controls using the IFormCollection. I don’t think it is common to receive such thing, but when talking about receiving files, this comes handy. The client (JavaScript) will then create a collection and send it using a multipart/form-data. In there we can find many things, however what we will only using here are the files (((IFormCollection)MyFormCollection).Files).

Let’s create a controller named ImagesController we will receive the files as stream and then copy those files to a temporary folders. If you already played around with file streaming you can probably skip this part.

[Route("api/[controller]")]
[ApiController]
public ImagesController : ControllerBase {
    // .. some constructor stuff

    /// <summary>
    /// This will save the image in your local "temp" folder.
    /// </summary>
    [HttpPost]
    [ProducesResponseType((int)HttpStatusCode.Created)]
    public async Task<IActionResult> PostAsync(IFormCollection formCollection)
    {
        var files = formCollection.Files;
        long size = files.Sum(f => f.Length);
        List<string> fileList = new List<string>();

        foreach (var formFile in files)
        {
            // full path to file in temp location
            var filePath = Path.GetTempFileName();
            if (formFile.Length > 0)
            {
                using (var stream = new FileStream(filePath, FileMode.Create))
                {
                    // Save to file... We could remove the await, have a List<Task<..>> and then do a Task.WhenAll(myList)
                    await formFile.CopyToAsync(stream);
                    fileList.Add(filePath);
                }
            }
        }

        // Example of processed uploaded files returning details of the new file + original request.
        // You shouldn't rely on (or) trust the FileName property without validation.
        return Ok(new { count = files.Count, size, fileList });
    }
}

This is named Part 1 since we will come back in that code in order to add some code to send to confluence.

Front-End

Do the snapshot

From JavaScript, we have two methods that are quite handy to take snapshot of a Canvas. The first one is “toBlob(…)” and the second is “toDataUrl(…)“. While “toBlob” is not supported everywhere, I find it more useful for the demo, otherwise feel free to use “toDataUrl” for all browsers supports except Edge and then convert that base64 into a binary data (image/png). In case you go towards the “toDataUrl” method, don’t forget that you will have to transform the data once it’s server side for something readable (binary) as an image/png.

You will see in the next sub-section how to start from a ChartJs chart which you’d like to push to your back-end having a resolution of 1200px wide. Don’t forget that if you use an adaptive screen UX, it will not be displayed as 1200px until you do a snapshot for a fraction of a second.

How does the resizing work?

As you already know, a ChartJs canvas does not resize automatically at your wishes and if you want a snapshot, you are required to hack your way. Next, we are going to have the following flow:

Interesting part in the JS, I will skip the trivial step of generating a chart since you’re I suspect that you’re already able to do so.

// Some code (I used VueJs, but other language should look alike)

snapshot: function () {
  // Resize to desired size, bigger it is, more heavy will be the blob file.
  this.$refs.chartContainer.style.width = '1200px'
  this.chart.resize()
  var ctx = this

  // Do a snapshot
  this.$refs.chart.toBlob(function (blob) {
    // Resize back to original size
    ctx.$refs.chartContainer.style.width = ""
    ctx.chart.resize()

    // Prepare the form post
    // The file name used will be the chart title, but depending on your case, you
    // might want to have something more precise based on parameter (hash, encoding, something). 
    var filename = `${ctx.chartConfig.options.title.text}.png`
    var data = new FormData()
    data.append('file', blob, filename)

    const config = {
        headers: { 'content-type': 'multipart/form-data' }
    }

    // Post the file to your backend
    ctx.$http.post('/api/images', data, config)
    // Later in the article it should become as
    // ctx.$http.post('/api/images/confluence/{desiredPageId}', data, config)
  }, "image/png", 0.95);
}

// Some code

As you can see, I resize to 1200px => snapshot (toBlob) => resize back to original => send the file as multipart/form-data to the api.

The file should normally be created within your temp folder and the exact location will come back through the API. It is also part of the current data contract. Now that you have that, you can consider yourself ready for the next step, which is to transfer that buffered binary data directly to confluence using their API’s.

Back-end Part 2 – Use confluence API’s

Now that we know we can receive file and save it, we now simply need to use the Confluence API’s from Atlassian. The related documentation for that is:

• How to do basic authentication with Confluence
• Confluence REST API’s description (Pretty much all you need) (for version 6.13 at time of this writing)

API’s that we’re going to use for this demo are:

• [GET] api/content/{pageId}/child/attachment?filename={formFile.FileName}&expand=version
  • Search/Retrieve the existing attachment. In case it does not exists, it will sends back an empty array.
• [POST] api/content/{pageId}/child/attachment/{attachmentData.Id}/data
  • Update in case of existing attachment
• [POST] api/content/{pageId}/child/attachment
  • Create the attachment resource if it was not already existing
• [GET] api/content/{pageId}?expand=version,body.storage
  • Retrieve the details on the current page, especially the body specified in readable/editable way (storage). The version is also mandatory when you want to update the page.
• [PUT] api/content/{pageId}
  • Api used in order to update the confluence page.

Update the ImagesController to forward to Confluence

There’s maybe more code than required in the controller. The proper approach would be to use a IDataProvider injected (for UT) and then implement the provider using the IHttpClientFactory. That way, all would be testable and also it would also put the logic where it should be. However, let’s put all for now in one place and please adapt for your needs.

// some code in the controller

        /// <summary>
        /// Receive 1 or more images to be sent to Confluence server.
        /// </summary>
        /// <param name="formCollection">The form data (only files are being consumed)</param>
        /// <param name="pageId">The confluence page Id</param>
        /// <remarks>
        /// More details can be found at https://developer.atlassian.com/server/confluence/confluence-rest-api-examples/
        /// </remarks>
        [HttpPost("confluence/{pageId}")]
        [ProducesResponseType((int)HttpStatusCode.Created)]
        public async Task<IActionResult> PostToConfluence(IFormCollection formCollection, int pageId)
        {
            var files = formCollection.Files;
            long size = files.Sum(f => f.Length);
            List<string> fileList = new List<string>();
            var forwardAttachmentTasks = new List<Task<FileTransferResult>>();

            foreach (var formFile in files)
            {
                if (formFile.Length > 0)
                {
                    forwardAttachmentTasks.Add(ForwardFileToConfluence(pageId, formFile));
                }
            }

            // In case we had multiple tasks at the same time.
            await Task.WhenAll(forwardAttachmentTasks.ToArray()).ConfigureAwait(false);
            await UpdatePage(pageId, forwardAttachmentTasks).ConfigureAwait(false);

            return StatusCode((int)HttpStatusCode.InternalServerError, new { count = files.Count, size, fileList });
        }

        private async Task UpdatePage(int pageId, List<Task<FileTransferResult>> forwardTasks)
        {
            if (forwardTasks.Any())
            {
                // Update the page
                var pageContentResult = await _confluenceHttpClient.GetAsync($"content/{pageId}?expand=version,body.storage");
                var pageContentData = JsonConvert.DeserializeObject<Models.Confluence.Content.ContentStorage>(await pageContentResult.Content.ReadAsStringAsync());

                string newContent = string.Empty;
                foreach (var sentAttachmentTask in forwardTasks)
                {
                    var sentAttachment = await sentAttachmentTask;
                    if (sentAttachment != null && sentAttachment.Results.Any())
                    {
                        // Add the file if not present on the page.
                        var fileName = sentAttachment.Results.First().Title;
                        if (pageContentData.Body.Storage.Value.IndexOf($"<ri:attachment ri:filename=\"{fileName}\" />") == -1)
                        {
                            newContent += $"<h2>You've just pushed: {fileName}</h2><p><ac:image><ri:attachment ri:filename=\"{fileName}\" /></ac:image></p>";
                        }
                        // Else: Nothing to do, it's already on the page somewhere.
                    }
                }

                // Update object (camelCase mandatory, so use a proper serializer in real life scenario)
                var updateQuery = new
                {
                    id = pageContentData.Id,
                    title = pageContentData.Title,
                    status = pageContentData.Status,
                    type = pageContentData.Type,
                    version = new { number = pageContentData.Version.Number + 1 },
                    body = new
                    {
                        storage = new
                        {
                            value = pageContentData.Body.Storage.Value + newContent,
                            representation = "storage"
                        }
                    }
                };

                var result = await _confluenceHttpClient.PutAsJsonAsync($"content/{pageId}", updateQuery);
            }
        }

        private async Task<FileTransferResult> ForwardFileToConfluence(int pageId, IFormFile formFile)
        {
            // Start getting if attachment exists
            var getIfAttachmentExists = _confluenceHttpClient.GetAsync($"content/{pageId}/child/attachment?filename={formFile.FileName}&expand=version").ConfigureAwait(false);
            // While previous request goes on, let's get the file.
            byte[] data;
            using (var br = new BinaryReader(formFile.OpenReadStream()))
            {
                data = br.ReadBytes((int)formFile.OpenReadStream().Length);
            }

            ByteArrayContent bytes = new ByteArrayContent(data);
            MultipartFormDataContent multipartContent = new MultipartFormDataContent();
            multipartContent.Add(bytes, "file", formFile.FileName);

            var attachmentRequestData = await getIfAttachmentExists;
            if (attachmentRequestData.IsSuccessStatusCode && attachmentRequestData.StatusCode == HttpStatusCode.OK)
            {
                // Page exists and no errors...
                var attachmentRequestContent = await attachmentRequestData.Content.ReadAsStringAsync().ConfigureAwait(false);
                var attachmentData = JsonConvert.DeserializeObject<FileSearch>(attachmentRequestContent);

                HttpResponseMessage putAttachmentResponse;
                // Update existing data.
                if (attachmentData.Size == 1)
                {
                    multipartContent.Add(new StringContent($"Automatic update/upload from TestApplication ;)."), "comment");
                    putAttachmentResponse = await _confluenceHttpClient.PostAsync(
                        $"content/{pageId}/child/attachment/{attachmentData.Results.First().Id}/data",
                        multipartContent);

                    // Result is 1 "item"
                    var content = await putAttachmentResponse.Content.ReadAsStringAsync().ConfigureAwait(false);
                    var result = JsonConvert.DeserializeObject<Models.Confluence.Result>(content);

                    return new FileTransferResult() { Results = new Models.Confluence.Result[] { result }, Size = 1 };
                }
                else
                {
                    // Create the attachment
                    multipartContent.Add(new StringContent($"Automatic upload from TestApplication ;)."), "comment");
                    putAttachmentResponse = await _confluenceHttpClient.PostAsync(
                        $"content/{pageId}/child/attachment",
                        multipartContent);

                    // Result is a list of item.
                    var content = await putAttachmentResponse.Content.ReadAsStringAsync().ConfigureAwait(false);
                    return JsonConvert.DeserializeObject<FileTransferResult>(content);
                }
            }

            return default(FileTransferResult);
        }

// some code in the controller

It’s a lot of code. By reading it, it should be really easy to understand. During the file upload to Atlassian Confluence, we add a comment (updated or created) and the version gets updated. That way you could show the changes over time.

What else you could do?

• Transform the backend in order to have a provider injected
• Create UT
• Create IT
• Change the token used in order to use the official Atlassian flow for plugins
• Automate everything back-end by creating a scheduled job (not tested, but should be feasible)
  1. Selenium
  2. Image docker + chromium
  3. Execute the javascript using chrome Webdriver
  4. Send the image using a job.
• Send a SnapShot (not necessarily from Charts) while building your backend app in a pipeline.

Conclusion

Thank you for reading and I hope you have learned something today, or at least enjoyed this article.

Pré-requis

• Docker en local
• Client heroku (CLI) installé et configuré
• Git, pour cloner un repository
• Dotnet core 2.1.x installé (ou plus récent)

Exécuter en local

Docker: Images à pré-télécharger

Le build va reposer principalement sur 2 images. Ces images peuvent aussi être téléchargée automatiquement lors du lancement de la commande docker build lors d’une étape subséquente. Si vous voulez lancer les téléchargements en avance, lancez les commandes “docker pull” suivantes:

> docker pull microsoft/dotnet:2.1.500-sdk-alpine3.7 
> docker pull microsoft/dotnet:2.1.6-aspnetcore-runtime-alpine3.7

Créer un projet, ou faire du scaffolding

Je vais opter pour du scaffolding sur un de mes templates. Pour lancer l’installation du template en local faite à partir d’un dossier vide dotnet new -i HoNoSoFt.DotNet.Web.Spa.ProjectTemplates. Ensuite, faire dotnet new vuejs-picnic afin de lancer le scaffolding.

Cette étape n’est sans doutes pas obligatoire, mais sachez qu’Heroku vous procure le HTTPS sans doute en utilisant un reverse proxy (je ne fait que supposer ici). Du coup, vous pouvez désactiver le HTTPS du le projet surtout si vous n’avez pas de certificat valide. Le fichier a modifier est le Startup.cs, mettez en commentaire les lignes app.UseHttpsRedirection(); et app.UseHsts();.

À priori, vous avez votre projet disponible. Vous pourrez donc effectuer un  dotnet build histoire de vous assurer que le build fonctionne. Et ensuite  dotnet run vous permettra de voir avec Kestrel votre site sur https://localhost:5001/.

Faire un build local de votre image Docker

Comme vous l’avez sans doute constaté, ou pas, le projet template utilisé pour le scaffolding contenait déjà un fichier Dockerfile. Ce fichier décrit comment effectuer un build et ensuite vous donne l’option d’exécuter l’image en local.

Contenu du fichier:

####################################################
# To build your own image: 
#    > docker build -t honosoft/vuejs-picnic:latest -t honosoft/vuejs-picnic:1.0 .
# To run your image once it's ready:
#    > docker run -d -p 39803:80 --name vuejs-picnic honosoft/vuejs-picnic
# To push the image into your docker repository:
#    > docker push honosoft/vuejs-picnic:latest
# If you wish to remove your dangling images, please do the following (not mandatory)
#    > docker rmi $(docker images -f “dangling=true” -q)
####################################################

# Build the container with Source code compiled
FROM microsoft/dotnet:2.1.500-sdk-alpine3.7 as buildenv
WORKDIR /source
RUN apk add --update nodejs nodejs-npm
COPY *.csproj .
RUN dotnet restore
COPY . .
# Publishing will also restore (install) the npm packages.
RUN dotnet publish -c Release -o /app/

# Stage 2 - Creating Image for compiled app
FROM microsoft/dotnet:2.1.6-aspnetcore-runtime-alpine3.7 as baseimage
RUN addgroup -S coreApp && adduser -S -G coreApp coreApp
RUN apk add --update nodejs nodejs-npm


WORKDIR /app
COPY --from=buildenv /app .
RUN chown -R coreApp:coreApp /app

# Replace the application name if required.
CMD ASPNETCORE_URLS=http://+:$PORT dotnet Sample.Heroku.dll

IMPORTANT! Si vous utilisez “ENTRYPOINT” pour lancer l’application, ça marchera en local mais pas sur Heroku. Ce qui fait en sorte que vous devrez remplacer la commande par “CMD”, pour plus de détails cliquer ici

Comme avez pu le constater, mon projet s’appelle Sample.Heroku et le point d’entrée afin de démarrer le conteneur sera le fichier Sample.Heroku.dll. Les images utilisée sont la SDK afin de faire la compilation et ensuite l’image Runtime afin d’exécuter la publication en mode Production.

Pour bâtir votre docker, exécuter la commande docker build -t honosoft/sample-heroku:latest .. L’image devrait faire dans les 200mb décompressé et environs 80mo compressée. Il y a des moyens afin de diminuer cela, mais pour le moment on se contentera des images par défaut fournie par Microsoft.

Une fois le build terminé, vous pourrez lister vos images avec la commande docker images. Si votre image s’est construite sans soucis, vous pourrez passer à l’étape suivante, sinon vous devrez faire des corrections par rapport aux erreurs.

Lancer l’image docker en local pour tester

Rien de plus simple, par défaut, docker avec dotnet core utilise le port 80 en interne. Du coup, pour lancer votre image, effectuer la commande suivante:

docker run -d -p 8080:80 --name sample-heroku honosoft/sample-heroku

Votre image devrait donc désormais être disponible en atteignant http://localhost:8080 par le proxy créé par Docker (Port 80 sur Docker et exposé sur votre machine sur 8080).

Déploiement sur Heroku

Créer une application sur Heroku

À partir du dashboard, simplement créer une nouvelle application. Dans mon cas, l’application sera “morning-oasis-26273”.

Deploiement avec le CLI

Vous connecter à votre compte Heroku avec le CLI:

heroku login
heroku container:login

Comme vous le feriez pour envoyer vers les registres de Docker privé, effectuer un tag Heroku de votre image fraîchement créée. Ensuite, vous n’aurez qu’à faire un push (à la git), de votre image vers votre site web.

docker tag honosoft/sample-heroku registry.heroku.com/morning-oasis-26273/web
docker push registry.heroku.com/morning-oasis-26273/web

Alternativement au docker tag/push vous pouvez aussi utiliser la commande Heroku qui effectuera les 2 commandes en une seule:

heroku container:push web -a morning-oasis-26273

Lors du push, ça prendra un peu de temps tout dépendant de votre connexion internet. Le push, tel que pour GIT enverra la différence vers le serveur de registre Docker. Le premier push prendra un peu plus de temps, mais les push subséquents seront rapide et avec un faible volume de données à envoyer.

Tout ce qui reste à faire maintenant, est d’activer votre image sur le site Heroku à l’aide du CLI:

heroku container:release web -a morning-oasis-26273

Avant d’atteindre votre application, vous pouvez tout démarrer les traces logs. Ce sera utile en cas de problème (conteneur qui ne démarre pas par exemple).

heroku logs --tail -a morning-oasis-26273

Conclusion

C’était peut-être un peu plus long que prévu. Mais le tout fonctionne, bonne journée!

If we look what we have in Dotnet world, we have something very similar that have been existing for a long time. It’s still rare to see such system being used. It will more likely already exists without having anyone really having to maintain it. Since in Dotnet Core 2.1, the namespaces changed a bit, it makes it interesting to explore with you. I guess that if you are on this post, you are most likely a technical guy. I assume that you’ve already done some research on what it is and that you’d like an example (step by step) to really show how easy it is to build. In this article we’ll cover only partially the Manageed Extensibility Framework (MEF).

Edit: For Dotnet Core 3, there’s a new feature, so follow this link to MSDN.

What is the Managed Extensibility Framework (A.k.a.: MEF)?

Often you will hear about the acronym MEF instead of its long name “Managed Extensibility Framework”.  In the past we were also talking in parallel about the MAF which stands for Managed Add-in Framework (See details here). MAF still exists within the Dotnet Framework with Windows Client (WPF for example), however in Dotnet Core you it is not available “yet”.

In the introduction, I stated that if you’ve used Java, you know the main idea about it. For the others, the general idea is, that when, you or a third party, have finished to create your plugin you drop your JAR in the plugins folder.  In C#/Dotnet world, MEF and MAF are using the same principle, whereas instead of dropping a Jar you drop your “Assemblies”.

Let’s go back to the question, what is MEF? It’s a contracts based extensibility managed by imports and exports within your programs or libraries. You will then make an extensible application by implementing interfaces and then in your main application you will have a provider to provide the implemented contracts (interfaces) implemented. The Assemblies that you want to import in your main application require the exports. Those exports are going to be discovered through “Reflection“.

Let’s take the famous calculator as an example where you could extends the functionalities (plus, minus, division, etc.). Each of those functionalities could be a provided within different “Assemblies” loaded at the startup of your application. There would be no need of project references to those assemblies within your main application. So if you add or remove “Assemblies”, functionalities are going to be added or removed. The magic comes from the exports you would discover. For the calculator example, you could have a “Name” (Square Root) for what it is and the official “Operator” (√) for the discovered feature. You would then have an implementation of the operator receiving “Number 1, …” producing a new result (Contract within an interface shared between all the libraries, a.k.a. interfaces). The Imports are, as stated previously, most likely be in your main executable (WebApi, Console, etc.).

How does it works?

As stated above, the main program will do your discovery of shared contracts API’s. Those Exports/Imports are being assigned using attributes on your classes. Those attributes, to name only a few, will look like [import], [ImportMany], [ExportMetadata(“something”, “here”)], [Export(typeof(IYourInterface))], etc.. As you can see, the import will import only one instance while ImportMany will create an IEnumerable. Those attributes can be found within the Nuget package “System.Composition.AttributedModel“. Keep that package in your mind since it will become handy in a later stage.

If you wonder why the ExportMetadata can become something really cool. I would say that you could have some filtering that could come from there regarding your application. That could also help in order to give some capabilities about your module (Extensibility).

Practice time – Let’s build a simple App (WebApi/SPA)

Of course, we’re not going to be building the famous calculator sample. It’s all over the place already. I don’t say that the calculator is a not a great example, but my point here is not to copy what already exists. In this “exercise”, you will be scratching the surface of the Extensibility. In a real-world scenario, you could have logs that need to strips out content based on rules that are either common or specific. Let’s say, the customer numbers are not the same from customer to customer as such that each customer requires to have different custom rules mixed with general ones. That one could be done using simply a regex, but let’s say it goes to something really complex like the passport numbers. In that case, you could implement custom rules for each customer (per country) and simply drop those rules within the plugin folder. That way, you could even request the customer to build the plugin themselves and if you thrust them enough then simply allow them to update their plugin through a portal (upload, push, and either restart your service or then load at runtime the updated plugin).

The current exercice is to simply create a simple Web Application written in Dotnet Core 2.1 using a basic UI querying the API. It will then show the result in raw of what plugin have discovered.

Scaffold a simple WebApi and Projects

In previous posts, I said that I like to use my own template since it’s quite a good starter. It’s compact and fast enough for anyone with basic knowledge of Dotnet Core and VueJs. The UX is using, instead of the common Bootstrap 4, something lighter called Picnic CSS. You can download/update the template using > dotnet new -i HoNoSoFt.DotNet.Web.Spa.ProjectTemplates(Documentation here). This exercise can also be accomplished within a Console application. However, I think the most common scenario will be around the usage of a WebApplication and then extend it somehow. Let’s create the structure of the project (Command line, it’s easier):

> mkdir Sample.Mef
> cd Sample.Mef
Sample.Mef> dotnet new vuejs-picnic -o Sample.Mef.Web
Sample.Mef> dotnet new classlib -o Sample.Mef.Api
Sample.Mef> dotnet new classlib -o Sample.Mef.GiveMeOne
Sample.Mef> dotnet new classlib -o Sample.Mef.GiveMeFive
Sample.Mef> dotnet new sln
Sample.Mef> dotnet sln add .\Sample.Mef.Web\Sample.Mef.Web.csproj
Sample.Mef> dotnet sln add .\Sample.Mef.Api\Sample.Mef.Api.csproj
Sample.Mef> dotnet sln add .\Sample.Mef.GiveMeOne\Sample.Mef.GiveMeOne.csproj
Sample.Mef> dotnet sln add .\Sample.Mef.GiveMeFive\Sample.Mef.GiveMeFive.csproj
Sample.Mef> cd Sample.Mef.Web
Sample.Mef\Sample.Mef.Web> npm install
Sample.Mef\Sample.Mef.Web> dotnet run

Normally after completing the previous command, you should have the Web Project starting. The URL of the project will be displayed within the console or if you are in Visual Studio, it will open the start page by itself.

For the next part of the blog I will be using Visual Studio Community, but feel free to use VS Code.

Exercise: Structure Application Tree

In the following screen capture, some renaming have already taken place (1) and as indicated in the image, some files needs to be removed (2) or modified (3).

Not marked on the picture:

• Remove IWeatherProvider.cs 
• Update ServiceCollectionExtensions.cs (remove the injection of the IWeatherService).

Implement the contract in GiveMeOne & GiveMeFive

Some project will require the reference in order to be able to use IGiveNumber interface. Those relation are shown within one of the previous section (UML like)

• Add the reference of Sample.Mef.Api project to
  • Sample.Mef.GiveMeOne
  • Sample.Mef.GiveMeFive
  • Sample.Mef.Web

The interface “IGiveNumber.cs” look like:

namespace Sample.Mef.Api
{
    public interface IGiveNumber
    {
        int GiveInt();
    }
}

This contract is going to be implemented within “GiveOne.cs” and “GiveFive.cs”

using Sample.Mef.Api;

namespace Sample.Mef.GiveMeOne
{
    public class GiveOne : IGiveNumber
    {
        public int GiveInt()
        {
            return 1;
        }
    }
}

using Sample.Mef.Api;

namespace Sample.Mef.GiveMeFive
{
    public class GiveFive : IGiveNumber
    {
        public int GiveInt()
        {
            return 5;
        }
    }
}

Now you should be able to build with no errors.

Add the Composition/Extensibility to Import/Export

You remember the nuget package from earlier? It gives the simple Import/Export and a few other basic functionalities. In our case, we will be using it simply for exporting the implemented interface. Let’s install it:

• Add Nuget package “System.Composition.AttributedModel” to
  • Sample.Mef.GiveMeOne
  • Sample.Mef.GiveMeFive

Add the “Export” attribute

Now, let’s update our two previously defined classes (GiveOne, GiveFive) and add our exports. Those exports allow the Reflection, in a later stage, to discover the implementations. Some customization could also be done, but for that, rely on the MSDN documentation.

Within the two previous project mentioned, add the following Export attribute:

using System.Composition;
// Some code...

[Export(typeof(IGiveNumber))]
public class ...// some code...

Add the “Import” matching the previous “Export” within a provider

This part is only modify “Sample.Mef.Web” project. As we’re going to create a new provider, let’s make it properly by using Dependency Injection (DI). Within the provider, we will also be using System.Composition. This is will help doing the discovery of the plugin(s).

1. Add the Nuget package reference to the project: “System.Composition“
2. Create an IGiveNumberProvider + GiveNumberProvider
3. Update the startup to inject the new provider

We will put IGiveNumberProvider and GiveNumberProvider within the same file, but it’s a sample and you can also do as you please.

using Sample.Mef.Api;
using System.Collections.Generic;
using System.Composition;
using System.Composition.Hosting;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Runtime.Loader;

namespace Sample.Mef.Web.Providers
{
    public class GiveNumberProvider : IGiveNumberProvider
    {
        public GiveNumberProvider()
        {
            Compose();
        }

        [ImportMany]
        public IEnumerable<IGiveNumber> Services { get; private set; }

        public IEnumerable<(string Id, int Value)> GetNumberFromAllFoundServices()
        {
            return Services.Select(f => new { Id = f.GetType().ToString(), Value = f.GiveInt()})
                .AsEnumerable()
                .Select(c => (c.Id, c.Value))
                .ToList();
        }

        private void Compose()
        {
            // Catalogs does not exists in Dotnet Core, so you need to manage your own.
            var assemblies = new List<Assembly>() { typeof(Program).GetTypeInfo().Assembly };
            var pluginAssemblies = Directory.GetFiles("d:\\plugins\\", "*.dll", SearchOption.TopDirectoryOnly)
                .Select(AssemblyLoadContext.Default.LoadFromAssemblyPath)
                // Ensure that the assembly contains an implementation for the given type.
                .Where(s => s.GetTypes().Where(p=> typeof(IGiveNumber).IsAssignableFrom(p)).Any());

            assemblies.AddRange(pluginAssemblies);

            var configuration = new ContainerConfiguration()
                .WithAssemblies(assemblies);

            using (var container = configuration.CreateContainer())
            {
                Services = container.GetExports<IGiveNumber>();
            }
        }
    }

    public interface IGiveNumberProvider
    {
        IEnumerable<(string Id, int Value)> GetNumberFromAllFoundServices();
    }
}

The code should be clear enough in order for you to understand what it does. However, let’s explain quickly:

• It’s important to note that I’ve set the Assemblies for the extensibility available in the “d:\plugins\” (Please adapt)
• We filter using reflection on the assemblies. This will enforce keeping only those that have at least one implementation from IGiveNumber
• In case the assembly can be loaded from the container, we take the related “Export” implementing IGiveNumber and push that within the services
• You can now access the implementations through the “Services” (Property field)
  • I use the Tuple as a return type, some of it is new in the C# 7+. In case you’ve missed that new feature, go on the following Blogs MSDN article

Add the Dependency Injection (DI)

Now that the provider is ready, let’s add the DI within Startup.cs. The usage of Singleton is privileged since we don’t want to rediscover at each HTTP requests.

// Code ...
        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            // code ...

            // Example with dependency injection for a data provider.
            services.AddSingleton<IGiveNumberProvider, GiveNumberProvider>();
        }
// Code ...

Alter the existing “api/values” endpoint in order to get the provider “values”.

using Microsoft.AspNetCore.Mvc;
using Sample.Mef.Web.Providers;

namespace Sample.Mef.Web.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        private readonly IGiveNumberProvider _giveNumberProvider;

        public ValuesController(IGiveNumberProvider giveNumberProvider)
        {
            _giveNumberProvider = giveNumberProvider;
        }

        // GET api/values
        [HttpGet]
        public IActionResult Get()
        {
            return Ok(_giveNumberProvider.GetNumberFromAllFoundServices().ToList().Select(f=> new { f.Id, f.Value }));
        }

        // Code
}

It’s now mostly complete. I would even say that you must put your project Assemblies (DLL) in “d:\plugins” or where you’ve decided to discover them. The assemblies we’re going to look for are described next.

Time to test by moving your dll’s in the plugins folder

Since you’ve already built, or maybe not yet, your solution, it’s now the time to bring the assemblies (dll) from Sample.Mef.GiveMeOne, Sample.Mef.GiveMeFive available through the bin directory. You then move them to the “d:\plugins”, or the reconfigured folder from previous step. When you copy your bin folder, you need to copy not only the Sample.Mef.GiveMeOne, you also need to copy it’s dependencies (i.e.: Sample.Mef.Api). Since the System.Composition is included in the Web project, it is not mandatory to have a copy in related assemblies plugin folder.

The plugin folder will then contains:

• Sample.Mef.GiveMeOne.dll
• Sample.Mef.GiveMeFive.dll
• Sample.Mef.Api.dll

Start your application and look at the results

Purely speaking, do a dotnet run from the Web application folder, or in Visual Studio push F5.

Go see if your API’s is answering properly before the last step

[Optional] Update your UX in order to do the call

The output is going to simply show a list from the homepage. The extensions to your project, after being loaded, will be displayed within the result of the API call.

<template>
  <div>
    <page-title title="Give the Extensions" />
    <p>He you will be finding your loaded extensions:</p>
    <ul>
      <li v-for="(data, idx) in numbers" :key="idx">{{data.id}}
          <ul>
            <li>{{data.value}}</li>
          </ul>
      </li>
    </ul>
  </div>
</template>

<script>
export default {
  data () {
    return {
      numbers: []
    }
  },

  mounted() {
    this._getNumbers()
  },

  methods: {
    async _getNumbers () {
      let response = await this.$http.get(`api/values`)
      this.numbers = response.data
    }
  }
}
</script>

Simply run the application and go on the home page. In my case, while using IIS Express, it gave me https://localhost:44307

Final result

Extra Resources

Those resource were not used that much during this blog post, but I think it can help people to also understand how it works in a different context.

• Official: https://docs.microsoft.com/en-us/dotnet/framework/mef/
• https://dotnetthoughts.net/using-mef-in-dotnet-core/
• https://blog.softwarepotential.com/porting-to-net-standard-2-0-part-2-porting-mef-1-0-to-mef-2-0-on-net-core/

Thank you!

By the way, all the source code is available in GitHub (personal @Nordes repository). Enjoy

Featured image original is from: https://unsplash.com/photos/l090uFWoPaI

This article will only do a quick start using the template I’ve created recently in Dotnet Core. I won’t put too much details around the code since it’s quite straight forward.

Pre-requisites

• Dotnet core 2.1 (at the time of writing)
• NodeJs + NPM (>10 at the time of writing)
• Visual Studio Code OR Visual Studio Community/Professional
• A browser (Chrome, or anything else)

Install a quick start from a Dotnet Core template

As mentioned before, you will be using a quick start I created. I use it quite often, so there’s improvement in it happening regularly. So I suggest you to look for updates once in a while. It gives a front-end that could run without backend, and a backend in dotnet core 2.1 ready to serve API’s (including swagger).

> dotnet new -i HoNoSoFt.DotNet.Web.Spa.ProjectTemplates

Once installed, let’s create our template (vuejs-picnic-table):

> mkdir Sonar.Reports
> cd Sonar.Reports
> dotnet new vuejs-picnic-table

And to be sure it works, then let’s run at least in development mode.

> npm install
> dotnet run --environment="Development"

The installation of the NPM packages are needed most likely the first time due to the nature of the project. This could be automated, but would make the project takes a lot of time before even being able to start editing any files. (Personal choice here)

The result should look like the following screen (https://localhost:5001/) OR the demo page available here.

You might get an error the time Webpack generate the files. In that case, simply hit refresh (F5)

Once the application is running, keep it running while you edit your files (next step). You will simply have to hit F5 to refresh the changes.

Clean or add route to the template

Delete all the un-necessary things or simply add a new page. We’ll go here with the latter.

• Create the file: ./ClientApp/pages/sonar.vue

  • <template>
     <div>
       <page-title title="Sonar" />
     </div>
    </template>
    
    <script>
    export default {
      
    }
    </script>
    

• Add the new route for the page in ./ClientApp/router/routes.js
  • Add a import in the import section: import Sonar from 'pages/sonar'
  • Add the route after about:  { name: 'Sonar', path: '/:lang?/sonar', component: Sonar, display: 'Sonar', i18n: 'route.sonar', icon: 'icon-home', meta: { order: 6 } },
• Add the translation/I18n for the new menu in ./ClientApp/_i18n/lang/en.js
  • In the routes group under about, add: sonar: 'Sonar'
• Save all this and hit F5 in the browser

Congratulation! You’ve created your first page in VueJs. Now it is the time to fill the data and before that, we need to create a service provider.

Access to Sonar Qube API’s from C#

Create your provider in C#, because if you’re not on the same server as your SonarQube, you might get some issue by only using the front-end. Here, we will be creating a simple proxy without any parameters. For those of you who didn’t know, the API is available at your SonarQube URL like the following: https://mySonarQube.url.com/api/.

Generate an API key for your user

• Go in your account (top right icon)
• Go under security
• Generate a new token (The name does not matters, but let’s name it: Sonar.Reports)
• Copy and paste the key somewhere you won’t loose. Otherwise you will have to re-generate the API token.

Open your project in VS Code or Visual studio

If you’re lucky enough, you will have a Properties folder, otherwise you will have to create it and add the file launchSettings.json

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "iisSettings": {
    "windowsAuthentication": false, 
    "anonymousAuthentication": true, 
    "iisExpress": {
      "applicationUrl": "http://localhost:21535",
      "sslPort": 44307
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "api/values",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "Sonar.Reports": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "api/values",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Update your ./Startup.cs and add a new Service configuration:

public void ConfigureServices(IServiceCollection services){
  // ...
  services.AddHttpClient();
  // ...
}

Create the file ./Controllers/SonarController.cs and add the following code:

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;

namespace Sonar.Reports.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class SonarController : ControllerBase
    {
        private HttpClient _sonarHttpClient;

        public SonarController(IHttpClientFactory httpClientFactory){
          _sonarHttpClient = httpClientFactory.CreateClient("sonar");
          _sonarHttpClient.BaseAddress = new Uri("https://sonar.yourSonarQube.com/api/");
          var basicToken = Convert.ToBase64String(Encoding.UTF8.GetBytes("f6d6fecfdcd7836612a0fef4a3f307b7725f8387:"));
          _sonarHttpClient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", basicToken);
        }

        /// <summary>
        /// GET Sonar data
        /// </summary>
        /// <returns>Returns an enumerable of value</returns>
        [ProducesResponseType((int)System.Net.HttpStatusCode.OK)]
        [HttpGet]
        public async Task<IActionResult> Get()
        {
            var result = await _sonarHttpClient.GetAsync("measures/search_history?component=yourComponentName&metrics=bugs%2Ccode_smells%2Cvulnerabilities%2Creliability_rating%2Csecurity_rating%2Csqale_rating&ps=1000");
            
            // Not perfect but it will do for the sample.
            return Content(await result.Content.ReadAsStringAsync());
        }
    }
}

Where:

• www.yourSonarQube.com is your address of your Sonar Qube
• The token you’ve created earlier replaces f6d6fecfdcd7836612a0fef4a3f307b7725f8387 (Don’t forget to keep the “:”, it is mandatory in a basic authentication, where it’s usually user:password in Base 64)
• yourComponentName is replaced by your real component name in Sonar Qube (To get it, open sonar qube, go in your project you want to test, and then take the value from the URL. It’s always there.)

Now, restart your application (Ctrl+C and then re-type dotnet run, if you’re in console mode).

You can test the endpoint by going to http://localhost:5001/swagger/ and use the swagger UI in order to test it. If you have errors, you will see it in your console (or output in Visual Studio).

Add the ChartJS to your project

Go in your root folder where your project is located (csproj) and then type the following command in order to install Chart.Js:

> npm install chart.js --save

Now that you have installed this new dependency, you can add the Chart.Js within your VueJs application.

Edit your ./ClientApp/pages/sonar.vue and add a default Chart.Js available through all their demo on their site. Here, I will be using the line API

<template>
  <div>
    <page-title title="Sonar" />

    <canvas ref="chart" id="canvas"></canvas>
  </div>
</template>

<script>
// Import ChartJS
import Chart from 'chart.js'

// Colors
var chartColors = [
  'rgb(255, 99, 132)',
  'rgb(255, 159, 64)',
  'rgb(255, 205, 86)',
  'rgb(75, 192, 192)',
  'rgb(54, 162, 235)',
  'rgb(153, 102, 255)',
  'rgb(201, 203, 207)'
]

export default {
  data () {
    return {
      chart: null,
      chartConfig: {
        type: 'line',
        data: {
          labels: [],
          datasets: []
        },
        options: {
          responsive: true,
          title: {
            display: true,
            text: 'Enjoy your Chart.Js with Sonar'
          },
          tooltips: {
            mode: 'index',
            intersect: false,
          },
          hover: {
            mode: 'nearest',
            intersect: true
          },
          scales: {
            xAxes: [{
              display: true,
              type: 'time',
              scaleLabel: {
                display: true,
                labelString: 'Date'
              }
            }],
            yAxes: [{
              display: true,
              scaleLabel: {
                display: true,
                labelString: 'Value'
              }
            }]
          }
        }
      }
    }
  },

  mounted () {
    this.chart = new Chart(this.$refs.chart, this.chartConfig)
    this._loadSonarData()
  },

  methods: {
    _loadSonarData: async function () {
      let response = await this.$http.get(`./api/sonar`)
      var sonarData = response.data

      // We now have measures + data
      var measures = sonarData.measures
      let allLabels = []
      for (var m = 0; m < measures.length; m++) {
        let currentColor = chartColors[m % chartColors.length]
        var data = {
          label: measures[m].metric,
          backgroundColor: currentColor,
          borderColor: currentColor,
          tension: 0, // If you don't want bezier curves
          data: [],
          fill: false,
        }

        for (var h = 0; h < measures[m].history.length; h++) {
          let date = new Date(measures[m].history[h].date)
          if (allLabels.indexOf(date) < 0) {
            allLabels.push(date)
          }

          data.data.push(measures[m].history[h].value)
        }
        
        this.chartConfig.data.datasets.push(data)
      }

      this.chartConfig.data.labels = allLabels
      this.chart.update()
    }
  }
}
</script>

Results

If you’ve followed and didn’t make any big mistakes, the result should looks somewhat like the following

Next step?

Basically, yes, there’s a next step. Since you have been able to call the Sonar Qube Api’s, you now know that you can also configure all the requests to it. For example, you could say “I want data for the last 30 days” or in my case, for the last 3 sprints and then draw vertical lines (using a plugin) in order to show exactly where are the sprint and how it went (For example: rush at the end or not).

You could also add a dropdown at the top, or different menu or customization for other projects/stats you’d like to have.

Since you’re using the canvas, don’t forget you could also make a download or extract image using JavaScript. In a way, you could auto-generate a Powerpoint or word document, or other since you have all the data required to do so.

Conclusion

I hope you’ve enjoyed this post.

Afin de répondre à cette question, il faut tout d’abord créer un template ou s’inspirer d’un existant. Notez qu’il est possible de créer des packets contenant plusieurs templates à la fois.

Comment créer un template .Net (core ou pas, c’est pas grave)

Pour débuter, on va faire ça simple. Créons un petit template C# dotnet avec rien de bien intéressant à l’intérieur a part peut être un pre-setting pour un album photo (Connection BD + Script de migration entity framework). Dans cet article, nous n’allons pas bâtir l’application, mais seulement expliquer les principes et le packaging.

Par exemple, vous pouriez faire dotnet new mvcet terminer le reste de votre projet de base (template). Ensuite, il afin de transformer ce projet en template, vous aurez à créer un répertoire spécial nommé .template.config qui se situe dans votre répertoire de projet. Ce fichier respecte doit respecter les standards Microsoft (disponible sur le site MSDN si vous cherchez un peu).

Ici par exemple vous pouriez avoir ce qui suit (Vous pouvez adapter à bon vous semble ;)):

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Nordes Menard-Lamarre",
  "classifications": [ "MVC", "PhotoGallery" ],
  "groupIdentity": "HoNoSoFt.DotNet.Web.Templates.Gallery",
  "identity": "HoNoSoFt.Gallery",
  "name": "Ce qui s'affiche dans la description",
  "preferNameDirectory": true,
  "primaryOutputs": [
    {
      "path": "HoNoSoFt.Gallery.csproj"
    }
  ],
  "shortName": "honosoft-gallery",
  "sourceName": "HoNoSoFt.Gallery",
  "sources": [
    {
      "source": "./",
      "target": "./",
      "exclude": [
        ".template.config/**"
      ],
      "modifiers": [
        {
          "condition": "(TargetFrameworkOverride == '')",
          "exclude": [
            "app.config"
          ]
        },
        {
          "condition": "(ExcludeLaunchSettings)",
          "exclude": [
            "Properties/launchSettings.json"
          ]
        }
      ]
    }
  ],
  "symbols": {
    "ExcludeLaunchSettings": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "description": "Whether to exclude launchSettings.json from the generated template."
    },
    "HttpPort": {
      "type": "parameter",
      "datatype": "integer",
      "description": "Port number to use for the HTTP endpoint in launchSettings.json."
    },
    "HttpPortGenerated": {
      "type": "generated",
      "generator": "port"
    },
    "HttpPortReplacer": {
      "type": "generated",
      "generator": "coalesce",
      "parameters": {
        "sourceVariableName": "HttpPort",
        "fallbackVariableName": "HttpPortGenerated"
      },
      "replaces": "8080"
    },
    "HttpsPort": {
      "type": "parameter",
      "datatype": "integer",
      "description": "Port number to use for the HTTPS endpoint in launchSettings.json. This option is only applicable when the parameter no-https is not used (no-https will be ignored if either IndividualAuth or OrganizationalAuth is used)."
    },
    "HttpsPortGenerated": {
      "type": "generated",
      "generator": "port",
      "parameters": {
        "low": 44300,
        "high": 44399
      }
    },
    "HttpsPortReplacer": {
      "type": "generated",
      "generator": "coalesce",
      "parameters": {
        "sourceVariableName": "HttpsPort",
        "fallbackVariableName": "HttpsPortGenerated"
      },
      "replaces": "44300"
    },
    "TargetFrameworkOverride": {
      "type": "parameter",
      "description": "Overrides the target framework",
      "replaces": "TargetFrameworkOverride",
      "datatype": "string",
      "defaultValue": ""
    },
    "Framework": {
      "type": "parameter",
      "description": "The target framework for the project.",
      "datatype": "choice",
      "choices": [
        {
          "choice": "netcoreapp2.1",
          "description": "Target netcoreapp2.1"
        }
      ],
      "replaces": "netcoreapp2.1",
      "defaultValue": "netcoreapp2.1"
    },
    "HostIdentifier": {
      "type": "bind",
      "binding": "HostIdentifier"
    },
    "skipRestore": {
      "type": "parameter",
      "datatype": "bool",
      "description": "If specified, skips the automatic restore of the project on create.",
      "defaultValue": "false"
    },
    "NoHttps": {
      "type": "parameter",
      "datatype": "bool",
      "defaultValue": "false",
      "description": "Whether to turn off HTTPS. This option only applies if Individual, IndividualB2C, SingleOrg, or MultiOrg aren't used for --auth."
    }
  },
  "tags": {
    "language": "C#",
    "type": "project"
  },


  "precedence": 100,
  "guids": [
      "6B3E8EE8-92E3-41CE-A356-A5F880EEA367"
  ],
  "postActions": [
      {
        "condition": "(!skipRestore)",
        "description": "Restore NuGet packages required by this project.",
        "manualInstructions": [
          {
            "text": "Run 'dotnet restore'"
          }
        ],
        "actionId": "210D431B-A78B-4D2F-B762-4ED3E3EA9025",
        "continueOnError": true
      }
    ]
}

Une fois ce fichier sauvegardé, ce n’est pas terminé. Vous devrez créer votre fichier “nuspec”. C’est possible de le créer à partir de Visual Studio, ou si vous avez la flemme, de le créer aussi manuellement. Dans tous les cas, vous devrez télécharger une version de nuget en ligne de commande.

Exemple de fichier nuspec (Aussi très bien documenté sur le site de MSDN):

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2012/06/nuspec.xsd">
  <metadata>
    <id>HoNoSoFt.DotNet.Web.Spa.ProjectTemplates</id>
    <authors>Nordes Menard-Lamarre</authors>
    <description>
      La description qui apparaitra sur le site de Nuget.org
    </description>
    <packageTypes>
      <packageType name="Template" />
    </packageTypes>
    <version>{{version}}</version>
    <iconUrl>https://www.honosoft.com/img/logo.png</iconUrl>
    <projectUrl>https://github.com/votre_nom/Votre.ProjectTemplates</projectUrl>
    <licenseUrl>https://github.com/votre_nom/Votre.ProjectTemplates/blob/master/LICENSE</licenseUrl>
  </metadata>
  <files>
    <file
      src="HoNoSoFt.Gallery.CSharp/**/*"
      exclude="**/node_modules/**;**/package-lock.json;**/bin/**;**/obj/**;**/.vs/**;**/.vscode/**;**/wwwroot/**"
      target="Content" />
  </files>
</package>

Ici concernant les fichiers, vous n’être absolument pas obligé d’avoir une configuration fichier par template. Si vous voulez vous simplifier la vie, vous pouvez simplement vous créer un répertoire “Contenu” et y mettre vos projets templates en C#. Ceci-dit, une fois complété, pour créer votre package “nupkg“, vous devrez lancer la ligne de commande avec nuget.

La commande est (à partir de votre répertoire nuspec) : nuget pack. Avant de lancer la commande, n’oubliez pas de mettre à jour votre numéro de {{version}}. Cette version doit être sous le standard Majeur.Mineur.Build.

Afin de tester votre template vous pourrez ensuite l’installer en effectuant: dotnet new -i votre.fichier.nupkg. Et pour voir si c’est bien installé, n’oubliez pas que vous pouvez aussi lister votre projet à l’aide de la commande dotnet new -l. Une fois que vous êtes certain que votre template est présent, vous pouvez créer un répertoire “temporaire” et tester l’initialization de votre template. La commande cette fois sera dotnet new votre-nom-de-templateet les options par défauts seront utilisées (Voir le template.json créer plus tôt).

Et si on veut ajouter d’autres templates en même temps?

Oui, c’est possible. Vous pouvez soit ajouter d’autre répertoire dans la liste des fichiers (balise files qui est dans le nuspec) ou bien si vous avez opté pour un répertoire plus global, comme “Contenu”, vous n’avez qu’à créer d’autres projets avec le répertoire .template.config. Cependant, il y a un point important. Et ce point est que vous devez impérativement avoir un nom différent dans le GroupIdentity du fichier template.json. Sinon, si vous voulez utiliser le même nom, vous devrez combiner avec des options (voir les détails du schéma)

Est-ce possible de créer des template non C# ou Microsoft

Je crois que c’est tout à fait possible et ce sera sans doute ce que je ferai dans l’avenir. J’aime bien travailler avec node pour des PoC et je crois que d’utiliser dotnet new avec les templates va faciliter le fait d’utiliser ou non un backend.

Exemple réel

Récemment, j’ai travailler sur un projet personnel qui crée un Template Dotnet Core 2.1 + VueJS + Picnic CSS + beaucoup d’autres trucs. Ce template est disponible sur https://github.com/nordes/HoNoSoFt.DotNet.Web.Spa.ProjectTemplates et vous pouvez aussi voir comment j’ai intégrer le tout avec AppVeyor pour les build automatisé et le déploiement automatique de l’artifact NuGet sur nuget.org.

Tous les détails afin d’utiliser les templates sont disponible sur le site Github ou bien sur la section Wiki de Github.

Bon coding!

Nordès