DEV Community: Stuart Lang

Xamarin Forms Accessible Headings

Stuart Lang — Mon, 02 Sep 2019 18:34:00 +0000

If you are developing a mobile app, it's worth enabling VoiceOver on iOS and considering the usability from the perspective of people who rely on these tools to access your app.

Out of the box, Xamarin Forms comes with some nice accessibility features that can control the VoiceOver experience, in particular Automation Properties allow you to annotate your XAML elements with metadata such as what text to read out when selected by VoiceOver.

In this post I won't be focusing on these features, but instead, looking at Headings.

Headings

Consider the following screen:

Visually, these headers convey the structure of the screen to the user. However, now let's try to navigate the page using solely VoiceOver. In this animation as we swipe left/right, the previous/next element is selected and its description is read aloud.

While all the content can be accessed, the headings just fade into the regular content if VoiceOver is your only UI.

Rotor control

Let's try using the Rotor navigation control to select Headings (with a two-finger twist gesture). Now we can navigate the screen by jumping through the headers with a swipe up/down gesture, however at the moment VoiceOver just says: "No Headings Found", which isn't very helpful.

On iOS, elements can be given a header accessibility trait. Using this, VoiceOver considers these elements as headings, and the swipe up/down gesture will now work and jump the selection to the next/previous heading.

This now functions much better as we can quick-jump between headings and still navigate to the items around them. Now let's build it.

How do we do it?

It turns out we don't need much code to make this happen. We'll create an attached property that will automatically add an effect to the element it's added to.

We first need to define our attached property, and create the effect which will be implemented only for iOS:

using System;
using System.Linq;
using Xamarin.Forms;

namespace XamAppWithHeaders
{
    public static class Accessibility
    {
        [Flags]
        public enum AccessibilityTrait
        {
            None,
            Header
        }

        public static readonly BindableProperty AccessibilityTraitsProperty =
            BindableProperty.CreateAttached("AccessibilityTraits", typeof(AccessibilityTrait), typeof(Accessibility), AccessibilityTrait.None, propertyChanged: OnAccessibilityTraitsChanged);

        public static AccessibilityTrait GetAccessibilityTraits(BindableObject view)
        {
            return (AccessibilityTrait)view.GetValue(AccessibilityTraitsProperty);
        }

        public static void SetAccessibilityTraits(BindableObject view, AccessibilityTrait value)
        {
            view.SetValue(AccessibilityTraitsProperty, value);
        }

        static void OnAccessibilityTraitsChanged(BindableObject bindable, object oldValue, object newValue)
        {
            if (!(bindable is View view))
            {
                return;
            }

            var newTraits = (AccessibilityTrait)newValue;
            var hasTraits = newTraits != AccessibilityTrait.None;

            if (hasTraits)
            {
                if (!view.Effects.OfType<AccessibilityTraitEffect>().Any())
                {
                    view.Effects.Add(new AccessibilityTraitEffect());
                }
            }
            else
            {
                var accessibilityTrait = view.Effects.OfType<AccessibilityTraitEffect>().FirstOrDefault();
                if (accessibilityTrait != null)
                {
                    view.Effects.Remove(accessibilityTrait);
                }
            }
        }

        public class AccessibilityTraitEffect : RoutingEffect
        {
            public AccessibilityTraitEffect() : base("XamAppWithHeaders.AccessibilityTraitEffect")
            {
            }
        }
    }
}

Be sure to change XamAppWithHeaders in the RoutingEffect base call to match your own namespace.

Now in our iOS project we will implement the effect and actually set the accessibility trait:

using UIKit;
using Xamarin.Forms;
using Xamarin.Forms.Platform.iOS;
using static XamAppWithHeaders.Accessibility;

[assembly: ResolutionGroupName("XamAppWithHeaders")]
[assembly: ExportEffect(typeof(XamAppWithHeaders.iOS.AccessibilityTraitEffect), "AccessibilityTraitEffect")]

namespace XamAppWithHeaders.iOS
{
    public class AccessibilityTraitEffect : PlatformEffect
    {
        protected override void OnAttached()
        {
            AddAccessibilityTraits();
        }

        protected override void OnDetached()
        {
        }

        protected override void OnElementPropertyChanged(System.ComponentModel.PropertyChangedEventArgs args)
        {
            if (args.PropertyName == AccessibilityTraitsProperty.PropertyName)
            {
                AddAccessibilityTraits();
            }
            else
            {
                base.OnElementPropertyChanged(args);
            }
        }

        void AddAccessibilityTraits()
        {
            var traits = Control.AccessibilityTraits;

            var newTraits = GetAccessibilityTraits(Element);

            if ((newTraits & AccessibilityTrait.Header) > 0) traits |= UIAccessibilityTrait.Header;

            Control.AccessibilityTraits = traits;
        }
    }
}

... and that's it, we can now bring the namespace into our xaml view and add it to any elements that we want to indicate as a heading.

<Label local:Accessibility.AccessibilityTraits="Header" Text="First Header" Style="{StaticResource headerStyle}" />

However, you can see that we already have a shared style for heading as is often the case with a real world app, in this case headerStyle. It turns out that you can add attached properties via a shared style, which looks like this:

<Style x:Key="headerStyle" TargetType="Label">
    <Setter Property="FontAttributes" Value="Bold" />
    <Setter Property="FontSize" Value="22" />
    <Setter Property="local:Accessibility.AccessibilityTraits" Value="Header" />
</Style>

Closing Thoughts

With just 2 code files and 1 line added to your heading styles, it couldn't be much simpler to make your app more accessible for people who rely on VoiceOver. Give it a try 😀

A working sample can be found here.

Testing with HttpClient Interception

Stuart Lang — Sun, 24 Mar 2019 20:45:24 +0000

In my last post I showed how to automatically generate a typed client for use with HttpClientFactory from a swagger file. Now I want to make changes to the client's behaviour and need unit tests, in this post I will look at the HttpClient Interception library and how we can effectively use it in our tests.

Take a look at the following code that makes use of our previously generated client.

var pet = await petStoreClient.GetPetByIdAsync(1, ct);
var firstTag = pet.Tags.FirstOrDefault();

This looks fine, right? But what happens if Tags is null? Can that event happen?

The quick fix would be to use ?. to propagate null safety, but maybe we want our deserialization to never allow collections to be null, but to instead default it to an empty collection.

To figure out the current behaviour and to document how we'd like it to work, we should write tests.

I will be writing these tests in F#, 'cos it rocks! Not only is it a really nice language, I want to use string literals containing JSON in my tests, and this is painful in C#.

HttpClient Interception

This library is really slick, it has a fluent API that can produce an HttpClient loaded with an HttpClientHandler that will intercept requests and return configured responses, so it's great for unit testing.

