Repository navigation
Understanding Local Runtime
Local Runtime (LR) (also could be mentioned as local runtime) is an emulation of Service Fabric Runtime (SRF) created to improve development experience by allowing developers to run service without deploying it to Service Fabric Cluster. Because local runtime is an emulation of SRF it doesn't support such features like: scaling, partitioning, routing, ..., etc. Instead of this it's features are focused on emulating environment required to successfully run single replica.
On startup local runtime looks for ServiceManifest.xml file inside PackageRoot directory. The search starts from the location of service entry assembly and moves up until it finds PackageRoot/ServiceManifest.xml.
This critical step makes an assumption of project's directory structure. This is quite safe because because typical Service Fabric service project has the following structure:
Root/
| bin/
| | Debug/
| | | netcoreapp2.2/
| | | | Service.dll <-- service's binary
| PackageRoot/
| | ServiceManifest.xml
| | Code/
| | | <-- empty
| | Config/
| | | Settings.xml
| | Data/
| | | Data-Sample.xml
When ServiceManifest.xml is found local runtime reads information about service types, configuration packages, data packages and endpoints. Information about code package isn't read from ServiceManifest.xml and is populated automatically. In addition to information stored inside ServiceManifest.xml local runtime also reads all Settings.xml files within identified configuration packages. All this information is then transformed and made accessible through standard SF classes and interfaces.
To better understand how it works let's use the above directory structure with the following ServiceManifest.xml and Config/Settings.xml files and see what information is made accessible by local runtime through SF classes and interfaces:
ServiceManifest.xml
<ServiceManifest Name="ServicePkg" Version="1.0.0">
<ServiceTypes>
<StatelessServiceType ServiceTypeName="ServiceType" />
</ServiceTypes>
<ConfigPackage Name="Config" Version="1.0.0" />
<DataPackage Name="Data" Version="1.0.0"/>
<Resources>
<Endpoints>
<Endpoint
Name="ServiceEndpoint"
Protocol="http"
UriScheme="http"
Port="5000"
CodePackageRef="Code"
Type="Input" />
</Endpoints>
</Resources>
</ServiceManifest>Config/Settings.xml
<Settings>
<Section Name="Test">
<Parameter Name="TestParam" Value="TestParamValue" />
</Section>
</Settings>All information read from PackageRoot is made accessible through ICodePackageActivationContext:
public interface ICodePackageActivationContext
{
// Package events and Health reporting are not supported and omitted
string WorkDirectory { get; }
// <-- "<user temp>\4da77362-897d-4806-ad10-9fec72209402\Temp"
string LogDirectory { get; }
// <-- "<user temp>\4da77362-897d-4806-ad10-9fec72209402\Log"
string TempDirectory { get; }
// <-- "<user temp>\4da77362-897d-4806-ad10-9fec72209402\Temp"
string ContextId { get; }
// <-- "4da77362-897d-4806-ad10-9fec72209402"
string CodePackageName { get; }
// <-- "Code"
string CodePackageVersion { get; }
// <-- "1.0.0"
string ApplicationName { get; }
// <-- "fabric:/ApplicationName"
string ApplicationTypeName { get; }
// <-- "ApplicationTypeName"
string GetServiceManifestName();
// <-- "ServicePkg"
string GetServiceManifestVersion();
// <-- "1.0.0"
IList<string> GetCodePackageNames();
// <-- ["Code"]
IList<string> GetConfigurationPackageNames();
// <-- ["Config"]
IList<string> GetDataPackageNames();
// <-- ["Data"]
KeyedCollection<string, ServiceTypeDescription> GetServiceTypes();
// <--
// :: key = "ServiceType"
// [
// ServiceTypeName : "ServiceType",
// ServiceTypeKind : Stateless
// ]
KeyedCollection<string, ServiceGroupTypeDescription> GetServiceGroupTypes();
// <-- null
EndpointResourceDescription GetEndpoint(string endpointName);
KeyedCollection<string, EndpointResourceDescription> GetEndpoints();
// <--
// :: key = "ServiceEndpoint"
// [
// Name : "ServiceType",
// CodePackageName : Stateless
// Protocol : Http
// EndpointType : Input
// Port : 5000
// ]
CodePackage GetCodePackageObject(string packageName);
// <--
// [
// Path : "Root/bin/Debug/netcoreapp2.2"
// Description
// | Name : "Code"
// | ServiceManifestName : "ServicePkg"
// | ServiceManifestVersion : "1.0.0"
// ]
ConfigurationPackage GetConfigurationPackageObject(string packageName);
// <--
// [
// Path : "Root/PackageRoot/Config"
// Description
// | Name : "Config"
// | ServiceManifestName : "ServicePkg"
// | ServiceManifestVersion : "1.0.0"
// Settings
// | Sections
// | | [
// | | Name : "Test"
// | | Parameters
// | | | [
// | | | Name : "TestParam"
// | | | Value : "TestParamValue"
// | | | ]
// | | ]
// ]
DataPackage GetDataPackageObject(string packageName);
// <--
// [
// Path : "Root/PackageRoot/Data"
// Description
// | Name : "Data"
// | ServiceManifestName : "ServicePkg"
// | ServiceManifestVersion : "1.0.0"
// ]
ApplicationPrincipalsDescription GetApplicationPrincipals();
// <-- new ApplicationPrincipalsDescription()
}Because most of the information returned by ICodePackageActivationContext is read from PackageRoot directory it allows both "access settings" and "access data" scenarios as if the service was deployed to SFC:
...
var configurationPackage =
codePackageActivationContext.GetConfigurationPackageObject("Config");
var configurationValue =
configurationPackage.Settings.Sections["Test"].Parameters["TestParam"].Value;
// configurationValue == "TestParamValue"
var dataPackage =
codePackageActivationContext.GetDataPackageObject("Data");
foreach (var fileName in Directory.EnumerateFileSystemEntries(dataPackage.Path))
{
// fileName == Root/PackageRoot/Data/Data-Sample.xml
}
...Information about current node is accessible through NodeContext:
public sealed class NodeContext
{
public string NodeName { get; }
// <-- "<machine name>"
public string IPAddressOrFQDN { get; }
// <-- "<machine name>"
public NodeId NodeId { get; }
// <-- 10000000000000000
public BigInteger NodeInstanceId { get; }
// <-- 1
public string NodeType { get; }
// <-- "<machine name>"
}On top of NodeContext and ICodePackageActivationContext contexts local runtime initializes an instances of ServiceContext:
public class ServiceContext
{
public NodeContext NodeContext { get; }
// <-- instance of NodeContext (see above)
public ICodePackageActivationContext CodePackageActivationContext { get; }
// <-- instance of ICodePackageActivationContext (see above)
public string ServiceName { get; }
// <-- $"fabric:/ApplicationName/ServiceType-1"
public string ServiceTypeName { get; }
// <-- "ServiceType"
public string PartitionId { get; }
// <-- "91322e39-b3ab-4d3b-a27c-3a06f0d44696"
public string ListenAddress { get; }
// <-- "<machine name>"
public string PublishAddress { get; }
// <-- "<machine name>"
public string ReplicaOrInstanceId { get; }
// <-- 1
public string TraceId { get; }
// <-- {91322e39-b3ab-4d3b-a27c-3a06f0d44696}:1
}... and also initializes a set of SF specific environment variables:
Fabric_NodeId = 10000000000000000
Fabric_NodeName = <machine name>
Fabric_NodeIPOrFQDN = <machine name>
Fabric_IsContainerHost = False
Fabric_ApplicationName = fabric:/ApplicationName
Fabric_ServiceName = fabric:/ApplicationName/ServiceType-1
Fabric_ServicePackageActivationId = 4da77362-897d-4806-ad10-9fec72209402
Fabric_CodePackageName = Code
Fabric_Folder_App_Log = <user temp>\4da77362-897d-4806-ad10-9fec72209402\Log
Fabric_Folder_App_Temp = <user temp>\4da77362-897d-4806-ad10-9fec72209402\Temp
Fabric_Folder_App_Work = <user temp>\4da77362-897d-4806-ad10-9fec72209402\Work
Fabric_Endpoint_ServiceEndpoint = 0
NOTE
The complete list of environment variables can be found here
When all these contexts are initialized local runtime creates service replica and executes it's Startup life-cycle routine (you can find more information about Startup routines of Stateless and Stateful services here and here correspondingly).
Starting from this point service replica is initialized and ready to process user requests.
Here is a list of environment variables to configure local runtime:
CS_EHSF_RUNTIME
-
Default- instructs infrastructure to use default runtime (Service Fabric runtime) -
Local- instructs infrastructure to use local runtime
Here is what you can do with local runtime:
- Debug & Test stateless services with one or more aspnetcore listeners
- Make use of configuration and data packages
Because local runtime is just an emulation of SFR it has the following limitations:
- stateful services aren't supported
- remoting listeners aren't supported
-
Fabric_ServicePackageNameandFabric_Folder_Applicationenvironment variables aren't initialized
- Sample application where you can try and see local runtime features when debugging application using Visual Studio.
(c) 2021 Coherent Solutions Inc.
GENERAL
GETTING STARTED
UNDERSTANDING THE PROJECT
SAMPLES