Stateless ASP.NET Core Host

What this library does

C3.ServiceFabric.AspNetCore.StatelessHost allows you to host stateless ASP.NET Core services in Service Fabric. The main feature of this library is, that the Service Fabric registration on application startup is optional! This means, you can run/debug your application without ever having to publish it into your local development cluster.

This also means you can keep using tools like dotnet watch, which is a huge productivty boost!

This feature makes this library a perfect fit if you are building a stateless gateway, a stateless Web API or a stateless web frontend!

What if I want to build a stateful ASP.NET Core service?

Have a look at Azure/service-fabric-aspnetcore and the documentation for the official ASP.NET Core hosting projects. They allow you to combine your ASP.NET Core project with all other types of Service Fabric services.

How it works

The library will only try to register itself at the Service Fabric cluster when the command line argument --fabric true is added.

If this parameter is added, the library will create the required FabricRuntime and it will ask Service Fabric for a valid endpoint URL. It will then pass this URL to Kestrel. If --fabric true is not added (or if it is set to something other than true), the library will not alter the URL. This means, you can either use the application with the Kestrel default port (5000) or you can configure your own port.

NOTE: ASP.NET Core apps require Kestrel or WebListener to run in Service Fabric. It is not possible to use IISIntegration with Service Fabric!

How to use the library

The sample projects HttpGateway and HttpService use this library, so please look at them if you need a working example.

Install the package

The package is called C3.ServiceFabric.AspNetCore.StatelessHost and is available on NuGet.org.

Modify your Main() code

To initialize the library, you just have to use the class ServiceFabricWebHostBuilder instead of the default WebHostBuilder when you are building your WebHost. It is required to pass the args parameter to the class in order for it to determine whether or not to attach the application to the Service Fabric cluster.

public static void Main(string[] args)
{
  using (var builder = new ServiceFabricWebHostBuilder(args))
  {
    builder
      .UseKestrel()
      .UseContentRoot(Directory.GetCurrentDirectory())
      .UseStartup<Startup>()
      .Build()
      .Run();
  }
}

Add --fabric true to your ServiceManifest.xml

To enable the Service Fabric registration when you publish your app into Service Fabric, you have to add --fabric true as an argument to your ServiceManifest.xml. This is an example from the HttpService project in this repository:

<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="HttpService" ...>
   <ServiceTypes>
      <StatelessServiceType ServiceTypeName="HttpServiceType" />
   </ServiceTypes>
   <CodePackage Name="Code" Version="1.0.0">
      <EntryPoint>
         <ExeHost>
            <Program>HttpService.exe</Program>
            <Arguments>--fabric true</Arguments>
            <WorkingFolder>CodePackage</WorkingFolder>
            <ConsoleRedirection FileRetentionCount="5" FileMaxSizeInKb="2048" />
         </ExeHost>
      </EntryPoint>
   </CodePackage>
   <Resources>
      <Endpoints>
         <Endpoint Name="HttpServiceTypeEndpoint" Protocol="http" Type="Input" />
      </Endpoints>
   </Resources>
</ServiceManifest>

If Visual Studio keeps changing your ServiceManifest.xml on builds, open the corresponding csproj-file in a text editor and set UpdateServiceFabricManifestEnabled to false. (Re-open your solution afterwards to make sure VS uses the most recent version)

Troubleshooting

On application startup, the library outputs debug information to the console. If you start the application without --fabric true, it should look like this:

ServiceFabricWebHostBuilder: Constructor
RunInServiceFabric: False
ServiceFabricWebHostBuilder: Build
ServiceFabricWebHostBuilder.Build -> returning regular host
Hosting environment: Production
Content root path: C:\some\folder
Now listening on: http://localhost:5000

If you run the application in Service Fabric, you don't see the console output. However, as you can see in the ServiceManifest.xml above, it contains a ConsoleRedirection section. This means, Service Fabric will store all output in a log file.

You can find these log files here: C:\SfDevCluster\Data\_App\_Node_<X>\<ApplicationTypeFolder>\log (look at the Service Fabric Explorer to find the actual node your app is running on)

This should show you an output like this:

ServiceFabricWebHostBuilder: Constructor
RunInServiceFabric: True
FabricRuntime initialized
ServiceFabricWebHostBuilder: Build
ServiceFabricWebHostBuilder -> using SF
UseServiceFabric
UseServiceFabric - ServiceTypeName: HttpServiceType
UseServiceFabric - ServerUrls: 
UseServiceFabric - Assigning SF Url: Http://localhost:32001
ServiceFabricWebHost: Constructor
ServiceFabricWebHost: Start
Hosting environment: Production
Content root path: C:\SfDevCluster\Data\_App\_Node_2\GatewaySampleType_App3\HttpService.Code.1.0.0-local-04161608\
Now listening on: Http://localhost:32001

As you can see, the application successfully obtained an endpoint address from Service Fabric.