Angeben von Ressourcen in einem DienstmanifestSpecify resources in a service manifest

ÜbersichtOverview

Mit dem Dienstmanifest können vom Dienst verwendete Ressourcen deklariert oder geändert werden, ohne dass der kompilierte Code geändert werden muss.The service manifest allows resources that are used by the service to be declared/changed without changing the compiled code. Azure Service Fabric unterstützt die Konfiguration von Endpunktressourcen für den Dienst.Azure Service Fabric supports configuration of endpoint resources for the service. Der Zugriff auf die im Dienstmanifest angegebenen Ressourcen kann über das SecurityGroup-Element im Anwendungsmanifest gesteuert werden.The access to the resources that are specified in the service manifest can be controlled via the SecurityGroup in the application manifest. Die Deklaration von Ressourcen ermöglicht es, dass diese Ressourcen zur Bereitstellungszeit geändert werden, sodass der Dienst keinen neuen Konfigurationsmechanismus einführen muss.The declaration of resources allows these resources to be changed at deployment time, meaning the service doesn't need to introduce a new configuration mechanism. Die Schemadefinition für die Datei „ServiceManifest.xml“ wird mit dem Service Fabric SDK und den Service Fabric-Tools unter C:\Programm\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd installiert.The schema definition for the ServiceManifest.xml file is installed with the Service Fabric SDK and tools to C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd.

EndpunkteEndpoints

Wenn eine Endpunktressource im Dienstmanifest definiert wird, weist Service Fabric Ports aus dem Bereich der reservierten Anwendungsports zu, sollte ein Port nicht explizit angegeben sein.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. Sehen Sie sich beispielsweise den Endpunkt ServiceEndpoint1 an, der im Codeausschnitt aus dem Manifest im Anschluss an diesen Absatz angegeben ist.For example, look at the endpoint ServiceEndpoint1 specified in the manifest snippet provided after this paragraph. Außerdem können Dienste auch einen bestimmten Port einer Ressource anfordern.Additionally, services can also request a specific port in a resource. Dienstreplikate, die auf unterschiedlichen Clusterknoten ausgeführt werden, können unterschiedlichen Portnummern zugewiesen werden, während für Replikate eines Diensts auf demselben Knoten derselbe Port verwendet wird.Service replicas running on different cluster nodes can be assigned different port numbers, while replicas of a service running on the same node share the port. Die Dienstreplikate können dann diese Ports nach Bedarf für die Replikation und das Überwachen auf Clientanforderungen nutzen.The service replicas can then use these ports as needed for replication and listening for client requests.

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.

Mit Version 7.0 werden wir eine Integritätswarnung ausgeben, wenn wir feststellen, dass die Nutzung des Anwendungsportbereichs über „HostingConfig::ApplicationPortExhaustThresholdPercentage“ hinausgeht (standardmäßig 80 %).With release 7.0 we will issue a Health Warning when we detect application port range usage goes beyond HostingConfig::ApplicationPortExhaustThresholdPercentage(default 80%).

<Resources>
  <Endpoints>
    <Endpoint Name="ServiceEndpoint1" Protocol="http"/>
    <Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
    <Endpoint Name="ServiceEndpoint3" Protocol="https"/>
  </Endpoints>
</Resources>

Wenn ein einzelnes Dienstpaket mehrere Codepakete enthält, muss im Abschnitt Endpoints ebenfalls auf das Codepaket verwiesen werden.If there are multiple code packages in a single service package, then the code package also needs to be referenced in the Endpoints section. Beispiel: Wenn ServiceEndpoint2a und ServiceEndpoint2b Endpunkte desselben Servicepakets sind, die auf unterschiedliche Codepakete verweisen, wird das Codepaket des jeweiligen Endpunkts wie folgt identifiziert:For example, if ServiceEndpoint2a and ServiceEndpoint2b are endpoints from the same service package referencing different code packages, the code package corresponding to each endpoint is clarified as follows:

<Resources>
  <Endpoints>
    <Endpoint Name="ServiceEndpoint2a" Protocol="http" Port="802" CodePackageRef="Code1"/>
    <Endpoint Name="ServiceEndpoint2b" Protocol="http" Port="801" CodePackageRef="Code2"/>
  </Endpoints>
</Resources>

Weitere Informationen zum Verweisen auf Endpunkte aus der Datei mit den Konfigurationspaketeinstellungen („settings.xml“) finden Sie unter Konfigurieren zustandsbehafteter Reliable Services .Refer to Configuring stateful Reliable Services to read more about referencing endpoints from the config package settings file (settings.xml).

Beispiel: Angeben eines HTTP-Endpunkts für Ihren DienstExample: specifying an HTTP endpoint for your service

Das folgende Dienstmanifest definiert eine TCP-Endpunktressource und zwei HTTP-Endpunktressourcen im <Resources>-Element.The following service manifest defines one TCP endpoint resource and two HTTP endpoint resources in the <Resources> element.

HTTP-Endpunkte werden von Service Fabric automatisch mit einer Zugriffssteuerungsliste (ACL) versehen.HTTP endpoints are automatically ACL'd by Service Fabric.

