There are some improvements of the way we get access to our configuration files in ASP.NET Core. The time as we did assign the properties of our config classes by ourselves and we have to deal with config entry keys is gone. With Microsoft.Extensions.Configuration and the Microsoft.Extensions.Options package we now have the ability to map our configuration sections to POCO's and inject them where we need it.

This is very helpful for a cleaner design not least since because the ASP.NET Core framework gives us the ability to store our configuration on different places. These places for example could be files (e.g. appsettings.json, $"appsettings.{env.EnvironmentName}.json"), environment variables, command line arguments an something else. So let us explore what paths we are now open to, and if you would try this by yourselves, you could find the sample code on GitHub in a SampleProject.

ConfigurationBuilder

The entry point of our configuration system is the class ConfigurationBuilder. This is the place where we can configure our configuration sources. After calling the Build method, we have full access to the configuration by using the IConfigurationRoot interface which also inherits the IConfiguration interface.

public IConfigurationRoot Configuration { get; }

public Startup(IHostingEnvironment env)  
{
    var builder = new ConfigurationBuilder()
        .AddCommandLine(Environment.GetCommandLineArgs())
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
        .AddEnvironmentVariables();
    Configuration = builder.Build();
}

To read now our configuration values we can use some of the interface methods like them shown below.

//Gets or sets a configuration value.
string this[string key] { get; set; }

//Gets the immediate descendant configuration sub-sections.
IEnumerable<IConfigurationSection> GetChildren();

//Gets a configuration sub-section with the specified key.
IConfigurationSection GetSection(string key);  

IOptions and IOptionsMonitor

And now let's take a look onto the new and recommended way to get access to the configuration values. This method named Options pattern is, as I think, a much better way doing this.

Firstly we have to create a POCO. The properties of this are representing our configuration settings/entries. For this class it is not necessary to inherit from any other class (for example there is no ConfigurationBase class or so).

public class MySettings  
{
    public string MySettingsEnry1{get; set;}
    public List<string> MySettingsEnryList{get; set;}
    public int MySettingsNumber{get; set;}
}

Attention: IEnumerable instead of List would not work!

As you can see, you create it with with strongly typed properties, not only 'everything is a string' and map it to a corresponding JSON section of our settings file. As a sample of this, we can map the JSON configuration section below with the class above according you have configured the binding as described in the next section.

{
  "MySettings" :{
    "MySettingsEnry1":"Value",
    "MySettingsEnryList":[
       "A",
       "B"
    ],
    "MySettingsNumber": 10
  }
}

Startup (configure the options bindings)

To use the configuration POCO's with the Options Pattern we now have to do some minimal configuration effort. But this is not so much work, it can easily be done in the ConfigureServices method of the Startup class.

In this method we have to define the mapping of the POCO's and the Section's of the configuration file. There we have to call services.Configure<POCONAME>(CONFIGSECTION) for every single mapping. And after this we than have to register the needed services in the Ioc of ASP.NET Core by calling services.AddOptions(). These few steps are shown in the next code snipet.

public class Startup  
{
    public IConfigurationRoot Configuration { get; }

    public Startup(IHostingEnvironment env)
    {
        var builder = new ConfigurationBuilder()
            .SetBasePath(env.ContentRootPath)
            .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
            .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true)
            .AddEnvironmentVariables();
        Configuration = builder.Build();
    }

    public void ConfigureServices(IServiceCollection services)
    {
        services.Configure<MySettings>(Configuration.GetSection("MySettings"));
        services.AddOptions();

        services.AddSingleton<IMySampleService, MySampleService>();
        ...
        services.AddMvc()
    }
}

Use your options

So now after we have configured all our needs I will show how we can use it in action. At this point we have two choices. First we take a look at the normal way where we only get an instance of our configuration POCO to read (and also write) our settings.

(Notice: Writing the settings could only change the value in the memory, not in the file. If you use the IOptions<MySettings> in different services, there will be an instance per service, which means if you change a settings value in service A, the settings value in service B will not be affected.)

public class MySampleService  
{
    private IOptions<MySettings> _settings;

    public MySampleService(IOptions<MySettings> settings)
    {
        _settings = settings; 
        //access options with _settings.Value.[PropertyName]
    }
}