The fluent API is really intuitive, you can see some great examples on the README.

module NSwag.PetStore.Client.Tests.Tests

open System
open Xunit
open NSwag.PetStore.Client
open JustEat.HttpClientInterception

[<Fact>]
let ``Given missing collection property, we deserialize to an empty collection. 🚀`` () =

    let builder =
        HttpRequestInterceptionBuilder()
            .Requests().ForAnyHost().ForPath("/pet/1234")
            .Responds().WithContent """{
  "id": 0,
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "status": "available"
}"""

    let options =  HttpClientInterceptorOptions().ThrowsOnMissingRegistration()
    builder.RegisterWith options |> ignore
    use innerClient = options.CreateHttpClient()

    innerClient.BaseAddress <- "http://test-host" |> Uri

    let client = PetStoreClient(innerClient)
    let pet = client.GetPetByIdAsync(1234L) |> Async.AwaitTask |> Async.RunSynchronously

    Assert.NotNull pet.Tags
    Assert.Empty pet.Tags

Some things to call out:

We're using xUnit, another great choice would be Expecto, however there's no test runner yet for Rider, and xUnit will work just fine here. xUnit works pretty well with F#, we don't have to have class definitions, notice how we have a module here, but as soon as we want to use ITestOutputHelper we have to switch to using classes.
Function names in F# can contain pretty much anything by escaping with double-ticks: spaces, punctuation, even emojis (which means you have to use them, surely!).
String literals can contain " when we use triple-quoted strings - this is great for JSON and XML snippets.

In terms of what we are doing with HttpClient Interceptor, it almost needs no explanation as it's completely declarative, the only comment I'd add is that you'll probably want the ThrowsOnMissingRegistration during tests, as this ensures everything is completely in-memory, and nothing passes through and materialises to an actual HTTP request .

As we suspected!

Right, so if the Tag part of the JSON is omitted then we end up with a null collection, which is not what we want, so let's change it.

NSwag lets us control the serialization settings in a few ways, one way is via the jsonSerializerSettingsTransformationMethod setting, it lets us point to a static method to configure the JsonSerializerSettings.

After lots of investigation, I found that this was the simplest way to achieve the deserialization that I wanted:

using System;
using System.Collections.Generic;
using System.Reflection;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;

namespace NSwag.PetStore.Client
{
    internal static class PetStoreSerializerSettings
    {
        public static JsonSerializerSettings TransformSettings(JsonSerializerSettings settings)
        {
            settings.DefaultValueHandling = DefaultValueHandling.Populate;
            settings.ContractResolver = new NullToEmptyListResolver();
            return settings;
        }
    }

    internal sealed class NullToEmptyListResolver : DefaultContractResolver
    {
        protected override JsonProperty CreateProperty(MemberInfo member, MemberSerialization memberSerialization)
        {
            var property = base.CreateProperty(member, memberSerialization);

            var propType = property.PropertyType;
            if (propType.IsGenericType && 
                propType.GetGenericTypeDefinition() == typeof(ICollection<>))
                property.NullValueHandling = NullValueHandling.Include;
            return property;
        }

        protected override IValueProvider CreateMemberValueProvider(MemberInfo member)
        {
            var provider = base.CreateMemberValueProvider(member);

            if (member.MemberType == MemberTypes.Property)
            {
                var propType = ((PropertyInfo)member).PropertyType;
                if (propType.IsGenericType && 
                    propType.GetGenericTypeDefinition() == typeof(ICollection<>))
                {
                    return new EmptyListValueProvider(provider, propType);
                }
            }

            return provider;
        }

        class EmptyListValueProvider : IValueProvider
        {
            readonly IValueProvider innerProvider;
            readonly object defaultValue;

            public EmptyListValueProvider(IValueProvider innerProvider, Type listType)
            {
                this.innerProvider = innerProvider;
                defaultValue = Array.CreateInstance(listType.GetGenericArguments()[0], 0);
            }

            public void SetValue(object target, object value) => innerProvider.SetValue(target, value ?? defaultValue);
            public object GetValue(object target) => innerProvider.GetValue(target) ?? defaultValue;
        }
    }
}

If there is a simpler way (and I suspect there must be!) do let me know in the comments.

Now when we run the tests again...

That's better 🙂

Other Options with HttpClient Interception

In this case I wanted my test to contain a JSON string literal, but in most cases we could instead use the WithJsonContent method, which takes an object and serializes it for us (optionally with serialization settings). Ironically it would have been easier in C# if I wanted to do this, as anonymous objects hasn't yet landed in F# (but it's sooo close!).

A compelling alternative would have been to use an HTTP bundle file, which to quote the docs, “can be used to store the HTTP requests to intercept and [store] their corresponding responses as JSON”.

Closing

HttpClient Interception is the brainchild of Martin Costello, who's always doing amazing things in the .NET Core community.

You can find all of the code in this post here.

Generating a Typed Client for use with HttpClientFactory using NSwag

Stuart Lang — Mon, 18 Mar 2019 09:29:42 +0000

If you're a .NET developer building web apps or microservices, odds are at some point you're going to want to call an HTTP API from an ASP.NET Core app. This post covers how to create a client using NSwag, with the appropriate settings for using it with HttpClientFactory.

Typed Clients and `HttpClientFactory`

For a proper introduction to these concepts I encourage you to read Steve Gordon's HttpClientFactory in ASP.NET Core 2.1 series, An Introduction to HttpClientFactory and Defining Named and Typed Clients, but the really short version is:

HttpClientFactory - This was introduced to solve the problems around managing the lifetime of HttpClients and their handlers, which historically has been problematic.
Typed Clients - This is a feature of HttpClientFactory which lets you register a class which simply wraps HttpClient (i.e. takes one in its constructor), thus giving you a typed client to your API, while not owning the lifetime of any HttpClients, letting HttpClientFactory do its thing.

NSwag

Where does NSwag fit into this?

NSwag is, on one hand, like Swashbuckle, in that with a couple of lines of code you can have your ASP.NET Core application serving up a swagger doc and swagger ui within your app at runtime. Then it also has the functionality of AutoRest, where it can take a swagger file and generate a C# typed client for you (and other languages such as TypeScript).

There are a couple of things that impress me about NSwag:

The number of integrations - it's a swiss army knife! Just take a minute to read the README, you quickly get the idea, it can generate swagger or OpenAPI file not just at runtime, but at build time from your web api assembly. Then you can generate clients in various languages with lots of settings to play around with.
Rico Suter, who is the primary maintainer, is continuously contributing to it and is so responsive to issues, and checking in fixes and features. It's like he has a team running his GitHub account!

Starting with swagger.json

