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.
Before you get started, make sure that you have set up your development environment.
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.
- Launch Visual Studio as an administrator.
- Click File > New Project > Cloud > Service Fabric Application.
Name the application and click OK.
On the next page, choose Stateful as the first service type to include in your application. Name it and click OK.
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.
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.
Press F5 in Visual Studio to deploy the application for debugging.
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.
Once the application starts, Visual Studio automatically brings up the Diagnostics Event Viewer, where you can see trace output from the service.
In the case of the stateful service template, the messages simply show the counter value incrementing in the
RunAsyncmethod of MyStatefulService.cs.
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.
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.
The application diagnostic events emitted by the project template use the included
ServiceEventSourceclass. For more information, see How to monitor and diagnose services locally.
Find the class in your service project that derives from StatefulService (for example, MyStatefulService) and set a breakpoint on the first line of the
To launch Service Fabric Explorer, right-click the Local Cluster Manager system tray app and choose Manage Local Cluster.
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.
- In the left pane, expand Cluster > Nodes and find the node where your code is running.
Click Actions > Deactivate (Restart) to simulate a machine restarting. Or, deactivate the node from the node list view in the left pane.)
Momentarily, you should see your breakpoint hit in Visual Studio as the computation you were doing on one node seamlessly fails over to another.
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.
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.
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:
- Launch a new PowerShell window as an administrator.
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:
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:
- To shut down the cluster but keep the application data and traces, click Stop Local Cluster in the system tray app.
- 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.
- Learn how to create a cluster in Azure or a standalone cluster on Windows.
- Try creating a service using the Reliable Services or Reliable Actors programming models.
- Try deploying a Windows container or an existing app as a guest executable.
- Learn how to expose your services to the Internet with a web service front end.
- Walk through a hands-on-lab and create a stateless service, configure monitoring and health reports, and perform an application upgrade.
- Learn about Service Fabric support options