Service Fabric-Anwendungs- und -DienstmanifesteService Fabric application and service manifests

In diesem Artikel wird beschrieben, wie Service Fabric-Anwendungen und -Dienste mit den Dateien „ApplicationManifest.xml“ und „ServiceManifest.xml“ definiert und mit Versionsangaben versehen werden.This article describes how Service Fabric applications and services are defined and versioned using the ApplicationManifest.xml and ServiceManifest.xml files. Ausführlichere Beispiele finden Sie unter Beispiele für Anwendungs- und Dienstmanifeste.For more detailed examples, see application and service manifest examples. Eine Dokumentation des XML-Schemas für diese Manifestdateien finden Sie unter ServiceFabricServiceModel.xsd – Schemadokumentation.The XML schema for these manifest files is documented in ServiceFabricServiceModel.xsd schema documentation.

Warnung

Das XML-Dateischema des Manifests erzwingt die richtige Reihenfolge der untergeordneten Elemente.The manifest XML file schema enforces correct ordering of child elements. Öffnen Sie als teilweise Problemumgehung „C: \Programme\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd“ in Visual Studio, während Sie eines der Manifeste von Service Fabric erstellen oder ändern.As a partial workaround, open "C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd" in Visual Studio while authoring or modifying any of the Service Fabric manifests. Auf diese Weise können Sie die Reihenfolge der untergeordneten Elemente überprüfen und IntelliSense nutzen.This will allow you to check the ordering of child elements and provides intelli-sense.

Beschreiben eines Diensts in der Datei „ServiceManifest.xml“Describe a service in ServiceManifest.xml

Das Dienstmanifest definiert deklarativ der Diensttyp und die Version.The service manifest declaratively defines the service type and version. Es legt Dienstmetadaten wie Diensttyp, Integritätseigenschaften, Lastenausgleichsmetriken, Dienstbinärdateien und Konfigurationsdateien fest.It specifies service metadata such as service type, health properties, load-balancing metrics, service binaries, and configuration files. Anders ausgedrückt: Es beschreibt den Code, die Konfiguration und die Datenpakete, die ein Dienstpaket bilden, mit dem ein oder mehrere Diensttypen unterstützt werden.Put another way, it describes the code, configuration, and data packages that compose a service package to support one or more service types. Ein Dienstmanifest kann mehrere Code-, Konfigurations- und Datenpakete enthalten, die unabhängig voneinander mit Versionsangaben versehen werden können.A service manifest can contain multiple code, configuration, and data packages, which can be versioned independently. Hier ist ein Dienstmanifest für den ASP.NET Core-Web-Front-End-Dienst der Voting-Beispielanwendung angegeben (und hier einige ausführlichere Beispiele):Here is a service manifest for the ASP.NET Core web front-end service of the Voting sample application (and here are some more detailed examples):

<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="VotingWebPkg"
                 Version="1.0.0"
                 xmlns="http://schemas.microsoft.com/2011/01/fabric"
                 xmlns:xsd="https://www.w3.org/2001/XMLSchema"
                 xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
  <ServiceTypes>
    <!-- This is the name of your ServiceType. 
         This name must match the string used in RegisterServiceType call in Program.cs. -->
    <StatelessServiceType ServiceTypeName="VotingWebType" />
  </ServiceTypes>

  <!-- Code package is your service executable. -->
  <CodePackage Name="Code" Version="1.0.0">
    <EntryPoint>
      <ExeHost>
        <Program>VotingWeb.exe</Program>
        <WorkingFolder>CodePackage</WorkingFolder>
      </ExeHost>
    </EntryPoint>
  </CodePackage>

  <!-- Config package is the contents of the Config directory under PackageRoot that contains an 
       independently-updateable and versioned set of custom configuration settings for your service. -->
  <ConfigPackage Name="Config" Version="1.0.0" />

  <Resources>
    <Endpoints>
      <!-- This endpoint is used by the communication listener to obtain the port on which to 
           listen. Please note that if your service is partitioned, this port is shared with 
           replicas of different partitions that are placed in your code. -->
      <Endpoint Protocol="http" Name="ServiceEndpoint" Type="Input" Port="8080" />
    </Endpoints>
  </Resources>
</ServiceManifest>