Now the second and more cool way is to use IOptionsMonitor which gave us also access to the configuration. But, in this variant we always have access to the current value also even the values of the configurations will get changed.(This means, another service which also has an injected IOptionsMonitor changes the settings in memory and also when the configuration file was changed). If we want to be informed about the changes of our files, we additionally have to configure reloadOnChange: true in our ConfigurationBuilder.

public class MySampleService  
{
    private IOptionsMonitor<MySettings> _settings;
    private IDisposable _configWatcher;

    public MySettings Settings{ get{ return _settings.CurrentValue; }}

    public MySampleService(IOptionsMonitor<MySettings> settings)
    {
        _settings = settings;
        _configWatcher = _settings.OnChange(ConfigChanged); 
        //access options with _settings.CurrentValue.[PropertyName]
    }

    private void ConfigChanged(MySettings currentConfig)
    {
    }
}

As the sample above shows, we always have access to the current configuration data by using the Settings property, because this points always on the CurrentValue of the settings POCO.
If you also need to get informed of a configuration change in your code, you could register the OnChanged Action of the IOptionsMonitor.

One thing is missing

As cool as this stuff already is, one thing is missing. In some of my projects i would like to change some configuration parts at the run time and then persist it to the file or so. But at the time of writing this post, there was no way implemented to do this. Nevertheless as the GitHub-Page of the ASP.Net team shows, this feature is on the backlog.

Summary

I think this extension of configuration is very helpful to create a clean and easy way to access your configuration data. I am very interested in how this component will evolve and what exciting functions will still be waiting for us.

In the reference section and in the language integration section you can find some additional links I used to learn and understand the functionality. I hope you find this article helpful. If this is the case or if you have some questions or find some bugs, please post in the comment section below. I will thankfully use your input to improve this blog-post

References

• SourceCode
• ASP.Net Core Documentation
• How to use the IOptions pattern for configuration in ASP.NET Core RC2
• IOptions

What the hell do I need that? That was my first thought as I once again tried to implement a TCP communication by using System.Net.Sockets in C#. Because I never used this type, I started to find out the difference between IList<ArraySegment<byte>> and byte[] which I used before. First of all I took a look on the MSDN page where was written:

ArraySegment<T> is a wrapper around an array that delimits a range of elements in that array. Multiple ArraySegment<T> instances can refer to the same original array and can overlap. The original array must be one-dimensional and must have zero-based indexing.

Note, however, that although the ArraySegment<T> structure can be used to divide an array into distinct segments, the segments are not completely independent of one another. The Array property returns the entire original array, not a copy of the array; therefore, changes made to the array returned by the Array property are made to the original array. If this is undesirable, you should perform operations on a copy of the array, rather than an ArraySegment<T> object that represents a portion of the array. 

Furthermore I found that this struct was part of the .NET Framework since version 2.0 (And is used in sockets since .NET Framework 3.5), and since version 4.6 ArraySegment<T> implements also the interface IReadOnlyCollection<T> which represents a strongly-typed, read-only collection of elements.

The core benefit of this is that an ArraySegment<T> structure is useful whenever the elements of an array will be manipulated in distinct segments. But what does this mean in real? What is so useful? Why should it be better than a list or another container datatype?

To find that out, I was just playing around a little bit to show how I can use it. For this blog-post, I provided a sample project with my tries on GitHub where I used the MSDN sample code as a Template:

private static void Usage()  
{
    var buffer = new byte[10];
    var segment1 = new ArraySegment<byte>(buffer);
    var segment2 = new ArraySegment<byte>(buffer, 5, 3);

    Console.WriteLine("Origin:");
    PrintOut(buffer, segment1, segment2);
    Console.WriteLine();

    Console.WriteLine("Update Buffer[5]:");
    buffer[5] = 0x01;
    PrintOut(buffer, segment1, segment2);
    Console.WriteLine();

    Console.WriteLine("Update Segment1.Array[5]:");
    segment1.Array[5] = 0x02;
    PrintOut(buffer, segment1, segment2);
    Console.WriteLine();

    Console.WriteLine("Update Segment2.Array[Segment2.Offset]:");
    segment2.Array[segment2.Offset] = 0x03;
    PrintOut(buffer, segment1, segment2);
    Console.WriteLine();
}

This sample code from above produces the following output:

As we can see, it's easy to use, but where is the benefit? Getting access to a specific index, I also have to use the Array and Offset Property like segemnt.Array[segment.Offset] = 1. No, not in real, due to the explicit interface implementation of IList<T> you can do some cool stuff like this:

