DEV Community: icarusComplexz

Debugging .NET Framework in VS Code

icarusComplexz — Fri, 06 Nov 2020 13:04:50 +0000

Why would you do this?

Have you used VS Code?

But seriously, there are lots of reasons to love Visual Studio, especially with the Community option available as that version is an extremely robust environment. However, there's a fundamental difference in purpose that makes me prefer VS Code, at least for most of what I do on the daily. As a developer, we mostly edit text, that's it. Actually, maybe we mostly just think about text, but that's another topic. Visual Studio is a full-bore, IDE. It's something that combines a lot of tools into one, super dense software package. VS Code is at it's heart a text editor. A very fancy, extremely powerful, super feature reach text editor that blurs the line between text editor and IDE, but still, a text editor. This means most of your tools will be BYO. I think that's why people love it. It's a simpler concept, and you're not inundated with hundreds of features that you're just not going to need all that often. I develop using both, but my "Daily Driver" as it were is VS Code. I think both serve their purpose in my workflow.

However, support for C# in VS Code is pretty much dedicated exclusively for .NET Core out of the box. What they don't tell you on the back of the box, is that it is actually possible to run and work with .NET framework apps in VS Code. Which is where we get to some of your BYO tooling. It's no doubt installed on your machine already, because who doesn't have Visual Studio if you're working with Framework. The assumption underpinning this blog is you have on hand some .NET framework project, but you're like me and have started to appreciate a simpler environment that you can get just about everything done in without having much in the way of features that are adding what feels like clutter when you don't need them.

If you get stuck, I've got the basic working version up on Git, don't worry about what the application, it's basically just a stubbed out project from one of Visual Studio's templates. Git: blog.VSCodeDemo

Well, hold on. There's some caveats. And whether or not they're dealbreakers for you will really depend on how into working with .csproj/.sln files or manually managing your NuGet packages you are. It's not a dealbreaker for me, and I'm going to try to find some ways around that, but these are just not going to be things you have Visual Studio hold your hand through. It's not a deal breaker for many, but for some, it's not for you and that's fine. In fact, generally speaking if you're trying to work on a Framework project, a lot of what you would need the Nuget Package Manager for is already done. I will have some details on how to use the Nuget CLI, but that is a deep topic that if there's enough interest in I will tackle later. We are basically going to be using it just to pull in packages currently configured for the project.

Adding a few things to your path

Since we're abandoning the comfortable shell of built in tools in Visual Studio, there's a few things that we're going to take with us from that installation. you can install these manually, however I'm assuming that if you're trying to convert ot VSCode, you've got Visual Studio installed. Let me know in the comments if there's any interests in walking through this from the perspective of someone brand spanking new to dotnet.

The most important thing that you're going to need to add to your path is msbuild.exe. For me, that path was below, but it depends on the version of Visual Studio you've got:

C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\Bin

However, there are a few different places that this could be installed with different versions. This is more than likely where yours is if you've installed Visual Studio 2019.

Next, load up IIS Express into your path as well.

c:\Program Files\IIS Express\

Lastly, add Chrome to your command line. We're gonna need it to trigger a startup task later:

C:\Program Files (x86)\Google\Chrome\Application.

And boom, there you have it. These are all the items you need for your path. Nuget.exe should be accessible from your command line already if you have Visual Studio installed.

Starting a Project

If you're like me, Visual Studio will still have a place in your toolkit if you're still working in .NET Framework. It is what it is, the .NET Foundation has sort of moved on from here. You can make your own custom templates for the dotnet CLI, but that falls way outside of scope for this tutorial. You could also build your own solution and project files, but that also falls way out of scope for this article. The goal here is to get you up and running with most of the basics you're used to having. With that in mind, I cheat on this step BIG TIME when starting a new framework project (although, this blog is really the only time in recent memory that I've needed it). Crack open Visual Studio and start a new project.

For the purpose of following along, the project is going to be an "ASP.NET Web Application (.NET Framework)" project. We're going to call it VSCodeDemo if you're following along, and we're targeting Framework 4.8. Also for the purpose of this walk through, it's going to be a "Web Forms" type of project.

And now we will ditch Visual Studio for VS Code. We're got some serious work to do, but from here on out we're in CLIs and VS Code, so get comfy.

First Steps

Let's go through a few of the things we're going to need to have down pat in order to keep this working. First, test our msbuild setup.

cd VSCodeDemo
msbuild VSCodeDemo.sln -m

That secoond command will run all of your build steps. If you ever need assistance sorting out what's available to you with MSBuild, you can run the following command and see all the subcommands available to you:

msbuild /?

All of your normal operations that are available to you in VS are available here for the most part. You can runa clean, build, rebuild, etc. as well as include parallel builds for your larger projects. In my experience, running this outside of VS is far faster that running it within the IDE. Your mileage may vary, but this has generally been a breath of fresh air for me. Another item that I include here is the -m flag, which is not needed here but in future, this will provide you the ability to build multiple .csproj projects in parallel.

Let's also test our IIS Express setup quickly before loading into VSCode. VS makes this easy for us by including a pre-built config from the template files. These are stored in the root of your directory under the .vs folder. To get there, navigate to that directory:

cd .vs/VSCodeDemo/config
ls

IIS Express accepts a lot of parameters, and before we dig into those, let's gather some IIS basics. When IIS is installed, the default directory it will look for configs for is in {user folder}\Documents\IISExpress. This is the way it was done before we had fancy IDEs with local configs built specifically for the site we're working on. Most of the flags you use with the iisexpress application will attempt to read from this configuration first. This is why we're working in that hidden directory (.vs). We will clean this up in a future step, but this is where you start. Additionally, any time you start a project using VS, a default site is created in the config called WebSite1, with the site index of 1, see below from the applicationhost.config in our local config folder:

<configuration>
    [...]
    <system.applicationHost>
        <sites>
            <site name="WebSite1" id="1" serverAutoStart="true">
                <application path="/">
                    <virtualDirectory path="/" physicalPath="%IIS_SITES_HOME%\WebSite1" />
                </application>
                <bindings>
                    <binding protocol="http" bindingInformation=":8080:localhost" />
                </bindings>
            </site>
            <site name="VSCodeDemo" id="2">
                <application path="/" applicationPool="Clr4IntegratedAppPool">
                    <virtualDirectory path="/" physicalPath="{path to user folder}\source\repos\VSCodeDemo\VSCodeDemo" />
                </application>
                <bindings>
                    <binding protocol="http" bindingInformation="*:53933:localhost" />
                    <binding protocol="https" bindingInformation="*:44358:localhost" />
                </bindings>
            </site>
            [...]
        </sites>
        [...]
    </system.applicationHost>
    [...]
</configuration>

That site does not have anything tied to it, and we'll just be taking it out later, and these configs are just the defaults. We won't be tweaking them very much, and are shown for reference. The key takeaway at the moment is that sites in these configs have two important properties: names and IDs. With this information, we can return to our consoles and target this using the iisexpress tool.

iisexpress /config:applicationhost.config /site:VSCodeDemo

IIS Express accepts parameters using the syntax /{parameter}:{value}. With that, we're passing in the config parameter and pointing it at the local applicationhost.config give to us by the template and passing in our site name VSCodeDemo. Alternatively, we could pass in the /siteid:2 parameter to target this application. You'll see a new tray icon for IIS Express and now you could open this up in a browser from the tray application or opening the browser and navigating to localhost:{port in the config}. With all of that setup, we're now ready to start working on our VSCode configuration.

Setup In VSCode

And this is what we've all been waiting for.

code .

Bam, blog's done, have fun, you're a wizard, Harry!

And while that's fairly true, there's this nasty little thing called debugging that will be much easier if we can set it up so we can debug it in VSCode. We could rely on the ASP.NET debugging pages, but that's going to be a nightmare, plus all of these configs are everywhere and that's going to be an absolute headache to manage, and we don't like those.

First things first, if you haven't, install the C# extension. Out of the box, it will only support Core projects, and that's one of the caveats here. You'll lose some debug functionality, but I haven't felt that pinch. In VSCode, open up VSCodeDemo/VSCodeDemo.csproj.

Look for this section and this is where we will be making some changes:

[...]
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
  </PropertyGroup>
[...]

[...]
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <DebugType>portable</DebugType>
    <Optimize>false</Optimize>
  </PropertyGroup>
[...]

Ensure that the Optimize is set to false, this caused me some issues when I didn't spot it as being an issue. Then, set the debug option to "portable". This converts your debug symbols from .NET Framework specific symbols to the newer open symbols. These are the symbols that can be read by the VSCode C# extension.

