DEV Community: William Olsen

Library vs Framework vs API

William Olsen — Thu, 12 May 2022 04:16:30 +0000

What are libraries, frameworks, and APIs? These terms get thrown around a lot and sometimes even used interchangably to describe the same thing.

So let me begin by saying that libraries, frameworks, and APIs are all different things. They may be used to accomplish the same task, but are all fundamentally different. "What are those differences?" I hear you ask. Let me explain each one:

Library

Basically, a library is just a bunch of methods/fields that can be reused to easily accomplish a task, or more usually a domain of tasks.

Pros:

More developer freedom
Usually easier to use
Able to add/remove/replace on-the-fly

Cons:

Developer is responsible for the structure
Longer road to finished product
Bigger possibility for human error

As I have annoyingly promoted throughout my blog posts thus far, I am developing my library Impart. The reason Impart is not a framework is because of the tool access. You can render a WebPage or start a Website anytime. There is no template for how the code is meant to be written, it provides the tools and gives you the freedom to use them.

Framework

Think of a framework as a more controlling library. A framework will handle the general flow of an application with no say from the developer.

Pros:

Framework is responsible for the structure
Shorter road to finished product
Less possibility for human error

Cons:

Less developer freedom
Usually more complex than libraries
Integration is more difficult

A great example of a framework is the .NET framework. Well... I should say .NET, as .NET Core (now called .NET) replaced it as the Microsoft framework solution with an open source license and better cross-platform capabilities. Microsoft makes things way too complicated, especially with their branding of "open source developer platform" and naming their main CLI "dotnet". Tangeant aside, just know by .NET I mean the cross-platform framework that is specifically a framework because it controls the flow of an application. By "it controls" I really mean the individual frameworks underneath it because .NET is just a bunch of frameworks for doing specific tasks. (possible blog post about what is included in .NET upcoming?)

API

This term is misused a lot. I don't think I have ever heard a code-related term be used incorrectly as much as API has. In short, an API (Application Programming Interface) is really just the exposed (public) part of an internal library/framework.

Pros:

Better user security
Simpler than hardware-level interactions
Less possibility for human error

Cons:

Less developer freedom
Parameter passing can be a pain
Integration is more difficult across systems

Going back to Microsoft, I love Windows' API: Win32. This API allows for system commands that Windows just doesn't trust the developer to do on their own. This can include things like editing the clipboard to having a password dialogue pop up. Given, parameter passing into the external methods can get annoying with the different types and having to create custom structs for certain tasks. But I do understand why Win32 exists. It adds a layer of security and standarization to an otherwise unsecure and non-regulated way of completing system-level tasks.

Web API

This is a type of API meant for sending, receiving, and processing information via web requests. This section will not have a pro/con portion considering that they are literally essential to web communication. I will instead elaborate on the common ways of implementing a web API.

REST (Representational State Transfer):

Standardization of incoming requests
More flexible
Generally uses JSON formatting
Stateless
Uses HTTP(S)
Responses can contain executable code

SOAP (Simple Object Access Protocol):

Generally less code required
More strict
Only uses XML formatting
Can use HTTP(S), SMTP, and TCP

My apologies for a longer wait for this post, I have been busy lately and this required a fair amount of research to compile together all of this information. It is very possible I made a mistake, so feel free to correct any misinformation in the comments.

Adapted from this amazing comment.

Thanks for reading!

(Cover image source)

Polymorphism in C#

William Olsen — Wed, 13 Apr 2022 02:47:03 +0000

Polymorphism is a very important pillar of object-oriented programming, right up there with encapsulation and inheritance. Polymorphism in Greek meaning "many-shaped", this pillar allows for objects to take multiple forms. This sounds more complex than it actually is, so lets dive into some examples.

I have class A and class B. B inherits A. In Main(), this allows for some interesting behaviour:

class A { } 

class B : A { }

public class Program
{
    public static void Main(string[] args)
    {
        A a = new B(); //No error?!
    }
}

How is there no error thrown? I am clearly trying to assign an incorrect type to a variable! Except I'm not. When B inherits A, it becomes a form of A, meaning it can be passed along as A when needed.

Let's look at some more examples:

using System;

public class Program
{
    public static void Main(string[] args)
    {
        DoSomething(new A());
        DoSomething(new B());
    }
    static void DoSomething(A obj)
    {
        Console.WriteLine($"Object Type: {obj.GetType()}");
    }
}

Output:

Object Type: A
Object Type: B

Another example:

using System;
using System.Collections.Generic;

public class Program
{
    public static void Main(string[] args)
    {
        List<A> objs = new List<A>();
        objs.Add(new A());
        objs.Add(new B());
        foreach (A obj in objs)
        {
            Console.WriteLine($"Object Type: {obj.GetType()}");
        }
    }
}

