Model an application in Service Fabric

This article provides an overview of the Azure Service Fabric application model and how to define an application and service via manifest files.

Understand the application model

An application is a collection of constituent services that perform a certain function or functions. A service performs a complete and standalone function and can start and run independently of other services. A service is composed of code, configuration, and data. For each service, code consists of the executable binaries, configuration consists of service settings that can be loaded at run time, and data consists of arbitrary static data to be consumed by the service. Each component in this hierarchical application model can be versioned and upgraded independently.

The Service Fabric application model

An application type is a categorization of an application and consists of a bundle of service types. A service type is a categorization of a service. The categorization can have different settings and configurations, but the core functionality remains the same. The instances of a service are the different service configuration variations of the same service type.

Classes (or "types") of applications and services are described through XML files (application manifests and service manifests). The manifests are the templates against which applications can be instantiated from the cluster's image store. The schema definition for the ServiceManifest.xml and ApplicationManifest.xml file is installed with the Service Fabric SDK and tools to C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd.

The code for different application instances run as separate processes even when hosted by the same Service Fabric node. Furthermore, the lifecycle of each application instance can be managed (for example, upgraded) independently. The following diagram shows how application types are composed of service types, which in turn are composed of code, configuration, and data packages. To simplify the diagram, only the code/config/data packages for ServiceType4 are shown, though each service type would include some or all those package types.

Service Fabric application types and service types

Two different manifest files are used to describe applications and services: the service manifest and application manifest. Manifests are covered in detail in the following sections.

There can be one or more instances of a service type active in the cluster. For example, stateful service instances, or replicas, achieve high reliability by replicating state between replicas located on different nodes in the cluster. Replication essentially provides redundancy for the service to be available even if one node in a cluster fails. A partitioned service further divides its state (and access patterns to that state) across nodes in the cluster.

The following diagram shows the relationship between applications and service instances, partitions, and replicas.

Partitions and replicas within a service

Tip

You can view the layout of applications in a cluster using the Service Fabric Explorer tool available at http://<yourclusteraddress>:19080/Explorer. For more information, see Visualizing your cluster with Service Fabric Explorer.

Describe a service

The service manifest declaratively defines the service type and version. It specifies service metadata such as service type, health properties, load-balancing metrics, service binaries, and configuration files. Put another way, it describes the code, configuration, and data packages that compose a service package to support one or more service types. Here is a simple example service manifest:

<?xml version="1.0" encoding="utf-8" ?>
<ServiceManifest Name="MyServiceManifest" Version="SvcManifestVersion1" xmlns="http://schemas.microsoft.com/2011/01/fabric" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Description>An example service manifest</Description>
  <ServiceTypes>
    <StatelessServiceType ServiceTypeName="MyServiceType" />
  </ServiceTypes>
  <CodePackage Name="MyCode" Version="CodeVersion1">
    <SetupEntryPoint>
      <ExeHost>
        <Program>MySetup.bat</Program>
      </ExeHost>
    </SetupEntryPoint>
    <EntryPoint>
      <ExeHost>
        <Program>MyServiceHost.exe</Program>
      </ExeHost>
    </EntryPoint>
    <EnvironmentVariables>
      <EnvironmentVariable Name="MyEnvVariable" Value=""/>
      <EnvironmentVariable Name="HttpGatewayPort" Value="19080"/>
    </EnvironmentVariables>
  </CodePackage>
  <ConfigPackage Name="MyConfig" Version="ConfigVersion1" />
  <DataPackage Name="MyData" Version="DataVersion1" />
</ServiceManifest>

Version attributes are unstructured strings and not parsed by the system. Version attributes are used to version each component for upgrades.

ServiceTypes declares what service types are supported by CodePackages in this manifest. When a service is instantiated against one of these service types, all code packages declared in this manifest are activated by running their entry points. The resulting processes are expected to register the supported service types at run time. Service types are declared at the manifest level and not the code package level. So when there are multiple code packages, they are all activated whenever the system looks for any one of the declared service types.

