Display Authorization properties in Swagger

Another handy extension to Swashbuckle which I have written displays which endpoints have Authorization, and which policies, roles, or users have access to that endpoint.

Authorizaton endpoints

You can get it by installing either my Swashbuckle.Examples or Swashbuckle.AspNetCore.Examples NuGet packages.

Installation instructions etc are at the above links.

Advertisements

Show Swagger documentation on Azure Service Fabric

Another blog post in what seems to be becoming a series of posts on Swagger.

Swashbuckle allows you to include XML comments on your API’s Swagger page. To do this you need to set your Build to output an XML file, which Swashbuckle reads the XML comments from.
Don’t forget to add that XML file to the “Release” build configuration too, otherwise you won’t have XML comments when your application is actually deployed to an environment.

Here’s a handy code snippet for your .NET Core .csproj file:

  <!-- Begin Swagger documentation file-->
  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\net46\win10-x64\swagger.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
    <DocumentationFile>bin\Debug\net46\win10-x64\swagger.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\Release\net46\win10-x64\swagger.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
    <DocumentationFile>bin\Release\net46\win10-x64\swagger.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>
  <!-- End Swagger documentation file-->

Additionally, if your application is deployed on Azure Service Fabric, you will also need to copy the XML file to your PublishDir, with the following snippet in your .csproj:

  <Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">
    <ItemGroup>
      <DocFile Include="bin\x64\$(Configuration)\$(TargetFramework)\win10-x64\*.xml" />
    </ItemGroup>
    <Copy SourceFiles="@(DocFile)" DestinationFolder="$(PublishDir)" SkipUnchangedFiles="false" />
  </Target>

And of course you need to tell Swashbuckle to use that XML file via the .IncludeXmlComments() method mentioned above.

Fix slow NCrunch build

NCrunch is a great unit test runner and has been part of my developer toolbox for many years.

Recently I was having an issue on a medium-sized project where the NCrunch’s Build step was taking almost 2 minutes to complete. That spinning “B” was taking forever!

NCrunch progress

The tests themselves would run in under one minute.

The problem was we use a custom Autofixture [AutoData] attribute on every test.

Our attribute’s constructor creates a TestServer for running the web tests against.
We then inject the test server into each test, i.e.