Version -Attribute sind unstrukturierte Zeichenfolgen und werden im System nicht analysiert.Version attributes are unstructured strings and not parsed by the system. Version-Attribute werden dazu verwendet, jede Komponente für Upgrades mit Versionsangaben zu versehen.Version attributes are used to version each component for upgrades.

ServiceTypes deklariert, welche Diensttypen von CodePackages in diesem Manifest unterstützt werden.ServiceTypes declares what service types are supported by CodePackages in this manifest. Wenn ein Dienst mit einem dieser Diensttypen instanziiert wird, werden alle Codepakete, die in diesem Manifest deklariert sind, durch Ausführen ihrer Einstiegspunkte aktiviert.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. Die resultierenden Prozesse registrieren die unterstützten Diensttypen zur Laufzeit.The resulting processes are expected to register the supported service types at run time. Diensttypen werden auf Ebene der Manifeste und nicht auf Ebene der Codepakete deklariert.Service types are declared at the manifest level and not the code package level. Wenn mehrere Codepakete vorhanden sind, werden sie daher alle aktiviert, wenn im System nach einem der deklarierten Diensttypen gesucht wird.So when there are multiple code packages, they are all activated whenever the system looks for any one of the declared service types.

Die durch EntryPoint angegebene ausführbare Datei ist üblicherweise der Diensthost mit langer Ausführungsdauer.The executable specified by EntryPoint is typically the long-running service host. SetupEntryPoint ist ein privilegierter Einstiegspunkt, der mit den gleichen Anmeldeinformationen wie Service Fabric (i.d.R. dem LocalSystem-Konto) vor jedem anderen Einstiegspunkt ausgeführt wird.SetupEntryPoint is a privileged entry point that runs with the same credentials as Service Fabric (typically the LocalSystem account) before any other entry point. Das Vorhandensein eines separaten Setupeinstiegspunkts vermeidet, dass der Diensthost über längere Zeiträume mit hohen Berechtigungen ausgeführt werden muss.The presence of a separate setup entry point avoids having to run the service host with high privileges for extended periods of time. Die von EntryPoint angegebene ausführbare Datei wird ausgeführt, nachdem SetupEntryPoint erfolgreich beendet wurde.The executable specified by EntryPoint is run after SetupEntryPoint exits successfully. Wenn der Prozess beendet wird oder abstürzt, wird der resultierende Prozess überwacht und neu gestartet (er beginnt wieder mit SetupEntryPoint).If the process ever terminates or crashes, the resulting process is monitored and restarted (beginning again with SetupEntryPoint).

Gängige Szenarios für die Verwendung von SetupEntryPoint sind die Ausführung einer ausführbaren Datei vor dem Starten des Diensts sowie die Ausführung eines Vorgangs mit erhöhten Rechten.Typical scenarios for using SetupEntryPoint are when you run an executable before the service starts or you perform an operation with elevated privileges. Beispiel:For example:

  • Einrichten und Initialisieren von Umgebungsvariablen, die die ausführbare Datei des Diensts benötigt.Setting up and initializing environment variables that the service executable needs. Dies ist nicht auf Dateien beschränkt, die mit den Service Fabric-Programmiermodellen geschrieben wurden.This is not limited to only executables written via the Service Fabric programming models. „npm.exe“ benötigt beispielsweise einige Umgebungsvariablen, die zum Bereitstellen einer node.js-Anwendung konfiguriert wurden.For example, npm.exe needs some environment variables configured for deploying a node.js application.
  • Einrichten einer Zugriffssteuerung durch Installieren von Sicherheitszertifikaten.Setting up access control by installing security certificates.

Weitere Informationen zum Konfigurieren von SetupEntryPoint finden Sie unter Konfigurieren der Richtlinie für einen Setupeinstiegspunkt für Dienste.For more information on how to configure the SetupEntryPoint, see Configure the policy for a service setup entry point

EnvironmentVariables (im vorhergehenden Beispiel nicht festgelegt) enthält eine Liste von Umgebungsvariablen, die für dieses Codepaket festgelegt wurden.EnvironmentVariables (not set in the preceding example) provides a list of environment variables that are set for this code package. Umgebungsvariablen können in ApplicationManifest.xml überschrieben werden, um unterschiedliche Werte für verschiedene Dienstinstanzen bereitzustellen.Environment variables can be overridden in the ApplicationManifest.xml to provide different values for different service instances.