Output:

Object Type: A
Object Type: B

I know you all are on the edges of your seats, but let me inform you of another crazy use of polymorphism: overriding methods. "But isn't that just inheritance?" I hear you ask. And you would be technically correct. Like all pillars of object-oriented programming, inheritance and polymorphism work hand-in-hand to provide you with the best features.

Now the method overriding can be done with two amazing keywords: virtual and override. virtual is essentially the method/field raising its hand to be overridden in a form of the class. override is the teacher calling on the method/field to override it in a form of the class.

Let's see these keywords in action:

using System;

public class Program
{
    public static void Main(string[] args)
    {
        DoStuff(new A());
        DoStuff(new B());
    }
    static void DoStuff(A obj)
    {
        obj.DoSomething();
    }
}

class A
{
    public virtual void DoSomething()
    {
        Console.WriteLine("I did something in A's method!");
    }
}

class B : A
{
    public override void DoSomething()
    {
        Console.WriteLine("I did something in B's method!");
    }
}

Output:

I did something in A's method!
I did something in B's method!

Both objects were passed as type A, yet had different implementations of the same method!

It is time to introduce the sealed keyword. If using virtual is like raising your hand, then using sealed is equivalent to keeping your hand down. And unlike that one teacher who tries to engage the whole class, the C# compiler will simply not call on that method/field to be overriden in a form of the class.

Yet another high octane example with us introducing class C:

class A
{
    public virtual void DoSomething()
    {
        Console.WriteLine("I did something in A's method!");
    }
}

class B : A
{
    public sealed override void DoSomething()
    {
        Console.WriteLine("I did something in B's method!");
    }
}

class C : B
{
    public override void DoSomething()
    {
        Console.WriteLine("I did something in C's method!");
    }
}

Output:

error CS0239: 'C.DoSomething()': cannot override inherited member 'B.DoSomething()'

So we can see that sealed cuts off the chain of overriding methods.

I know at this point you are in a code-induced coma from the amazing keywords you just learned how to use, but let me sneak one last keyword in the pile. Continuing with the classroom analogy, the new keyword is similar to that one overly enthusiastic student raising their hand and blocking another student behind them. This results in the teacher calling on the student in front, rather than the student behind. And before you freak out, I was also very surprised that the new keyword has another use than initializing objects.

Note: When using a form of a class as that base class, any new methods/fields will not work in hiding the original ones.

Example:

using System;

public class Program
{
    public static void Main(string[] args)
    {
        DoStuff(new A());
        DoStuff(new B());
    }
    static void DoStuff(A obj)
    {
        obj.DoSomething();
    }
}

class A
{
    public void DoSomething()
    {
        Console.WriteLine("I did something in A's method!");
    }
}

class B : A
{
    public new void DoSomething()
    {
        Console.WriteLine("I did something in B's method!");
    }
}

Output:

I did something in A's method!
I did something in A's method!

The new keyword failed because of passing B as type A. (this is why override exists!) An example of new working:

using System;

public class Program
{
    public static void Main(string[] args)
    {
        new A().DoSomething();
        new B().DoSomething();
    }
}

class A
{
    public void DoSomething()
    {
        Console.WriteLine("I did something in A's method!");
    }
}

class B : A
{
    public new void DoSomething()
    {
        Console.WriteLine("I did something in B's method!");
    }
}

Output:

I did something in A's method!
I did something in B's method!

Now, this hurts me as much as it hurts you, but I need to introduce one last keyword. And I know I said that new would be the last, but this is what happens when you trust a C# developer! Anyways, the last crucial keyword that you need to know is base. The base keyword allows you to access the base class methods and fields from a form of it, while not having to create a whole new object. It is just as convenient as it sounds.

Example:

using System;

public class Program
{
    public static void Main(string[] args)
    {
        new B().DoSomething();
    }
}

class A
{
    public virtual void DoSomething()
    {
        Console.WriteLine("I did something in A's method!");
    }
}

class B : A
{
    public override void DoSomething()
    {
        Console.WriteLine("I did something in B's method!");
        base.DoSomething();
    }
}

Output:

I did something in B's method!
I did something in A's method!

If you want to learn about all of the possibilities of using polymorphism in C#, I would suggest further investigating this Microsoft article.

Thanks for reading!

(Cover image source)

Documenting Code in C#

William Olsen — Sat, 02 Apr 2022 21:30:20 +0000

Oh boy, it's that time again. Ever get that feeling of dread when you write a new feature, realizing that you need to document the code for it?

We've all been there. But hopefully, this guide can help alleviate the pain of trying to standardize documentation across your codebase.

