• Array.Empty<T>

• string.Empty

// instead of
string foo = "";
byte[] bar = new byte[0];

// prefer
string foo = string.Empty;
byte[] bar = Array.Empty<byte>();

If you are now asking yourself why you should use this - string and array are immutable (they will always be created new when the content does change and the old memory is garbaged). By using the static fields there is no additional memory location for the value of the variable, it will always be the same.

Naturally, you will first note a real impact if you are creating very much strings and/or arrays. But it is always better to follow best practices from the beginning instead of running into problems afterwards...

In one of my older projects, I often had to synchronize and work with different parallel threads. Using async, parallel or 'real' threads does not make a real difference when it is coming to thread safety.

As a very short short instruction to thread safety: Every value is stored in memory somewhere, somehow. The location in memory has got an address, so called memory address. When you set the value once and only read from it in the rest of the program you won't have any problems (e.g. const). But if you set the value multiple times and read from it, you do not know which result you will get as all threads are accessing the same memory address at the same time.

Let us take an example, you have a string in memory containing '1234567890' and re-writing this the whole time to '0987654321'. It does require time to set the value in memory and reading is much faster. When you read this value in parallel from another thread you will never know which value you get. It may also happen that you get 'garbage'.

This article does only cover handling variables not the program flow itself. When working in parallel, always make sure that all parts of your application or area can be handled parallel (ServiceProvider / external resources).

Integer

Integers can be implemented quite simple using Interlocked and the corresponding methods.

The main method I mostly work with is Exchange(), please just take a look at the ThreadSafeBool class further down.

Boolean

Following just a short dump of a thread safe bool class implemented using Interlocked.

public class ThreadSafeBool
    {
        /// <summary> internal storage </summary>
        private int _internalBackingDoNotUse;

        /// <summary> Use interlock exchange for thread safety </summary>
        private bool ThreadSafeBoolValue
        {
            get => Interlocked.CompareExchange(ref _internalBackingDoNotUse, 1, 1) == 1;
            set
            {
                if (value) Interlocked.CompareExchange(ref _internalBackingDoNotUse, 1, 0);
                else Interlocked.CompareExchange(ref _internalBackingDoNotUse, 0, 1);
            }
        }

        public static bool operator true(ThreadSafeBool tsb)
        {
            return tsb.ThreadSafeBoolValue;
        }

        public static bool operator false(ThreadSafeBool tsb)
        {
            return !tsb.ThreadSafeBoolValue;
        }

        public ThreadSafeBool()
        {
        }

        public ThreadSafeBool(bool value)
        {
            ThreadSafeBoolValue = value;
        }

        public static implicit operator ThreadSafeBool(bool value)
        {
            ThreadSafeBool tsb = new ThreadSafeBool
                {
                    ThreadSafeBoolValue = value
                };
            return tsb;
        }

        /// <summary> 
        /// operator for using retrieving
        /// </summary>
        /// <param name="tsb"></param>
        public static implicit operator bool(ThreadSafeBool tsb)
        {
            return tsb.ThreadSafeBoolValue;
        }

        /// <inheritdoc />
        public override bool Equals(object obj)
        {
            return base.Equals(obj);
        }

        /// <inheritdoc />
        public bool Equals(bool other)
        {
            return ThreadSafeBoolValue == other;
        }

        /// <inheritdoc />
        public override int GetHashCode()
        {
            return ThreadSafeBoolValue ? 1 : 0;
        }
    }

    [TestClass]
    public class ThreadSafeBoolTests
    {
        [TestMethod]
        public void TestMethod1()
        {
            ThreadSafeBool tsb = false;

            bool currentValue = tsb;
            Assert.AreEqual(currentValue, false);

            if (tsb)
                Assert.Fail();
            if (tsb == true)
                Assert.Fail();


            tsb = true;
            currentValue = tsb;
            Assert.AreEqual(currentValue, true);

            if (!tsb)
                Assert.Fail();
            if (tsb == false)
                Assert.Fail();
        }
    }

Lock

Using the lock statement we can use a simple object as some kind of 'blocker'. As in, we use this object to synchronize our requests. It is required to ensure that all access to the variable is only done using the lock statement.

Following a short example with lock and a string by using properties ensuring the access to the variable only inside the lock:

public class Program
{
    private object _sampleLockedStringLock = new object();
    private string _sampleLockedString = string.Empty;
    public string SampleLockedString
    {
        get
        {
            lock(_sampleLockedStringLock)
            {
                return _sampleLockedString;
            }
        }
        set 
        { 
            lock(_sampleLockedStringLock)
            {
                if (_sampleLockedString == value)
                    return;

                _sampleLockedString = value;
            }
        }
    }
}

ASP.NET IMemoryCache

For web projects a great thread safe alternative for caches is IMemoryCache. Providing easy setter/getter and even expiration for the cache entries!

Thread safe collections

To round up, please also refer to thread safe collections and the great article when to use them.

Do not forget, that the collection itself is thread safe, but not the content if you are storing reference types inside.

User interfaces overview

At first, we take a general look at the several available UserInterfaces. There are naturally more, but these are the most popular imho. Web interface is no choice, as we require a direct connection to the databases.

WPF

In my current job I am heavily working with WPF, so at least I got the knowledge to do a fast migration. We could for example change to WPF windows and host the windows forms controls inside the WindowsFormsHost, migrate the windows step by step. Up from .Net 5 there is support for WindowsForms and WPF in .Net. However the new cross platform chosen by Microsoft is based on Xamarin and called MAUI. I could not find any information, beside some dev blogs or questions on reddit/quora, which will give us an inside if WPF will be further developed or discontinued at some point. But WPF is now OpenSource and released under the MIT license, so everyone can further develop it. As many business apps nowadays are based on WPF, we can estimate that it will be supported and working at least one more decade.

MAUI

This is the "new" cross-platform GUI for .Net announced back in 2020. In effect it is Xamarin merged into .Net 6. The official release was in March 2022. If you ever developed any apps for Android or iOS with Xamarin you will find yourself very comfortable in MAUI.

AvalonUI

OpenSource, MIT licensed, .Net cross platform UI. A great start is the FAQ. In short:

• Developed by around 20 people as core team and according to the faq by 'hundreds of developers'
• Started in 2013 under the name Perspect
• Enterprise support possible It seems to be possible to host winforms/wpf controls in AvalonUI, but all links from this issue lead to 404.

Declaration of requirements

As we are porting a WindowsForms application to the new user interfaces, we have to think about the most important point of the application. NyxSql is a graphical interface for sql queries and database content. As databases normally contain many data the performant display of data in a grid is the main concern. Especially if a query will return hundreds of thousands of rows.

Furthermore, we will need to decide if it shall be cross platform or only windows. I will get some feedback on this topic and plan to continue with that series at the end of the month.