DataPackage (im vorhergehenden Beispiel nicht festgelegt) deklariert einen Ordner, der durch das Name-Attribut benannt wird und beliebige statische Daten enthält, die zur Laufzeit vom Prozess verarbeitet werden sollen.DataPackage (not set in the preceding example) declares a folder, named by the Name attribute, that contains arbitrary static data to be consumed by the process at run time.

ConfigPackage deklariert einen Ordner, der durch das Name-Attribut benannt wird und die Datei Settings.xml enthält.ConfigPackage declares a folder, named by the Name attribute, that contains a Settings.xml file. Diese Einstellungsdatei enthält Abschnitte mit benutzerdefinierten Einstellungen für Schlüssel-Wert-Paare, die der Prozess zur Laufzeit einliest.The settings file contains sections of user-defined, key-value pair settings that the process reads back at run time. Wenn sich während eines Upgrades nur die Version von ConfigPackage geändert hat, wird der ausgeführte Prozess nicht neu gestartet.During an upgrade, if only the ConfigPackage version has changed, then the running process is not restarted. Stattdessen benachrichtigt ein Rückruf den Prozess, dass sich Konfigurationseinstellungen geändert haben, sodass sie dynamisch neu geladen werden können.Instead, a callback notifies the process that configuration settings have changed so they can be reloaded dynamically. Hier ein Beispiel der Datei Settings.xml :Here is an example Settings.xml file:

<Settings xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://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>

Ein Service Fabric-Dienstendpunkt ist ein Beispiel für eine Service Fabric-Ressource.A Service Fabric Service Endpoint is an example of a Service Fabric Resource. Eine Service Fabric-Ressource kann deklariert/geändert werden, ohne dass der kompilierte Code geändert wird.A Service Fabric Resource can be declared/changed without changing the compiled code. Der Zugriff auf die im Dienstmanifest angegebenen Service Fabric-Ressourcen kann über das SecurityGroup-Element im Anwendungsmanifest gesteuert werden.Access to the Service Fabric Resources that are specified in the service manifest can be controlled through the SecurityGroup in the application manifest. Wenn eine Endpunktressource im Dienstmanifest definiert wird, weist Service Fabric Ports aus dem Bereich der reservierten Anwendungsports zu, sofern nicht explizit ein Port angegeben wird.When an Endpoint Resource is defined in the service manifest, Service Fabric assigns ports from the reserved application port range when a port isn't specified explicitly. Erfahren Sie mehr über das Angeben oder Überschreiben von Endpunktressourcen.Read more about specifying or overriding endpoint resources.

Warnung

Statische Ports sollten sich nicht mit dem im Clustermanifest angegebenen Anwendungsportbereich überschneiden.By design static ports should not overlap with application port range specified in the ClusterManifest. Wenn Sie einen statischen Port angeben, weisen Sie ihn außerhalb des Anwendungsportbereichs zu, andernfalls führt dies zu Portkonflikten.If you specify a static port, assign it outside of application port range, otherwise it will result in port conflicts. Mit Release 6.5CU2 werden wir eine Integritätswarnung ausgeben, wenn wir einen solchen Konflikt erkennen, aber die Bereitstellung in Übereinstimmung mit dem ausgelieferten 6.5-Verhalten fortsetzen.With release 6.5CU2 we will issue a Health Warning when we detect such a conflict but let the deployment continue in sync with the shipped 6.5 behaviour. Es ist jedoch möglich, dass wir die Anwendungsbereitstellung ab den nächsten Hauptversionen unterbinden.However, we may prevent the application deployment from the next major releases.

Beschreiben einer Anwendung in der Datei „ApplicationManifest.xml“Describe an application in ApplicationManifest.xml

Das Anwendungsmanifest beschreibt deklarativ den Typ und die Version der Anwendung.The application manifest declaratively describes the application type and version. Es gibt Dienstzusammensetzungs-Metadaten wie z. B. dauerhafte Namen, Partitionierungsschema, Anzahl der Instanzen/Replikationsfaktor, Richtlinie für Sicherheit/Isolation, Platzierungseinschränkungen, Konfigurationsüberschreibungen und zugehörige Diensttypen an.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. Zudem werden die Lastenausgleichsdomänen beschrieben, in denen die Anwendung eingefügt wird.The load-balancing domains into which the application is placed are also described.

