Create your first Azure Service Fabric application

The Service Fabric SDK includes an add-in for Visual Studio that provides templates and tools for creating, deploying, and debugging Service Fabric applications. This topic walks you through the process of creating your first application in Visual Studio 2017 or Visual Studio 2015.

Prerequisites

Before you get started, make sure that you have set up your development environment.

Video walkthrough

The following video walks through the steps in this tutorial:

Create the application

A Service Fabric application can contain one or more services, each with a specific role in delivering the application's functionality. Create an application project, along with your first service project, using the New Project wizard. You can also add more services later if you want.

  1. Launch Visual Studio as an administrator.
  2. Click File > New Project > Cloud > Service Fabric Application.
  3. Name the application and click OK.

    New project dialog in Visual Studio

  4. On the next page, choose Stateful as the first service type to include in your application. Name it and click OK.

    New service dialog in Visual Studio

    Note

    For more information about the options, see Service Fabric programming model overview.

    Visual Studio creates the application project and the stateful service project and displays them in Solution Explorer.

    Solution Explorer following creation of application with stateful service

    The application project does not contain any code directly. Instead, it references a set of service projects. In addition, it contains three other types of content:

    • Publish profiles: Used to manage tooling preferences for different environments.
    • Scripts: Includes a PowerShell script for deploying/upgrading your application. Visual Studio uses the script behind-the-scenes. The script can also be invoked directly at the command line.
    • Application definition: Includes the application manifest under ApplicationPackageRoot. Associated application parameter files are under ApplicationParameters, which define the application and allow you to configure it specifically for a given environment.

      For an overview of the contents of the service project, see Getting started with Reliable Services.

Deploy and debug the application

Now that you have an application, try running it.

  1. Press F5 in Visual Studio to deploy the application for debugging.

    Note

    Deploying takes a while the first time, as Visual Studio is creating a local cluster for development. A local cluster runs the same platform code that you build on in a multi-machine cluster, just on a single machine. The cluster creation status displays in the Visual Studio output window.

    When the cluster is ready, you get a notification from the local cluster system tray manager application included with the SDK.

    Local cluster system tray notification

  2. Once the application starts, Visual Studio automatically brings up the Diagnostics Event Viewer, where you can see trace output from the service.

    Diagnostic events viewer

    In the case of the stateful service template, the messages simply show the counter value incrementing in the RunAsync method of MyStatefulService.cs.

  3. Expand one of the events to see more details, including the node where the code is running. In this case, it is _Node_2, though it may differ on your machine.

    Diagnostic events viewer detail

    The local cluster contains five nodes hosted on a single machine. It mimics a five-node cluster, where nodes are on distinct machines. To simulate the loss of a machine while exercising the Visual Studio debugger at the same time, let's take down one of the nodes on the local cluster.

    Note

    The application diagnostic events emitted by the project template use the included ServiceEventSource class. For more information, see How to monitor and diagnose services locally.

  4. Find the class in your service project that derives from StatefulService (for example, MyStatefulService) and set a breakpoint on the first line of the RunAsync method.

    Breakpoint in stateful service RunAsync method

  5. To launch Service Fabric Explorer, right-click the Local Cluster Manager system tray app and choose Manage Local Cluster.

    Launch Service Fabric Explorer from the Local Cluster Manager

    Service Fabric Explorer offers a visual representation of a cluster--including the set of applications deployed to it and the set of physical nodes that make it up. To learn more about Service Fabric Explorer, see Visualizing your cluster.

  6. In the left pane, expand Cluster > Nodes and find the node where your code is running.
  7. Click Actions > Deactivate (Restart) to simulate a machine restarting. Or, deactivate the node from the node list view in the left pane.)

    Stop a node in Service Fabric Explorer

    Momentarily, you should see your breakpoint hit in Visual Studio as the computation you were doing on one node seamlessly fails over to another.

  8. Return to the Diagnostic Events Viewer and observe the messages. The counter has continued incrementing, even though the events are actually coming from a different node.

    Diagnostic events viewer after failover

Switch cluster mode

By default, the local development cluster is configured to run as a five-node cluster, which is useful for debugging services deployed across multiple nodes. Deploying an application to the five-node development cluster can take some time, however. If you want to iterate code changes quickly, without running your app on five nodes, switch the development cluster to one-node mode. To run your code on a cluster with one node, right-click on the Local Cluster Manager in the system tray and select Switch Cluster Mode -> 1 Node.

Switch cluster mode

The development cluster resets when you change cluster mode and all applications provisioned or running on the cluster are removed.

You can also change the cluster mode using PowerShell:

  1. Launch a new PowerShell window as an administrator.
  2. Run the cluster setup script from the SDK folder:

     & "$ENV:ProgramFiles\Microsoft SDKs\Service Fabric\ClusterSetup\DevClusterSetup.ps1" -CreateOneNodeCluster
    

    Cluster setup takes a few moments. After setup is finished, you should see output similar to:

    Cluster setup output

Cleaning up

Before wrapping up, it's important to remember that the local cluster is real. Stopping the debugger removes your application instance and unregisters the application type. The cluster continues to run in the background, however. You have several options to manage the cluster:

  1. To shut down the cluster but keep the application data and traces, click Stop Local Cluster in the system tray app.
  2. To delete the cluster entirely, click Remove Local Cluster in the system tray app. This option will result in another slow deployment the next time you press F5 in Visual Studio. Delete the cluster only if you don't intend to use the local cluster for some time or if you need to reclaim resources.

Next steps