Now, it is kinda like 'evil', because you do not get prompted again. The invalid credentials are saved and you are just lost seeing error messages the whole time.

Following solutions are available:

• Remove the source from Visual Studio, close, open, enter them again (works 2 of 4 times)
• Go to Control panel - User Accounts - Manage your credentials and check if they are listed there (never had that...)
• Update the credentials with dotnet:

list all and update afterwards:

dotnet nuget list source
dotnet nuget update source "<source name>" -u <username> -p <pass>

With a link to open the configuration manager. My thought was like 'Uh great, fix is directly there'. Sadly you can click whatever you want in the configuration manager the problem does not go away... Furthermore no build is carried out

The fix is like:

• Close Visual Studio
• Open the projects solution file (.sln) with an editor of your choice
• Search for: GlobalSection(ProjectConfigurationPlatforms) = postSolution
• Delete ALL lines until EndGlobalSection
• Save
• Open with Visual Studio again

Within this article we will take a look at the upgrade project file and how it should look like : )

With .Net (Core), Microsoft introduced a much better formatted and usable project file than in previous versions. Sadly, the upgrade assistant and new projects had been a mess in the beginning (for creating the project files), but slowly it seems to get better.

At the end of this article, you can find an example of the Nyx project file after the upgrade. I am not posting it right here, because nobody likes to scroll over dozens of lines...

General

When reformatting/extracting the project file, it is important to know about the different properties. So, if you find some which are unknown to you, just look it up using the MSDN and be happy that you learned something new! : ) *Sadly, right now F1 (=Open Help) is only usable on the root properties, so we have to look them up manually.

Especially when working in teams it is important to have a unique structure throughout all projects. Imagine you want to change some setting, and always must search the project file, if and where this setting is used.

The first thing I normally do is execute the auto-formatting on the file by pressing Ctrl + Alt + Enter. Another important thing, use commentary blocks for a better visual structure.

Normally I split the project file into two different blocks. The first one does contain properties that are valid/required for all projects and the second one which is different for each project.

The first, general, block

The properties which are valid for all projects: `

<Project Sdk="Microsoft.NET.Sdk">
    <!--
    fixed settings, same for every .net 6 project
    -->
    <PropertyGroup>
        <!--general -->
        <Company>y0</Company>
        <Copyright>Copyright © 2022</Copyright>
        <PackageLicenseUrl>www.mit-license.com</PackageLicenseUrl>
        <PackageProjectUrl>www.myproject.com</PackageProjectUrl>
        <!--application versioning-->
        <AssemblyVersion>1.1.0</AssemblyVersion>
        <!--general settings-->
        <RestorePackages>true</RestorePackages>
        <PlatformTarget>x64</PlatformTarget>
        <TargetFramework>net6.0-windows</TargetFramework>
        <LangVersion>latest</LangVersion>
        <Deterministic>False</Deterministic>
        <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
        <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
    </PropertyGroup>
    <!-- unit test / visible to .Test assembly -->
    <ItemGroup>
        <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
            <_Parameter1>$(AssemblyName).Tests</_Parameter1>
        </AssemblyAttribute>
    </ItemGroup>
    <!--general debug and release settings-->
    <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
        <DefineConstants>TRACE;DEBUG;</DefineConstants>
        <CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
    </PropertyGroup>
    <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
        <DebugType>portable</DebugType>
    </PropertyGroup>
    <PropertyGroup>
        <OutputType>Exe</OutputType>
    </PropertyGroup>
    <!--
    dynamic project related 
    -->
</Project>

Conditions, Configuration == build configurations

Settings related to the configuration, platform or other conditions are next.

Do we really require different AnyCpu/x86/x64 conditions? Very rare required but mostly taking much space and causing big confusions (the platform target was already set in the first section.

If not, we can simply remove the platform condition by transferring:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' "> .. </PropertyGroup> <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' "> ... </PropertyGroup> <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' "> .. </PropertyGroup> <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x86' "> ... </PropertyGroup> to: ```