SetupEntryPoint is a privileged entry point that runs with the same credentials as Service Fabric (typically the LocalSystem account) before any other entry point. The executable specified by EntryPoint is typically the long-running service host. The presence of a separate setup entry point avoids having to run the service host with high privileges for extended periods of time. The executable specified by EntryPoint is run after SetupEntryPoint exits successfully. If the process ever terminates or crashes, the resulting process is monitored and restarted (beginning again with SetupEntryPoint).

Typical scenarios for using SetupEntryPoint are when you run an executable before the service starts or you perform an operation with elevated privileges. For example:

  • Setting up and initializing environment variables that the service executable needs. This is not limited to only executables written via the Service Fabric programming models. For example, npm.exe needs some environment variables configured for deploying a node.js application.
  • Setting up access control by installing security certificates.

For more details on how to configure the SetupEntryPoint see Configure the policy for a service setup entry point

EnvironmentVariables provides a list of environment variables that are set for this code package. Environmentment variables can be overridden in the ApplicationManifest.xml to provide different values for different service instances.

DataPackage declares a folder, named by the Name attribute, that contains arbitrary static data to be consumed by the process at run time.

ConfigPackage declares a folder, named by the Name attribute, that contains a Settings.xml file. The settings file contains sections of user-defined, key-value pair settings that the process reads back at run time. During an upgrade, if only the ConfigPackage version has changed, then the running process is not restarted. Instead, a callback notifies the process that configuration settings have changed so they can be reloaded dynamically. Here is an example Settings.xml file:

<Settings xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/2011/01/fabric">
  <Section Name="MyConfigurationSection">
    <Parameter Name="MySettingA" Value="Example1" />
    <Parameter Name="MySettingB" Value="Example2" />
  </Section>
</Settings>

Note

A service manifest can contain multiple code, configuration, and data packages. Each of those can be versioned independently.

Describe an application

The application manifest declaratively describes the application type and version. It specifies service composition metadata such as stable names, partitioning scheme, instance count/replication factor, security/isolation policy, placement constraints, configuration overrides, and constituent service types. The load-balancing domains into which the application is placed are also described.

Thus, an application manifest describes elements at the application level and references one or more service manifests to compose an application type. Here is a simple example application manifest:

<?xml version="1.0" encoding="utf-8" ?>
<ApplicationManifest
      ApplicationTypeName="MyApplicationType"
      ApplicationTypeVersion="AppManifestVersion1"
      xmlns="http://schemas.microsoft.com/2011/01/fabric"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Description>An example application manifest</Description>
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="MyServiceManifest" ServiceManifestVersion="SvcManifestVersion1"/>
    <ConfigOverrides/>
    <EnvironmentOverrides CodePackageRef="MyCode"/>
  </ServiceManifestImport>
  <DefaultServices>
     <Service Name="MyService">
         <StatelessService ServiceTypeName="MyServiceType" InstanceCount="1">
             <SingletonPartition/>
         </StatelessService>
     </Service>
  </DefaultServices>
</ApplicationManifest>

Like service manifests, Version attributes are unstructured strings and are not parsed by the system. Version attributes are also used to version each component for upgrades.

ServiceManifestImport contains references to service manifests that compose this application type. Imported service manifests determine what service types are valid within this application type. Within the ServiceManifestImport, you override configuration values in Settings.xml and environment variables in ServiceManifest.xml files.

DefaultServices declares service instances that are automatically created whenever an application is instantiated against this application type. Default services are just a convenience and behave like normal services in every respect after they have been created. They are upgraded along with any other services in the application instance and can be removed as well.

Note

An application manifest can contain multiple service manifest imports and default services. Each service manifest import can be versioned independently.

To learn how to maintain different application and service parameters for individual environments, see Managing application parameters for multiple environments.

Next steps

Package an application and make it ready to deploy.

Deploy and remove applications describes how to use PowerShell to manage application instances.

Managing application parameters for multiple environments describes how to configure parameters and environment variables for different application instances.

Configure security policies for your application describes how to run services under security policies to restrict access.

Application hosting models describe relationship between replicas (or instances) of a deployed service and service-host process.