Getting started with DocFx

I have been lately pretty impressed with the DocFx, Microsoft’s static documentation generator. In this blog post, I thought I would outline how easy it is to configure the DocFx for generating documentation for your project.

Assumption : Project already has Xml documentations enabled and the code have the necessary comments.

Step 1 : Install Chocolatey

  • Head over to Chocolatey’s official website and copy the command given in the getting started page.
  • Open the Powershell with Administrative prileges and executed the command copied.

For reference, the command is as follows.

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString(''))

Step 2 : Install Docfx

  • Install Doxfx with following command
cinst docfx -y

Step 3 : Generate DocFx Project

  • Generate Sample DocFx Project for your Project Documentation with the following command.
docfx init -q

Or if you would like to dictate the name for your project.

docfx init -q -o <DocumentationProjectName>

This would generate sample project for your purpose.

Step 4: Specify Project Details

The next step is to specify the location of your Project Files. This has to be mentioned in the docfx.json file.

I am including only the relavant part of docfx.json.

"src": [
          "files": "src/infrastructure/Nt.Infrastructure.UI/**.csproj",
          "cwd": "..",
          "src": "../.."

As you can observe, we have used base path using the src and cwd values, and use the files to specify the projects under consideration.

Step 5 : Build and Generate your documentation website.

That’s all the configuration you would need. Rest of the magic would be done by Docfx for you. To build the project and generate the website, you need to use the following command.

docfx --serve

And there you have it, you have your documentation up and running in the development server. You could access it via (http://localhost:8080/).

We will explore more features of DocFx and related configuration in later post, but surely, this would get you started.

Oxyplot : Selectable Point

While OxyPlot continues to be one of the attractive plotting library for .Net developers, there are times when you find longing for features that could make it even more better.

One of such feature is ability to select/highlight a point in a series. While there is a Selectable Property with LineSeries, it doesn’t quite let you highlight the Data Point.

However, this can be easily achieved using another series with has a single point (the point which was selected). I guess it is easier to show the code than describe it. So let’s go ahead and hit Visual Studio.

We would begin by defining couple of Custom Series. For the sake of example, I am considering LineSeries in this case. The first Custom Series we would define would be the series which displays the Selected Item.

public class SelectedLineSeries:LineSeries

As you can observe, it hardly does anything new. The purpose of the definition is to allow is to easily differenciate between our special Series from Line Series. This would be further clarified when introduce our second custom series, which denotes a series which can be selected.

public class SelectableLineSeries:LineSeries
public bool IsDataPointSelectable { get; set; }

public DataPoint CurrentSelection { get; set; }

public OxyColor SelectedDataPointColor { get; set; } = OxyColors.Red;

public double SelectedMarkerSize { get; set; }

public SelectableLineSeries()
SelectedMarkerSize = MarkerSize;
MouseDown += SelectableLineSeries_MouseDown;

private void SelectableLineSeries_MouseDown(object sender, OxyMouseDownEventArgs e)
if (IsDataPointSelectable)
var activeSeries = (sender as OxyPlot.Series.Series);
var currentPlotModel = activeSeries.PlotModel;
var nearestPoint = activeSeries.GetNearestPoint(e.Position, false);
CurrentSelection = nearestPoint.DataPoint;

currentPlotModel = ClearCurrentSelection(currentPlotModel);

var selectedSeries = new SelectedLineSeries
MarkerSize = MarkerSize + 2,
MarkerFill = SelectedDataPointColor,
MarkerType = MarkerType


private PlotModel ClearCurrentSelection(PlotModel plotModel)
while(plotModel.Series.Any(x=> x is SelectedLineSeries))
plotModel.Series.Remove(plotModel.Series.First(x=> x is SelectedLineSeries));
return plotModel;


The core functionality of the Class is defined in the Series Mouse Down event. This ensures that whenever a point is selected, a new series is added to the Parent PlotModel, which has a single Data Point ( same as the currently selected data point).

Well, that’s all our definition is about. Now we can go ahead and define our PlotModel to be used along with Series definition.

var random = new Random();
var collection = Enumerable.Range(1, 5).Select(x => new DataPoint(x, random.Next(100, 400))).ToList();
var series = new SelectableLineSeries
IsDataPointSelectable = true,
MarkerFill = OxyColors.Blue,
MarkerType = MarkerType.Square,
LineStyle = LineStyle.Solid,
Color = OxyColors.Blue,
ItemsSource = collection,
MarkerSize = 5

GraphModel = new PlotModel();

GraphModel.Axes.Add(new OxyPlot.Axes.LinearAxis
Position = Axes.AxisPosition.Bottom

GraphModel.Axes.Add(new OxyPlot.Axes.LinearAxis
Position = Axes.AxisPosition.Left


That’s it. Hit F5 and test your Selectable Line Series. You can access the source code shown in the demo in my Github.

Oxyplot Selectable

Zoom Rectangle with OxyPlot

Let’s stick to OxyPlot for some more time. This time, we would attempt to change the color of Zoom Rectangle. For those who are new to Oxyplot, the control allows you to zoom in a particular location by permitting the user to draw rectangles in the graph. This particular rectangle is known as Zoom Rectangle.

You can enable the Zoom Rectangle by using the PlotController.

public PlotController ChartController { get; set; }

ChartController = new PlotController();
ChartController.BindMouseDown(OxyMouseButton.Left, PlotCommands.ZoomRectangle);

You can now bind the PlotController with your OxyPlot PlotView instance in XAML.

<oxy:PlotView Model="{Binding Model}" Controller="{Binding ChartController,UpdateSourceTrigger=PropertyChanged}"/>

While would enable the Zoom Rectangle, you would ideally would like to do a bit of Customization, for example, changing the appearance(color) of the rectangle.

You can do so by customizing the ZoomRectangleTemplate. Let’s change the default color of the Zoom Rectangle we just created.

<oxy:PlotView Model="{Binding Model}" Controller="{Binding ChartController,UpdateSourceTrigger=PropertyChanged}">
<Border BorderBrush="Black" BorderThickness="1">
<Rectangle Fill="Orange" />

That’s all you need. You now have your fully customized Zoom Rectangle.


Caliburn.Micro Template Pack now supports VS 2019

So glad to announce that Caliburn.Micro Template Pack now supports Visual Studio 2019.

Caliburn.Micro Template Pack for WPF contains a comprehensive collection of Project Templates and Code Snippets for developing WPF application using Caliburn.Micro. It also includes Bootstrap templates for SimpleContainer, MEF and Unity.

You can download the template from Visual Studio Marketplace

You can read more on the template here

Oxyplot : Using Datagrid for tooltip

Oxyplot uses Tracker Controls for displaying tooltip. You could extend the display by Customizing the Default Tracker control. In this article, we will look deeper into that Tracker Control and aim to display a Grid in the Tracker Control.

For sake of example, let us assume a Fruit Seller, who wants to plot his sales per day on a Line Series. To begin with, let us create some random data to emulate the sales.

private enum eFruits
public IEnumerable<Fruit> Generate()
var random = new Random();
return Enumerable.Range(1, 10)
.SelectMany(x =>
return ((eFruits[])Enum.GetValues(typeof(eFruits))).Select(f =>
new Fruit
Name = f.ToString(),
ItemsSold = random.Next(0, 100),
Date = DateTime.Now.AddDays(x)

In his first attempt, he plots the Line Series, grouping the data by Date on which items where sold.

private void CreatePlotModel(IEnumerable<Fruit> totalSalesDetails)
var salesGrouping = totalSalesDetails.GroupBy(x => x.Date);
var yAxis = new LinearAxis
Position = AxisPosition.Left
var xAxis = new DateTimeAxis
Position = AxisPosition.Bottom,
Minimum = DateTimeAxis.ToDouble(salesGrouping.Min(x => x.Key)),
Maximum = DateTimeAxis.ToDouble(salesGrouping.Max(x => x.Key)),

var lineSeries = new LineSeries
MarkerFill = OxyColors.Blue,
MarkerType = MarkerType.Circle,
TrackerFormatString = "{0}\n{1}: {2:dd.MM.yy}\n{3}: {4:0.###}"
lineSeries.Points.AddRange(salesGrouping.Select(x => new DataPoint(DateTimeAxis.ToDouble(x.Key), x.Sum(c => c.ItemsSold))));


<oxy:PlotView Model="{Binding DataPlotModel}"/>

This gave him his desired out as the following.

Initial Design

However, this left a lot to be desired. Currently the tooltip would display total sales per day. He knew he could decifer that from the chart itself and hence wanted to make use of tooltip for something more useful. He decided to display the details of sales, ie, number of each fruit sold during the day in the tooltip. This would give him a better insight into the sales.

Grid inside the Tooltip

While he knew the Oxyplot’s default Tracker control could be customized, he soon realized this wasn’t as straightward as he assumed it to be. As always, the problem lies in the details.

<oxy:PlotView Model="{Binding DataPlotModel}">
<DataGrid ItemsSource="{Binding}"/>

The TrackerControl accepted a TrackerHitResult as its DataContext, displaying the TrackerHitResult.Text as tooltip, and there seemed no direct way for him to bind a collection of items to the TrackerControl if he was to customize it to include a DataGrid.

A bit of googling and with a tip from his mentor, he soon realized that there was a way instead. What if he can write a Converter that reads the required information from TrackerHitResult and returns a collection for DataGrid to bind to.

For this, he needs to extend the DataPoint so that it would contain the sub-collection information. This would ensure that the same would be available in the DataContext (TrackerHitResult)

public class ExtendedDataPoint : IDataPointProvider
public DateTime Date { get; set; }
public IEnumerable<Fruit> ItemsSold { get; set; }

public DataPoint GetDataPoint()
return new DataPoint(DateTimeAxis.ToDouble(Date), ItemsSold.Sum(x=>x.ItemsSold));

He can now rewrite his CreatePlotModel method to use the ExtendedDataPoint for adding points to the Line Series.

var lineSeries = new LineSeries
MarkerFill = OxyColors.Blue,
MarkerType = MarkerType.Circle,

lineSeries.ItemsSource = salesGrouping.Select(x => new ExtendedDataPoint
Date = x.Key.Date,
ItemsSold = x.ToList()

As you can notice, he has removed the TrackerFormatString as well, as he would not require it any longer. The next step would be to write the Converter required for transforming the TrackerHitResult to IEnumerable<Fruit>.

public class TrackerHitResultConverter : IValueConverter
public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
if(value is TrackerHitResult data)
return (data.Item as ExtendedDataPoint).ItemsSold;
return null;

public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
throw new NotImplementedException();

Since he had already defined his required sub-collection as a part of ExtendedDataPoint, the role of TrackerHitResultConverter became a lot easier. The last piece in the puzzle was to modify the Xaml to use the Converter.

<oxy:PlotView Model="{Binding DataPlotModel}">
<oxy:TrackerControl Position="{Binding Position}" Background="Transparent" BorderBrush="Transparent">
<DataGrid HeadersVisibility="None" ItemsSource="{Binding Converter={StaticResource TrackerHitResultConverter}}" AutoGenerateColumns="False" CanUserAddRows="False" CanUserDeleteRows="False">
<DataGridTextColumn Binding="{Binding Date,StringFormat=d}" Header="Date" />
<DataGridTextColumn Binding="{Binding Name}" Header="Fruit"/>
<DataGridTextColumn Binding="{Binding ItemsSold}" Header="Items Sold" />

With that in place, he was ready to Hit F5 and vola, his tooltip was ready.

Final output

Entire source code discussed in this article is available in my Github.

Rectangle Annotation With Rounded Corner in Oxyplot

It has been few months since I started playing around with Oxyplot, and it continues to impresses me. Having said that, there are times when certain challenges are thrown showing light on certain limitation of the tool. One of such limitation and a way to overcome is being discussed in this blog post.

Oxyplot supports a wide range of Annotations including Rectangle Annotation, Text Annotation, Image Annotation, Ellipse Annotation and Line Annotation among others. These by itself are extremely powerful and easy to use. However, recently I came across a business need where I would need to draw a Rectangle Annotation with Rounded Corner.

The Oxyplot library doesn’t allow us an in-build mechanism to do it. However, the good part is, that is not end of the road. We can create our own custom annotation. Before we hit code, it would be a good idea to discuss how we plan to create a RoundedCornerRectangleAnnotation.

Rounded Rectangle OxyPlot

The crux of the idea is to generate the rounded effect by drawing a set of two rectangle and 4 circle/ellipse. The Radius of the circles would be the intended corner radius of the final rectangle.

Okay, that’s enough for idea, let’s go ahead and write some code.

Part of Custom Annotation Class

 private void DrawRoundedRectangle(IRenderContext rc)
            var xMin = double.IsNaN(this.MinimumX) || this.MinimumX.Equals(double.MinValue)
                            ? this.ClipByXAxis
                                ? this.XAxis.ActualMinimum
                                : this.XAxis.InverseTransform(this.PlotModel.PlotArea.Left)
                            : this.MinimumX;
            var xMax = double.IsNaN(this.MaximumX) || this.MaximumX.Equals(double.MaxValue)
                            ? this.ClipByXAxis
                                ? this.XAxis.ActualMaximum
                                : this.XAxis.InverseTransform(this.PlotModel.PlotArea.Right)
                            : this.MaximumX;
            var yMin = double.IsNaN(this.MinimumY) || this.MinimumY.Equals(double.MinValue)
                            ? this.ClipByYAxis
                                ? this.YAxis.ActualMinimum
                                : this.YAxis.InverseTransform(this.PlotModel.PlotArea.Bottom)
                            : this.MinimumY;
            var yMax = double.IsNaN(this.MaximumY) || this.MaximumY.Equals(double.MaxValue)
                            ? this.ClipByYAxis
                                ? this.YAxis.ActualMaximum
                                : this.YAxis.InverseTransform(this.PlotModel.PlotArea.Top)
                            : this.MaximumY;
            var xCornerRadius = (CornerRadius / (XAxis.Maximum - XAxis.Minimum)) * 100;
            var yCornerRadius = (CornerRadius / (YAxis.Maximum - YAxis.Minimum)) * 100;
            this.screenRectangleWithClippedXAxis = new OxyRect(this.Transform(xMin + xCornerRadius, yMin), this.Transform(xMax - xCornerRadius, yMax));
            this.screenRectangleWithClippedYAxis = new OxyRect(this.Transform(xMin, yMin + yCornerRadius), this.Transform(xMax, yMax - yCornerRadius));
            this.screenEllipseLeftBottom = new OxyRect(this.Transform(xMin, yMin), this.Transform(xMin + 2* xCornerRadius, yMin + 2* yCornerRadius));
            this.screenEllipseLeftTop = new OxyRect(this.Transform(xMin, yMax), this.Transform(xMin + 2 * xCornerRadius, yMax - 2 * yCornerRadius));
            this.screenEllipseRightBottom = new OxyRect(this.Transform(xMax, yMin), this.Transform(xMax - 2 * xCornerRadius, yMin + 2 * yCornerRadius));
            this.screenEllipseRightTop = new OxyRect(this.Transform(xMax, yMax), this.Transform(xMax - 2 * xCornerRadius, yMax - 2 * yCornerRadius));
            // clip to the area defined by the axes
            var clippingRectangle = OxyRect.Create(
                this.ClipByXAxis ? this.XAxis.ScreenMin.X : this.PlotModel.PlotArea.Left,
                this.ClipByYAxis ? this.YAxis.ScreenMin.Y : this.PlotModel.PlotArea.Top,
                this.ClipByXAxis ? this.XAxis.ScreenMax.X : this.PlotModel.PlotArea.Right,
                this.ClipByYAxis ? this.YAxis.ScreenMax.Y : this.PlotModel.PlotArea.Bottom);
            rc.DrawClippedRectangle(clippingRectangle, this.screenRectangleWithClippedYAxis,
            rc.DrawClippedEllipse(clippingRectangle, screenEllipseLeftBottom,
            rc.DrawClippedEllipse(clippingRectangle, screenEllipseLeftTop,
            rc.DrawClippedEllipse(clippingRectangle, screenEllipseRightBottom,
            rc.DrawClippedEllipse(clippingRectangle, screenEllipseRightTop,
            if (!string.IsNullOrEmpty(this.Text))
                var textPosition = this.GetActualTextPosition(() => this.screenRectangle.Center);


You can find the complete class code in Gist Link. The complete source code, including the WPF Wrapper can be found in the forked implementation at my GitHub.

PS:The implementation, of course has its own flaws. You cannot set Stroke for the Rounded Rectangle, hopefully, I would be able to workaround this issue soon.

Custom Tooltip in Oxyplot

Working with OxyPlot sometimes throw these interesting problems, mainly due to lack of documentation. One of the recent challenges involved creating a custom tooltip, which at the hindsight, was pretty straightforward – only if the developers had continued their effort in completing the documentation.


Alright back to out problem. Oxyplot, by default provides a neat little tooltip for the Data Points in the graph. On most occasions, these are more than enough. On others, you need to tweak the tooltip a bit more to include additional information.


If you browse through the Series Class (LineSeries, BarSeries etc), you would notice it has a property named TrackerFormatString. This is the key to unlocking the tooltip. For sake of example, we will examine the LineSeries in this post. By default, following is the format of TrackerFormatString


"{0}\n{1}: {2:0.###}\n{3}: {4:0.###}"


{0} = Title of Series
{1} = Title of X-Axis
{2} = X Value
{3} = Title of Y-Axis
{4} = Y Value

Some of the basic customization can happen within the TrackerFormatString property itself, say, suppose you want format the values to display only 2 decimal places. This again would be sufficient to cover a lot of cases.

However, at times, you might be interested to display additional information. Unfortunately the DataPoint class has only two properties, which you could use for loading your data. This cripples you desire to add a third value associated with the DataPoint in addition to X & Y, especially if you notice that the DataPoint is a sealed class and Series.Points.Points.AddRange accepts only DataPoints as parameter.

Thankfully, Oxyplot developers has left another door open while closing the DataPoint class. It allows you to assign the Points to Series using the Series.ItemSource Property, which accepts an IEnumerable. The only criteria for your IEnumerable is to the type needs to implement IDataPointProvider.
Let’s go ahead and implement our demo class.


public class CustomDataPoint : IDataPointProvider
  public double X { get; set; }
  public double Y { get; set; }
  public string Description { get; set; }
  public DataPoint GetDataPoint() => new DataPoint(X, Y);

  public CustomDataPoint(double x,double y,string description)
    X = x;
    Y = y;
    Description = description;

var points = new CustomDataPoint[]
  new CustomDataPoint(5,12,"Info 1"),
  new CustomDataPoint(6,10,"Info 2"),
  new CustomDataPoint(7,9,"Info 3"),
  new CustomDataPoint(8,13,"Info 4"),
  new CustomDataPoint(9,14,"Info 5"),
  new CustomDataPoint(10,10,"Info 6")

And now we will use the ItemSource property to assign the points to Series. We will also use the TrackerFormatString to format our tooltip to display additional information.

var seriesVisible = new OxyPlot.Series.LineSeries();
seriesVisible.ItemsSource = points;
seriesVisible.TrackerFormatString = "X={2},\nY={4},\nAdditionalInfo={Description}";

That’s it and we have our additional information displayed in tooltip. Go and run your application


Quick Intro to Protobuf

Protobuf-net is a .net adaption of Google’s Protocol Buffers and is generally considered to be a really fast serialization/deserialization library.  The target serializable classes are decorated with mainly 3 attributes.

The target class is decorated with the ProtoContract attributes, indicating that the class can be serialized.

The ProtoMember attribute indicates the field that will be serialized, while the number N denotes the order in which the property would be serialized. By default, the properties would be serialized in alphabetical order.

As the name suggests, the ProtoIgnore attributes is used to indicate the properties that needs to be ignored while serializing.

Let’s create the example class which we would be serializing.

public class Student
  public string Name { get; set; }

In order to serialize the class, you would be using the Static method Serialize.

var stOriginal = new Student() { Name = "jia" };
byte[] array;
using (var stream = new System.IO.MemoryStream())
   ProtoBuf.Serializer.Serialize(stream, stOriginal);
   array = stream.ToArray();

Similarly, the static method Deserialize can be used to deserialize the object back.

Student stDeserialized;
using (var stream = new System.IO.MemoryStream(array))
  stDeserialized = ProtoBuf.Serializer.Deserialize(stream);

Easy as that !! Happy Coding !!

Sneak Peak at Response Files (.rsp)

The Visual Studio has evolved so much that anyone hardly uses the CSC.exe tool and command line switches any longer. But there could be days when you are forced to opt for CSC.exe and the biggest woe is the huge list of switches/parameters that you need to associate each time you want to compile using csc.exe.

The response files (*.rsp) provides a cleaner way to find a solution for this problem, inevitably also taking caring of accidentally missing parameters. Response files is plain text files which contains a set of switches you would like to apply to your compilation command. Let’s consider the example.

csc.exe /out:jia.exe /t:exe program.cs

We have opted for a simple example. In real life, you could be referring to a bag full of dependencies, which you would have to include using the /r switch. But for sake of example, we will stick to simple example mentioned above. We will now write out response file to include the /out and /t switches.


We will name it as “app.rsp”. Now, to compile our cs file, we would need to specify the rsp file using the @ prefix.

csc.exe @app.rsp program.cs

The .Net framework uses a similar approach internally by employing a global response file (csc.rsp). This is the reason we could compile the source files even when skip referencing commonly used dlls in command.

Oxyplot and DateTime Axis

Anyone who has just been introduced to OxyPlot and had to deal with a graph comprising of a Time/DateTime axis might find themselves in a corner. The first thing you would notice is that the DataPoint structure accepts only double and that means trouble, especially with a not-so-exhaustive documentation the tool supports. But if you keep persisting and look around a bit, you will soon notice that the OxyPlot developers has done a fair bit of job to ensure TimeAxis (and many more) are possible. The DateTimeAxis Class enables you to add a DateTime object to your PlotModel.

But prior to jumping to your Axes, you need to find a solution to add a DateTime to your DataPoint Collection. This is again made possible by the DateTimeAxis class and the ToDouble method.

var  dataPoints = new[]
    new DataPoint(DateTimeAxis.ToDouble(new DateTime(2018,1,1,7,23,0)),12),
    new DataPoint(DateTimeAxis.ToDouble(new DateTime(2018,1,1,8,23,0)),9),
    new DataPoint(DateTimeAxis.ToDouble(new DateTime(2018,1,1,10,23,0)),13)

Now let’s add the required axes.

MainGraphModel.Axes.Add(new DateTimeAxis()
  Maximum = DateTimeAxis.ToDouble(new DateTime(2018, 1, 1, 12, 23, 0)),
  Minimum = DateTimeAxis.ToDouble(new DateTime(2018, 1, 1, 6, 23, 0)),
  Position = AxisPosition.Bottom,
  IntervalType = DateTimeIntervalType.Hours,
  MinorIntervalType = DateTimeIntervalType.Hours


Oxyplot does look pretty good, only if they had better documentation.