We are going to be generating a client from swagger.json, if you need to produce this from your own ASP.NET Core application then you can generate a swagger.json using the NSwag CLI, see here.

Generating the Client in Build

For this, we will use the NSwag.ConsoleCore CLI tool package (we could also use the NSwag.MSBuild package, the process is largely the same). I'm using the Pet Store swagger, and start by dropping the swagger.json into my project folder.

There are 2 ways to pass config into the NSwag commands, one is via command line args, the other is via a JSON config file which is what I'll be using here.

Firs create an empty library (here we will target netstandard2.0) and add the following snippet to an ItemGroup in your .csproj file:

<DotNetCliToolReference Include="NSwag.ConsoleCore" Version="12.0.15" />

After a dotnet restore we can now run in the project folder dotnet nswag new, this will create us a default config file, we can strip it down so it looks like this. Here's a trimmed down version:

{
  "runtime": "NetCore22",
  "defaultVariables": null,
  "swaggerGenerator":{
    "fromSwagger":{
      "json":"$(InputSwagger)"
    }
  },
  "codeGenerators": {
    "swaggerToCSharpClient": {
      ... OMITTING LOTS OF DEFAULT CONFIG ...
      "generateClientInterfaces": true,
      "injectHttpClient": true,
      "disposeHttpClient": false,
      "generateExceptionClasses": true,
      "exceptionClass": "$(ClientName)Exception",
      "useBaseUrl": false,
      "className": "$(ClientName)Client",
      "generateOptionalParameters": true,
      "generateJsonMethods": false,
      "namespace": "$(ClientNamespace)",
      "classStyle": "Poco",
      "output": "$(GeneratedSwaggerClientFile)"
    }
  }
}

Here are settings that I changed from their defaults:

generateClientInterfaces - This gives us an interface for our typed client, abstracting the implementation away. This may seem like something you wouldn't think of doing without, but there is merit in using the implementation of the typed client under test and mocking at the HttpClient level (shout out to httpclient-interception).
InjectHttpClient - This creates a constructor to the client that takes in a HttpClient, which is what we need to use it as a typed client with HttpClientFactory.
disposeHttpClient - It mostly doesn't matter if you call Dispose on HttpClient when used with HttpClientFactory, it's mostly a no-op. However, for correctness sake, it would be weird for the typed client to dispose of something it doesn't own.
generateOptionalParameters - By default NSwag will create 2 methods per operation, one with and one without a CancellationToken, enabling this will combine them.
generateJsonMethods - By default NSwag will add instance methods that serialize and deserialize types, they just delegate to one-liner static methods from Json.NET. I like my POCOs nice and plain, so I disable this.
useBaseUrl - This is an important one, we want to use the BaseAddress of HttpClient only, we don't want to override that with a property on the typed client (which is what will happen by default), so we set this to false. We can configure the BaseAddress at the time we register the typed client.
exceptionClass - The type of exception that is thrown on error, by default it would be SwaggerException, which feels like an implementation leak.
classStyle - By default NSwag uses the style Inpc which is short for INotifyPropertyChange, which is a strange default, I can only think it would be useful if you were building an MVVM client app and wanted to reuse the classes to bind to directly (still feels wrong to me). By selecting Poco, we end up with just a typical class with getter and setter properties.

You can see I use variables in this file, such as "$(InputSwagger)", we can pass these in via the nswag command.

What we want to do is to just do a dotnet build and to have the project automatically create the generated .cs file, and include it in the files to build. So here's the .csproj:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>netstandard2.0</TargetFramework>
        <DebugType>embedded</DebugType>
        <EmbedAllSources>true</EmbedAllSources>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="12.0.1" />
        <PackageReference Include="System.ComponentModel.Annotations" Version="4.5.0" />
        <DotNetCliToolReference Include="NSwag.ConsoleCore" Version="12.0.15" />
    </ItemGroup>

    <Target Name="GenerateNSwagClient">
        <PropertyGroup>
            <InputSwagger>swagger.json</InputSwagger>
            <ClientName>PetStore</ClientName>
            <GeneratedSwaggerClientFile Condition="'$(GeneratedSwaggerClientFile)' ==''">$(IntermediateOutputPath)$(MSBuildProjectName).$(ClientName)Client.cs</GeneratedSwaggerClientFile>
        </PropertyGroup>
        <Exec Command="dotnet nswag run nswag.json /variables:InputSwagger=$(InputSwagger),ClientName=$(ClientName),ClientNamespace=$(RootNamespace),GeneratedSwaggerClientFile=$(GeneratedSwaggerClientFile)" />
    </Target>

    <Target Name="IncludeNSwagClient" BeforeTargets="CoreCompile" DependsOnTargets="GenerateNSwagClient">
        <ItemGroup Condition="Exists('$(GeneratedSwaggerClientFile)')">
            <Compile Include="$(GeneratedSwaggerClientFile)" />
            <FileWrites Include="$(GeneratedSwaggerClientFile)" />
        </ItemGroup>
    </Target>
</Project>

Things to note:

The only thing in this file that is specific to the Pet Store swagger, is the <ClientName>PetStore</ClientName>, feel free to use this as a recipe for your own clients.
We hook our targets before CoreCompile, giving us the opportunity to add files to compile.
The generated file goes into the IntermediateOutputPath, this is the configuration-specific folder inside of obj, this is exactly how AssemblyInfo.cs is generated, and is likely already part of your .gitignore.
We have included the required Newtonsoft.Json and System.ComponentModel.Annotations packages.
Variables are passed into the nswag.json using the variables argument.
<DebugType>embedded</DebugType> and <EmbedAllSources>true</EmbedAllSources> gives us one .dll which contains an embedded PDB file, which contains all of the source within it for debugging purposes. You could also use symbol packages, which in my option is a step backwards from this solution.

Using the Client with `HttpClientFactory`

Right, we have our package/project, let's use it!

Let's create a new ASP.NET Core Web API using the template, and add a reference to our client project and add the Microsoft.Extensions.Http package. See here for an example.

Now we can register our client in the ConfigureServices method, like this:

services.AddHttpClient<IPetStoreClient, PetStoreClient>(c => c.BaseAddress = new Uri("https://petstore.swagger.io/v2/"));

And that's it! Now we can start using our client, here's an example from our controller:

[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    readonly IPetStoreClient petStoreClient;

    public ValuesController(IPetStoreClient petStoreClient)
    {
        this.petStoreClient = petStoreClient;
    }

    [HttpGet]
    public async Task<ActionResult<IEnumerable<string>>> Get(CancellationToken ct)
    {
        var stu = await petStoreClient.GetUserByNameAsync("Stu", ct);
        return new[] { stu.Email };
    }
}

You can see all of the code here.

