DjsBlog: Softata -An ASP.NET Core API Interface

Site Calendar

About setting up an ASP.NET Core API app enhanced with XML comments as with the SoftataWebApp app.

Try the Softata Swagger on Azure:

Link: softatawebapi on azurewebsites.net Nb Link here may change.

Will separately need the Pico up and running to action API but can c=view it here without.

Nb: Is minus MetaInfo as below … working on it.

Softata Links

The GitHub Repository: djaus2/Soft-ata
Blog posts index: Softata

About

The previous post provided an overview of the ASP.NET Core API app for the SoftataLib C# library. This library invokes individual Softata methods on a RPi Pico W running as an Arduino device. Invocation is via a TCPIP service running on the Pico. The methods interact with various devices connected to the Pico.

Softata enables the remote interaction with Arduino peripherals by a .NET app whether a Console, Blazor and now ASP.NET app.

This post look at the ASP.NET Core aspects of the SoftataWebAPI app.

Overview

The task was to create an ASP.NET Core app that wrappers the SoftataLib methods as ASP.NET Controller methods. The main classes in SoftataLib are:

SoftaLib (The main class)
- Connectivity
- low level calls to the server, etc.
Sensors
- Setup
- Read
Displays
- Setup
- Write
Actuators
- Setup
- Write

SoftatWebAPI mirrors each of those as a controller.

Setup

In Visual Studio (Version 17.9.3) a new project was created using the “ASP.NET Core Web API” template, making sure the following where enabled on the second dialog:

Enable OpenAI Support
Use Controllers

This is discussed in more detail in links 1 and 2 above.

When this is built and run you get the Swagger interface to the /WeatherForecast [Get] method.

Get Post Put Delete

The web terms Get Post Put and Delete are verbs that refer specifically to Database functions. By how do they map onto more general functionality in an ASP.NET Controller.

Get: Get information
Post: Post a new entity
Put : Update an existing entity
Delete: Delete an entity

The Softata has various methods with various types of functions. Some are clearly a Get Operation:

GetDeviceTypes
GetSensors
GetPins
ReadSensor

What about Setup for a specific device? This context has been interpreted as a Post returning Ok or Fail. With Ok, an index for the the instantiation is returned which is used to identify the device in subsequent calls

Is writing a value to a display or actuator a Post or Put? Philosophically, it is probably a Put as it is modifying an existing (instantiated) device. Post was though used also returning Ok or Fail. Disconnecting a device is probably a Delete but that disconnection is not supported by Softata.

The SensorController Interface:

namespace SoftataWebAPI.Controllers
{
    public interface ISoftataSensorController
    {
        // Get methods
        IEnumerable<string> Get(); //Get Sensors
        string GetPins(int isensor);
        IEnumerable<string> GetProperties(int isensor);
        double Read(int sensorListIndex, int property);
        IEnumerable<double> ReadAll(int sensorListIndex);
        string ReadTelemetry(int sensorListIndex);
        // Post methods
        IActionResult Setup(int isensor, int pin, List<byte> settings = null);
        IActionResult SetupDefault(int isensor);
    }
}

ActuatorController Methods

    public interface ISoftataActuatorController
    {
        // Get Methods
        IEnumerable<string> Get(); //Get Actuators
        string GetPins(int iactuator);
        string GetValueRange(int iactuator);
        // Post Methods
        IActionResult Setup(int iactuator, int pin, List<byte> settings = null);
        IActionResult SetupDefault(int iactuator);
        IActionResult WriteByte(int displayLinkedListIndex, int value);
    }

Link 2 provides detail guidance for using Controller method’s metadata with Swagger. For example the Summary and Parameter information that can be initiated for a method by entering /// just above it. For example (the green comments below)

    /// <summary>
    /// Write a byte to Actuator
    /// </summary>
    /// <param name="actuatorListIndex">Display Instance index</param>
    /// <param name="value">Value to set</param>
    /// <returns>OK or Fail</returns>
    // POST api/<SoftataController>
    [Route("WriteByte")]
    [HttpPost]
    public IActionResult WriteByte(int actuatorListIndex, int value)
    {
        bool result = SoftataLib.Actuator.ActuatorWrite((byte)actuatorListIndex, (byte)value);
        if (!result)
        {
            return BadRequest("Actuator:WriteByte fail.");
        }
        return Ok($"Actuator:WriteByte");
    }

When the steps outlined in Link 2 above, these then appear in the Swagger UI for a method:

Before metainfo is added

After metainfo is added

As per Link 1, even more details can be made available in Swagger with more metainfo embedded in the code.

Footnote

In deploying to Azure you get an error A call to warmup your site failed with response code: ‘InternalServerError’. This was “fixed” by commenting out c.IncludeXmlComments(xmlPath);in Program.cs but means the meta-info doesn’t get generated/displayed.

Also, ultimately the //if (app.Environment.IsDevelopment()) condition needs to be removed (leaving the two UseSwagger actions always operable).

Conclusion

Swagger provides a useful test environment for ASP.NET Web APIs and can be significantly enhanced by adding meta-information about controller methods as XML Document Comments: Comments immediately above a method.

	Topic	Subtopic

	*This Category Links*
*Category:*	Softata Index:	Softata
Next: >	Softata	Many ways to skin a cat
< Prev:	Softata	An ASP.NET Core API Interface - 1

Blog on Microsoft Technologies esp. IoT