Now, add a folder specific for the VSCode configuration in your project's root directory call .vscode and a launch.json file. For this config, we're going to add the following:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Attach",
            "type": "clr",
            "request": "attach",
            "processName": "iisexpress"
        }
    ]
}

The key portions to pay attention to here is that by default, VSCode will attempt to set this up with more detail specifically for .NET Core apps. I pull out everything that is in there that I don't use, but we will add a few back in as we go. The key attributes are this is specifying that we should use the normal, non-core clr, the request we will send from the debugger is the attach command, which will have the debugger attach to an already running application. With the debugger, we have the option to target a processId or processName, and we will only be running one instance of the process and won't know the PID in advance, so we're specifying the processName as iisexpress. This will have the debugger look for that process by name, attach to it and load the appropriate symbols for breakpoints and console writes. This will cover the .NET side of debugging, at least. I'm still working on JS debugging.

Set a breakpoint in your About.aspx.cs on the Page_Load method to test this out.

Now, to get this rolling, back to the commandline. What I normally do is have one terminal window open in the root and one open within the .vs\VSCodeDemo\Config directory. This allows for me to run my build steps and restart IIS Express without having to change directories so often. We will fix this in a minute, but this has been my workflow for a while and it's fairly comfortable, but I want to tweak it and we'll get to that in a minute. For now, open a second terminal, and navigate to your project's root folder.

msbuild VSCodeDemo.sln

This will build your solution. Now, switch to your other terminal, which should hopefully be in your VS config folder, and run:

iisexpress /config:applicationhost.config /site:VSCodeDemo

Navigate to the site in your browser and see that the breakpoint is hit. If it's hit, you're good to go! That means the debugger is able to listen to the new portable format of the debugging symbols and attached to the IIS instance with no problems. With that together, I would prefer to be able to start this site from somewhere other than this odd, buried directory that I'm going to forget about. Open up that applicationhost.config in VSCode and grab the site's specific details. Should look something like below:

<site name="VSCodeDemo" id="3">
    <application path="/" applicationPool="Clr4IntegratedAppPool">
        <virtualDirectory path="/" physicalPath="C:\Users\icarus\source\repos\VSCodeDemo\VSCodeDemo" />
    </application>
    <bindings>
        <binding protocol="http" bindingInformation="*:53933:localhost" />
        <binding protocol="https" bindingInformation="*:44358:localhost" />
    </bindings>
</site>

With the power of copying and pasting, grab this site and open the default IIS config for your machine. It's hosted in /Documents/IIS Express/applicationhost.config. Find the "sites" section and paste it in. You should now have a section that looks similar to below. Ensure that when you paste this in, you update the ID and the name to be distinct from what is already present.

<system.applicationHost>
    [...]
        <sites>
            <site name="WebSite1" id="1" serverAutoStart="true">
                <application path="/">
                    <virtualDirectory path="/" physicalPath="%IIS_SITES_HOME%\WebSite1" />
                </application>
                <bindings>
                    <binding protocol="http" bindingInformation=":8080:localhost" />
                </bindings>
            </site>
            [...]
            <site name="VSCodeDemo" id="2">
                <application path="/" applicationPool="Clr4IntegratedAppPool">
                    <virtualDirectory path="/" physicalPath="C:\Users\icarus\source\repos\VSCodeDemo\VSCodeDemo" />
                </application>
                <bindings>
                    <binding protocol="http" bindingInformation="*:53933:localhost" />
                    <binding protocol="https" bindingInformation="*:44358:localhost" />
                </bindings>
            </site>
            [...]
        </sites>
        <webLimits />
    [...]
    </system.applicationHost>

With this in your default IIS Express configuration, you can call if from any folder, without needing to specify the config file you're working in. You are now able to feed in the site index or the site name under the /siteid:2 or /siteName:VSCodeDemo. And that's it! We're going to take a look at a few more things that I prefer to have next, but that's the basics. With this in place, you're good to go for most workflows. At least, these are the most essential portions of development for me that I use on the daily. All that I feel is missing from this picture is Nuget and one-button application starting. Believe it or not, Nuget was easy to transition to, so let's do that one next.

Nuget

If you have VS installed, you more than likely already have the nuget cli installed. If you've used the nuget cli before, this will be very familiar to you. What I didn't know until very recently was that it could be used to install packages into .NET Framework projects. Navigate to your project's root directory, and give it a shot by adding Newtonsoft:

nuget install Newtonsoft.Json -Version 12.0.3

For me, this took immediately and I had my shiny new package rolling immediately. It does mean that instead of using the Package Manager GUI, you'll be using the nuget site to find packages and get the correct versions for your project, but this to me was a small trade off as I found the package manager GUI to be a little tough to use anyway. If you have pulled down an already established Framework project, you can do a nuget restore command in the root of your project and it will pull in those packages as well.

With that, nuget's done and dusted.

VS Code Tasks

Now, the beast has risen it's ugly head. The hardest part of getting up and rolling in VS Code: Tasks. I've not managed to get this to 100% of Visual Studio, but from a day to day standpoint, what's we've done already covers about 95% of what I find myself doing. In general, it's been easier to run the commands manually in my terminal, but VSCode has this really interesting set of tooling around starting up the application, so I went ahead and worked out how to get the process running using this method. I, personally, would probably use the set up that has been put into place so far, but this is the last mile so let's finish this.

VS Code relies on a launch.json to manage your debugging/application runnning. For this application, this is how I've configured that launch.json:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Attach to Chrome",
            "port": 9222,
            "request": "attach",
            "type": "pwa-chrome",
            "webRoot": "${workspaceFolder}"
        },
        {
            "name": "Start App",
            "type": "clr",
            "request": "attach",
            "processName": "iisexpress",
            "preLaunchTask": "startChromeDebug",
            "postDebugTask": "iisStop"
        }
    ],
    "compounds":[
        {
            "name": "Launch apps and attach debuggers",
            "configurations": [ "Start App","Attach to Chrome"]
        }
    ]
}

As a basic rundowm, there are two configurations present: one attaches the debugger to Chrome, and the other calls all of the startup processes. In this case, they are referencing a tasks.json file that runs various commands that I've placed in there. These are chained together in a way I will show in a minute. The important thing to note here is that there are two tasks in the "Start App" configuration. There is the pre-launch task, which is run before trying to attach the debugger, and there is the "postDebugTask", which is a cleanup process to stop the instance of IISExpress I am running.

Initially when I was putting this together, though, I couldn't figure out how to attach both debuggers (the chrome debugger and the C# debugger). These configurations were run either one or the other, which was workable but not the full picture I was hoping for. Turns out, VS Code supports running multiple debug configurations through something they called "compounds". In this section, we define the combination we want to run, in this case first "Start App" followed by "Attach to Chrome". The first one will run scripting to build the application, start up IIS Express, and start Chrome with the debugging port open. The second one will attach the Chrome debugging extension to the instance of Chrome we just opened. Additionally, I've added a tear down task to the "Start App" configuration that will stop the instance of IIS Express we're running.

Now, let's take a look at these tasks.

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "msbuild",
            "type": "shell",
            "command": "msbuild",
            "args": [
                "/p:Configuration=Debug",
                "/t:build",
                "-m"
            ],
            "presentation": {
                "reveal": "silent"
            },
            "problemMatcher": "$msCompile"
        },
        {
            "label":"iisStart",
            "type":"shell",
            "dependsOn":"msbuild",
            "command":"Start-Process",
            "args": ["iisexpress","/siteid:2"],
            "presentation": {
                "reveal": "silent",
            }
        },
        {
            "label":"iisStop",
            "type":"shell",
            "command":"Stop-Process",
            "args": ["-Name","iisexpress"]
        },
        {
            "label":"startChromeDebug",
            "type":"shell",
            "command":"chrome",
            "dependsOn":"iisStart",
            "args":[
                "https://localhost:44315/",
                "--remote-debugging-port=9222"
            ]
        }
    ]
}

The first task is the msbuild task, which will call the msbuild exetuable and run it to build our debug configuration.

{
    "label": "msbuild",
    "type": "shell",
    "command": "msbuild",
    "args": [
        "/p:Configuration=Debug",
        "/t:build",
        "-m"
    ],
    "presentation": {
        "reveal": "silent"
    },
    "problemMatcher": "$msCompile"
}