Miscellaneous C# Async Tips

Stuart Lang — Mon, 03 Dec 2018 07:50:29 +0000

There are lots of great async tips out there, here a random few that I've collected over the past couple of years that I haven't seen much written about.

Use Discards with `Task.Run` for Fire and Forget

This is a minor bit of guidance, but one of my favourites. If you are starting a Task in a fire-and-forget manner with Task.Run, other readers of the code might be thinking "did they forget to await the returned task here?".

You could make your intent explicit with a comment, but a very concise and clear way to indicate this was your intention is to use the discard feature in C# 7.0:

Task.Run(() => SomeBackgroundWork()); // Fire and forget

// becomes

_ = Task.Run(() => SomeBackgroundWork());

Of course, comment if you need to clarify anything, but in this example, I think it makes sense to omit the comment as it leaves less noise.

Replace `Task.Factory.StartNew`

Task.Factory.StartNew was often used before Task.Run was a thing, and StartNew can be a bit misleading when you are dealing with async code as it represents the initial synchronous part of an async delegate, due to their being no overload that takes a Func<Task<T>>.

Stephen Cleary even goes as far to say it is dangerous, and has very few valid use cases, including being able to start a LongRunning task for work that will block in order to prevent blocking on your precious thread pool threads. Bar Arnon points out this almost never mixes well with async code. In short StartNew is rarely useful, and importantly could cause confusion.

My first tip is, where ever you see the following:

Task.Factory.StartNew(/* Something */).Unwrap()

to make it more familiar to other readers of the code, you can replace it with:

Task.Run(/* Something */)

If you see usages without Unwrap(), there's a chance it's not doing what you think it's doing. Or if you are using it to start a task with custom TaskCreationOptions, be sure it's required for your scenario. To be clear, here is a rare scenario where it would make sense:

Task.Factory.StartNew(() =>
{
    while (true)
    {
        Thread.Sleep(1000); // Some blocking work you wouldn't want happening on your threadpool threads.
        DoSomething();
    }
}, TaskCreationOptions.LongRunning);

Async & Lazy

One common place where people get caught out in migrating synchronous code to async is where they have lazy initiated properties or singletons, and it now needs to be initialized asynchronously. A great tool in your toolbelt in the sync world to deal with this is Lazy<T>, however, how can we use this with async and Tasks?

By default Lazy<T> uses the setting LazyThreadSafetyMode.ExecutionAndPublication, this means it's thread-safe, and if multiple concurrent threads try to access the value, only one triggers the creation, and the others all wait for the value to become available.

What's nice is this is kind of how Task<T> works with regards to awaiting. If one thread creates a Task instance that is awaited by other threads before it completes, they wait for the value to become available, without additionally executing the same work. However we need a thread-safe way to create the Task instance, so we can combine it with Lazy<T> like this:

readonly Lazy<Task<string>> _lazyAccessToken = new Lazy<Task<string>>(async () => {
    return await RetrieveAccessTokenAsync();
});

public Task<string> AccessToken => _lazyAccessToken.Value;

I've written this verbosely to be clear, but we can reduce this by making the statement a lambda, eliding the await, and replacing the invocation of RetrieveAccessTokenAsync with the method group like this:

readonly Lazy<Task<string>> _lazyAccessToken = new Lazy<Task<string>>(RetrieveAccessTokenAsync);

public Task<string> AccessToken => _lazyAccessToken.Value;

Note that it's important to defer the accessing of .Value.

We could encapsulate into a type like this:

internal sealed class AsyncLazy<T> : Lazy<Task<T>>
{
    public AsyncLazy(Func<Task<T>> taskFactory) :
    base(taskFactory) { }
}

Or we could use the great vs-threading library from Microsoft (if you can get over the VisualStudio namespace), which contains lots of well-polished async primitives such as AsyncLazy<T> you would almost expect to come included with the framework and part of .NET Standard.

Also, an honourable mention goes to AsyncLazy defined in Nito.AsyncEx.Coordination by Stephen Cleary.

An alternative strategy to AsyncLazy<T> if you don't require it to be lazy, is to eagerly assign a field or property with a task in a constructor, which is started but not awaited, like this:

class ApiClient
{
    public ApiClient()
    {
        AccessToken = RetrieveAccessTokenAsync();
    }