Somit beschreibt ein Anwendungsmanifest Elemente auf Anwendungsebene, verweist auf ein oder mehrere Dienstmanifeste und bildet so einen Anwendungstyp.Thus, an application manifest describes elements at the application level and references one or more service manifests to compose an application type. Hier ist das Anwendungsmanifest für die Beispielanwendung „Voting“ angegeben (und hier einige ausführlichere Beispiele):Here is the application manifest for the Voting sample application (and here are some more detailed examples):

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" ApplicationTypeName="VotingType" ApplicationTypeVersion="1.0.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">
  <Parameters>
    <Parameter Name="VotingData_MinReplicaSetSize" DefaultValue="3" />
    <Parameter Name="VotingData_PartitionCount" DefaultValue="1" />
    <Parameter Name="VotingData_TargetReplicaSetSize" DefaultValue="3" />
    <Parameter Name="VotingWeb_InstanceCount" DefaultValue="-1" />
  </Parameters>
  <!-- Import the ServiceManifest from the ServicePackage. The ServiceManifestName and ServiceManifestVersion 
       should match the Name and Version attributes of the ServiceManifest element defined in the 
       ServiceManifest.xml file. -->
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="VotingDataPkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
  </ServiceManifestImport>
  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="VotingWebPkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
  </ServiceManifestImport>
  <DefaultServices>
    <!-- The section below creates instances of service types, when an instance of this 
         application type is created. You can also create one or more instances of service type using the 
         ServiceFabric PowerShell module.
         
         The attribute ServiceTypeName below must match the name defined in the imported ServiceManifest.xml file. -->
    <Service Name="VotingData">
      <StatefulService ServiceTypeName="VotingDataType" TargetReplicaSetSize="[VotingData_TargetReplicaSetSize]" MinReplicaSetSize="[VotingData_MinReplicaSetSize]">
        <UniformInt64Partition PartitionCount="[VotingData_PartitionCount]" LowKey="0" HighKey="25" />
      </StatefulService>
    </Service>
    <Service Name="VotingWeb" ServicePackageActivationMode="ExclusiveProcess">
      <StatelessService ServiceTypeName="VotingWebType" InstanceCount="[VotingWeb_InstanceCount]">
        <SingletonPartition />
         <PlacementConstraints>(NodeType==NodeType0)</PlacementConstraints
      </StatelessService>
    </Service>
  </DefaultServices>
</ApplicationManifest>

Wie bei Dienstmanifesten sind Version -Attribute unstrukturierte Zeichenfolgen, die im System nicht analysiert werden.Like service manifests, Version attributes are unstructured strings and are not parsed by the system. Version-Attribute werden zudem dazu verwendet, jede Komponente für Upgrades mit Versionsangaben zu versehen.Version attributes are also used to version each component for upgrades.

Parameter definiert die im gesamten Anwendungsmanifest verwendeten Parameter.Parameters defines the parameters used throughout the application manifest. Die Werte dieser Parameter können angegeben werden, wenn die Anwendung instanziiert wird, und sie können die Anwendungs- oder Dienstkonfigurationseinstellungen außer Kraft setzen.The values of these parameters can be supplied when the application is instantiated and can override application or service configuration settings. Der Standardparameterwert wird verwendet, wenn der Wert nicht bei der Anwendungsinstanziierung geändert wird.The default parameter value is used if the value is not changed during application instantiation. Weitere Informationen zum Verwalten verschiedener Anwendungs- und Dienstparameter für einzelne Umgebungen finden Sie unter Verwalten von Anwendungsparametern für mehrere Umgebungen.To learn how to maintain different application and service parameters for individual environments, see Managing application parameters for multiple environments.

ServiceManifestImport enthält Verweise auf Dienstmanifeste zum Erstellen des entsprechenden Anwendungstyps.ServiceManifestImport contains references to service manifests that compose this application type. Ein Anwendungsmanifest kann mehrere Dienstmanifestimporte enthalten, die jeweils unabhängig voneinander mit Versionsangaben versehen werden können.An application manifest can contain multiple service manifest imports, each one can be versioned independently. Importierte Dienstmanifeste legen fest, welche Diensttypen innerhalb des Anwendungstyps gültig sind.Imported service manifests determine what service types are valid within this application type. In ServiceManifestImport überschreiben Sie Konfigurationswerte in „Settings.xml“ und Umgebungsvariablen in „ServiceManifest.xml“.Within the ServiceManifestImport, you override configuration values in Settings.xml and environment variables in ServiceManifest.xml files. Richtlinien (im vorhergehenden Beispiel nicht festgelegt) für die Endpunktbindung, für Sicherheit und Zugriff sowie für die Paketfreigabe können in importierten Dienstmanifesten festgelegt werden.Policies (not set in the preceding example) for end-point binding, security and access, and package sharing can be set on imported service manifests. Weitere Informationen finden Sie unter Konfigurieren von Sicherheitsrichtlinien für Ihre Anwendung.For more information, see Configure security policies for your application.