[Scenario]
[WebHostAutoData]
public void CreateJob_ShouldCreateSuccessfully(
    WebApiClientFixture apiFixture

As it turns out, NCrunch enumerates all test attributes during Analysis, so you should not have any expensive code in your attribute’s constructor.

In my case, I fixed this by introducing a base class for all of my tests, which creates the TestServer (during test run). I then dropped our custom [AutoData] attribute.

Add an upload button to your swagger page

The swagger adventures continue…

In .NET Core the current recommended way to upload a file in ASP.NET is with an IFormFile.

If you’re using an IFormFile in your ASP.NET Web Api like so:

[HttpPost("upload")]
public IActionResult UploadFile(IFormFile file)
{

If you do this, the Swagger page as rendered by Swashbuckle won’t look correct:

However, if you install version 2.5.0 or later of my Swashbuckle.AspNetCore.Examples NuGet package, then you can add the [AddSwaggerFileUploadButton] attribute to your controller action, like so:

[HttpPost("upload")]
[AddSwaggerFileUploadButton]
public IActionResult UploadFile(IFormFile file)
{

and then enable my filter in your Startup.cs:

services.AddSwaggerGen(c =>
{
    c.OperationFilter<AddFileParamTypesOperationFilter>();

Then you’ll get a nice upload button:

Speed up development in a NuGet package-centric solution

As microservices architectures become more popular, so increases usage of NuGet as a way of sharing code amongst separate services. The last few projects I’ve worked on have typically contained a number of “Core” NuGet packages with shared code and interfaces that are consumed by one or more services in the solution. Our build pipeline will publish these NuGet packages to an in-house NuGet server.

This can cause a lot of developer friction when you’re working in one of the services and you decide you need to change one of the Core projects. Typically you’ll

  1. make the change to Core
  2. commit it
  3. (Perhaps raise a PR and wait for approval)
  4. wait for the build to publish new versions of the package
  5. and finally updated the package in your service.

Probably at least 20 min wait for all that to happen. And then you realise that your change didn’t quite work, so you have to go through the cycle again with another change.

Well, here’s a shortcut to that cycle and it’s pretty darn simple. Note that this only works if you’re using the newer .NET Core style .csproj containing <PackageReference>. Simply

  1. make the change in Core and compile it locally
  2. Copy the resulting dll(s) to your local NuGet packages feed folder. NOT the bin folder of your service, or the packages folder of your service. On my machine the local NuGet packages feed folder is C:\Users\matt\.nuget\packages\.

As soon as the dll is copied, Visual Studio detects the change – you don’t need to tell it to update the NuGet packages or even compile!

Another surprise bonus of this – while debugging you can step into the Core code! You don’t need to mess around copying PDBs around or anything. I don’t know how it works, but Visual Studio seems to somehow know that the DLL you’ve copied into the NuGet folder came from your local machine and thus it knows where the source code for it is.

Obviously once you’re happy that your changes to Core are working correctly, then you can can commit them and consume an updated version of the package in your service as usual.

Anyway, hopefully this will speed up your local development as much as it has mine.

How to include Swashbuckle .xml files in your Service Fabric project

If you’re using Swashbuckle’s IncludeXmlComments() option, then your build needs to output an XML file containing the various comments.

By default, the XML file will not be included in your Service Fabric deployment. To get it to work, one way is to add the following section to your Web project’s .csproj:

  <Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">
    <ItemGroup>
      <DocFile Include="bin\x64\$(Configuration)\$(TargetFramework)\win7-x64\*.xml" />
    </ItemGroup>
    <Copy SourceFiles="@(DocFile)" DestinationFolder="$(PublishDir)" SkipUnchangedFiles="false" />
  </Target>

You should also make sure that your xml file is output for all of these different build configurations, again in your Web project’s .csproj:

  
  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\net46\win7-x64\WebHost.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
    <DocumentationFile>bin\Debug\net46\win7-x64\WebHost.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\Release\net46\win7-x64\WebHost.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
    <DocumentationFile>bin\Release\net46\win7-x64\WebHost.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

Thanks to vdevappa’s comment here https://github.com/dotnet/sdk/issues/795#issuecomment-306202030

Run a Service Fabric solution locally without deploying to Service Fabric

This is a similar piece to another post of mine from a few years ago Run a Windows Azure cloud service locally without the Azure compute emulator

So you’re working on a Service Fabric application which has an ASP.NET Web api host project. I find the debugging experience painful, for two reasons:

  1. Time to start debugging the project is a minimum of 45 seconds, every time, because the app gets deployed to a local service fabric cluster which takes forever.
  2. You need to remember to run Visual Studio as administrator in order for the above local deployment to succeed.

If either of these things bug you, then here’s a possible solution. Once we’re done you’ll be able to set the Web project in your solution as the StartUp project instead of the Service Fabric application, for much faster debugging, and you’ll no longer need to run VS as admin.

First, change the Program.cs in the Web project:

private static void Main()
{
	if (UseServiceFabric())
	{
		StartServiceFabric();
	}
	else
	{
		StartWebHost();
	}
}

private static bool UseServiceFabric()
{
	var webHostBuilder = new WebHostBuilder();
	var environment = webHostBuilder.GetSetting("environment");

	return environment != "Development";
}

private static void StartWebHost()
{
	var builder = new WebHostBuilder()
		.UseKestrel()
		.UseContentRoot(Directory.GetCurrentDirectory())
		.UseStartup<Startup>();

	var host = builder.Build();
	host.Run();
}

private static void StartServiceFabric()
{
	try
	{
		// The ServiceManifest.XML file defines one or more service type names.
		// Registering a service maps a service type name to a .NET type.
		// When Service Fabric creates an instance of this service type,
		// an instance of the class is created in this host process.

		ServiceRuntime.RegisterServiceAsync("Web1Type",
			context => new WebHost(context)).GetAwaiter().GetResult();

		ServiceEventSource.Current.ServiceTypeRegistered(Process.GetCurrentProcess().Id, typeof(Web1).Name);

		// Prevents this host process from terminating so services keeps running. 
		Thread.Sleep(Timeout.Infinite);
	}
	catch (Exception e)
	{
		ServiceEventSource.Current.ServiceHostInitializationFailed(e.ToString());
		throw;
	}
}

If the ASPNETCORE_ENVIRONMENT setting is Development, then it won’t use Service Fabric at all and will just use a plain ol’ ASP.NET Core WebHostBuilder to start the web host.

You’ll also need to change your Debug target to be the Web project, instead of IISExpress, via the VS Standard toolbar.

And just like that the app startup time has shrunk from around 40 seconds to around 5 seconds. Or from an unbearable 100 seconds for the application the team I just joined is working on.