    public Task<string> AccessToken { get; }
    // here AccessToken is a hot Task, that may or may not be complete by the time it's first accessed

Async & Lock

Another thing that trips people up when migrating their synchronous code is dealing with lock blocks, where async code cannot go. First I say, what are you trying to achieve? If it's thread-safe initialization of a resource or singleton, then use Lazy/AsyncLazy mentioned above, your code will likely be cleaner and express your intent better.

If you do need a lock block which contains async code, try using a SemaphoreSlim. SemaphoreSlim does a bit more than Monitor and what you need for a lock block, but you can use it in a way that gives you the same behaviour. By initializing the SemaphoreSlim with an initial value of 1, and a maximum value of 1, we can use it to get thread-safe gated access to some region of code that guarantees exclusive execution.

_semaphore = new SemaphoreSlim(1,1) // initial: 1, max: 1  

async Task MyMethod(CancellationToken cancellationToken = default)
{
    await _semaphore.WaitAsync(cancellationToken);
    try
    {
        // the following line will only ever be called by one thread at any time
        await SomethingAsync();
    }
    finally
    {
        _semaphore.Release();
    }
}

What's also cool is that SemaphoreSlim has a synchronous Wait method in addition to WaitAsync, so we can use it in scenarios where we need both synchronous and asynchronous access (be careful of course).

It may also be worth checking out AsyncLock from Nito.AsyncEx.Coordination.

That's it for now, a bit of a random assortment I know.

Update: Thanks to Thomas Levesque for pointing out in the comments that SemaphoreSlim differs from Monitor/lock because it is not reentrant. This means a lock has no issue being acquired from a thread that has already acquired it, whereas with a SemaphoreSlim you would end up deadlocking yourself under the same scenario.

Another caveat feedback by odinserj in the comments is that on .NET Framework, a thread abort exception could leave the semaphore forever depleted, so it's not bulletproof.

BigInteger to String in Any Base with F#

Stuart Lang — Sat, 01 Dec 2018 23:19:09 +0000

I spend a lot of time persuading people that F# is not about maths and finance, it's a great general purpose language that shines in many areas (such as domain modelling). However I've been playing around with some maths lately, and F# is my go-to for this, so here's a post.

As the numbers we do arithmetic with get increasingly larger, the usual numeric types in .NET quickly fall short, with Int32.MaxValue being 2147483647, and Int64.MaxValue being 9223372036854775807. When we need to go beyond this we can use BigInteger aka bigint (the type abbreviation in F#) which can represent an arbitrarily large integer.

I had the need to print a bigint in any given base (not just decimal, binary, hexadecimal...), and to my surprise, there was nothing out of the box to do this.

The code

First I want to turn a bigint into a list of digits.

// int -> bigint -> int list
let bigintToDigits b source =
    let rec loop (b : int) num digits =
        let (quotient, remainder) = bigint.DivRem(num, bigint b)
        match quotient with
        | zero when zero = 0I -> int remainder :: digits
        | _ -> loop b quotient (int remainder :: digits)
    loop b source []

Things to note;

The inner function is recursive (given by the rec keyword), and the outer function just kicks it off with the initial empty digit list. Here b is the base (base is a keyword, unfortunately).
Recursion is often used in functional languages as an alternative to mutable state within loops, and in many cases can lead to a more natural expression of an algorithm/routine. Recursion in F# doesn't overflow the stack and is fast, provided it is tail call optimizable like in this case (i.e. the last thing the function does is call itself, or returns out).
We divide by the base and take the remainder as the least significant digit, then we pass accumulated digits into the loop, along with the quotient and keep going until we get a quotient of 0.
bigint.DivRem returns a quotient and a remainder out parameter, with F# we can treat methods without parameters as if it returned a tuple of the result and the out parameter.
Usually, we could pattern match with 0 as a literal, but because 0I (bigint zero) is a "non-primative literal", we aren't allowed to use it as a constant pattern. Hence the when zero = 0I syntax.
:: is the cons operator, we can use it to construct F# lists, the part to the left is prepended to the part on the right.
F# calls a spade a spade - list<'a> is a linked list, while the C# List<T> is type abbreviated in F# to what it really is, a ResizeArray:

type ResizeArray<'T> = System.Collections.Generic.List<'T>

Now we have a list of digits, let's have a function to convert it to a string (this only supports bases up to 16 at the moment).

let digitsToString source =
    source
    |> List.map (fun (x : int) -> x.ToString("X").ToLowerInvariant())
    |> String.concat ""

Putting this together, if we want to print a bigint in base 16, we do:

let printBigintAsHex source =
    let bigintToHex = bigintToDigits 16
    source |> bigintToHex |>  digitsToString |> printf "%s"

I couldn't find anything on Google or Stack Overflow to do this, so I thought I'd share it here so that it'll show up next time someone looks for it.

How to dotnet build and Target net4x on macOS

Stuart Lang — Mon, 24 Sep 2018 19:01:37 +0000

In a previous post, I made a recommendation of additionally targeting net461 in addition to netstandard2.0 in certain scenarios, however one of the nice things about targeting netstandard2.x is that on macOS you can install the .NET Core SDK, build it, and "it just works".

With net4x however, when you run dotnet build you might see this error:

error MSB3644: The reference assemblies for framework ".NETFramework,Version=v4.6.1" were not found.

And that makes a lot of sense because in order to compile for net461 in this case, we need the reference assemblies of that framework, these are dlls that are the same as the runtime assemblies, but just the signatures, no implementation. On Windows these are called "Targeting Packs" and you would have these ship with Visual Studio, or packaged via standalone installers called "Developer Packs".

On macOS, there are 2 ways to reference these reference assemblies that I know of;

1. Using the mono reference assemblies

If you have Visual Studio for Mac or Rider installed, then you probably already have this installed, and otherwise, it's a good idea to get the latest stable version installed from here. You will probably be able to find the reference assemblies located under version folders within /Library/Frameworks/Mono.framework/Versions/Current/lib/mono.

Now the MSBuild that comes with the .NET Core SDK needs to know where to find the reference assemblies. I found a solution here, however, I'm not sure where it originates from (maybe it was from there?).

You can include a file named netfx.props with this content, and import it into your project like this:

<Project Sdk="Microsoft.NET.Sdk">
  <Import Project="netfx.props" />
  <PropertyGroup>
    <Description>...

And now you are good to go!

2. Obtain the reference assemblies via MyGet

An alternative approach that doesn't require having mono installed is to obtain them via nuget, however, they are not available on nuget.org as of today, there is a GitHub issue that can be tracked regarding this. They currently exist on a MyGet feed (from version 4.5 and up). These are official Microsoft packages, here's an example for 4.6.1.

First, you need to add the feed like this:

  <PropertyGroup>
    <TargetFrameworks>net461;netstandard2.0</TargetFrameworks>
    <RestoreAdditionalProjectSources>
      https://dotnet.myget.org/F/dotnet-core/api/v3/index.json
    </RestoreAdditionalProjectSources>
  </PropertyGroup>

You may have also seen this done via NuGet.config (which is just less cool), or you may have seen this using the RestoreSources property, which would require you to append it to the existing source like this: <RestoreSources>$(RestoreSources);...</RestoreSources>

You can read more about that here.

Now we can import the package:

 <ItemGroup Condition=" '$(TargetFramework)' == 'net461' ">
    <PackageReference Include="Microsoft.TargetingPack.NETFramework.v4.6.1"
                        Version="1.0.1" ExcludeAssets="All" PrivateAssets="All" />
  </ItemGroup>

Finally, we need to point the FrameworkPathOverride to the assemblies from this package:

  <PropertyGroup Condition="'$(TargetFramework)'== 'net461'">
      <FrameworkPathOverride>$(NuGetPackageRoot)microsoft.targetingpack.netframework.v4.6.1/1.0.1/lib/net461/</FrameworkPathOverride>
  </PropertyGroup>

Conclusion

And that's it. There is always the option of using msbuild shipped with mono too by running it just for the net4x tfm, and using dotnet build for other tfms, but where's the fun in that? Let me know if you have other ways of approaching this in the comments.

Displaying Images in iTerm from .NET Console Apps

Stuart Lang — Sun, 02 Sep 2018 18:32:18 +0000

Now that dotnet global tools are a thing, we are seeing an explosion of cool new cross-platform command line apps being built with dotnet. A recent example of this is Giphy CLI, this is a tool to quickly get a gif url from giphy.com and markdown snippet ready for pasting.

My favourite terminal when using my Mac is iTerm2, it has lots of cool features, including the ability to display images right in the console! So I thought it would be great to add this feature to Giphy CLI, but first, how does it work?

Instructions from Docs

iTerm2 extends the xterm protocol with a set of proprietary escape sequences. In general, the pattern is:

ESC ] 1337 ; key = value ^G

Whitespace is shown here for ease of reading: in practice, no spaces should be used.

For file transfer and inline images, the code is:

ESC ] 1337 ; File = [optional arguments] : base-64 encoded file contents ^G

.NET Implementation

So to be honest, from mostly trial and error, I found that this is what you need to do from .NET:

Console.Write("\u001B]1337");
Console.Write(";File=;inline=1:");
Console.Write(Convert.ToBase64String(imageBytes));
Console.Write("\u0007");

where imageBytes are the bytes of the image you want to display. You may also want to detect if you are running in iTerm in the first place and only run this code if this is the case. Thankfully iTerm sets an environment variable we can use, named TERM_PROGRAM, which will have the value iTerm.app in the case where it's running under iTerm. Let's do that:

if (Environment.GetEnvironmentVariable("TERM_PROGRAM") == "iTerm.app") 
{
    Console.Write("\u001B]1337");
    Console.Write(";File=;inline=1:");
    Console.Write(Convert.ToBase64String(imageBytes));
    Console.Write("\u0007");
}

Here is the result:

You can see this PR for a full working example.

Thanks to David De Sloovere for building this cool little tool.

.NET Framework Support for .NET Standard 2.0

Stuart Lang — Tue, 28 Aug 2018 16:50:54 +0000

When .NET Standard 2.0 was introduced, it wasn't plain sailing. .NET Standard 1.5 and 1.6 were already a thing, and they included APIs from .NET Frameworks higher than .NET Framework 4.6.1. Since .NET Standard releases should always be supersets of the previous releases, it naturally followed that .NET Standard 2.0 would only be supported in .NET Frameworks greater than or equal to 4.7.0, as Standard 1.5 included APIs from Framework 4.6.2, and Standard 1.6 included APIs from Framework 4.6.3.

However Microsoft saw an opportunity to broaden the compatibility of .NET Standard 2.0 to include .NET Framework 4.6.1, this meant changing the existing Framework support levels for .NET Standard 1.5 and 1.6, as they had already been released. This was the direction taken due to the fact that the 4.6.1 runtime was so widely used it would have hindered the adoption and success of .NET Standard, and .NET Core as a result, had it been left out.

Having .NET Framework 4.6.1 work with .NET Standard 2.0 packages was very ambitious given that it was already out there in use, support needed to be built retrospectively.

While this mostly worked, in practice I found that there were many problems faced in writing .NET Standard libraries that would run on .NET Framework 4.6.1, and consuming them. Some of the issues I faced were to do with CI build agents not having the necessary versions of nuget and MSBuild to deal with .NET Standard 2.0 libraries, but the larger issues were around assembly binding redirects, and runtime issues, here is just a flavour. There were a number of issues that emerged over time and have become known issues.

Because of all of the issues that I faced, and from other developers stories, the guidance I was giving people last year was to target both netstandard2.0 and net461 at the first sign of trouble if they were really keen on having just one target, or to target both from the beginning for a happy and peaceful life.

Recently Immo Landwerth has said in a tweet that making .NET Standard 2.0 work on .NET Framework 4.6.1 was a mistake, and that the documentation will be updated to reflect the new guidance. He has clarified that it is nothing to do with missing APIs (which is the case for some largely unused APIs in 1.5 & 1.6) but more to do with other issues such as tooling. You can see just some of these issues discussed in this GitHub issue.

Immo Landwerth

@terrajobst

Sorry but we messed up. We tried to make .NET Framework 4.6.1 retroactively implement .NET Standard 2.0. This was a mistake as we don't have a time machine and there is a tail of bugs.

If you want to consume .NET Standard 1.5+ from .NET Framework, I recommend to be on 4.7.2. twitter.com/marcgravell/st…

20:21 PM - 21 Aug 2018

Marc Gravell @marcgravell
Sigh; another report of problems with System.Numerics.Vectors in a .net standard 2.0 lib running on net461 causing binding problems. Yay?

157 313

There has been a recent drive to move to netstandard2.0 to get the benefits it brings to development time thanks to this recent tweet from David Fowler, which is great advice, but many have opted to take this opportunity to remove net461 or lower, meaning that consumers that update now face some of these problems.

David Fowler

@davidfowl

I know we said target The lowest netstandard but we really want everyone to re-baseline at netstandard 2.0. At the very least add a netstandard 2.0 target. #dotnetcore #dotnet

20:58 PM - 17 Jun 2018

69 148

Recommendations

So my recommendation today for library authors that intend to build packages for multiple platforms, including running on net461 - net471, is to target netstandard2.0 and the net4x platform you want to support. .NET Framework 4.7.2 has been built with netstandard2.0 in mind, so it's at that point you can lose the separate target.

If we want to quickly visualise this with the .NET Standard implementation support table, then here's what it looks like:

.NET Standard	2.0	2.1
.NET Core	2.0	3.0
.NET Framework	Feasible but problematic: 4.6.1 Works: 4.7.2	TBC (Not 4.8)

If the "Feasible but problematic" part makes you feel uncomfortable, feel free to interpret that as "Does not work". Really it means get ready for possible pain, which is something that as a library author you don't want to unleash on your consumers.

If you are that consumer that is experiencing these issues as a result of running .NET Standard packages on .NET Framework 4.6.1, you should prioritise upgrading to 4.7.2, this will really save you time and pain in the long run. If you aren't directly able to do this, apply pressure to those that are in control of this.

Microsoft will be updating their documentation around this topic with official guidance, and I will be updating this post once that is released.

TL;DR

Pattern Matching F# Union Types in C# 7

Stuart Lang — Fri, 27 Jul 2018 13:26:27 +0000

Starting with C# 7.0, there is basic pattern matching support. I want to look at using this to interop with F# Discriminated Unions, and see what consuming F# code from C# could look like at it's best.

Here is an example of an F# Discriminated Union (hereafter DU)

type Record = { Name: string; Age: int }

type Abc =
    | A
    | B of double
    | C of Record

For those unfamiliar with DUs, the Abc type defined above can be either A, B, or C (and nothing else), and in the case of A there is no "payload", with B and C there is a payload that comes with it.

So given that this compiles down to a sealed class, and that the cases become classes, we can use the new type pattern in C# to match this with:

void HandleAbc(Abc abc)
{
    switch (abc)
    {
        case Abc.B _:
            Console.WriteLine("B");
            break;
        case Abc.C c:
            Console.WriteLine(c.Item.Name);
            break;
    }
}

There are some things to notice here:

1. It's really nice

The code here is clean I'd say, we are matching on type and can either ignore the result of the cast using _ or we can take it as a named variable (like with c in this example).

2. We don't get the safety we have in F

In F#, when handling DUs the compiler ensure that we have handled all cases, in C#, these safety checks aren't enforced.

3. What about case `A`!

Yeah, so this is where it's not perfect. The F# compiler does generate a type for case A however it is marked as internal and therefore is not accessible for us to match against, however, there are a few options, I'll let you pick which is your favourite:

void HandleAbc(Abc abc)
{
    switch (abc)
    {
        // Option 1:
        case var x when x.IsA:
            Console.WriteLine("A");
            break;
        // Option 2:
        case var x when x == Abc.A:
            Console.WriteLine("A");
            break;
    }

    switch (abc.Tag)
    {
        // Option 3:
        case abc.Tags.A:
            Console.WriteLine("A");
            break;
    }
}

Let me know in the comments what your preference is, or is there a better option?

Thanks for reading!

IAsyncEnumerable - An Introduction

Stuart Lang — Thu, 14 Jun 2018 14:56:13 +0000

The problem

public async Task<IEnumerable<User>> GetUsers()
{
    var allResults = new List<User>();
    var nextUrl = "https://account.zendesk.com/api/v2/users.json";
    while (nextUrl != null)
    {
        var page = await _client.GetAsync(nextUrl)
                            .Content.ReadAsAsync<UsersListResponse>();
        allResults.AddRange(page.Users);
        nextUrl = page.NextPage;
        // eg "https://account.zendesk.com/api/v2/users.json?page=2"
    }
    return allResults;
}

Take a look at the above code, you may have run into this familiar issue yourself. We'd like to represent the pageable results of this HTTP API in our types, while still be asynchronous.

Traditionally there would be 4 ways to approach this;

Block on the async code with .Result/.GetAwaiter().GetResult() or .Wait(). This is not a good idea.
The above approach of awaiting each asynchronous task, but doing it all eagerly and returning the complete results in a materialised collection. This defeats the purpose of this paging API, and more generally we lose the laziness of the problem we are trying to model.
We flip the return type to IEnumerable<Task<User>>. This would require that we trust any consumers of this code to await the result of each task after every enumeration. There are ways to enforce this at runtime, and throw an exception if it's not consumed correctly, however, this ultimately is a misleading type, and the shape of the type doesn't communicate its hidden constraints.
We don't try returning a single type such as Task<IEnumerable<T>> and we model it ourselves. This can be a good idea, but we lose the benefits of having a familiar type to work with.

Well, it's about time we adopted a new type and end this madness. That's what IAsyncEnumerable<T> is for.

About Ix.Async

Currently IAsyncEnumerable<T> is a concept which exists in a few places, with no singular definition. The version I will be using today lives in the Reactive Extensions repo, in a fork that is based on the latest C# 8.0 proposal.

Reactive Extensions (Rx) is the home of Observable implementation and extensions, it is also home to a sibling project named Interactive Extensions (Ix for short). Rx has lots of extensions and tools for composing pushed based sequences, and Ix is very similar but for pull-based sequences (IEnumerable<T>). The part I am interested in for this post is the async part, which I'll be referring to as Ix.Async, this is shipped in its own nuget package, and I will generally be referring to the IAsyncEnumerable<T> definition that lives here (although this will map trivially to other implementations).

In the near future, C# 8.0 will introduce Async Streams (I prefer the term Sequence, as Stream is already a different .NET concept) as a language feature, and there will be a new definition of IAsyncEnumerable<T> it will work with, but that doesn't stop us using Ix.Async today, either using the current definition which slightly differs from the C# 8.0 proposal or building the fork with the latest definition in.

Definition

public interface IAsyncEnumerable<out T>
{
    IAsyncEnumerator<T> GetAsyncEnumerator();
}

public interface IAsyncEnumerator<out T> : IAsyncDisposable
{
    T Current { get; }
    ValueTask<bool> MoveNextAsync();
}

public interface IAsyncDisposable
{
    ValueTask DisposeAsync();
}

This is the definition of IAsyncEnumerable<T> from the C# 8.0 proposal, it should look very familiar, it is just IEnumerable<T> with an async MoveNext method, as you might expect.

We can now see the relationship with IObservable<T> and IEnumerable<T>.

Being in this familiar family means that we don't have to learn new concepts to start consuming and composing operations over this type.

IAsyncEnumerable<Bar> ConvertGoodFoosToBars(IAsyncEnumerable<Foo> items)
{
    return items
        .Where(foo => foo.IsGood)
        .Select(foo => Bar.FromFoo(foo));
}

These extension methods are immediately understandable to us and are ubiquitous in C# already.

Producing sequences

All of this would be pretty academic if we couldn't generate sequences to be consumed. Today there are a few options.

1. Implement the `IAsyncEnumerable<T>` and `IAsyncEnumerator<T>` interfaces directly

You can do this, and for performance critical code, this might be the most suitable approach.

It does require a fair bit of boilerplate code, however, so here is a starting point:

// A starting point for your own IAsyncEnumerable extensions
public static class AsyncEnumerableExtensions
{
    public static IAsyncEnumerable<T> MyExtensionMethod<T>(this IAsyncEnumerable<T> source)
    {
        return new MyAsyncEnumerable<T>(source);
    }

    public struct MyAsyncEnumerable<T> : IAsyncEnumerable<T>
    {
        readonly IAsyncEnumerable<T> enumerable;

        internal MyAsyncEnumerable(IAsyncEnumerable<T> enumerable)
        {
            this.enumerable = enumerable;
        }

        public IAsyncEnumerator<T> GetAsyncEnumerator()
        {
            return new MyAsyncEnumerator(enumerable.GetAsyncEnumerator());
        }

        public struct MyAsyncEnumerator : IAsyncEnumerator<T>
        {
            readonly IAsyncEnumerator<T> enumerator;

            internal MyAsyncEnumerator(IAsyncEnumerator<T> enumerator)
            {
                this.enumerator = enumerator;
            }

            public ValueTask DisposeAsync()
            {
                return enumerator.DisposeAsync();
            }

            public T Current => enumerator.Current;

            public ValueTask<bool> MoveNextAsync()
            {
                return enumerator.MoveNextAsync();
            }
        }
    }
}

2. Use the static helper methods in Ix.NET

IAsyncEnumerable<int> GenerateWithIx()
{
    return AsyncEnumerable.CreateEnumerable( 
        () =>
        {
            var current = 0;

            async Task<bool> f(CancellationToken ct)
            {
                await Task. Delay(TimeSpan.FromSeconds(0.5));
                current++; 
                return true; 
            } 

            return AsyncEnumerable.CreateEnumerator( 
                moveNext: f,
                current: () => current,
                dispose: () => { } 
            );
        });
}

3. Use CXuesong.AsyncEnumerableExtensions

I wanted to build something like this myself, and then I found this library, so I don't need to! Credit to Chen, this is a great library.

// using CXuesong.AsyncEnumerableExtensions 
async Task Generator(IAsyncEnumerableSink<int> sink)
{
    var i = 1;
    while (true)
    {
        await Task.Delay(TimeSpan.FromSeconds(0.5));
        await sink.YieldAndWait(i++);
    }
}

