Specificare le risorse in un manifesto del servizioSpecify resources in a service manifest

PanoramicaOverview

Il manifesto del servizio consente alle risorse di essere usate dal servizio per essere dichiarate/modificate senza modificare il codice compilato.The service manifest allows resources that are used by the service to be declared/changed without changing the compiled code. Azure Service Fabric supporta la configurazione delle risorse dell'endpoint del servizio.Azure Service Fabric supports configuration of endpoint resources for the service. È possibile controllare l'accesso alle risorse specificate nel manifesto del servizio tramite SecurityGroup nel manifesto dell'applicazione.The access to the resources that are specified in the service manifest can be controlled via the SecurityGroup in the application manifest. La dichiarazione delle risorse consente a queste ultime di essere modificate in fase di distribuzione, in questo modo il servizio non deve introdurre un nuovo meccanismo di configurazione.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. La definizione dello schema per il file ServiceManifest.xml viene installata con l'SDK e gli strumenti di Service Fabric in C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd.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.

EndpointEndpoints

Quando una risorsa dell'endpoint viene definita nel manifesto del servizio, Service Fabric assegna le porte dall'intervallo di porte riservate dell'applicazione se la porta non è esplicitamente specificata.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. Ad esempio, esaminare l'endpoint ServiceEndpoint1 specificato nel frammento di manifesto fornito dopo questo paragrafo.For example, look at the endpoint ServiceEndpoint1 specified in the manifest snippet provided after this paragraph. Inoltre, i servizi possono richiedere anche una porta specifica in una risorsa.Additionally, services can also request a specific port in a resource. Alle repliche del servizio in esecuzione sui diversi nodi del cluster possono essere assegnati diversi numeri di porta, mentre le repliche di un servizio in esecuzione nello stesso nodo condividono la porta.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. Le repliche del servizio possono quindi usare queste porte in base alle esigenze per la replica e l'ascolto delle richieste client.The service replicas can then use these ports as needed for replication and listening for client requests.

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

Se sono presenti più pacchetti di codice in un singolo pacchetto del servizio, è necessario fare riferimento anche al pacchetto di codice nella sezione Endpoint.If there are multiple code packages in a single service package, then the code package also needs to be referenced in the Endpoints section. Ad esempio, se ServiceEndpoint2a e ServiceEndpoint2b sono endpoint dello stesso pacchetto del servizio che fanno riferimento a pacchetti di codice diversi, il pacchetto di codice corrispondente a ogni endpoint viene definito come indicato di seguito: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>

Per altre informazioni sugli endpoint di riferimento del file delle impostazioni del pacchetto di configurazione (settings.xml), vedere Configurazione di Reliable Services con stato .Refer to Configuring stateful Reliable Services to read more about referencing endpoints from the config package settings file (settings.xml).

Esempio: specificare un endpoint HTTP per il servizioExample: specifying an HTTP endpoint for your service

Il manifesto del servizio seguente definisce una risorsa di endpoint TCP e due risorse di endpoint HTTP nell'elemento <Risorse>.The following service manifest defines one TCP endpoint resource and two HTTP endpoint resources in the <Resources> element.

Gli endpoint HTTP vengono automaticamente inseriti nell'elenco di controllo di accesso da Service Fabric.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="http://www.w3.org/2001/XMLSchema"
                 xmlns:xsi="http://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 directoy 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>

Esempio: specificare un endpoint HTTPS per il servizioExample: specifying an HTTPS endpoint for your service

Il protocollo HTTPS fornisce l’autenticazione del server e viene anche usato per crittografare la comunicazione del client-server.The HTTPS protocol provides server authentication and is also used for encrypting client-server communication. Per abilitare il protocollo HTTPS nel servizio di Service Fabric, specificare il protocollo nella sezione Risorse -> Endpoint -> Endpoint del manifesto del servizio, come illustrato in precedenza per l'endpoint ServiceEndpoint3.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.

Nota

Un protocollo del servizio non può essere modificato durante l'aggiornamento dell'applicazione.A service’s protocol cannot be changed during application upgrade. Se viene modificato durante l'aggiornamento, si tratta di una modifica importante.If it is changed during upgrade, it is a breaking change.