To break this down, what happens with the task is it is fed into your CLI, in my case and in most it'll be Power Shell by default. The label is what is used to identify it within the your configurations in launch.config. The command is, in this case, the MSBuild.exe, which we've added to our path (for me, it was located here: C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\Bin since it's installed alongside of Visual Studio Community 2019 there). Your args are built off of what parameters are fed into the application. Basically, if you can learn how to use a CLI tool, it can be configured here. The flags we're using, as it's for a debug build, specify the flags /p for "property", which will locate the "Configuration" property in our .csproj file and build accordingly. The /t flag will target a process, here we're targeting build, but you can also use "rebuild" or "clean" if needed. Essentially, here is replicated the "Build" button within Visual Studio.

 {
    "label":"iisStart",
    "type":"shell",
    "dependsOn":"msbuild",
    "command":"Start-Process",
    "args": ["iisexpress","/siteid:2"],
    "presentation": {
        "reveal": "silent",
    }
}

Now, since we're using the PowerShell CLI, in addition to calling the the msbuild.exe application, we can also add in PowerShell commands. Setup is the same: the label we're going to call it, the type being "shell" to designate it as a CLI task. The first "new" item is what allows us to chain tasks together in VSCode. The dependsOn flag specifies what other tasks need to precede this task in order for it to work. Also, since IISExpress runs continuously until stopped, instead of just calling iisexpress from the command line as we normally do, we're going to call Start-Process, which allows for control to return to the remaining tasks after the process is started. The args, in this case, are the same ones we've been using to run the site so far. The presentation/review flag, in this case at least in my testing, doesn't seem to do what I think it does (I thought it ran it in the background, I believe this is just supressing errors).

{
    "label":"iisStop",
    "type":"shell",
    "command":"Stop-Process",
    "args": ["-Name","iisexpress"]
},

This piece uses PowerShell's Stop-Process call in order to end IISExpress when we're done. This is referenced in the postDebug flag inside of our launch.json. This task works the same, so if you had multiple tear down processes you could effectively configure them here with dependsOn flags.

{
    "label":"startChromeDebug",
    "type":"shell",
    "command":"chrome",
    "dependsOn":"iisStart",
    "args":[
        "https://localhost:44315/",
        "--remote-debugging-port=9222"
    ]
}

The final task we're adding requires for you to add your Chrome browser to your path so that you can call it from your CLI. For me, it was located here: The parameter you'll need to add is the site's URL from your ApplicationHost.config and the flag enabling your remote debugging port.

Phew, that was a lot of configuration. However, if you go to your "Debug" tab in your VSCode workspace, you now have multiple configurations available, including in this case a new one labeled "Launch Apps and Debuggers". That's our new compound task that combines ALLLL of this business together, starts your IIS Express, builds the things, starts Chrome, and attaches both the .NET debugger and your Chrome debug tooling.

Regrets

I have some regrets here, really I do. I thought this would be way simpler and honestly this blog has sucked up a ton of my time with headaches. The vast majority of this time was spent trying to figure out how to get IIS working, I'm really not that great at PowerShell or CLI tooling. Working at it every day, a lot of it gets easier, but for me it still seems simpler (if less efficient) to just run a manual build in the CLI followed by starting IISExpress. It's easy enough to configure the debugger to attach to the IIS Express instance without all of these tasks being wired up, but I feel like these tasks will make someone's QOL better. And I know for a FACT there's dozens of blogs out there getting into each piece of this in major detail, but I have always struggled to understand all of this because often times what I see is the author explaining the thing that they were stuck on instead of walking through the whole process. That's what I wanted to do here, but trust me, I have to thank the internet and all of you command line commandos out there who had snippets of various pieces of the process.

SQL Local DB

icarusComplexz — Tue, 03 Nov 2020 12:40:10 +0000

LocalDB

I love working with databases, but I hate having to share them. I'm extremely selfish in that regard. There's an extent to which it may be a character flaw, but here's the deal: I don't want to impact other folks' workflows. That's it. That's the whole deal. A lot of times when I'm working with a database, I'm trying to load data or transform data. I don't like sharing because I can't stand the idea of targeting the wrong table. Trust me, I've done this before, you make a mistake and suddenly a table is just....gone. And you're not getting it back because you didn't add a rollback. And someone is working with pushing test data around in your application and now they're panicked because they just saw that table was out and they're calling the database person, and if you just dropped the table there's a chance that's you. You have a backup?

There's a handful of ways to get around this, one I'll follow this up with later. it's way more chic and won't have the limitations this option will, but I don't see this option used that often despite how handy it is. There's an option available right out of the box from Visual Studio, even the community option has it. SqlLocalDB is a developer tool that is essentially a stripped down version of SQL Server Express available for development. Why would you use this instead of SQL Server Express? Well, ya got me there. I like using localdb because it's much easier to setup and is inherently locked by Windows to my user account. SQL Local DB is also incredibly easy to setup when compared to other options, and given how much it can accomplish for you, it will probably solve most of your needs for database work locally.

Installing

Do you have a flavor of Visual Studio installed? Congrats! You probably have it, if not loads the data work work load using the Visual Studio installer. If not, Microsoft has a really solid walk through here: https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/sql-server-express-localdb?view=sql-server-ver15

(It's easiest through the Visual Studio installer, if you use VSCode, just install it that way, you'll get other dev tools that are packaged installation wise with Visual Studio).

Using

Believe it or don't, all you pretty much need from here on out is you standard SQL tooling and the commands attached to sqllocaldb. First, let's see if there are any databases set up.



sqllocaldb info

This spitsout the databases setup during the install of local db. In most cases, there should be an MSSQLLocalDB. To work with this database, we will need to start it:



sqllocaldb start mssqllocaldb

Or if you want to create a new one:



sqllocaldb create BlogDatabase

This will create a new database to connect to call BlogDatabase.

From here, you can navigate and work with this database locally with nearly the same amount of tooling you're used to having. there are plenty of things that Local DB does not have, like the ability to install an SSISDB, but I've found it to handle so much of my day to day, it really is a tool I wish someone tapped me on the shoulder and said "hey, you should know about this" when I was getting started.

Great...I have SQL but no data

Almost forgot. We're going to use the Northwind database example just to keep things easy. First, download it from their git: https://github.com/Microsoft/sql-server-samples/tree/master/samples/databases/northwind-pubs

This is another tool I wish someone, ANYONE would have told me existed when I was learning anything related to SQL. I needed something to practice with desperately, learning SQL in production is not a good thing to do, but I couldn't figure out where to find or get this down, so I'm going to spend a little extra time here. If you're familiar with git, feel free to skip ahead.

We're going to use Azure Data Studio, so point an internet machine here and get it:
https://docs.microsoft.com/en-us/sql/azure-data-studio/download-azure-data-studio?view=sql-server-ver15

This is to SQL Server Management Studio what Visual Studio Code is to Visual Studio. It's lighter, has a different feature set, but has most of everything you'll want on the day to day. (It's also available on Mac, which is a huge plus for me because it means less context switching).

Once that's installed, you'll want to use Windows Authentication to connect to the database, and your connection string will be (localdb)<database to connect to>, or from the examples above, the below examples:



(localdb)\MSSQLLocalDB
(local)\BlogDataBase

You'll open this up by selecting "New Connection" in the start page of Data Studio.

Since it is connected by default to your Windows credentials, you will need to set "Windows Authentication".

Now that we're in, pull the Northwind files and let's walk through how to use this setup to setup the Northwind database. First, fork the repo into you're git (so you're not working out of their branches). Next, clone them locally and open the instnwnd.sql and instpub.sql files in Azure data studio. They should automatically connect to the database you just connected to. After you have them open, all you need to do is run them, and you will have a functional local db loaded with the Northwind databases.

Well...that's great and all...

But yeah, this probably isn't what you have lying around. You probably do, however, either have or have the capability of having a .bak to restore a database from. If not, and with your DBA's permission, here's how you can get one. Log into that server with Azure Data studio. We're going to stick with the Northwind as it's what we have right now.

Under the server explorer tab for this database instance, locate the Northwind (or other) database you want a backup to restore from. Click the ellipses and select "Backup" from the drop down menu.

From there, you will need to select where you want to store your backup. Once that's done, return to the local database you'll be working in, in our case it's going to be the BlogDataBase we created.

In the topmost dropdown, select "Backup File" from the "Restore From" dropdown. Select the "Backup File path" as the backup you just made. The rest should fill out itself from those backup files. When I did this, I needed to go to the "Options" tab and select "Overwrite the existing database (WITH REPLACE)" to manage the restore. And now, congratulations, you have a local database that you can run riot in and not really have any major risks associated with. You have isolation from your fellow testers and have the capability to just restore from a good backups in the event that things go completely sideways.

Abstract C#

icarusComplexz — Fri, 11 Sep 2020 02:09:52 +0000

Abstraction

One of the things that is imminently useful within software development, and by no means exclusive to .NET, is the ability to have an abstraction of something. For example, coffee. (If you're following along with my other blogs here, you might notice a disturbing trend now.) Famous companies named after first mates and dipping pastries all peddle this fantastic beverage. You may drink it sweetened, but I prefer it straight. All of these shops craft their own unique drinks, but they are all known as coffee. That's because while a caramel machiato is functionally different from a double americano, they both somehow fall into this grander category called "coffee".

In software development, we call it abstraction. In object oriented programming, we treat what we interact with, design, and store data in our code as objects. However, this short hand has an additional analogue to the real world. In .NET there are two different types of abstraction. In ascending order of abstract-ness (it's totally a word. But don't look it up.), you have concrete classes, abstract classes, and interfaces.

In what is commonly referred to as a concrete class, the details of what the thing is are inherently tied to the thing itself. Using your phone as an example, imagine a world in which every phone had the same exact apps, same exact code, same exact functionality. It'd be kinda boring, but at least we'd all rest easy that the dang thing is pretty easily replaced.

Now, an abstract class is a collection of ideas and actions that something can do, but they're over written by the concrete representation if needed. Using cell phones again, you could have the cell phone object that sends messages using SMS, one that overrides the send feature with a fancy thing called IMessages (blue bubbles unite!), and one that overrides that functionality with something just called Messages (which is technically a better implementation, but does anyone use it?). With this sort of abstraction, the messaging application can still use the default option in combination with it's specific flavor as well. Something like this:

public abstract class CellPhone
{
    public virtual void SendMessage()
    {
        Console.WriteLine("SMS Sent");
    }
}

public class FruitPhone : CellPhone
{
    public override void SendMessage()
    {
        Console.WriteLine("Fancy message sent with a blue bubble, how fancy.");
        base.SendMessage();
    }
}

public class RobotPhone : CellPhone
{
    public override void SendMessage()
    {
        Console.WriteLine("Sent RCS Message with awesome features");
        base.SendMessage();
    }
}

Essentially, what we've done here is have three different devices handle the same functionality, but differently with a fallback to a standardized default protocol. This is very handy because as long as something is expecting a cellphone, you can send it a FruitPhone or a RobotPhone and it will call that SendMessage() method. So, realistically if you have a method that sends messages and it receives the CellPhone abstraction like so:

SendMessage(CellPhone phone)
{
    phone.SendMessage();
}

It will take either a FruitPhone or a RobotPhone and send the message. The phone is the only thing that needs to know how to send the message. Think of this level of abstraction as a means of defining your object while needing to ensure that certain, core functionality is shared across all possible implementations.

Now we're up to my favorite, interfaces. Interfaces are super handy, but they require a little more work. They're a level of abstract that requires anything that inherits it to implement everything. As a practice in .NET, they are prefixed with an i to help spot them in your code. Let's take our last project of coffee making and start to simplify some parts of it.

Why Abstraction

Abstraction makes your life easier, specifically because of how we created the method that brewed our coffee. One of the interesting things about abstraction is that it serves to reduce the amount of information you need to know about something in order to use it. Look at how our switch operates from the last blog:

switch (coffeeType)
{
    case BrewStyle.FrenchPress:
        var press = new FrenchPress();
        press.Brew();
        press.Press();
        press.Pour();
        break;
    case BrewStyle.PodSystem:
        var pod = new PodSystem();
        pod.Brew();
        pod.Pour();
        break;
}

I'm cringing at this, and I wrote it! If we needed to add a new coffee type, we're going to have to make changes here to handle that. Additionally, if we need to add a step to the PodSystem, we're going to need to change it. Aye-ya-yaye. In software development, this is called "coupling", and it's a no-no. If at all possible, keep this from happening in your code because chasing these things down long term will be difficult, time consuming, and confusing. I'm willing to accept difficulty, but confusion and time consumption is definitely not something I would wish on someone else, so let's tidy up my mistake.

Short hand of "knowledge"
I forget where I picked this up, but the way I like to think about the usefulness of abstraction comes down to "knowledge". The more one piece of code needs to know about how another piece of code operates, the more dependent or coupled they are. This coupling increases complexity and changing things becomes more difficult as systems grow. I will keep using this terminology, because it's been very helpful to me in thinking through how to work on these sorts of problems.

First, if you're following along, go ahead and navigate to your Brew folder and make a new file called Coffee.cs.

cd Brew
touch Coffee.cs
cd ..
code .

Our goal at this moment is to move the nested classes out from the brewing class. Thinking in terms of what different aspect of the application should know, we want to setup the brew to be agnostic: able to handle a french press, a podsystem, or even be able to take in a brand new coffee we want to make without needing to worry about updating the brewer. To start, let's open up our Coffee

First, let's move our brewstyle enumeration into this file. And, let's add another one.

public enum BrewStyle
{
    FrenchPress, PodSystem, FrisbeeBrew
}

public enum Granularity
{
    Fine = 0, KindaFine = 1, Medium = 3, KindaCoarse = 4, Coarse = 5, Chunky = 6, WholeBean = 7
}

If we keep relying on concretely represented classes, adding a FrisbeeBrew will be sort of the last straw. So, let's write up a representation of all things coffee, and for this we're going to use an interface.

public interface iCoffee
{
    int Temperature { get; set; }
    BrewStyle Style { get; }
    Granularity GrindGranularity { get; set; }
    iCoffee Brew();
    iCoffee Pour();
}

With interfaces, we simply define what properties the class will have and what things the application can do. In this case, all of our coffees will have a set of instructions to Brew() and Pour(). By convention, interfaces get an i in front of their name. Additionaly, we've give the property of Temperature.

Now, let's refactor our French Press.

public class FrenchPress : iCoffee
{
    public int Temperature { get; set; } = 70;
    public BrewStyle Style => BrewStyle.FrenchPress;
    public Granularity GrindGranularity { get; set; } = Granularity.WholeBean;
    public iCoffee Brew()
    {
        BoilWater();
        GrindBeans();
        WaitAMinute();
        return this;
    }

    private void WaitAMinute()
    {
        for (int i = 0; i < 100; i++)
            Write($"\r{GetChar(i)}  ");
        Console.WriteLine();
    }

    private char GetChar(int position) =>
        (position % 4) switch
        {
            0 => '|',
            1 => '/',
            2 => '-',
            3 => '\\'
        };

    private void GrindBeans()
    {
        Console.WriteLine("Grinding beans.");
        while (GrindGranularity != Granularity.KindaCoarse)
            Write($"\rCurrent granularity: {--GrindGranularity}.");

        Console.WriteLine();
    }
    private void BoilWater()
    {
        Console.WriteLine("Boiling water.");
        while (Temperature < 200)
            Write($"\rCurrent temperature is {++Temperature}°F.");
        Console.WriteLine();
    }

    private void Write(string line)
    {
        Console.Write(line);
        System.Threading.Thread.Sleep(100);
    }

    public iCoffee Pour()
    {
        Console.WriteLine("Pouring.");
        Console.WriteLine("Enjoy!");
        return this;
    }
}

There's a few things to notice here. First, the class definition has a : attached to it. This means several things in C#, this one in particular means "implements". By and large, that : bit means "inherits", however with an interface, there's nothing to inherit. With C#, usually we use inheritance as a means of taking predefined functionality and applying it to another class, or in the case of abstraction taking predefined functionality and having the option to override it. When inheriting from an interface, there's nothing to inherit other than these general descriptions, so it's more common to refer to this as "implementing".

The method Brew() has been implemented to call several internal methods, as has Pour(). Remember the earlier note about what things "know"? Well, with this methodology, everything labelled "public" is determined to be things that are needed to be known by what is using our code. In this case, the interface says that things will need to know the coffee's temperature and how to Brew and Pour the coffee. Everything else? None of the external code's business. We're having those accessible only privately, internal to the coffee.

Let's add into this file the other two types of coffee and take a look at how we can use this technique of interfaces to make our brewing system cleaner:

public class PodSystem : iCoffee
{
    public int Temperature { get; set; }
    public BrewStyle Style => BrewStyle.PodSystem;
    public Granularity GrindGranularity { get; set; } = Granularity.KindaFine;
    public iCoffee Brew()
    {
        InsertPod();
        PushButton();
        return this;
    }

    private void InsertPod()
    {
        Console.WriteLine("Inserting pod.");
    }

    private void PushButton()
    {
        Console.WriteLine("Button pressed.");
        Console.WriteLine("Waiting for coffee.");
        Console.WriteLine("Done.");
    }

    public iCoffee Pour()
    {
        return this;
    }
}

public class FrisbeeBrew : iCoffee
{
    public int Temperature { get; set; } = 70;
    public BrewStyle Style => BrewStyle.FrisbeeBrew;
    public Granularity GrindGranularity { get; set; } = Granularity.WholeBean;
    public iCoffee Brew()
    {
        BoilWater();
        GrindBeans();
        Console.WriteLine("Stirring.");
        Stir();
        WaitAMinute();
        return this;
    }

    private void Write(string line)
    {
        Console.Write(line);
        System.Threading.Thread.Sleep(100);
    }
    private void BoilWater()
    {
        Console.WriteLine("Boiling water.");
        while (Temperature < 200)
            Write($"\rCurrent temperature is {++Temperature}°F.");
        Console.WriteLine();
    }
    private void GrindBeans()
    {
        Console.WriteLine("Grinding beans.");

        while (GrindGranularity != Granularity.Fine)
            Write($"\rCurrent granularity: {--GrindGranularity}.".PadRight(50));

        Console.WriteLine();
    }

    private void Stir()
    {
        for (int i = 0; i < 50000; i++)
            Console.Write($"\r{GetChar(i)}  ");

        Console.WriteLine();
    }

    private void WaitAMinute()
    {
        for (int i = 0; i < 100; i++)
            Write($"\r{GetChar(i)}  ");

        Console.WriteLine();
    }

    private char GetChar(int position) =>
        (position % 4) switch
        {
            0 => '|',
            1 => '/',
            2 => '-',
            3 => '\\'
        };
    public iCoffee Pour()
    {
        Console.WriteLine("Pouring.");
        return this;
    }
}

Now, before you judge, we'll get to some of this copy and pasted code a little later. For now, the important thing is that we now have three different classes implementing the same interface, but doing different things.

Now, how on earth are we going to use it? My first gut instinct with interfaces was to just new up the concrete instances and assign them to a variable that's using the interface like so:

iCoffee coffee = new FrenchPress();

Which, is perfectly valid and certainly not a bad thing to do. And there are more than a few places where this would be what you would do, but for our purposes, we're going to be using a factory pattern. This will allow for us to generate what we need, when we need it.

cd Brew
touch CoffeeFactory.cs
cd ..

Open up CoffeFactory.cs and add the following:

using System;
using System.Collections.Generic;
using System.Linq;

namespace Brewing
{
    public class CoffeeFactory
    {
        public static List<iCoffee> coffees = new List<iCoffee>();
        internal static iCoffee Create(BrewStyle coffeeType)
        {
            if (!coffees.Exists(coffee => coffee.Style == coffeeType))
                coffees.Add(CoffeeSwitch(coffeeType));

            return coffees.First(coffee => coffee.Style == coffeeType);
        }

        internal static iCoffee CoffeeSwitch(BrewStyle coffeeType) =>
            coffeeType switch
            {
                BrewStyle.FrenchPress => new FrenchPress(),
                BrewStyle.PodSystem => new PodSystem(),
                BrewStyle.FrisbeeBrew => new FrisbeeBrew()
            };
    }
}

We're creating a static factory that takes in what BrewStyle we need. In the interest of simplicity, we ensure that there's only one coffee of each type being being given to our coffee brewer by using a list of coffees. We first check to see if there are any coffees in existence that have the needed BrewStyle. If there isn't one, we ask the CoffeeSwitch to give us a new one, add it to the list, then return the correct coffee by BrewStyle. Nice and clean. And, if we need to add more coffees, we have one place that we need to add it as an option.

Now, we need to go back to Brew.cs and do some more work. Some of my personal favorite work. Deleting as much as possible.

public class Brew : System.CommandLine.Command
{
    public Brew(string name, string description = null) : base(name, description)
    {
        Add(new Option<BrewStyle>("--coffeeType"));
        Handler = CommandHandler.Create<BrewStyle>(BrewCoffee);
    }

    public void BrewCoffee(BrewStyle coffeeType)
    {
        var coffee = CoffeeFactory.Create(coffeeType);
        coffee.Brew();
        coffee.Pour();
    }
}

Look at that. Now, we can add as many different types of coffee as we want and the brewing mechanism won't change. It won't have to because it doesn't know how to brew the coffee, that knowledge is kept in the coffee class. It also doesn't even need to know what type of coffee it is, our switch is now gone. The BrewCoffee method takes the data from the CLI implementation, passes it agnostically to the BrewCoffee() method, and without knowing anything about French Press, PodSystem, or FrisbeeBrewing makes every variation.

Let's do a quick check on our Program.cs:

static void Main(string[] args)
{
    var rootCommand = new RootCommand() { new Brewing.Brew("brew") };
    rootCommand.InvokeAsync(args).Wait();
}

Let's test it out, now. With this setup, you can now use the dotnet CLI to test the application.

dotnet run -- brew --coffeeType FrenchPress

This brews a french press. Let's try another coffeetype:

dotnet run -- brew --coffeType PodSystem

And lastly, let's try the new coffee: Frisbee Brew!

dotnet run -- brew --coffeeType FrisbeeBrew

Cool, coffee?

Yes, coffee and factories. If you're like me, seeing these pieces all written up and together helps. Help yourself to the example over at github. Feel free to fork it and clone locally if you want to tinker and extend this.

Sound off below, let me know what you would like to see changed or expanded. Would you like to make something cleaner? Send me a pull request! Curious about more tools with System.Commandline? Me too! That's next on the agenda.

DotNet's System.CommandLine

icarusComplexz — Tue, 08 Sep 2020 14:15:12 +0000

System.CommandLine

One of the most common applications I've found myself writing has been backend services. Writing little console applications that get posted up a schedule and shift things around. Recently, however, I had the distinct pleasure of writing some developer tools for a custom framework I was working in. This requried a basic console app, but we would need to be able to assign it to the path and send in parameterized values. This lead to the discovery of Dotnet Core's take on a command line parser.

It may just be me, but command line parsing is annoying. I don't like doing it, and I always reach for what felt like the indomitable package CommandLineParser, which I encourage you to checkout over on NuGet. It's very handy, and someday maybe I'll circle back. However, there's something to be said to using "native" options where possible.

Setup

Carrying forward from our last time, let's start a new project. And while we're at it, let's make some coffee. We're going to use git to track our progress, but feel free to skip anything prefixed "git" if you won't be while following along with that.

mkdir coffeemaker
git init
cd coffeemaker
dotnet new console

This creates a new console project, and as you're in the coffeemaker directory, it'll be labelled "coffeemaker".

With recent changes in .NET Core, our package manager console has been moved into a new home: you guessed it, the .NET CLI. It's rather convenient.

dotnet nuget --help

--OUTPUT--

NuGet Command Line 5.7.0.7

Usage: dotnet nuget [options] [command]

Options:
  -h|--help  Show help information
  --version  Show version information

Commands:
  add      Add a NuGet source.
  delete   Deletes a package from the server.
  disable  Disable a NuGet source.
  enable   Enable a NuGet source.
  list     List configured NuGet sources.
  locals   Clears or lists local NuGet resources such as http requests cache, packages folder, plugin operations cache  or machine-wide global packages folder.
  push     Pushes a package to the server and publishes it.
  remove   Remove a NuGet source.
  update   Update a NuGet source.

Use "dotnet nuget [command] --help" for more information about a command.
--/OUTPUT

Without invoking the package manger console in Visual Studio, we can handle pretty much all of our operations when it comes to package management. It's almost like Node and NPM!

But, that's cool, uh, how to I find things?
NuGet has a discoverability issue. Really does, not a huge fan of this part, but with so many projects on Git these days, it's very easy to find new things there. Nuget's site has searches, but it's a workflow breaker. Sort of. There is an extension available that I found through GitHub that will add searching, but I haven't tried it yet. This is solely to illustrate the best way to find NuGet packages is.....not NuGet....

Since we know the package we want to add, we're going to go ahead and add it.

dotnet add package System.CommandLine --version 2.0.0-beta1.20427.1

And when we tree this directory:

tree
--OUTPUT--
.
├── Program.cs
├── bin
│   └── Debug
│       └── netcoreapp3.1
├── coffeemaker.csproj
└── obj
    ├── Debug
    │   └── netcoreapp3.1
    │       ├── coffeemaker.AssemblyInfo.cs
    │       ├── coffeemaker.AssemblyInfoInputs.cache
    │       └── coffeemaker.assets.cache
    ├── coffeemaker.csproj.nuget.dgspec.json
    ├── coffeemaker.csproj.nuget.g.props
    ├── coffeemaker.csproj.nuget.g.targets
    ├── project.assets.json
    └── project.nuget.cache

Taking a look at it, everything seems to be in a nice, tight location as if we built everything using Visual Studio. There's a few interesting bits in here I'd like to tuck into for a second.

The AssemblyInfo has been moved to the obj\Debug{framework} folder. This is excellent if you're targeting multiple Core standards. The AssemblyInfo.cs file is what keeps all of your compile information: copyrights, application names, versioning, etc. When we installed the System.CommandLine, several items were added to help track that information, the most import of which is in project.assets.json. This is what tracks the version of dependencies your using, their dependencies, where they're located (since you've installed them locally, they'll be relative paths), etc. Essentially, this means that if you build this application and source control it, there's no need to include them in your source control. Speaking of, before we forget:

dotnet new gitignore

The folks building the CLI really thought of everything. I am not a fan of making all kinds of updates to the .gitignore. I always forget things, but here we can, in one line, grab pretty much everything we need. If you find yourself with some time on your hands, take a look at it. It's an excellent example of what you should keep out of your source repo as they just produce bloat for commits.

That was fun, where's my coffee

Before we get too far along, let's start by adding a place to keep all of our coffee items tidy:

mkdir Brew
cd Brew
touch Brew.cs
code Brew.cs

Pop open Brew.cs in your favorite text editor, the above example will open it in VS Code. I've used nearly a half dozen different editors, and while it took some getting used to, I highly recommend giving it a chance. It's so light and customizable, I barely think of using other tools any more. Except maybe Vim, but that's more of my white whale. I have a complicated relationship with Vim.

Up at the top of your new Brew.cs file, go ahead a pull in the libraries we will need.

using System;
using System.CommandLine;
using System.CommandLine.Invocation;

Adding a namespace, let's go with Brewing for now. One of the things that I place a premium on is organization, and namespaces help you do that. If you're familiar with some basics of object oriented programming, think of namespaces as the containers you keep the objects in. They should group similar things together. Like a toolbox. It won't do you much good unless you have a very small collection of tools to place the same tools for electrical work as wood work. That's what a namespace does for you.

namespace Brewing
{
}

Inside the brewing namespace, we're going to add our first command. since the application's name is coffeemaker, the way we'll input commands is as follows:

coffeemaker brew

So with this in mind, let's go over some ground rules on how to use System.CommandLine.

System.CommandLine

This library is tailored to take in parameters from the shell. The elements it expects are:

[application] [verb] [options]

In our above example, with the coffeemaker, the application is coffeemaker, and brew is the first verb or action the application can do. Let's add a target action to take.

coffeemaker brew --Type PodSystem

With this arrangement, we're going to have the root command be the application. The child command, nested within the top level, is brew, and we're asking specificaly for the PodSystem style of coffee. We're in a hurry, after all. Just give us the gross bean water that gives life to our code and joy to our hearts! (Maybe I've had too much.)

Let's start wiring this action up inside of the Brewing namespace, shall we?

namespace Brewing
{
    public enum BrewStyle
    {
        FrenchPress,
        PodSystem
    }
    public class Brew : System.CommandLine.Command
    {
        public Brew(string name, string description = null) : base(name, description)
        {
            Add(new Option<BrewStyle>("--coffeeType"));
            Handler = CommandHandler.Create<BrewStyle>(BrewCoffee);
        }

        public void BrewCoffee(BrewStyle coffeeType)
        {
            switch (coffeeType)
            {
                case BrewStyle.FrenchPress:
                    var press = new FrenchPress();
                    press.Brew();
                    press.Press();
                    press.Pour();
                    break;
                case BrewStyle.PodSystem:
                    var pod = new PodSystem();
                    pod.Brew();
                    pod.Pour();
                    break;
            }
        }

        private class FrenchPress
        {
            public FrenchPress()
            {
            }

            internal void Brew()
            {
                Console.WriteLine("Brewing.");
            }

            internal void Press()
            {
                Console.WriteLine("Pressing.");
            }

            internal void Pour()
            {
                Console.WriteLine("Pouring.");
            }
        }

        private class PodSystem
        {
            public PodSystem()
            {

            }

            internal void Brew()
            {
                Console.WriteLine("Brewing.");
            }

            internal void Pour()
            {
                Console.WriteLine("Pouring.");
            }
        }
    }
}

Yes, that's a whole bunch of code, and yes, it's a bit of a mess. We have plans to fix that, but for now we're just trying to get our coffee out. Let's unpack our little brewer and look at the manual a bit before we toss it and forget about it.

public class Brew : System.CommandLine.Command

Within the System.CommandLine library, the rule of thumb I follow is commands are aligned with classes. This helps keep our code files focused and lean. Although there are plenty of reasons to break this rule, I prefer to start with this idea in mind.

Let's take a look at that constructor:

public Brew(string name, string description = null) : base(name, description)
{
    Add(new Option<BrewStyle>("--coffeeType"));
    Handler = CommandHandler.Create<BrewStyle>(BrewCoffee);
}

Commands are given names, these commands may or may not line up with the class name, so the library allows for you to name them separately. Maybe you have a class called SuperSecretProprietary and want to call it with action. Well, that's why we accept a name. The description is how the library will supply the using guide to the user should they call the command with --help or -h. We're going to keep wiring that up somewhere else for now.

The first thing we actively do is add an option --coffeeType. This is how we allow for the parameter to be called with the command to brew coffee. Lastly, we need a handler for our command, and for that we use the factory method Create. The <BrewStyle> bit is telling the library what parameters are needed to feed to the method we're marking for execution (BrewCoffee).

Wait, what's that BrewStyle thing?

That is possibly one of my favorite parts of C#, the Enum. Enumerations are a means of aligning actions in your code quickly. It's like a shorthand for different ways of grouping your work. Instead of having a stack of "if" statements, it allows you to flag behaviors around a set of easy to read and think through options. We declare it like so:

public enum BrewStyle
{
    FrenchPress,
    PodSystem
}

This is how we indicate to the application there's a limited number of choices. There are other ways, but this is an extremely readable way to handle this.

public void BrewCoffee(BrewStyle coffeeType)
{
    switch (coffeeType)
    {
        case BrewStyle.FrenchPress:
            var press = new FrenchPress();
            press.Brew();
            press.Press();
            press.Pour();
            break;
        case BrewStyle.PodSystem:
            var pod = new PodSystem();
            pod.Brew();
            pod.Pour();
            break;
    }
}

Now, this method is not going to win any prizes for elegance. But, it's going to get us started. Now, a word about CommandLine's behavior: it is extremely important that the paramter lines up with the name of the variable that's being used locally. What I mean by that is System.CommandLine looks for a parameter in BrewCoffee based off of the option name "--coffeeType" and the typing of the parameter (BrewStyle). Make sure these match, otherwise you will do like I do and spend entirely too long wondering why you're not getting your PodSystem brewed.

Additionally, we define two internal classes, FrenchPress and PodSystem, we use the parameter fed in to determine what actions should be taken. In this case, they're just a few methods that will report back to the console that actions have been taken.

With this, we have our first command written as well as our first parameter that can be accepted. But we have no way to actually use them from the command line just yet. Let's open up Program.cs and do a few quick tweaks and see the fruit of our labor.

namespace coffeemaker
{
    class Program
    {
        static void Main(string[] args)
        {
            var rootCommand = new RootCommand() { new Brewing.Brew("brew") };
            rootCommand.InvokeAsync(args).Wait();
        }
    }
}

What's happening here is we initialize the root command, which in this case as we are not naming it or providing a description defaults to the name of the application. Using a handy technique called Collection Initialization, we add a new command, our trusty Brewing.Brew() command, naming it "brew". Lastly, we invoke it, passing in the args and wait for it to finish executing. Using the System.CommandLine vocabulary, the parent command is the root command of the applicaiton, with it's child command of "brew" being able to be called.

If you're using VS Code or a similar editor, it's no doubt shouting at you right now. There's probably red squiggles and highlights right around the Brewing.Brew line, and it looks very unhappy and the program will not build. This is because we've asked it to do something without the right toolboxes on the workbench. Let's fix that by telling Program.cs what toolboxes to look into for the tools it needs:

using System;
using System.CommandLine;
using Brewing;

There we go, all better. Now, the application is less angry and will build.

This is where the dotnet CLI comes back in with a really cool feature. The dotnet CLI allows for you to pass in all of these arguments and commands straight into the run command. Let's take a look at how these things all work together.

CLI to Victory

dotnet build

There are a few ways to run this command, but for a simple project like ours we only need to be in the root directory of our application where the csproj file is. The build command will look for a csproj, and using that will build the application. If you have multiple projects, you can build just the project you're working with by specifying the project:

dotnet build coffeemaker.csproj

Additionally, sometimes things get stuck. Maybe there's a reference that doesn't quite work correctly, maybe you just need to check that you're building the most current version. For that, you can do a clean:

dotnet clean

This removes all of the built items. If you're coming from a Visual Studio background, the Rebuild option is handled by combining these two commands.

Now, to run the application, oddly enough we will use this:

dotnet run

Right away, the application fails and provides some helpful hints as to why. Right there in red letters is the message that we've forgotten a required command. Down at the bottom of the console output, there's a list of commands that are available to you, let's try that again, using the parameter functions of dotnet run.

dotnet run -- brew

The run command uses the double dash to separate dotnet CLI commands and what is fed into your application. If everything has gone accoring to plan, you were just notified that a tasty batch of FrenchPress is ready to drink. But, as I said, we're in a hurry. There's never enough time in the day and we needed a quick hit of that sweet delicious coffee without waiting for a french press. Let's add our last parameters in and re-run the application.

dotnet run -- brew --coffeeType PodSystem

Now, we're passing the coffee type as a string and selecting that enumerator to feed into the switch statement above. We get a quick report that the two steps needed have been complete and we have our pod system coffee.

Next Steps

Definitely checkout the System.CommandLine github. I'm going to be using this heavily to begin building out the One Coffee Maker to Rule Them All. Another path we might travel is to create an extension to the .NET core CLI that begins to include some git functionality. At least, that's a topic that is interesting to me.

As always, I would love to hear from you all. Coding is best when collaboritive. Where did this help you? Where could it have been more clear? What kinds of coffee should we include in the final product?

In our next episode, we'll begin by doing some house keeping. Refactoring is an extremely important aspect of writing code and I hope to share some of my process when I do that. How do you keep things tidy? What bits would you move in this application so far to help others get to coding more quickly?

.NET Core's Command Line

icarusComplexz — Mon, 07 Sep 2020 14:35:33 +0000

Don't Bore Us Get to the Chorus

For those who are like me and might want to skip over to the things you want, here's a quick jump list.

Topic	Section Heading
Accessing the CLI	Shell? Like Powershell, Right?
First steps in the command line	All Right, I opened it, now what?
The .NET CLI vs. plain command line	So this is the .NET CLI?
How to use --help and the .NET CLI	HELP! I NEED SOMBODY!
Where do I go from Here?	Great! Am I coding now?

The Command Line

When I first started to learn how to write code, there was this unshaken sense that I would never be able to do it for real. So many preconceptions about how developers work exist, and they exist for a reason. One of the major barriers to my journey was an absolute, unwarranted, but very real fear of the command line. Why can't I just use my File Explorer? How come I can't click "File => New => C# Class" in Visual Studio and have it show up magically? It turned out, it's absolutely possible to never use the command line to develop .NET. It's been a few years since I got started, and since then I've realized that the command line, is a wonderful place to work, even for scaredy cats like me.

What changed was how much I used Linux. While Ubuntu and related distros have made incredible strides to being an out of the box best in class experience, for most users the command line will still become a part of your day to day life. (sudo apt-get update anyone?) While I still use file system explorers like Finder, File Explorer, and Nautilus, often times it's just far, far simpler to reach out and touch something with a shell. (I got dad jokes. Not sorry. 🧀🧀)

Shell? Like Powershell, Right?

Right! And not right, sort of. Powershell is a command line shell application. On a Mac, the most common is "Terminal". If you're on Linux, chances are you know what your shell is, but if you're new to it, it's probably also called "Terminal" or "Konsole".

What these application have in common is that you don't click around to get work done. You type everything out. It sounds exhausting, but trust me, the process becomes and absolute treat after a while and will feel faster than using your mouse. It may not make you a 10x developer though. Or maybe it will, I don't know, green text on a black screen makes me feel more productive.

All Right, I opened it, now what?

Jumping right in! I love it!

I by no means am a CLI expert, but these commands I use every day, all day.

mkdir
- mkdir NewDirectory
- Make directory. Makes a new folder for you to store all your cool new things in.
- Works in Powershell as well, but if you really want to get fancy, PowerShell's New-Item is very flexible. It's done using the same thing we id before, but using parameters.
  - New-Item -Name NewDirectory -ItemType Directory
  - In CLIs, it is common to express a command (New-Item) and then pass parameters (-Name, -ItemType) with values (NewDirectory, Directory). For mkdir, the parameter and the value of it are NewDirectory.
cd
- cd .\NewDirectory
- cd in most shells means "change directory". In CLIs, folders are termed "directories". The above will change directory, using the location you're currently at (.) and looking for the directory dev (because of the \dev telling it where to go).
- Also works in Powershell!
touch
- touch NewFile.txt
- Tells your system to make a new file. It's used like
- If you're in Powershell, it's a little different. New-Item NewFile.txt will get you sorted.
rm
- rm NewDirectory
- This removes things. For most systems, it will not remove directories that have things inside of them, instead asking you to confirm. If you want to skip confirming it, you can use -rf as a parameter. This adds two flags for "recursive" and "force", which will tell the system "Yes, I know there's stuff inside there, and there are nested folders, just get rid of it". And poof, files are gone forever. (To make this work, you'll need to cd .., which will move directories to the parent directory.)

What are those dots all about?
As you become accustomed to the command line, you wil find out that typing a lot is a real pain. You can be way more efficient using a command line, but there is a lot more typing. The dots are designed to help you out. A single dot means the current directory. Double dots will mean the parent directory. If you use something like cd ..\..\, you will move "up" two directories.

So this is the .NET CLI?

Not quite, but this will be helpful. But, now you know enough to get started for sure.

So, while you're at your terminal, go ahead and check out if the .NET CLI is installed. Put on your favorite hacker shades/hater blockers and run the following (type it in the command line and press enter):

dotnet --version

If .NET Core is installed, this will print the version of what is installed. If you get an error, PANIC right away. Then breathe and head over to Microsoft's page here and they will get you sorted out. I'll wait, I have time. I'd tell you how to install it, but frankly they do a better job anyway. You might even like their tutorials better, they've gotten quite good.

If, however, numbers printed in the output (that bit under where you entered your commands) got some numbers then you're all set and it's installed. One of the things that will really help in your journey with the command line is knowing that help is only five keystrokes away with most commands. Let's see what I mean.

HELP! I NEED SOMBODY!

Run the following:

dotnet --help

Look at everything that printed out. That's a lot of information, and I'm assuming you're following along. We're a few steps away from being able to finally work with this tool, but let's take a deep breath and look at what it just spit out for us because this is one of the things that I've found that this team does really, really well.

I'm going to do a little skipping here because there are a boatload and a half of tools available in this tool. Let's focus on the SDK commands for now.

A few lines down, you should see the following:

Usage: dotnet [sdk-options] [command] [command-options] [arguments]

This is how the application is telling you to run the various commands that make the operation work and the order in which you need to input them. First, you enter any options you will need, then the command, the command options, and any arguments the command options will need.

Under this line is a series of useful things that are broken out into sections. sdk-options has a list of what you can put in front of your commands to have them do a few extra things on top of what they already will do. Under that is a section labelled SDK Commands that lists the commands that can be run. "But where are the command options? Where's the arguments? What do these things all need to run?" Well, this is where the --help command really does it's work. If you head back over to the command line, you can call any of the commands for the SDK with --help, and the application will let you know what you need to run it.

For example:

dotnet new --help

Will run the application dotnet, with the command new with the option --help and print out instructions on how to use the command as well as a list of solutions that you can make right out of the tool. These templates are built into Visual Studio, so if you're like me you might see some old friends and some new ones.

Great! Am I coding now?

Well, if we're not careful we're going to make a mess. Let's put this all together into something interesting, after all you've been reading a lot of boring stuff that may not have been fun.

Now, maybe you're like me and you've been copying and pasting things so far. That's fine, but let's really, really work on not doing that for this next part. It will help you get used to how the CLI works if you're typing now. It's a lot to ask, but give it a shot.

First, let's figure out where we are:

ls

A new command appeared! I know, I didn't tell you about this one. This one is extremely helpful. It's a listing command. It looks where you're at and shows you all of the directories and files that are listed within the directory you're in. More than likely, it's in your "home" folder and probably has a ton of things in it. Let's get out of here and go somewhere else to do work.

Make a directory called newtoys.

mkdir newtoys

List the files in the directory you're currently in and you should see a new directory.

ls

Let's switch to it and start doing something.

cd newtoys

If you list what's in there right now, there's nothing in it. It's a blank canvas for your new masterpiece.

dotnet new console

Using the dotnet cli, you're asking for it to create a new application using the template console. By default, since no arguments are sent in, the dotnet tool will use the folder that you're working in as a cue for what the application should be named. Listing the files shows Program.cs, newtoys.csproj, and an obj directory.

I use VS Code for my editing, so for me, we can run that from the CLI as well. If you have it installed, run the following:

code Program.cs

This will open the file for editting. It isn't really essential to have anything special in there right now, but I went ahead and changed what it prints like so:

using System;

namespace newtoys
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello Dev.to!");
        }
    }
}