First, we need to establish how C# Intellisense handles suggestion comments. The format is akin to XML in commented-out code. There are many special tags to help document your method/class/field, but only a few really matter.

The most important tag in my opinion is the <summary> tag. This tag allows you to make a summary of what your code does. For an example, let's make a simple method.

This method takes an integer as a parameter and returns the value doubled:

public int Double(int i)
{
    return i * 2;
}

When I add the summary tag, it looks like this:

/// <summary>Doubles an integer.</summary>
public int Double(int i)
{
    return i * 2;
}

For the developer interacting with Double(), this is what is displayed:

The second most important tag is the <value> tag. Now this tag only really applies to fields, and is basically a summary for variables.

An example:

/// <value>The value of 2 doubled.</value>
public int DoubledNumber = Double(2);

What the developer sees:

The second-to-last tag I deem necessary is the <returns> tag. The use of this tag is kind of in-the-name (it informs about what the method returns).

Going back to Double(), here's an example:

/// <summary>Doubles an integer.</summary>
/// <returns>An integer.</returns>
public int Double(int i)
{
    return i * 2;
}

What the developer sees:

Notice how the information is starting to pile up. This is one of the reasons I prefer to only have a few tags per method - we don't want to overwhelm the developer with trivial information.

The last tag we will discuss is the <param> tag. This is used in a slightly different way than the other ones, so pay attention. Essentially, the tag is used to give information about each individual parameter in a method.

An example:

/// <summary>Doubles an integer.</summary>
/// <returns>An integer.</returns>
/// <param name="i">The integer to double.</param>
public int Double(int i)
{
    return i * 2;
}

What the developer sees:

Even though I only used the <param> tag once, you can stack it for as many paramaters as you want.

Now that we went over the basic tags, you should have a general understanding of how the comment system works. If you want to learn about more tags, I find this Microsoft reference article works fine.

Thanks for reading!

Request Handler Design

William Olsen — Mon, 21 Mar 2022 04:20:50 +0000

This post is a little abstract, not a tutorial or anything. I was rewriting the the class in Impart for the handling of Rest API requests. This led to a a bit of a fork in how I should design the handler.

The idea I previously had was:
(covered in this post)

using Impart;
using Impart.API;

public class Program
{
    static void Main(string[] args)
    {
        Rest r = new Rest();
        r.OnRequest += OnRequest;
        r.Start();
    }
    static void OnRequest(APIEventArgs e, RestContext c)
    {
        Json j = new Json("Impart", ("Developer", "William Olsen"), ("Current Downloads", 519), ("Current Stars", 8));
        c.Respond(j);
    }
}

Obviously this doesn't even begin to account for the URL routing. For example, if I wanted to send a specific JSON response at localhost:8080/test, I am unable. This basically defeats the entire point of creating an API.

The first idea for a fix that comes to mind is to simply include the URL information in the APIEventArgs or RestContext objects. That would however, lead to the developer writing something like this:

static void OnRequest(APIEventArgs e, RestContext c)
{
    switch (c.Url)
    {
        case "/test":
            //the user accessed localhost:8080/test
            break;
        case "":
            //the user accessed localhost:8080
            break;
    }
}

Now me being the kind of person who didn't add slash commands using Discord.Net because they specifically entailed using giant switch statements, this didn't feel right.

Studying popular C# API hosting libraries, it seems like the clearest fix is to separate each request by method.

But how would one go about doing this?

The answer is using System.Reflection and custom attributes. A little warning: the code to analyze these methods is very, very, ugly, so beware.

A quick implementation would look like this to the developer:

[RestRequest("/test")]
public void RequestHandle1(APIEventArgs e, RestContext c)
{
    //the user accessed localhost:8080/test
}

[RestRequest("")]
public void RequestHandle2(APIEventArgs e, RestContext c)
{
    //the user accessed localhost:8080
}

I realize that this is incredibly similar to ASP.NET, but whatever. The invocation of the class inheriting Rest will still be the same though.

Hopefully this improved Rest class will be finished in time for Impart v2.0.2 when I (eventually) release it at the end of March.

Additionally, I will either update the post I mentioned earlier, or create one about how to host a REST API when the update is released.

Hosting a REST API using Impart

William Olsen — Sun, 13 Mar 2022 16:26:14 +0000

After finishing up my REST API class in Impart, I thought I should share how to easily host a REST API using it. Disclaimer: All code in this post is subject to change as I update and rework the library.

First, we need to add Impart to our project. Find out how in the README here: https://github.com/PixelatedLagg/Impart

Next, we will add our using statements:

using Impart;
using Impart.API;

Now, we can jump to Main() and write the following:

static void Main(string[] args)
{   
    Rest r = new Rest();
    r.OnRequest += OnRequest;
    r.Start();
}