DefaultServices deklariert Dienstinstanzen, die automatisch erstellt werden, wenn eine Anwendung mit diesem Anwendungstyp instanziiert wird.DefaultServices declares service instances that are automatically created whenever an application is instantiated against this application type. Standarddienste dienen lediglich der Benutzerfreundlichkeit und verhalten sich nach der Erstellung in jeder Hinsicht wie normale Dienste.Default services are just a convenience and behave like normal services in every respect after they have been created. Sie werden zusammen mit allen anderen Diensten in der Anwendungsinstanz aktualisiert und können auch entfernt werden.They are upgraded along with any other services in the application instance and can be removed as well. Ein Anwendungsmanifest kann mehrere Standarddienste enthalten.An application manifest can contain multiple default services.

Zertifikate (im vorhergehenden Beispiel nicht festgelegt) deklariert die zum Einrichten von HTTPS-Endpunkten oder zum Verschlüsseln der geheimen Schlüssel im Anwendungsmanifest verwendeten Zertifikate.Certificates (not set in the preceding example) declares the certificates used to setup HTTPS endpoints or encrypt secrets in the application manifest.

Platzierungseinschränkungen sind Anweisungen, mit denen Sie definieren, an welcher Stelle Dienste ausgeführt werden sollen.Placement Constraints are the statements that define where services should run. Diese Anweisungen werden an einzelne Dienste angefügt, die Sie für mindestens eine Knoteneigenschaft auswählen.These statements are attached to individual services that you select for one or more node properties. Weitere Informationen finden Sie unter Syntax von Platzierungseinschränkungen und Knoteneigenschaften.For more information, see Placement constraints and node property syntax

Richtlinien (im vorherigen Beispiel nicht festgelegt) beschreibt die Richtlinien für die Protokollsammlung, das standardmäßige Ausführungskonto, die Integrität und den Sicherheitszugriff, die auf Anwendungsebene festzulegen sind. Dazu gehört auch, ob die Dienste Zugriff auf die Service Fabric-Runtime haben.Policies (not set in the preceding example) describes the log collection, default run-as, health, and security access policies to set at the application level, including whether the service(s) have access to the Service Fabric runtime.

Hinweis

Standardmäßig haben Service Fabric-Anwendungen Zugriff auf die Service Fabric-Runtime in Form eines Endpunkts, der anwendungsspezifische Anforderungen akzeptiert, und in Form von Umgebungsvariablen, die auf Dateipfade auf dem Host verweisen, die Fabric- und anwendungsspezifische Dateien enthalten.By default, Service Fabric applications have access to the Service Fabric runtime, in the form of an endpoint accepting application-specific requests, and environment variables pointing to file paths on the host containing Fabric and application-specific files. Sie sollten erwägen, diesen Zugriff zu deaktivieren, wenn die Anwendung nicht vertrauenswürdigen Code hostet (d. h. Code, dessen Herkunft unbekannt ist oder von dem der Anwendungsbesitzer weiß, dass bei seiner Ausführung die Sicherheit gefährdet ist).Consider disabling this access when the application hosts untrusted code (i.e. code whose provenance is unknown, or which the application owner knows not to be safe to execute). Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit in Service Fabric.For more information, please see security best practices in Service Fabric.

Prinzipale (im vorhergehenden Beispiel nicht festgelegt) beschreiben die Sicherheitsprinzipale (Benutzer oder Gruppen), die zum Ausführen von Diensten und sicheren Dienstressourcen benötigt werden.Principals (not set in the preceding example) describe the security principals (users or groups) required to run services and secure service resources. Auf Prinzipale wird in den Abschnitten über Richtlinien verwiesen.Principals are referenced in the Policies sections.

Nächste SchritteNext steps