Now, we have an application. We can run it in VS Code, Visual Studio, Rider, or whatever you want. But let's press on.

dotnet build

Since you're working in the same directory as the newtoys.csproj, running the build command will search that directory for any project files (.csproj) that describe an pplication. since it found the newtoys.csproj file, it went ahead and compiled everything, reporting back success and giving a breakdown of the process. If, like me, you're curious about how things work, you can pass in a few more options and have the application's logging enhanced.

dotnet build -v d

This will re-run the build process with the "verbosity" (-v) set to "d[etailed]". This is a moment-to-moment list of the oeprations that dotnet build ran. This can be helpful if you run into something not working quite as expected and most CLIs will have some option that will let you set how verbose of feedback to give you.

ls

There is a new folder now, \bin. This directory is the default directory that dotnet will build out into. "Bin" is short for "binaries", and holds all of the compiled pieces of your application.

dotnet run

While you're here, this will re-build the application, compile all the binaries and copy them to the \bin directory and execute the application.

Now What?

Now, we've covered a few basics of the CLI. With this, you can navigate directory trees, start a new project, make new files, wire them up and build them. However, here's the deal, cards on the table so to speak. I'm relatively new to blogging. This article is something that I wish existed three years ago when I was grinding away, bound to Visual Studio and hopelessly uncomfortable with what I felt was how a "real developer" worked.