But wait! What is OnRequest()?

That is the method I made for handling requests:

static void OnRequest(APIEventArgs e, RestContext c)
{

}

The Rest class in Impart is using JSON formatting for responses, so let's use the convenient Json struct to handle response creation. Now, I hear your sighs behind the monitor, but this stays easy - trust me.

In this line, I create a simple JSON document titled 'Impart':

Json j = new Json("Impart", ("Developer", "William Olsen"), ("Current Downloads", 519), ("Current Stars", 8));

Next, we can respond to the request with the RestContext class.

c.Respond(j);

Putting it all together:

using Impart;
using Impart.API;

public class Program
{
    static void Main(string[] args)
    {
        Rest r = new Rest();
        r.OnRequest += OnRequest;
        r.Start();
    }
    static void OnRequest(APIEventArgs e, RestContext c)
    {
        Json j = new Json("Impart", ("Developer", "William Olsen"), ("Current Downloads", 519), ("Current Stars", 8));
        c.Respond(j);
    }
}

The default port for hosting is 8080, however you can specify a custom one in the constructor of Rest.

Visiting localhost:8080, we are greeted with this:

In short, it worked!

As I continue to rework Impart, I will be adding an easy way to host SOAP APIs and make JSON/XML formatting simpler.

Stay posted to see all new updates to the internet's simplest website/networking library, Impart.

Impart

William Olsen — Wed, 09 Mar 2022 00:11:25 +0000

Impart is a library that I have been working on for a while now. The primary purpose is bypassing HTML/CSS/JS in creating a functional webpage. Impart allows the developer to create a full website in a single C# script - including hosting. Currently, I am working on events and researching ways of registering them smoothly. I however, am unable to finish this library of techno-wizardry alone. If you are as interested as I am in fighting web standards, consider opening up a request on the repo. If you are unable to contribute though, leaving a star doesn't hurt :)

(find the repo here)

Code Example:

using Impart;

public class Program
{
    static void Main(string[] args)
    {
        Website web = new Website(new Test());
        web.Start();
    }
}
class Test : WebPage
{
    public Test() : base()
    {
        AddText(new Text("Hello World!"));
    }
}

SQL Commands with C#

William Olsen — Sat, 05 Mar 2022 23:53:26 +0000

As a first post, I thought it would be fitting to discuss how to interact with vanilla SQL commands in C#. Firstly, I want to praise .NET (well technically ADO.NET) for the absolute ease of running SQL commands through its library.

Taking a quick look at .NET's reference source, we can see they that really value SQL integrations:

Without further adieu, let's get into the code. For our implementation, we will mainly be using System.Data.SqlClient.SqlCommand. This class is not included in the default .NET namespaces, so you will have to add its namespace yourself.

Add using the Dotnet CLI:

dotnet add package System.Data.SqlClient

Don't forget to include your using statements:

using System.Data;
using System.Data.SqlClient;

Let's also add using System; just to be safe.

Next, we have to connect to a database (obviously). Depending on the circumstances, the information needed for this step varies. But generally speaking, you will need the following fields:

User ID
Password/Pwd (they mean the same thing)
Data Source/Server/Address/Addr/Network Address (they all mean the same thing too)

Using this information, we can specify a connection:

SqlConnection connection = new SqlConnection(@"user id=yourUsername;password=yourPassword;server=yourServer;database=yourDirectory;Trusted_Connection=True;");
//when specifying a directory, consider using a verbatim string literal to ignore escapes

A simple method will allow us to finish creating the connection:

connection.Open();

We have now reached the fun part. We can finally write SQL commands to the connection. I hope you are as excited as I am!

Initialization and field assignment of the command:

SqlCommand command = new SqlCommand();
command.CommandTimeout = 60;
//a command timeout of 60 is recommended
command.Connection = connection;
command.CommandType = CommandType.Text;
command.CommandText = "yourCommand";

Time to send the command on its way. (they grow up so fast!)

command.ExecuteScalar();

Reading the command response (if any) is as simple as:

command.ExecuteReader();

This returns a System.Data.SqlClient.SqlDataReader object, which we can then use to easily read values.

Now me being me, I wrote a class encapsulating this code for convenience:

using System;
using System.Data;
using System.Data.SqlClient;

public static class Command
{
    private static SqlCommand command = new SqlCommand();

    public static SqlDataReader Send(string commandtext, SqlConnection connection, int timeout = 60)
    {
        command.CommandTimeout = timeout;
        command.Connection = connection;
        command.CommandType = CommandType.Text;
        command.CommandText = commandtext;
        command.ExecuteScalar();
        return command.ExecuteReader();
    }
}

Now we can interact with SQL commands in a simple way. Feel free to copy this code for your own use.