<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="Stateful1Pkg"
                 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 the RegisterServiceType call in Program.cs. -->
    <StatefulServiceType ServiceTypeName="Stateful1Type" HasPersistedState="true" />
  </ServiceTypes>

  <!-- Code package is your service executable. -->
  <CodePackage Name="Code" Version="1.0.0">
    <EntryPoint>
      <ExeHost>
        <Program>Stateful1.exe</Program>
      </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 number on which to
           listen. Note that if your service is partitioned, this port is shared with
           replicas of different partitions that are placed in your code. -->
      <Endpoint Name="ServiceEndpoint1" Protocol="http"/>
      <Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
      <Endpoint Name="ServiceEndpoint3" Protocol="https"/>

      <!-- This endpoint is used by the replicator for replicating the state of your service.
           This endpoint is configured through the ReplicatorSettings config section in the Settings.xml
           file under the ConfigPackage. -->
      <Endpoint Name="ReplicatorEndpoint" />
    </Endpoints>
  </Resources>
</ServiceManifest>

Beispiel: Angeben eines HTTPS-Endpunkts für Ihren DienstExample: specifying an HTTPS endpoint for your service

Das HTTPS-Protokoll ermöglicht die Serverauthentifizierung und wird auch zum Verschlüsseln der Kommunikation zwischen Client und Server verwendet.The HTTPS protocol provides server authentication and is also used for encrypting client-server communication. Um HTTPS für Ihren Service Fabric-Dienst zu aktivieren, geben Sie dieses Protokoll im Abschnitt Ressourcen -> Endpunkte -> Endpunkt des Dienstmanifests an, wie weiter oben für den Endpunkt ServiceEndpoint3 gezeigt.To enable HTTPS on your Service Fabric service, specify the protocol in the Resources -> Endpoints -> Endpoint section of the service manifest, as shown earlier for the endpoint ServiceEndpoint3.

Hinweis

Das Protokoll eines Diensts kann nicht während eines Anwendungsupgrades geändert werden.A service’s protocol cannot be changed during application upgrade. Ein solche Änderung während des Upgrades würde zu einem Verlust der Abwärtskompatibilität führen.If it is changed during upgrade, it is a breaking change.

Warnung

Wenn HTTPS verwendet wird, verwenden Sie nicht den gleichen Port und das gleiche Zertifikat für verschiedene Dienstinstanzen (unabhängig von der Anwendung), die für den gleichen Knoten bereitgestellt werden.When using HTTPS, do not use the same port and certificate for different service instances (independent of the application) deployed to the same node. Das Upgrade von zwei verschiedenen Diensten unter Verwendung desselben Ports in verschiedenen Anwendungsinstanzen führt zu einem Upgradefehler.Upgrading two different services using the same port in different application instances will result in an upgrade failure. Weitere Informationen finden Sie unter Aktualisieren von mehreren Anwendungen mit HTTPS-Endpunkten.For more information, see Upgrading multiple applications with HTTPS endpoints .

Hier sehen Sie ein Beispiel für ein Anwendungsmanifest, das Sie für HTTPS festlegen müssen.Here is an example ApplicationManifest that you need to set for HTTPS. Der Fingerabdruck Ihres Zertifikats muss bereitgestellt werden.The thumbprint for your certificate must be provided. Bei EndpointRef handelt es sich um einen Verweis auf die Endpunktressource im Dienstmanifest, für das Sie das HTTPS-Protokoll festgelegt haben.The EndpointRef is a reference to EndpointResource in ServiceManifest, for which you set the HTTPS protocol. Sie können mehrere Endpunktzertifikate hinzufügen.You can add more than one EndpointCertificate.

<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest ApplicationTypeName="Application1Type"
                     ApplicationTypeVersion="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">
  <Parameters>
    <Parameter Name="Stateful1_MinReplicaSetSize" DefaultValue="3" />
    <Parameter Name="Stateful1_PartitionCount" DefaultValue="1" />
    <Parameter Name="Stateful1_TargetReplicaSetSize" DefaultValue="3" />
  </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="Stateful1Pkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
    <Policies>
      <EndpointBindingPolicy CertificateRef="TestCert1" EndpointRef="ServiceEndpoint3"/>
    </Policies>
  </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 by using the
         Service Fabric PowerShell module.

         The attribute ServiceTypeName below must match the name defined in the imported ServiceManifest.xml file. -->
    <Service Name="Stateful1">
      <StatefulService ServiceTypeName="Stateful1Type" TargetReplicaSetSize="[Stateful1_TargetReplicaSetSize]" MinReplicaSetSize="[Stateful1_ ]">
        <UniformInt64Partition PartitionCount="[Stateful1_PartitionCount]" LowKey="-9223372036854775808" HighKey="9223372036854775807" />
      </StatefulService>
    </Service>
  </DefaultServices>
  <Certificates>
    <EndpointCertificate Name="TestCert1" X509FindValue="FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF F0" X509StoreName="MY" />  
  </Certificates>