So, with that in mind, let's make this a collaborative effort.

Folks who found this article to be too basic: what should I have added? What are the killer commands that you wish someone had sat you down and explained?

Y'all who are wondering how to take next steps: where do you want this to go? What are you working with? Where do you need help? I can't promise I have all the answers, but here's what I do love: finding cool new things that others will benefit from. Maybe you're like me and don't want to ask a question "because it's somewhere on Stack Exchange". Well, ask anyway.

Next Steps

I'll be building this into a full application! It's going to be a little quirky, but the goal is to showcase the .NET command line parsing tools. Having built a tool or two that uses nothing but console applications, I have learned to love the level of support that it's getting with recent Core developments. If you want a peak in advance, here's the tooling I'll be using to start this application: https://github.com/dotnet/command-line-api . (Trust me, it's awesome!)

How To Learn A New Framework

icarusComplexz — Thu, 07 May 2020 01:53:25 +0000

How I Learn a new Framework/Tool

Inspired by my recently started journey in node.js.

Begin by finding that new 🔥

If you're looking for something new to learn, I may not be able to help you. You're on Dev.to and there's hundreds of other bloggers with really cool new projects. We're going to assume you've already completed this step.

Phase 1: Getting Started🏁

Now that you've selected your new toy, find out a little more about it. Open your favorite search engine and yeet that framework's name right into the search bar and smack that space bar.

