Documenting Web APIs with Swagger

A while back I posted an article on how to extend the existing help pages generated by Visual Studio for Web API projects to use reflection instead of XML documentation. One of the limitations of that approach was that you could not test the APIs directly. You had to use SoapUI or equivalent. Since then I have started using Swagger for documentation. As a documentation/testing tool it fills the need. In this article I will demonstrate how to integrate Swagger into a Web API project. Additionally I will continue to use the reflection provider from the previous article.

Read More

Creating an SSIS Custom Task, Part 1

Recently I had the need to create a couple of custom tasks for SQL Server Integration Services (SSIS) at work and I was shocked at how few the resources were for doing this. There are a lot of blogs and articles about creating SSIS custom tasks, but most of them are outdated or wrong. Even Microsoft’s own documentation has clearly been promoted from older versions and is no longer accurate. This leads to a lot of wasted time and scratching of your head trying to figure out what is wrong.

In this series of articles I’m going to demonstrate how to create a custom task for SSIS 2014. This information is also applicable to SSIS 2012 but doesn’t necessarily work with earlier or later versions of SSIS. In this first article we will set up a simple SSIS package that we can use for the remainder of the series.

Read More

Documenting Web APIs

Prerequisite: This post assumes you understand what web APIs are, what they are designed for and how to write them. If not then take a look at this MSDN article first.

In order for web APIs to be useful they need documentation. Unlike traditional APIs there is no function signatures to look at. Even if you know the name of the “function” there is no easy way to get the parameters or return value. Hence documentation is important to anyone wanting to use such an API. If you are writing a REST API then the documentation is technically where the HATEOAS concept comes in. The reality is, for now at least, most people write web APIs using the REST API philosophy but without HATEOAS. Hence documentation is still needed.

The biggest issue with documentation is keeping it in sync with the code. We have XML doc tags for .NET languages and can use them with web API. But to be useful we have to ensure the documentation is refreshed whenever the API changes.  ASP.NET solves this problem by relying on the existing XML doc tags that you’re likely already using. At runtime the documentation is rendered on demand based upon the existing comments. This is one approach to solving the problem. In this article I will take a look at the “built in” functionality, identify when it might not be useful to you and provide an alternative approach that I use.

Read More

WebHooks vs Message Bus

WebHooks are a relatively new concept in ASP.NET but they have been around for a while with other platforms. GitHub, PayPal and even Dropbox support them already. If you are unfamiliar with the concept of a webHook then go read the introduction first. Recently I needed to solve a problem for which WebHooks seemed like a possible solution. This is my journey through that decision process.

Read More

Office 2016 Is Here!! Uninstalled…

When Office 2016 was released the other day I was both surprised and excited. Office 2013 has been around a while and I knew Office 2016 was in development but there was no pre-release warning, it just appeared. In the continual need to always be using the latest stuff I uninstalled Office 2013 and installed 2016. Then the problems began.

Read More

T4 Templates Update for Visual Studio 2015

A while back I posted a series of articles on how to use T4 and a custom VS extension to simplify some common code like application settings, WCF clients and environmental transforms. With the release of Visual Studio 2015 I had to update my own extension and templates so I wanted to posted a follow up article on the changes that need to be made to allow the extension to work with Visual Studio 2015. As part of the update I added some functionality to the app settings template. Before continuing be sure to download the previous version of the series (or simply download the final version below).

Read More

Visual Studio 2015 RC NuGet Package Bug

UPDATE: NuGet Package Manager 3.1 has been released to Visual Studio Gallery. It resolves the issue mentioned here.

For those of you using the Visual Studio 2015 RC/RTM release you should be aware of a bug in the version of NuGet that ships with it. The bug manifests itself when building or debugging a project. When you first start VS the package is fine and you can go to ToolsOptionsNuGet Package Manager and adjust settings. Clearly the package has been successfully loaded. But when you start to build the project (or start to debug which triggers a build check) then VS may report that the package failed to load.

The problem is that NuGet is attempting to update the nuget.config file to a new version and the file is read only causing the package to fail. The file can be read only for a number of reasons but the most likely case is when you are using source control (like TFS) and the file is checked in. The bug has been reported to NuGet and appears to be resolved in future versions.  For now the workaround, if you encounter this issue, is to simply modify the nuget.config file to not be read only (or check the file out of source control) so that the update can succeed.

Using Parallel HttpClientConnection objects in SSIS

In SSIS (SQL Server Integration Service) you often need to talk with web resources like WCF services. To do that you will generally define the connection using Connection Manager and HTTP. This sets up SSIS to communicate with the remote resource. To use the connection you normally use a script task to get the connection from Connection Manager, create an HttpClientConnection object and then use the methods on the connection to communicate with the remote server. You will generally find code similar to the following.

Read More

Creating a Money Type

.NET does not have a type to represent monetary values. In general you will simply use Decimal as it has the necessary accuracy. This has some limitations though:

  • Without looking at surrounding code it is difficult to tell if a variable represents money or simply a large decimal value
  • Currency information is not part of the type so it is possible to incorrectly mix monetary values in systems that support multiple currencies at once
  • Displaying money requires that you use a format string to indicate the currency

There have been many implementations of money in .NET. This is my version. Please note that this code is new so bugs may exist. Additionally I’ve taken the requirements and implementation from my own needs. Your needs may differ so you may need to modify the code to behave differently for your applications.

Read More