(segment2 as IList<byte>)[2] = 0x04;
var x = (segment2 as IList<byte>)[2];  

Adding this code lines to our sample, we produces the output below:

This fills the gap, but I find the explicit implementation not very common in use. The reason why this is done this way is because ArraySegment<T> implements IList<T> and IReadOnlyList<T> and for this they need a separation. I would prefer a second type, for example ReadOnlyArraySegment<T> to get a better usage.

Performance

Ok, we saw the usage, now let's check the performance. In the sample you will also find a method to test that in case of memory and speed to see whether it pays off.

Test("List        ", (arr, offset, elements) =>  
                     new List<int>(arr.Skip(offset).Take(elements)));

Test("Array       ", (arr, offset, elements) =>  
                     new List<int>(arr.Skip(offset).Take(elements)));

Test("ArraySegment", (arr, offset, elements) =>  
                     new ArraySegment<int>(arr, offset, elements));

Test("ArrayCopy   ", (arr, offset, elements) =>  
{
    var array = new int[elements];
    Array.Copy(arr, offset, array, 0, elements);
    return array;
});

I think the result speaks for itself:

Average Runtime in ms

Average Total Memory in byte

Implementation

Referred to this evaluation I think it's clear why this is useful. Now, after this I took a look on the source code of this structure to see how this works. I extracted some parts to show you the basic use. As you can see in the following code, it is what it is, a wrapper around an array of T[] which supports the IList<T> and IReadOnlyList<T> interface explicit:

 [Serializable]
 public struct ArraySegment<T> : IList<T>, IReadOnlyList<T>
 {
     private T[] _array;
     private int _offset;
     private int _count;

     public ArraySegment(T[] array, int offset, int count)
     {
        _array = array;
        _offset = offset;
        _count = count;
     }

     public T[] Array{ get { return _array;} }
     public int Offset{ get { return _offset;} }
     public int Count{ get { return _count;} }

     ...
     T IList<T>.this[int index]
     {
         get { return _array[_offset + index]; }
         set { _array[_offset + index] = value; }
     }
     ...
 }

Attention: Microsoft insert a code comment for the Count and Offset property as following:

Since copying value types is not atomic and callers cannot atomically read all three fields, we cannot guarantee that Count/Offset is within the bounds of Array.  That's our intent, but let's not specify it as a post condition - force callers to re-verify this themselves after reading each field out of an `ArraySegment` into their stack.  

To check this by yourself you can you an implementation such the class from which was used by Microsoft (RangeValidatorHelper) for the sockets.

Span

Now let us take a look into the future. In the last few section we could see what ArraySegments can be used for. But now Microsoft (formals joeduffy) is working on a new structure named Span, which is part of a preview nuget package called System.Slices that is placed on the nuget channel "https://dotnet.myget.org/F/dotnet-corefxlab/api/v3/index.json" and maybe will be part of C# 7.

Description

Span is a uniform API for dealing with arrays and subarrays, strings and substrings, and unmanaged memory buffers. It adds minimal overhead to regular accesses and is a struct so that creation and subslicing do not require additional allocations. It is type- and memory-safe.

Samples

To show the usage of the new span-type, I also created some methods in the sample project:

private unsafe static void FillSpans()  
{
    // Over an array:
    Span<int> ints = new Span<int>(new int[] { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 });

    // Over a string (of chars):
    Span<char> chars = new Span<char>("Hello, Slice!".ToArray());

    // Over an unmanaged memory buffer:
    byte* bb = stackalloc byte[256];
    Span<byte>bytes = new Span<byte>(bb, 256);


    PrintSpan1(ints);
    PrintSpan1(chars);
    PrintSpan1(bytes);

    PrintSpan2(ints);
    PrintSpan2(chars);
    PrintSpan2(bytes);
}

private static void PrintSpan1<T>(Span<T> slice)  
{
    for (int i = 0; i < slice.Length; i++)
        Console.Write("{0} ", slice[i]);
    Console.WriteLine();
}

private static void PrintSpan2<T>(Span<T> slice)  
{
    foreach (T t in slice)
        Console.Write("{0} ", t);
    Console.WriteLine();
}

As you see, this structure is similar to the ArraySegment but spans do not implement the two interfaces. Instead it implements IEquatable<T[]>.
Span provides a few constructors, which also support the initialization with a pointer, what we will discuss later in the section Unsafe To Safe. In contrast to ArraySegment here we also can use the index operator direct, without casting. Also sub-slicing without additional allocations can be used as you can see in the following snippet:

private static void Subslicing()  
{
    //Extract sub span
    Span<int> ints = new Span<int>(
                       new int[] { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 });
    Span<int> subints = ints.Slice(5, 3);

    //No reallocation of the string
    ReadOnlySpan<char> testSpan = "Span Test".Slice();
    int space = testSpan.IndexOf(' ');
    ReadOnlySpan<char> firstName = testSpan.Slice(0, space);
    ReadOnlySpan<char> lastName = testSpan.Slice(space + 1);
}

Unsafe To Safe

Another benefit of this type is, as we described previously the unsafe constructor. So the array can be initialized in an unsafe Method and then you it can be used anywhere else in an safe way like the following listing shows.

unsafe void Unsafe(byte* payload, int length)  
{
    Safe(new Span<byte>(payload, length));
}

void Safe(Span<byte> payload)  
{
  //now the payload could be handled in a safe way because it is wrapped
}

Language integration

By writing this blog-post I red many discussions about this new type and I created a short list of the top 6:

• https://github.com/dotnet/corefxlab/issues/816
• https://github.com/dotnet/roslyn/issues/98
• https://github.com/dotnet/roslyn/issues/120
• https://github.com/dotnet/roslyn/issues/10378
• https://github.com/dotnet/corefx/issues/7593
• https://github.com/dotnet/corefx/issues/6740

Some really cool things will be coming if this type will be part of the language. One of the proposed usage I copied out of the discussion to show you the future (maybe):

int[] primes = new int[] { 2, 3, 5, 7, 9, 11, 13 };  
int item = primes[1];   // Regular array access, producing the value 3  
int[:] a = primes[0:3]; // A slice with elements {2, 3, 5}  
int[:] b = primes[1:2]; // A slice with elements {3}  
int[:] c = primes[:5];  // A slice with elements {2, 3, 5, 7, 9}  
int[:] d = primes[2:];  // A slice with elements {5, 7, 9, 11, 13}  
int[:] e = primes[:];   // A slice with elements {2, 3, 5, 7, 9, 11, 13}  
int[:] f = a[1:2];      // A slice with elements {3}  

I think it will be very interesting to see the final version of Slices and I'm anxiously waiting on it.

Updated on 07.11.2016: SpanOfT Review

Summary

In the reference section and in the language integration section you can find some additional links I used to learn and understand the functionality. I hope you find this article helpful. If this is the case or if you have some questions or find some bugs, please post in the comment section below. I will thankfully use your input to improve this blog-post.

References

• System.ArraySegment
• System.Slices

To run these tools, I used some classes that were not very good documented at the time of coding. One of these classes is used to find the references of my assembly, some others to compile the code from a file and to load the compiled assembly. Compared to old .NET code I developed, the reference finding and assembly loading is quite different now. The reason is that there is no AppDomain.GetAssemblies() and Assembly.LoadFile() in CoreClr. It took me some time to find a solution for this .NET Core.

For this blog-post I provided a project called DynCode.Sample on GitHub, where you can try the functionality on a simple project.

Find referenced assemblies

First of all you need a reference of the dependency context which holds the references of an assembly.

using System.Reflection; 

var myEntryAssembly = Assembly.GetEntryAssembly();  
var context = DependencyContext.Load(myEntryAssembly );  

If your context should be the context of your entry assembly (to get all references of your application) you could also use DependencyContext.Default.

You can use the following code snipet to show all assemblies your entry assembly is compiled against. To get detailed Information about the compiled libraries, you have to make the according settings (compilationOptions.preserveCompilationContext : true) in package.json:

    "compilationOptions": {
        "preserveCompilationContext": true,
        "emitEntryPoint": true
    },
    "dependencies": {
      ...
      "Microsoft.Extensions.DependencyModel": "1.0.1-beta-003206",
      ...
    },

public static void ShowReferences()  
{
    var context = DependencyContext.Default;

    if (!context.CompileLibraries.Any())
        Console.WriteLine("Compilation libraries empty");

    foreach (var compilationLibrary in context.CompileLibraries)
    {
        foreach (var resolvedPath in compilationLibrary
                                      .ResolveReferencePaths())
        {
            Console.WriteLine($"Compilation {compilationLibrary.Name}:{Path.GetFileName(resolvedPath)}");
            if (!File.Exists(resolvedPath))
                Console.WriteLine($"Compilation library resolved to non existent path {resolvedPath}");
        }
    }

    foreach (var runtimeLibrary in context.RuntimeLibraries)
    {
        foreach (var assembly in runtimeLibrary.GetDefaultAssemblyNames(context))
            Console.WriteLine($"Runtime {runtimeLibrary.Name}:{assembly.Name}");
    }
}