After you read the first link, which is of course their site/git/nuget/npm/pile of post it notes/twitter, realize you need to add "tutorial" because you have no idea what's happening right now.

That last part is important because it's a trigger. You're going to need to make a nice big [ glass | mug ] of your favorite [ beverage | ( coffee | tea ) ]. Take a sip, the journey begins!

Phase 2: Onward to Excellence 🏆

Now that you've got a nice big list of results, ignore everything else on the page and go to the first one. Don't worry about learning styles/getting to know the tutorial author, it's all the same.

Phase 3: Do All the Things 🤓

Diligently read each step of the tutorial at first. This is super important as following the instructions will walk you through the basics of the what you're trying to learn. It's important to understand these fundamental concepts before continuing. Keep in mind the tutorial author does not know what you know or don't know, so there may be some early sections you will want to skim, but make sure that you're not missing anything. Lord only knows what weird thing is different about this framework, behind that keyword you recognized is an ocean of code.

Phase 4: Get Super Bored 🥱 *

Maybe you have a few things under your belt, maybe you just got started, but code is code and changing a few variable names couldn't hurt, right? Just go ahead and start renaming things. I mean, they're only variables.

And what's with all of these paths and files? Just store everything in the root directory. This is supposed to be a quick jog through the basics, you know this all already. Just toss everything in a pile, you can clean it up later.