AsyncEnumerableFactory.FromAsyncGenerator<int>(Generator)

This library offers a very nice and simple way to express sequences. You build an async function that takes an IAsyncEnumberableSink<T> (defined by the library) and returns a Task. Now you can do your awaits, but when you want to yield an item to the sequence, you call sink.YieldAndWait(value) where sink is that parameter.

4. Coming soon to a C# 8.0 near you

Today you cannot use the async keyword and iterator methods together, so having an async iterator method would require a new language feature. Well, good news, it's in the works, take a sneak peek here.

Here is a snippet showing what it could look like.

static async IAsyncEnumerable<int> Mylterator()
{
    try
    {
        for (int i = 0; i < 100; i++)
        {
            await Task.Delay(1000);
            yield return i;
        }
    }
    finally
    {
        await Task.Delay(200); 
        Console.WriteLine("finally");
    }
}

Consuming sequencing

We can produce sequences, but that won't be much use to us if we cannot consume them.

1. ForEachAsync

Just like the .ForEach(...) extension method on List<T>, we have .ForEachAsync(...) from Ix.Async, this lets us do work on each item, and gives us a Task to await to drive the whole chain of pull-based work.

await seq.ForEachAsync(x => Console.WriteLine(x));

Unfortunately, dogmatism fails here, ForEachAsync is suffixed with Async because it returns a Task and operates asynchronously, however, the delegate it takes is synchronous, this led me to build a method that can take an async delegate and name it ForEachAsyncButActuallyAsync. 🤦

await seq.ForEachAsyncButActuallyAsync(x => Console.WriteLine(x));

2. C# 8.0 foreach

Again, we have language support on the way. Here's what it would look like:

var asyncSequence = GetMyAsyncSequence(cancellationToken: ct);
await foreach (var item in asyncSequence)
{
    ...
}

Design Decisions

One of the problems that have meant that we've had to wait so long a first class IAsyncEnumberable<T> and language features is because there are many design decisions that need answering, for example;

Does IAsyncEnumerator<T> implement IDisposable or a new async version (IAsyncDisposable)? Update IAsyncDisposable it is!
If there is going to be an IAsyncDisposable, should the language support the using syntax for it?
Does the CancellationToken get passed into MoveNext each move or GetEnumerator once? Update CancellationTokens are not going to be handled by syntax, so you should flow it into the IAsyncEnumerable<T> types yourself.
Should it be MoveNext, or MoveNextAsync? Update MoveNextAsync wins!
Should MoveNextAsync return a Task<bool> or a ValueTask<bool>? Update ValueTask<bool> has it!
In the foreach syntax, where does the await modifier go? Outside the brackets? (Yes, of course, what sort of monster do you take me for?)
In the foreach syntax, how do you do the equivalent of .ConfigureAwait(false)? Update like this.
Will the foreach syntax look for the type, or the pattern? await doesn't just apply to Task for example.

and that's just what comes immediately to mind, the more you think, the more you uncover.

Who is using it today?

There are a couple of large projects using this today:

Entity Framework Core - Currently using an internal definition, but there is talk of plans to use whatever comes in C# 8.
Google Cloud Platform Libraries - This one was a bit of a surprise to me. If you install any Google Cloud package, it will reference their Core package, which uses and references Ix.Async. One of the members of the team that builds this is (the) Jon Skeet, so that's quite an endorsement!

Stay tuned, there is more to come on this topic.

Adding AssemblyMetadataAttribute using new SDK project, with MSBuild

Stuart Lang — Mon, 26 Mar 2018 19:20:36 +0000

Now that we have the new project system, and we can define common assembly info in our .csproj, we can say good-bye to AssemblyInfo.cs, well, I still see these left around for general assembly attributes.

For example it is quite common to see an InternalsVisibileTo.cs file these days, instead of AssemblyInfo.cs, see here for an example.

However what if you want to add your own assembly attribute with a value you want to pass in as an MSBuild property? For example, an AssemblyMetadataAttribute that contains a git commit hash?

Well, we are in luck, there is an AssemblyAttribute item we can add to our ItemGroup! If we had a property named CommitHash we could write the following:

<AssemblyAttribute Include="System.Reflection.AssemblyMetadataAttribute" Condition="$(CommitHash) != ''" >
    <_Parameter1>CommitHash</_Parameter1>
    <_Parameter2>$(CommitHash)</_Parameter2>
</AssemblyAttribute>

Great! One last thing, we need to say when this is going to happen, and that is before CoreGenerateAssemblyInfo, so:

<Target Name="AddGitMetadaAssemblyAttributes"
          BeforeTargets="CoreGenerateAssemblyInfo">
    <ItemGroup>
        <AssemblyAttribute Include="System.Reflection.AssemblyMetadataAttribute" Condition="$(CommitHash) != ''" >
            <_Parameter1>CommitHash</_Parameter1>
            <_Parameter2>$(CommitHash)</_Parameter2>
        </AssemblyAttribute>
    </ItemGroup>
</Target>

Cool. But wait! It doesn't always work. Sometimes when I do a build, the value doesn't change. What gives?

So it turns out in .NET SDK 2 and up, there are lots of measures to improve performance, one of which is the <AssemblyName>.AssemblyInfoInputs.cache file, which appears in the obj folder, and just contains a hash of the AssemblyInfo inputs as you'd expect.

The hash is calculated internally only by the _Parameter1 values, so in our example where we put the varying data in _Parameter2, this doesn't bust the cache. We can see the logic for this here in CreateGeneratedAssemblyInfoInputsCacheFile.

As a hacky workaround, we can temporarily add our values to _Parameter1 then remove them after the hash is generated. Like this:

<Target Name="GitMetadataAssemblyInfoCacheFileFix"
        BeforeTargets="CreateGeneratedAssemblyInfoInputsCacheFile" >
    <ItemGroup>
      <AssemblyAttribute Include="TemporaryAdditionalHashItem" Condition=" $(CommitHash) != '' ">
        <_Parameter1>$(CommitHash)</_Parameter1>
      </AssemblyAttribute>
    </ItemGroup>
</Target>
<Target Name="CleanupTemporaryAdditionalHashItem"
  AfterTargets="CreateGeneratedAssemblyInfoInputsCacheFile;AddGitMetadaAssemblyAttributes" >
    <ItemGroup>
      <AssemblyAttribute Remove="TemporaryAdditionalHashItem" />
    </ItemGroup>
</Target>

Now we recompile whenever there is a change to our added value. For the end result, see here.

UPDATE: In the upcoming SDK at the time of writing (2.1.300), this hack is no longer required as @natemcmaster has fixed it here. Hurray!