Load assemblies

In my application I would also implement the ability to load some additional assembly references (this could also be used if you support a plugin system). To do this you need another nuget package:

    "dependencies": {
        ...
        "System.Runtime.Loader": "4.0.0",
        ...
    }

This package contains a class called AssemblyLoadContext which is placed in the System.Runtime.Loader.dll.

To get the current load context, you can use the static property AssemblyLoadContext.Defaul or pass an assembly into the method AssemblyLoadContext.GetLoadContext(asm); for a different one. The
resulting context gives you the opportunity to load assemblies (from file, by name, ...).

AssemblyLoadContext.Default.Resolving += CustomResolving;  
var asm = AssemblyLoadContext.Default.LoadFromAssemblyPath(path);  

The context also provides a Resolving-event which could be used to bring in your resolving code, if an assembly could not be resolved byte the LoadContext itself.

private static Assembly CustomResolving(AssemblyLoadContext arg1, AssemblyName arg2)  
{
    Console.WriteLine($"Try resolve: {arg2.FullName}");
    //Maybe Load from different path e.g. Addon Path.
    return arg1.LoadFromAssemblyPath(@"C:\Addons\" + arg2.Name + ".dll");
}

Compile files from location

    "dependencies": {
        ...
        "Microsoft.CodeAnalysis.CSharp": "2.0.0-beta3",
        ...
    }

Now as we can determine the references and load assemblies, we can start to implement the compile method. This can be done very easily by using
the .Net Compiler Platform (formally known as Roslyn). The following listing shows how this works. Each element of the list could be represent a file of C# source code.

private static Assembly Compile(string assemblyName, IEnumerable<string> codes, IEnumerable<string> usings = null)  
{
    if (codes == null || !codes.Any())
        throw new ArgumentNullException(nameof(codes));

    //we need to get a tree per source
    var trees = new List<SyntaxTree>();
    var additionalUsings = usings != null 
                               ? usings.Select(s => 
                                                SyntaxFactory
                                                .UsingDirective(SyntaxFactory
                                                      .ParseName(s))).ToArray() 
                               : new UsingDirectiveSyntax[0];

    foreach (var code in codes)
    {
        // Parse the script to a SyntaxTree
        var syntaxTree = CSharpSyntaxTree.ParseText(code);
        var root = (CompilationUnitSyntax)syntaxTree.GetRoot();

        if (additionalUsings.Any())
            root = root.AddUsings(additionalUsings);

        trees.Add(SyntaxFactory.SyntaxTree(root));
    }

    // Compile the SyntaxTree to an in memory assembly
    var compilation = CSharpCompilation.Create(
        assemblyName,
        trees,
        GetMetaDataReferences(),
        new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary)
        );

    using (var outputStream = new MemoryStream())
    {
        using (var pdbStream = new MemoryStream())
        {
            var result = compilation.Emit(outputStream);
            if (result.Success)
            {
                outputStream.Position = 0;
                return AssemblyLoadContext.Default.LoadFromStream(outputStream);
            }
            else
            {
                Console.WriteLine(result.Diagnostics.Select(x => $"{x.ToString()}{Environment.NewLine}"));
                return null;
            }
        }
    }
}

private static IEnumerable<MetadataReference> GetMetaDataReferences()  
{
    return DependencyContext.Default
        .CompileLibraries
        .SelectMany(x => x.ResolveReferencePaths())
        .Where(path => !string.IsNullOrWhiteSpace(path))
        .Select(path => MetadataReference.CreateFromFile(path));
}

Summary

In the reference section you can find some additional links I used to learn and understand the functionality. I hope you find this article helpful. If this is the case or if you have some questions or find some bugs, please post in the comment section below. I will thankfully use your input to improve this blog-post.

References

• AssemblyLoadContext
• System.Loader.Tests
• CustomAssemblyLoader
• StackOverflow
• Calling from managed to native code
• assemblynative
• issue
• DependencyContextValidator
• Announcements