Or maybe the organization of the tutorial isn't what you like, just stuff it into another folder and re-use some shorthand. Personally, I use the Seussian "thing" naming pattern. You'll never run out of variables iterating through "thing1", "thing2", "thingN", or if you're feeling frisky "thingBuzz". If your language supports emojis, definitely use those. There's no reason why you can't iterate by doing a foreach(var 👩‍🚒 in 🚒) Seriously, just go nuts here, gotta keep it interesting.

Phase 5: Debugging 🦋

All right. If you're like me, you're now somewhere around 10-15% of the way through the tutorial, but there's red squiggles and things aren't compiling.

🛑 🛑 DO NOT PANIC! 🛑 🛑

There's probably something clarifying what your [ linter | debugger | whatever that thing's called ] is complaining about on the page before that we've skimmed through. Just take a step back and read through it.

This is a perfect time to get up, stretch, refresh your beverage, pet the cat, walk the dog, water the plants, or check Twitter. Go ahead, I'll wait.

Are you back? How's the pet/plants? Anything fun on Twitter? Did you bring me a coffee? No? Ok, fair enough. Now, start searching all those errors. To save you a step, remember to put the framework at the end of the query. If that doesn't work, just search the framework and "github". There's probably an issue out there that is exactly what you're looking for because there's no way it's not working because of the previous step. Trust me, we've all been there.