Avviso

Quando si usa HTTPS, non usare la stessa porta e lo stesso certificato per diverse istanze del servizio (indipendenti dell'applicazione) distribuite nello stesso nodo.When using HTTPS, do not use the same port and certificate for different service instances (independant of the application) deployed to the same node. L'aggiornamento di due servizi diversi mediante la stessa porta in istanze dell'applicazione diverse comporterà un errore di aggiornamento.Upgrading two different services using the same port in different application instances will result in an upgrade failure. Per altre informazioni, vedere Aggiornamento di più applicazioni con endpoint HTTPS.For more information, see Upgrading multiple applications with HTTPS endpoints .

Di seguito è riportato un esempio ApplicationManifest che è necessario impostare per il protocollo HTTPS.Here is an example ApplicationManifest that you need to set for HTTPS. È necessario fornire l'identificazione personale per il certificato.The thumbprint for your certificate must be provided. EndpointRef è un riferimento a EndpointResource in ServiceManifest per cui si imposta il protocollo HTTPS.The EndpointRef is a reference to EndpointResource in ServiceManifest, for which you set the HTTPS protocol. È possibile aggiungere più Endpointcertificate.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="http://www.w3.org/2001/XMLSchema"
                     xmlns:xsi="http://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>

Per i cluster Linux, l'archivio MY predefinito è la cartella /var/lib/sfcerts.For Linux clusters, the MY store defaults to the folder /var/lib/sfcerts.

Override degli endpoint in ServiceManifest.xmlOverriding Endpoints in ServiceManifest.xml

In ApplicationManifest aggiungere una sezione ResourceOverride che sarà un elemento di pari livello della sezione ConfigOverrides.In the ApplicationManifest add a ResourceOverrides section, which will be a sibling to ConfigOverrides section. In questa sezione è possibile specificare l'override per la sezione Endpoint nella sezione delle risorse specificata in ServiceManifest.In this section, you can specify the override for the Endpoints section in the resources section specified in the Service manifest. L'override degli endpoint è supportato nel runtime 5.7.217/SDK 2.7.217 e versioni successive.Overriding endpoints is supported in runtime 5.7.217/SDK 2.7.217 and higher.

Per eseguire l'override di EndPoint in ServiceManifest usando ApplicationParameters, modificare ApplicationManifest come riportato di seguito:In order to override EndPoint in ServiceManifest using ApplicationParameters change the ApplicationManifest as following:

Nella sezione ServiceManifestImport aggiungere una nuova sezione "ResourceOverrides".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>

In Parameters aggiungere quanto riportato di seguito: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>

Durante la distribuzione dell'applicazione è possibile trasmettere questi valori come ApplicationParameters.While deploying the application you can pass in these values as ApplicationParameters. Ad esempio: 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'}

Nota: se i valori forniti per ApplicationParameters sono vuoti, si torna al valore predefinito fornito in ServiceManifest per l'EndPointName corrispondente.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.

Ad esempio: For example:

Se in ServiceManifest è stato specificatoIf in the ServiceManifest you specified

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

e i valori Port1 e Protocol1 per i parametri di Aplication sono null o vuoti.And the Port1 and Protocol1 value for Application parameters is null or empty. La porta è comunque stabilita da ServiceFabric.The port is still decided by ServiceFabric. E il protocollo sarà tcp.And the Protocol will tcp.

Si supponga di specificare un valore errato.Suppose you specify a wrong value. Ad esempio per la porta è stato specificato un valore stringa "Foo" anziché di tipo int. Il comando New-ServiceFabricApplication avrà esito negativo con l'errore seguente: The override parameter with name 'ServiceEndpoint1' attribute 'Port1' in section 'ResourceOverrides' is invalid (Il parametro di override con nome "ServiceEndpoint1" attributo "Port1" nella sezione "ResourceOverrides" non è valido).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. Il valore specificato è "Foo", mentre era richiesto "int".The value specified is 'Foo' and required is 'int'.