true TRACE;DEBUG; portable ```

Empty project folders

By using the upgrade-assistant, all empty folders without source files are integrated: <ItemGroup> <Folder Include="NyxMsSql\" /> </ItemGroup> As it is just an empty folder, we delete the folder by using Solution Explorer. By handling it this way, the section is also automatically removed.

Assembly/project references and NuGet packages

And finally, the nodes for the project/assembly references and the NuGet packages. I personally keep the project, then the assembly references and finally the NuGet packages, because NuGet packages are handled automatically.

Summary

With the latest upgrade-assistant it is, not anymore, such a big mess. However, the same structure of the project files is coming in very handy if working with dozens of projects.

One project file is done, two to go! : )

Example formatted file

<Project Sdk="Microsoft.NET.Sdk">
    <!--
    General settings, mostly the same for all projects
    -->
    <PropertyGroup>
        <!--copyright -->
        <Company>Dominik Schischma</Company>
        <Copyright>Copyright © 2022</Copyright>
        <PackageLicenseUrl>www.sigterm.eu</PackageLicenseUrl>
        <PackageProjectUrl>www.sigterm.eu</PackageProjectUrl>
        <!--application versioning-->
        <AssemblyVersion>0.0.1</AssemblyVersion>
        <!--general settings-->
        <RestorePackages>true</RestorePackages>
        <PlatformTarget>AnyCPU</PlatformTarget>
        <TargetFramework>net6.0-windows</TargetFramework>
        <LangVersion>latest</LangVersion>
        <Deterministic>False</Deterministic>
        <!--do not create sub directories like 'net-6.0' -->
        <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath><AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
    </PropertyGroup>
    <!-- build configuration -->
    <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
        <!--only use in debug!-->
        <CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
        <DefineConstants>TRACE;DEBUG;</DefineConstants>
    </PropertyGroup>
    <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
        <DebugType>portable</DebugType>
    </PropertyGroup>
    <!-- unit test / internals visible to .Tests assembly -->
    <ItemGroup>
        <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
            <_Parameter1>$(AssemblyName).Tests</_Parameter1>
        </AssemblyAttribute>
    </ItemGroup>
    <!--
    nyxsql
    -->
    <PropertyGroup>
        <OutputType>WinExe</OutputType>
        <AssemblyName>NyxSql</AssemblyName>
        <RootNamespace>NyxSql</RootNamespace>
        <!--<StartupObject>Nyx.Program</StartupObject>-->
        <ApplicationIcon>Resources\Nyx.ico</ApplicationIcon>
        <!-- still windows forms -->
        <UseWindowsForms>true</UseWindowsForms>
        <ImportWindowsDesktopTargets>true</ImportWindowsDesktopTargets>
    </PropertyGroup>
    <!--non-classes & usercontrols-->
    <ItemGroup>
        <Compile Update="NyxControls\AutoCompletition\AcListBox.cs">
            <SubType>Component</SubType>
        </Compile>
        <Compile Update="NyxControls\PreviewTab.cs">
            <SubType>UserControl</SubType>
        </Compile>
        <Compile Update="NyxControls\ProcedureTab.cs">
            <SubType>UserControl</SubType>
        </Compile>
        <Compile Update="Tools\Connection\ConnectionInput.cs">
            <SubType>UserControl</SubType>
        </Compile>
        <Compile Update="NyxControls\SqlRichTextBox.cs">
            <SubType>Component</SubType>
        </Compile>
        <Compile Update="NyxControls\SqlTab.AutoCompletition.cs">
            <DependentUpon>SqlTab.cs</DependentUpon>
            <SubType>UserControl</SubType>
        </Compile>
        <Compile Update="NyxControls\TableTab.cs">
            <SubType>UserControl</SubType>
        </Compile>
        <Compile Update="NyxControls\TriggerTab.cs">
            <SubType>UserControl</SubType>
        </Compile>
        <Compile Update="NyxControls\ViewTab.cs">
            <SubType>UserControl</SubType>
        </Compile>
        <Compile Update="NyxControls\SqlTab.cs">
            <SubType>UserControl</SubType>
        </Compile>
    </ItemGroup>
    <!--project references-->
    <ItemGroup>
        <ProjectReference Include="..\NyxSettings\NyxSettings\NyxSettings.csproj" />
    </ItemGroup>
    <!--assembly references-->
    <ItemGroup>
        <None Update="Assemblies\Mono.Security.dll">
            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
        <None Update="Assemblies\MySql.Data.dll">
            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
        <None Update="Assemblies\Npgsql.dll">
            <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
    </ItemGroup>
    <!--nuget-->
    <ItemGroup>
        <PackageReference Include="odp.net.managed" Version="121.1.2" />
        <PackageReference Include="System.Configuration.ConfigurationManager" Version="5.0.0" />
        <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
            <PrivateAssets>all</PrivateAssets>
        </PackageReference>
        <Reference Include="MySql.Data, Version=5.0.7.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d, processorArchitecture=MSIL">
            <Private>False</Private>
        </Reference>
        <Reference Include="Npgsql, Version=0.99.3.0, Culture=neutral, PublicKeyToken=5d8b90d52f46fda7, processorArchitecture=MSIL">
            <SpecificVersion>False</SpecificVersion>
            <HintPath>assemblies\Npgsql.dll</HintPath>
            <Private>False</Private>
        </Reference>
    </ItemGroup>
</Project>

Example file after the upgrade

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-windows</TargetFramework>
    <OutputType>WinExe</OutputType>
    <AssemblyName>NyxSql</AssemblyName>
    <StartupObject>Nyx.Program</StartupObject>
    <ApplicationIcon>Resources\Nyx.ico</ApplicationIcon>
    <SignAssembly>true</SignAssembly>
    <AssemblyOriginatorKeyFile>NyxKey.snk</AssemblyOriginatorKeyFile>
    <TargetZone>LocalIntranet</TargetZone>
    <GenerateManifests>false</GenerateManifests>
    <SignManifests>true</SignManifests>
    <ManifestCertificateThumbprint>37D2B3D67A093A04C499A9FE8A89B1EA7E3532D7</ManifestCertificateThumbprint>
    <ApplicationRevision>0</ApplicationRevision>
    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
    <UseWindowsForms>true</UseWindowsForms>
    <ImportWindowsDesktopTargets>true</ImportWindowsDesktopTargets>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
    <UseVSHostingProcess>false</UseVSHostingProcess>
    <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies>
    <DocumentationFile>bin\Release\NyxSql.XML</DocumentationFile>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <DebugType>none</DebugType>
    <CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
    <UseVSHostingProcess>false</UseVSHostingProcess>
    <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies>
    <DocumentationFile>bin\Release\NyxSql.XML</DocumentationFile>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x86' ">
    <OutputPath>bin\x86\Debug\</OutputPath>
    <CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
    <DocumentationFile>bin\Release\NyxSql.XML</DocumentationFile>
    <UseVSHostingProcess>false</UseVSHostingProcess>
    <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|x86' ">
    <OutputPath>bin\x86\Release\</OutputPath>
    <CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
    <DocumentationFile>bin\Release\NyxSql.XML</DocumentationFile>
    <DebugType>
    </DebugType>
    <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies>
  </PropertyGroup>
  <ItemGroup>
    <Reference Include="MySql.Data, Version=5.0.7.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d, processorArchitecture=MSIL">
      <Private>False</Private>
    </Reference>
    <Reference Include="Npgsql, Version=0.99.3.0, Culture=neutral, PublicKeyToken=5d8b90d52f46fda7, processorArchitecture=MSIL">
      <SpecificVersion>False</SpecificVersion>
      <HintPath>assemblies\Npgsql.dll</HintPath>
      <Private>False</Private>
    </Reference>
  </ItemGroup>
  <ItemGroup>
    <Compile Update="NyxControls\AutoCompletition\AcListBox.cs">
      <SubType>Component</SubType>
    </Compile>
    <Compile Update="NyxControls\PreviewTab.cs">
      <SubType>UserControl</SubType>
    </Compile>
    <Compile Update="NyxControls\ProcedureTab.cs">
      <SubType>UserControl</SubType>
    </Compile>
    <Compile Update="Tools\Connection\ConnectionInput.cs">
      <SubType>UserControl</SubType>
    </Compile>
    <Compile Update="NyxControls\SqlRichTextBox.cs">
      <SubType>Component</SubType>
    </Compile>
    <Compile Update="NyxControls\SqlTab.AutoCompletition.cs">
      <DependentUpon>SqlTab.cs</DependentUpon>
      <SubType>UserControl</SubType>
    </Compile>
    <Compile Update="NyxControls\TableTab.cs">
      <SubType>UserControl</SubType>
    </Compile>
    <Compile Update="NyxControls\TriggerTab.cs">
      <SubType>UserControl</SubType>
    </Compile>
    <Compile Update="NyxControls\ViewTab.cs">
      <SubType>UserControl</SubType>
    </Compile>
    <Compile Update="NyxControls\SqlTab.cs">
      <SubType>UserControl</SubType>
    </Compile>
  </ItemGroup>
  <ItemGroup>
    <None Update="Assemblies\Mono.Security.dll">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="Assemblies\MySql.Data.dll">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="Assemblies\Npgsql.dll">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <BaseApplicationManifest Include="Properties\app.manifest" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\NyxSettings\NyxSettings\NyxSettings.csproj" />
  </ItemGroup>
  <ItemGroup>
    <Folder Include="NyxMsSql\" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="odp.net.managed" Version="121.1.2" />
    <PackageReference Include="System.Configuration.ConfigurationManager" Version="5.0.0" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>
</Project>

In this series, I will write about upgrading a project which was created on .Net Framework 2 to .Net Core. All steps will be included, as in pushing to a fresh github repository and every major step of the migration.

NyxSql?

At first, the name was inspired by Nyx. I decided to write this program over a decade ago, due to the lag of universal sql editors / gui tools from windows to most common databases. It was intended to be a learning project using WinForms. As I mainly used it for Oracle database it was abandoned by me when SqlDeveloper was released.

Restore of the sources and upload to github

• Unzipped the old svn backup
• Removed the .svn folder

Git repository

Currently I created a private git repository at GitHub. Perhaps I will make it public at some time, but due to bad experiences with projects, which had been completely cloned and used without any credits, I am keeping it private right now.

First loading of project after some years

After git was pushed and all files in place, I opened the solution with Visual Studio. The very first question which came was the 'Target framework not supported', where the upgrade to 4.8 was confirmed.

Afterwards a whole batch build and installation of odp.net.managed nuget package. Then NyxSql started without any further complains! As happy as I was about the successful start, as ugly is the GUI.. but we will have another article about that.

Upgrade assistant

For upgrading from .Net Framework or .Net Core to .Net we can use the .net upgrade assistant from Microsoft. I personally prefer to visit the github project page directly.

Now we require a command prompt (cmd) or powershell for executing the following commands.

Installation:

dotnet tool install -g --add-source https://api.nuget.org/v3/index.json --ignore-failed-sources upgrade-assistant

or if it is already installed, the update:

dotnet tool update -g --add-source https://api.nuget.org/v3/index.json --ignore-failed-sources upgrade-assistant

The upgrade itself

Open a powershell and change to the project directory, e.g.: sl d:\source\c#\NyxSql

Then we start the upgrade with: upgrade-assistant upgrade --skip-backup --non-interactive Nyx.sln

Where we use:

• skip-backup as we are using git and need no file backup
• non-interactive as we do not want to press 'y' over and over again for each project

Warnings / errors

After the upgrade is finished, you should analyze the output for warnings. When upgrading NyxSql we got for example following warnings:

[20:18:16 WRN] Default font in Windows Forms has been changed from Microsoft Sans Serif to Seg Segoe UI, in order to change the default font use the API - Application.SetDefaultFont(Font font). For more details see here - https://devblogs.microsoft.com/dotnet/whats-new-in-windows-forms-in-net-6-0-preview-5/#application-wide-default-font.
[20:18:41 WRN] No version of odp.net.managed found that supports ["net6.0-windows"]; leaving unchanged
[20:18:43 WRN] HighDpiMode needs to set in Main() instead of app.config or app.manifest - Application.SetHighDpiMode(HighDpiMode.<setting>). It is recommended to use SystemAware as the HighDpiMode option for better results.
[20:19:02 WRN] Manual updates needed to address: UA0013_M@SourceFile(d:\source\c#\NyxSql\Nyx\Tools\UserSettingsManager\DisplayProperty.cs[1462..1470)): Windows Forms Deprecated controls : DataGrid needs to be replaced with DataGridView. For more details see - https://docs.microsoft.com/en-us/dotnet/core/compatibility/winforms#removed-controls

Next to the solution Nyx it was also required to update NyxUpdate.sln in another step.

In the next article we will look at how to create plain project files and if we can run the project.

As I am already working a very long time (around 22 years) with oracle databases using file storage (no ASM, datafiles), a repetitive task always has been managing and extending the datafiles. This post is more a scratchpad of common queries I used to handle the file storage. Please refer to the official oracle documentation if you are not yet used to file handling as this blog post is no replacement for the oracle documentation nor make me responsible if you made something stupid : )

The post will be extended step by step...

CAUTION

Before extending oracle files, always make sure to check the:

• free disk space in advance
• naming of the file that it is 'in line' with the other data files

Imho, best practice for file names is the following schematics: __.dbf Naturally, the extension is free of choice, dbf for DataBaseFile

Tabelspace

A tablespace is a logical organization unit for one or more datafiles. The datafiles itself are holding the data, not the tablespace.

Space overview

SELECT df.tablespace_name "TS",
       df.total_gb "GB total",
       used_gb "GB used",
       (df.total_gb - ds.used_gb) "GB free",
       ROUND(100 * ( (df.total_gb - ds.used_gb)/ df.total_gb),2) "% free"
  FROM (SELECT tablespace_name, 
               ROUND(SUM(bytes) / 1024 / 1024 / 1024,2) total_gb
          FROM dba_data_files
         GROUP BY tablespace_name) df,
       (SELECT ROUND(SUM(bytes)/(1024*1024*1024),2) used_gb, 
               tablespace_name
          FROM dba_segments
         GROUP BY tablespace_name) ds
 WHERE df.tablespace_name = ds.tablespace_name;

Output is in GB - if you wish to use MB, just remove one 1024 in line 7 and 10.

Add

Here we add a new tablespace 'NEWTS' with one datafile:

create tablespace NEWTS
   DATAFILE '/opt/ora/data/EXA/NEWTS/EXA_NEWTS_01.dbf' SIZE 2M;

Now with two:

create tablespace NEWTS
   DATAFILE '/opt/ora/data/EXA/NEWTS/EXA_NEWTS_01.dbf' SIZE 2M,
                    '/opt/ora/data/EXA/NEWTS/EXA_NEWTS_02.dbf' SIZE 2M;

Drop

Really? : )

drop tablespace NEWTS;

If you want to drop the tablespace with ALL content:

drop tablespace NEWTS including contents;

Datafiles

Space overview

SELECT df.NAME as file_name, 
       round(df.bytes / 1024 / 1024 / 1024,2) "GB total",
       round(((df.bytes / 1024 / 1024 / 1024) - NVL (SUM (dfs.bytes) / 1024 / 1024 / 1024, 0)),2) "GB used",
       round(NVL (SUM (dfs.bytes) / 1024 / 1024 / 1024, 0),2) "GB free"
  FROM v$datafile df, dba_free_space dfs
 WHERE df.file# = dfs.file_id(+)
 GROUP BY dfs.file_id, df.NAME, df.file#, df.bytes
 ORDER BY file_name;

Add

Tablespace name in this example is "NEWTS"

alter tablespace NEWTS add datafile '/opt/ora/data/EXA/NEWTS/EXA_NEWTS_03.dbf' size 32M;

Resize

alter database datafile '/opt/ora/data/EXA/NEWTS/EXA_NEWTS_03.dbf' resize 64M;

Tempfiles

Space overview

SELECT tf.NAME file_name, 
       round(tf.bytes / 1024 / 1024 / 1024,2) "GB total",
       round(((tf.bytes / 1024 / 1024 / 1024) - NVL (SUM (dfs.bytes) / 1024 / 1024 / 1024, 0)),2) "GB used",
       round(NVL (SUM (dfs.bytes) / 1024 / 1024 / 1024, 0),2) "GB free"
  FROM v$tempfile tf, dba_free_space dfs
 WHERE tf.file# = dfs.file_id(+)
 GROUP BY dfs.file_id, tf.NAME, tf.file#, tf.bytes
 ORDER BY file_name;

Add

Temporary tablespace name in this example is "temp_data"

alter tablespace temp_data add tempfile '/opt/ora/temp/EXA/EXA_temp_03.dbf' size 32M;

Resize

alter database tempfile '/opt/ora/temp/EXA/EXA_temp_03.dbf' resize 64M;

Verifying the build number together with the version when has proven itself when it is coming to many builds in short time (to deploy multiple changes to multiple customers).

In .net this can be handled by the project file directly using these 2 properties:

<!--application versioning-->
<AssemblyVersion>6.6.0.3</AssemblyVersion>
<SourceRevisionId>build$([System.DateTime]::UtcNow.ToString("yyyyMMddHHmmss"))</SourceRevisionId>

Please note, not to use the old AssemblyInfo.cs as this will result in a conflict.

After this change, the correct version and 'revision' is visible in the properties of the executable. But how to retrieve it? Really, in the first minutes I was very confused... However here is the solution:

public static (string AppName, string Version, string Build) GetCSharpVersion()
{
    var entryAssembly = Assembly.GetEntryAssembly();
    if (entryAssembly == null)
        return ("itxClLogon", "0.00", "0");

    string appName = entryAssembly.GetName().Name;
    var appVersion = entryAssembly.GetName().Version;

    DateTime buildDate = DateTime.MinValue;

    const string buildVersionMetadataPrefix = "+build";
    var attribute = entryAssembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>();
    if (attribute?.InformationalVersion == null) 
        return (appName, $"{appVersion}", $"{buildDate:yyyyMMdd.HHmm}");
    var value = attribute.InformationalVersion;
    var index = value.IndexOf(buildVersionMetadataPrefix, StringComparison.Ordinal);
    if (index > 0)
    {
        value = value.Substring(index + buildVersionMetadataPrefix.Length);
        DateTime.TryParseExact(value, "yyyyMMddHHmmss", CultureInfo.InvariantCulture, DateTimeStyles.None, out buildDate);
    }

    return (appName, $"{appVersion}", $"{buildDate:yyyyMMdd.HHmm}");
}

Happy coding!

Specific code areas can be excluded by using the formatter directive:

switch (arg.ToLower())
{
  // @formatter:off
  case "create": action = CliAction.Create; break;
  case "list": action = CliAction.List; break;
  // @formatter:on
}

As always, when I connect 2 foreign device vendors, testing different parameters and algorithms for the connection (...but they nearly all use strongswan...). After some time, the connection was established for phase 1 and phase 2 (note, that the IPSec identifiers are the corresponding IP addresses, if 'IP Address' is selected in OCI).

Sadly, after the initial connection was established, the connection always dropped when the IPSEC Phase2 rekey timeout was reached.

Took some time to find correct phase 2 parameters, so I wanted to share the final parameters which came out to work stable:

Another great reference can be found here.

While windows services had their own implementation classes in the .Net Framework, when migrating to .Net (Core) we noticed that we had to re-implement the whole service control.

Our requirements are, imho, basic requirements for a background windows service:

• Is getting notified when the service controller is stopping the service
• Can stop itself from within on a fatal error
• Will run below windows service and linux systemd

Required nuget

For integration we require the NuGet package Microsoft.Extensions.Hosting.WindowsServices. There is also one for the systemd part of Linux (Microsoft.Extensions.Hosting.Systemd), however I will cover that later.

The main entry point for the service

We use the Program.cs for starting up the service. Normally, before I start the service itself, I verify the settings and so on. If we just return from the main method, the service will not start using the windows service controller and throw an error 'service could not be started'.

static async Task Main(string[] args)
{
    // load settings / verify environment....

    // start the service 
    using IHost host = Host.CreateDefaultBuilder(args)
        .UseWindowsService(options =>
            {
                options.ServiceName = "MyServiceName";
            })
            .UseSystemd()
            .ConfigureServices(services =>
            {
                services.AddHostedService<CustomService >();
             })
             .Build();
    await host.RunAsync();
}

Background service class

We start, by deriving our CustomService.cs from BackgroundService where we must override the ExecuteAsync method:

public class CustomService : BackgroundService
{
    protected override Task ExecuteAsync(CancellationToken stoppingToken)
    {
        throw new NotImplementedException();
    }
}

The stoppingToken is cancelled when the service is stopped by the service controller. It is brought to use by the dependency injection, what we can also use to get a reference to the IHostApplicationLifetime from the constructor, which we save us for later in the class itself AND directly register to a delegate which is getting executed when the application is stopping:

    private readonly IHostApplicationLifetime _appLifeTime;

    /// <summary> constructor </summary>
    public CustomService(IHostApplicationLifetime appLifeTime)
    {
        _appLifeTime = appLifeTime;
        _appLifeTime.ApplicationStopping.Register(AppStopping);
    }

    private void AppStopping()
    {

    }

By the delegate registration we do not require to loop, checking the stoppingToken, for the current state.

Stopping ourselves

By using the IHostApplicationLifetime we can stop ourselves pretty simple:

_appLifeTime.StopApplication();

Be aware, that the delegate ApplicationStopping is also executed!

Installation on windows

The previous windows service installation was based on a 'service installer' which was executed after starting the 'installutil.exe' from the .net framework folder

This is not anymore valid, so we use the New-Service cmdlet, which also has got much more options than the previous method using the 'service installer'.

To use the cmdlet, take a look here. I even prefer this method about invoke the windows apis directly.

Installation on linux

On Linux we require a systemd services file. Here we will create a system service called 'sample-dotnet':

vi /etc/systemd/system/sample-dotnet.service

Content:

# reload: systemctl deamon-reload
# enable: systemctl enable itxprdsrv.service

[Unit]
Description=sample dotnet service

[Service]
User=opc
Type=simple
ExecStart=/opt/sample-dotnet
TimeoutStopSec=2

[Install]
WantedBy=multi-user.target

Afterwards, reload and enable systemd:

systemctl deamon-reload
systemctl enable sample-dotnet.service

Naturally you have to set the executable the execute permission:

chmod +x /opt/sample-dotnet

If you have SELinux enabled, this will block it. In development environments we can work around by:

semanage fcontext -a -t bin_t 'sample-dotnet'

Some time ago we had to develop and deploy a new system side application for our customers. As our customer base is using mainly Windows and System i, and our whole new system configurations have been developed in c# we had to decide which way we go. Either rewrite the current codebase in c++ and port it to System i or find another solution. As c++ is very specific on the System i, it would have been an own development on its own.

After some digging in the internet I came across some articles (sadly I haven't saved them, so I cannot reference these) which described the execution of scripts by using sql (strsql) on the System i.

Prerequisites

I installed the IBM i Access client solution on my dev workstation, including the ODBC-Drivers for DB2 and started up Visual Studio. As a side note: at this time there was no native .net DB2 driver and later on I never got it really running - however as we want to control the System i and not transfer insert/update many data in the database, I did not care about using ODBC.

The whole integration ended up in using:

• ODBC to access the database and execute commandos (Access to QSYS.QCMDEXC required
• The IFS (integrated file system) for transferring files by SMB/CIFS

A specific connection string should be used, to set the required library list:

Driver={Client Access ODbC Driver (32-bit)};System=i5system;Uid=user;Pwd=password;DefaultLibraries=ITLIB1,ITLIB2

Executing cl procedures

By executing a normal 'non query' and QSYS.QCMDEXC we can execute any command. Here we will execute a CL procedure in ITLIB2 which is called TESTCN. The CL procedure which we call will receive 2 parameters and the 'native' call on the System i is stored in the variable clCmd:

string clCmd = "CALL PGM(ITLIB2/TESTCN) PARM('1stParam' '2condParam')";

The call itself, please note that we need to escape the single quotes ' when using them in the sql query. Furthermore, QCMDEXC does require the length of the command string in 15,5 packed format.

 string pgmParm = $"CALL QSYS.QCMDEXC('{cmdtext.Replace("'", "''")}', {clCmd.Length.ToString("0000000000.00000").Replace(',', '.')})";

Error handling

An error at calling will throw an exception (OdbcException) which can then be examined for the exact error code.

Spool files

For reading spool files with SQL, SYSTOOLS with SPOOLED_FILE_DATA is available.

Conclusion

Naturally, a native port would have been much better implementation BUT by creating some CL procedures and building up an architecture where the platform calls are handled by specific procedures/functions we got a fluent integration which can run from any windows operating system.

History bit/byte

Let us start from the beginning. To represent letters or characters they must be stored in the memory / hard disk wherever. As we all know, computers in general can only store 1 and 0. 1 and 0 refer to the state of one bit. So we got one bit, which can be either active(=set)=1 or inactive(=not set)=0. Now 1 byte are 8 bits nearly everywhere nowadays - why? Because it was determined to use this to encode (store) one character. From 2 states for 8 bits you end up with 2^8 = 256.

Storage / representation of characters

So we can store 256 different states in 1 byte. How can we express characters with this? The most and (if I remember correctly) first code chart and character encoding which was standardized for electronic communications is ASCII. There is a great picture at Wikipedia about it:

If you focus on the upper and left area you will notice 'Bits' with the description of b1 until b7. Based on the states of these bits the corresponding character is displayed. So:

• All bits set to 0 will result in 'NUL'
• All bits set to 1 will result in 'DEL'
• 0 0 0 0 1 1 0 will result in 0
• 0 0 0 1 1 1 0 will result in 8 Please note, that you have to pay attention on the order of bytes. Here I ordered them from b1 to b7, where as the table is ordering in reverse order (as the first bit in memory is the most right one).

I will further use hexadecimal for byte descriptions. Hexadecimal is a numbering system which has the base number of 16. As we only got 10 numbers (0 ... 9), the first characters of the alphabet are used in addition (A ... F). You can read more about it here.

To keep it short, 00 is NUL where es 30 is 0. If you have got notepad++ installed, you can view a great ASCII panel by using 'Edit' -> 'Character panel'. Furthermore, you can just double click to insert the character/hex/value (I use this for testing industrial devices with putty). On the german wikipedia there is a great ASCII-hex-table on the UTF-8 page:

'Special' or control characters

Beside the characters there was the need for some additional characters. These had been used for the control of the input by keyboard or controlling the printers. For example, FF does revere to 'Form Feed' - to eject the current page from the printer. Other famous are 'Carriage Return' and 'Line Feed' which execute 'go to position 1 of the line' and 'go to next line'. On each operation system they are interpreted a little bit different. E. g. Windows does require CRLF whereas Unix only does require LF for a line break. If you ever get in contact with older protocols, you will also get in contact with STX/ETX or SYN and so on which are mostly used in RS232 protocols or industrial devices. Do not ask me why they are still there (sometimes I have the feeling, that they just re-use damn old controllers), but for polling meter counters or scales within some milliseconds you do not want to use json or some other bloated protocol - you are just happy about least traffic as possible.

Other languages, other characters - problems arised

After taking a close look at the characters which are visible in the ASCII character encoding you will notice that there are only US characters. No other characters like french, german, norwegian, chinese, russian, arabaic and so on characters. As the memory was very limited in the beginning and each country and big tech company (especially Microsoft, IBM and Oracle) did not talk to each other many new character sets have been defined. Mostly for different regions, sometimes for countries and always depending on the operating system or source application.

As each character set is storing the characters differently, a conversion must apply. For converting between the character sets you must know from which to which you need to convert. But not all character sets support the same characters - so when you convert one text with a specific character set to another you may loose some characters depending on the character sets used.

Single byte and multi byte character sets

At some point the problems with the codepages and the conversions got that much that Unicode was born. Unicode is a 'multi-byte-character-set' (short MBCS) which does encode the characters in multiple bytes as one byte is not enough to encode the most written languages in the world (think of traditional chinese with round about 50.000 characters). There are some other MBCS like Shift-JIS, BIG5 or BG2312 beside Unicode but the most important are UTF-8, UTF-16 or UTF-32. Whereas UTF-8 is the most used character set in the internet.

I will further describe MBCS based on UTF-8 and in hexadecimal representation. Nearly every codepage does integrate ASCII with the original encoding. So ASCII characters are always safe. Following a short (incomplete) description:

• 00 -> 7F = One byte long, same as ASCII
• 80 -> BF = Second, third or fourth byte of a multi-byte-sequence
• C0 -> C1 = In short, invalid
• C2 -> DF = Start of a 2 byte long sequence
• E0 -> EF = Start of a 3 byte long sequence
• F0 -> F4 = Start of a 4 byte long sequence By using this declaration, it is possible to parse the encoding, detecting how many bytes together describe one character.

If you want to browse UTF-8 you can also take a look here.

.Net character set and file encoding

.Net does internally use UTF-16 to encode characters. If you want to read in a file in a different character set it is quite simple:

// load encoding 850
Encoding inputEncoding = Encoding.GetEncoding(850);

// read in file
string convertedText = File.ReadAllText(@"d:\test-850.txt", inputEncoding);

Nearly every class for accessing external resources is coming with a constructor which has got an overload to pass an encoding. The list of encodings is different from operating system to operating system, to see your encodings you can use GetEncodings. On the link you can also find a list of common encodings.

Converting bytes / strings

If you receive data by network, from a foreign system, you also mostly have to deal with encodings. For this, following code may come in handy:

// load encoding 850
Encoding inputEncoding = Encoding.GetEncoding(850);

// convert source byte array with character set 850 to string
string convertedString = inputEncoding.GetString(someReceivedData);

Other way round:

// load encoding 850
Encoding inputEncoding = Encoding.GetEncoding(850);

// convert string to target byte array in character set 850
byte[] convertedBytes = inputEncoding.GetBytes(convertedString);

If you are required/or interested in getting the number of bytes in a string you can also use the GetByteCount() method.

Thank you for reading!

Credits

Photo by Nathaniel Shuman on Unsplash

The log files only show the following and alert log is empty:

Connected to: Oracle Database 19c Standard Edition 2 Release 19.0.0.0.0 - Production
ORA-39150: bad flashback time
ORA-08186: invalid timestamp specified

Metalink from Oracle just telling us that the timestamp format is wrong, and we do not need to worry about timestamp format if we use systimestamp.

After digging around a little bit, I noticed that the times in log files suddenly 'jumped' without any notice about a time drift, neither from windows nor oracle (and oracle is very verbose in logging this).

Restarting the whole database got rid of the error. The reason for all of this seems to be that the customer changed the region format of the server without restarting the database. However, I have not tried reproducing this in a lab, but it seems to be the only change which was done on the server in the last days.

As a side note, if you are questioning yourself why we are running a daily datapump export: Naturally we are running an additional recovery manager backup and we always advise the customers to use some solid tested robust fancy backup software with a dedicated database agent for handling the database backup correctly with monitoring and so on and on... BUT if you have got a big application database and someone started a wrongly configured cleanup operation, naturally without any verification in the dev environment, or 'accidently dropping' the wrong table / deleting single rows, you do not want to role backup a whole database to a specific point in time, sometimes not even a specific table. Depending on the type of data (low change rate, e.g. master data) you can recover them sometimes much faster from dump instead of recovering from backup. Another point... we also experienced people who 'lost' their rman backup or some files and you end up with an old backup or need to contact oracle support for an inconsistent recovery because of the missing files. Then a datapump files is also coming in handy...

We take a very short look into BitConverter

byte to hex dump

BitConverter.ToString

// 104 is the int representation of the char 'h', hex '68'
// 105 is the int representation of the char 'i', hex '69'
byte[] someByteArr = new byte[2] {104,105}; 

string hexDump = BitConverter.ToString(someByteArr);
Console.WriteLine(hexDump);
// output: 68-69

There are numerous hexadecimal notations. For example: 68-69, 0x68 0x69, \x68 \x69 and so on... If Hexadecimal is unknown to you, I strongly recommend reading the article from Wikipedia as it will improve your understanding massively.

bytes to int32 (exemplary)

Simply:

byte[] someByteArr = new byte[2] {132,1};

short result = BitConverter.ToInt16(someByteArr);
Console.WriteLine(result);
// output: 388

When converting this way, please remind the byte required byte array length (e.g., 2 bytes for int16/4bytes for int32/8bytes for int64) and the order of bytes you received (host byte order or network byte order / lowHIGH or HIGHlow).

Some little history: In general, it is called 'endianness', the order of the bytes of a word in the memory, where we have big-endian and little-endian. In the beginning the mainframes dominated the world which all used big-endianness. When the personal computer came up it switched to little-endianness. However, the network is still mostly big-endianness because the IETF RFCs (public declarations of protocols) use them. You can read more about this at Wikipedia. You can test endianness yourself if you simply switch the bytes in the upper array:

byte[] someByteArr = new byte[2] {1,132};

short result = BitConverter.ToInt16(someByteArr);
Console.WriteLine(result);
// output: -31743

The framework itself does implement IPAddress.HostToNetworkOrder and IPAddress.NetworkToHostOrder for switching between the endiannesses. As an alternative, just use Array.Reverse.

Converting one byte to int representation

The conversion is still using the good old Convert class. Where we simply can convert one byte to the corresponding representation. This is a hard conversion, so exceptions may and often happen. We are just converting the representation, not dealing with the real 'data'. For example, a byte can be also expressed using an int as used in above examples for the byte array initialization:

byte[] someByteArr = new byte[2] {132,1};

int result = Convert.ToInt32(someByteArr[0]);
Console.WriteLine(result);
// output: 132

result = Convert.ToInt32(someByteArr[1]);
Console.WriteLine(result);
// output: 1

Just taking an exit before the end to go the way through unsigned/signed

Here we will use integer / int here. uint stands for unsigned integer whereas int is for signed integer. Unsigned integers can only have positive values and signed also negative. In the memory itself however, the occupied space is the same so a 'trick' is used to accomplish this resulting in different ranges: int -2,147,483,648 to 2,147,483,647 uint 0 to 4,294,967,295 You can read more about this here.

As the data in the memory is different, the type is important for casting. If the wrong type is used an 'overflow' may happen which does result in wrong interpretation of the data.

I will not dive deep into the memory storage itself, there are much better articles about that for example at Wikipedia, which you already find referenced in this article.

Credits

Photo by mostafa meraji on Unsplash

So, instead of returning pure error messages with indicators if a method suceeded (see my Tuples article here), Exceptions had been thrown.

Now, Exceptions are not anymore that nice when it comes to:

• program flow (some exception is thrown somewhere and catched 4 times up the call stack)
• they are 'cost intensive' - which does mean they require some ressources
• call stack or inner exceptions are lost if not handled correctly

But they are great to use when something really worse happend for your application and you cannot continue.

Short introduction

Exceptions?

When an exception is thrown, the following program code is not executed anymore (beside there is a finally block) until it is catched. If it is not catched somewhere, the program is terminated.

// we just want one method throwing the exception
private void ExcSample()
{
  throw Exception("foo");
}

// 
public static void Main()
{
   // will result in termination of the program as no exception will be catched
   ExcSample();

   // will catch the exception in the catch block and write the message to console
   try
   {
      ExcSample();
   }
   catch(Exception exc)
   {
      Console.WriteLine($"Error occured: {exc.Message}");
   }

   // example with finally block
   try
   {
      ExcSample();
   }
   catch(Exception exc)
   {
      Console.WriteLine($"Error occured: {exc.Message}");
   }
   finally 
   {
      // code here would be always executed: if an exception does occur or if not
   }

   // also possible, only finally
   try
   {
      ExcSample();
   }
   finally 
   {
      // code here would be always executed: if an exception does occur or if not
   }
}

Custom or user-defined exceptions

Custom or user-defined exceptions are exceptions which have been created by yourself. The decision to create own exceptions may be due to additional requirements for the Exception itself (e. g. localization or for logic operations where no existing Exception may fit your needs.

Exceptions can be simply created by deriving your new Exception class from the base class or any other Exception class:

public class MyOwnException : Exception
{
    public uint MyInternalErrorCode { get; set; }

    public MyOwnException(uint errorCode)
    {
        MyInternalErrorCode = errorCode;
    }

    /// <inheritdoc />
    public MyOwnException(string? message) : base(message)
    {
    }

    public MyOwnException(string? message, uint myInternalErrorCode) : base(message)
    {
        MyInternalErrorCode = myInternalErrorCode;
    }

    /// <inheritdoc />
    public MyOwnException(string? message, Exception? innerException) : base(message, innerException)
    {
    }

    public MyOwnException(string? message, Exception? innerException, uint myInternalErrorCode) : base(message, innerException)
    {
        MyInternalErrorCode = myInternalErrorCode;
    }
}

Catching multiple exceptions

Please refer to my article about when

Catching unhandled exceptions

To catch all unhandled exceptions in your program, e. g. for logging it to a file instead of default logging facilities it is possible to subscribe to some even:

static async Task Main(string[] args)
{
    // subscribe to event for all unhandled eceptions
    AppDomain.CurrentDomain.UnhandledException += ApplicationUnhandledException;
    // rest of code...
}

// event handler
private static void ApplicationUnhandledException(object sender, UnhandledExceptionEventArgs e)
{
    // log the exception for example
    Logger.Fatal((Exception) e.ExceptionObject, "Unhandled exception: {0}", e.ExceptionObject);
}

Using Tasks the above will not work, but the TaskScheduler class does provide an Event UnobservedTaskException which we can use in this case.

Credits

Photo by Anthony Duran on Unsplash

In the very first beginning of tuples in c# I firstly skipped it, because the readability had been not what I though of creating readable code.

Example from MSDN:

(bool, string) t1 = (true, "");
Console.WriteLine($"Tuple with value {t1.Item1} and string {t1.Item2}.");

When using tuples with more than 2 variables it was always about remembering which variable is which item.

With the introduction of ValueTuples this changed. Now it is possible to assign a 'name' to each tuple variable:

(bool rc, string error) t2 = (true, "");
Console.WriteLine($"Tuple with value {t2.rc} and string {t2.error}.");

Where for?

Now where should I use tuples?

Data storage

In general they can be used everywhere. However imho for complex data, the code readability will be worse, if you use it for storing big data instead of using classes. Let me show you an example:

(string FirstName, string LastName, DateTime BirthDay) person

Using it together with a list will result in:

List<(string FirstName, string LastName, DateTime BirthDay) person>

In this case using a dedicated data class should be prefered as the readability greatly improves and the data class can be extended with additional methods.

But for temporarily storing small data constructs, where Dictionaries, Collections or Hastables do not bring in any benefit, they are great also!

Method return type

That is the point where we switched to value tuples and now using them heavily. Instead of using out variables or ref variables for providing the error messages to the calling method we switched to tuples. Please note, that this is specific about requirements of returning an error - it is NOT a recommendation of when to use return values or Exceptions. See for example language agnostic - Which, and why, do you prefer Exceptions or Return codes? - Stack Overflow

Previously:

string error = "";
bool rc = FirstMethod(ref string error);
if(!rc)
  _logger.Error(error);

rc = SecondMethod(ref string error);
if(!rc)
  _logger.Error(error);

Now with tuples:

(bool success, string error) callRc = FirstMethod();
if(!callRc.success)
  _logger.Error(callRc.error);

callRc = SecondMethod();
if(!callRc.success)
  _logger.Error(callRc.error);

It can be easily extended with a more complex tuple for also handling an additional variable providing e. g. data from the called method which does work great together with nullable:

(bool success, string error, string[] lines) callRc = LoadFile();
if(!callRc.success)
{
   _logger.Error(callRc.error);
   return;
}
// process data using callRc.lines ...

var

Instead of specifying the return values each on it's own:

(bool success, string error) callRc = FirstMethod();

We can also use var which does work perfect with IntelliSense:

var callRc = FirstMethod();

Deconstruct

And last but not least, we can also 'desconstruct' the tuple and direct access the single variables:

(bool success, string error) = FirstMethod();
if(!success)
  _logger.Error(error);

// use them again but without declaration 
(success, error) = SecondMethod();
if(!success)
  _logger.Error(error);

Naming conventions

Internally we decided to use the following typing conventions with tuples:

• For return tuples, we use tuple variables in lowerCase

• For data tuples, we use tuple variables in UpperCase

Last but not least, please remind yourself that tuples are value types!

Why I am so happy about that? When we talk about using external ressources, we talk about exceptions which may happen... They can occure everywhere... for example reading a file, creating a connection and so on.

Before when

What I came accross in my developers life are the following examples:

// instead of multiple catch blocks for specific exceptions, just the Exception base class is catched
try { }
catch (Exception ex) {}

// sometimes afterwards filtered
try { }
catch (Exception ex) 
{
   if (ex.Message.Contains("...")) { }
   else throw;
}

// or filtering for some properties of the exception
catch (HttpRequestException exc) 
{
   if(exc.StatusCode is HttpStatusCode.BadGateway)
   { }
   else 
     throw;
}

Now catching the base class/general exception is bad practice or here.

The other problem is the stack unwinding, which is happening as soon as a catch block is entered. So every time an exception is not handled, but rethrown from the catch block, stack unwinding is happening, which will not only be done multiple times if the exception is rethrown, but you also loose your stack trace (beside you call another method again).

Using when

Using 'when', we can filter with any kind of bool logic without any stack unwinding happening:

catch (HttpRequestException exc) when (exc.StatusCode is HttpStatusCode.BadGateway)

Furthermore, we can easily improve code readability by combining catch blocks which do the same:

catch (UnauthorizedAccessException exc)
{
    return (false, exc.Message);
}
catch (SecurityException exc)
{
    return (false, exc.Message);
}
catch (IOException exc)
{
    return (false, exc.Message);
}

All three catch clauses do the same but instead of 4 lines we used 12. Now, using 'when' we can easily rewrite this to:

catch (Exception exc) when (exc is UnauthorizedAccessException or SecurityException or IOException)
{
    return (false, false, exc.Message);
}

If you require specific exception objects, eg. the Socket Errorcode, you still need to catch the SocketException itself.