Phase 6: Return to the Tutorial 👩‍🏫

All right, so, that didn't work. Let's give the devs the benefit of the doubt, they probably know what they're doing. I might have lead you too far afield with using emojis in code, that was my bad. Find the tutorial you were reading before, copy the example code and pop it into your IDE.

Phase 7: Guide Rails 🚉

Search your IDE's extensions/plugins for the framework. Add as many as possible, we've lost precious minutes already. Bonus points if the framework provides one specific to your IDE. A good benchmark here is at least five plugins to ensure success.

Bonus Tip: Write down these extension names on a post-it note, you'll need that for a later phase.

Phase 8: De-clutter your IDE 😒

Got that post-it note? Yeah, me neither.

Either way, these plugins are not bringing me joy, so away they go. Just get rid of anything that's not from the framework provider.

Phase 9: Find Another Tutorial 🔍

But keep your old code. You're going to need it. Copy it and rename it the same with a 1 (e.g. app1.js, index2.html). Don't worry about referencing other files, we're not coming back to them and they're only referenced by that one folder.

Well, that's not true. As you're starting the new tutorial, skip the first few pages as you were just in another one and there's probably nothing new there**. Adapt your other files as you can, but there'll be clarification if you can find roughly the same spot in this tutorial equivalent to where you were in the first one.

Phase 10: Goto Phase 3 🎡

All right, off you go now. Repeat the previous steps with a new tutorial until you get back here at least 2-3 times. If you're just returning, go ahead to the next phase, I don't have anything witty here.

Phase 11: Return to the Original and Complete 🎭

Now that I think about it, let's go back to that first tutorial and finish it. I mean, really finish it. Delete everything, and start with step one. Definitely read the details even if it's not new to you at this point, that debug step was probably confusing.

Once you've made it through one tutorial, head back to one or two of the others and give them a shot. With a few under your belt, you'll grasp the basics and now it's absolutely time to implement this at scale! Add it to your LinkedIn and start drumming up use cases!

(If you made it this far and wonder what the joke is, this is legit how I do it and there's some problems with my methodology. Send help/coffee!)

* Tutorial authors: please don't take this to heart. I'm a fan, really. If it weren't for your efforts, I wouldn't know anything about how programming works.
** For real, tutorial authors, you're the real MVP here.