</ApplicationManifest>

Für Linux-Cluster wird für den MY-Speicher standardmäßig der Ordner /var/lib/sfcerts verwendet.For Linux clusters, the MY store defaults to the folder /var/lib/sfcerts.

Außerkraftsetzen von Endpunkten in „ServiceManifest.xml“Overriding Endpoints in ServiceManifest.xml

Fügen Sie dem Anwendungsmanifest einen Abschnitt vom Typ „ResourceOverrides“ hinzu, der dem Abschnitt „ConfigOverrides“ gleichgestellt ist.In the ApplicationManifest add a ResourceOverrides section, which will be a sibling to ConfigOverrides section. In diesem Abschnitt können Sie die Außerkraftsetzung für den Abschnitt „Endpoints“ im Ressourcenabschnitt des Dienstmanifests angeben.In this section, you can specify the override for the Endpoints section in the resources section specified in the Service manifest. Das Überschreiben von Endpunkten wird in Runtime 5.7.217/SDK 2.7.217 und höher unterstützt.Overriding endpoints is supported in runtime 5.7.217/SDK 2.7.217 and higher.

Wenn Sie „EndPoint“ im Dienstmanifest mithilfe von „ApplicationParameters“ außer Kraft setzen möchten, ändern Sie das Anwendungsmanifest wie folgt:In order to override EndPoint in ServiceManifest using ApplicationParameters change the ApplicationManifest as following:

Fügen Sie im Abschnitt „ServiceManifestImport“ einen neuen Abschnitt namens „ResourceOverrides“ hinzu.In the ServiceManifestImport section, add a new section "ResourceOverrides".

<ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="Stateless1Pkg" ServiceManifestVersion="1.0.0" />
    <ConfigOverrides />
    <ResourceOverrides>
      <Endpoints>
        <Endpoint Name="ServiceEndpoint" Port="[Port]" Protocol="[Protocol]" Type="[Type]" />
        <Endpoint Name="ServiceEndpoint1" Port="[Port1]" Protocol="[Protocol1] "/>
      </Endpoints>
    </ResourceOverrides>
        <Policies>
           <EndpointBindingPolicy CertificateRef="TestCert1" EndpointRef="ServiceEndpoint"/>
        </Policies>
  </ServiceManifestImport>

Fügen Sie unter „Parameters“ Folgendes hinzu:In the Parameters add below:

  <Parameters>
    <Parameter Name="Port" DefaultValue="" />
    <Parameter Name="Protocol" DefaultValue="" />
    <Parameter Name="Type" DefaultValue="" />
    <Parameter Name="Port1" DefaultValue="" />
    <Parameter Name="Protocol1" DefaultValue="" />
  </Parameters>

Beim Bereitstellen der Anwendung können Sie die folgenden Werte als ApplicationParameters übergeben.While deploying the application you can pass in these values as ApplicationParameters. Beispiel:For example:

PS C:\> New-ServiceFabricApplication -ApplicationName fabric:/myapp -ApplicationTypeName "AppType" -ApplicationTypeVersion "1.0.0" -ApplicationParameter @{Port='1001'; Protocol='https'; Type='Input'; Port1='2001'; Protocol='http'}

Hinweis: Wenn für die Anwendungsparameter keine Werte angegeben wurden, wird der Standardwert für den entsprechenden EndPointName aus dem ServiceManifest verwendet.Note: If the values provide for the ApplicationParameters is empty, we go back to the default value provided in the ServiceManifest for the corresponding EndPointName.

Beispiel:For example:

Angenommen, Sie haben im Dienstmanifest Folgendes angegeben:If in the ServiceManifest you specified

  <Resources>
    <Endpoints>
      <Endpoint Name="ServiceEndpoint1" Protocol="tcp"/>
    </Endpoints>
  </Resources>

Und nehmen wir weiter an, der Port1- und der Protocol1-Wert für die Anwendungsparameter sind NULL oder leer.And the Port1 and Protocol1 value for Application parameters is null or empty. Der Port wird weiterhin von ServiceFabric bestimmt.The port is still decided by ServiceFabric. Und das TCP-Protokoll wird verwendet.And the Protocol will tcp.

Angenommen, Sie geben einen falschen Wert an –Suppose you specify a wrong value. beispielsweise den Zeichenfolgenwert „Foo“ anstelle einer ganzen Zahl für den Port. Für den Befehl New-ServiceFabricApplication tritt ein Fehler mit dem Hinweis auf, dass der Außerkraftsetzungsparameter mit dem Namen „ServiceEndpoint1“ und dem Attribut „Port1“ im Abschnitt „ResourceOverrides“ ungültig ist.Like for Port you specified a string value "Foo" instead of an int. New-ServiceFabricApplication command will fail with an error : The override parameter with name 'ServiceEndpoint1' attribute 'Port1' in section 'ResourceOverrides' is invalid. Außerdem werden Sie darauf hingewiesen, dass „Foo“ angegeben wurde, aber eine ganze Zahl erforderlich ist.The value specified is 'Foo' and required is 'int'.