Gestire i parametri dell'applicazione per più ambientiManage application parameters for multiple environments

I cluster di Azure Service Fabric possono essere creati usando un solo computer fino a molte migliaia.You can create Azure Service Fabric clusters by using anywhere from one to many thousands of machines. Anche se i file binari dell'applicazione possono essere eseguiti senza modifiche in questa ampia gamma di ambienti, spesso è consigliabile configurare l'applicazione in modo diverso, in base al numero di computer in cui si esegue la distribuzione.While application binaries can run without modification across this wide spectrum of environments, you often want to configure the application differently, depending on the number of machines you're deploying to.

Ad esempio, considerare InstanceCount per un servizio senza stato.As a simple example, consider InstanceCount for a stateless service. Quando si eseguono applicazioni in Azure, in genere è consigliabile impostare questo parametro sul valore speciale "-1".When you are running applications in Azure, you generally want to set this parameter to the special value of "-1". Questa configurazione garantisce che il servizio sia in esecuzione in ogni nodo del cluster (o in ogni nodo nel tipo di nodo se è stato impostato un vincolo di posizionamento).This configuration ensures that your service is running on every node in the cluster (or every node in the node type if you have set a placement constraint). Non è tuttavia appropriata per un cluster con un singolo computer, perché non è possibile avere più processi in ascolto sullo stesso endpoint in un singolo computer.However, this configuration is not suitable for a single-machine cluster since you cannot have multiple processes listening on the same endpoint on a single machine. Al contrario, InstanceCount viene in genere impostato su "1".Instead, you typically set InstanceCount to "1".

Definizione dei parametri specifici dell'ambienteSpecifying environment-specific parameters

La soluzione per questo problema di configurazione è costituita da un set di servizi predefiniti con parametri e file di parametri dell'applicazione che compilano i valori dei parametri per un determinato ambiente.The solution to this configuration issue is a set of parameterized default services and application parameter files that fill in those parameter values for a given environment. I parametri predefiniti per servizi e applicazioni vengono configurati all'interno dei manifesti dei servizi e delle applicazioni.Default services and application parameters are configured in the application and service manifests. La definizione dello schema per i file ServiceManifest.xml e ApplicationManifest.xml viene installata con gli strumenti e l'SDK di Service Fabric in C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd.The schema definition for the ServiceManifest.xml and ApplicationManifest.xml files is installed with the Service Fabric SDK and tools to C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd.

Servizi predefinitiDefault services

Le applicazioni di infrastruttura di servizi sono costituite da una raccolta di istanze del servizio.Service Fabric applications are made up of a collection of service instances. Anche se è possibile creare un'applicazione vuota e quindi tutte le istanze del servizio dinamicamente, la maggior parte delle applicazioni include un set di servizi di base che devono essere sempre creati quando si creano istanze dell'applicazione.While it is possible for you to create an empty application and then create all service instances dynamically, most applications have a set of core services that should always be created when the application is instantiated. Questi servizi sono detti "servizi predefiniti" eThese are referred to as "default services". vengono specificati nel manifesto dell'applicazione, con i segnaposto per la configurazione specifica dei singoli ambienti racchiusi tra parentesi quadre:They are specified in the application manifest, with placeholders for per-environment configuration included in square brackets:

  <DefaultServices>
      <Service Name="Stateful1">
          <StatefulService
              ServiceTypeName="Stateful1Type"
              TargetReplicaSetSize="[Stateful1_TargetReplicaSetSize]"
              MinReplicaSetSize="[Stateful1_MinReplicaSetSize]">

              <UniformInt64Partition
                  PartitionCount="[Stateful1_PartitionCount]"
                  LowKey="-9223372036854775808"
                  HighKey="9223372036854775807"
              />
        </StatefulService>
    </Service>
  </DefaultServices>

Ogni parametro denominato deve essere definito nell'elemento Parameters del manifesto dell'applicazione:Each of the named parameters must be defined within the Parameters element of the application manifest:

    <Parameters>
        <Parameter Name="Stateful1_MinReplicaSetSize" DefaultValue="3" />
        <Parameter Name="Stateful1_PartitionCount" DefaultValue="1" />
        <Parameter Name="Stateful1_TargetReplicaSetSize" DefaultValue="3" />
    </Parameters>

L'attributo DefaultValue specifica il valore da usare in assenza di un parametro più specifico per un determinato ambiente.The DefaultValue attribute specifies the value to be used in the absence of a more-specific parameter for a given environment.

Nota

Non tutti i parametri di istanza del servizio sono idonei alla configurazione specifica per il singolo ambiente.Not all service instance parameters are suitable for per-environment configuration. Nell'esempio precedente i valori LowKey e HighKey per lo schema di partizionamento del servizio sono definiti in modo esplicito per tutte le istanze del servizio, perché l'intervallo di partizione è una funzione del dominio di dati, non dell'ambiente.In the example above, the LowKey and HighKey values for the service's partitioning scheme are explicitly defined for all instances of the service since the partition range is a function of the data domain, not the environment.

Impostazioni della configurazione del servizio specifica per il singolo ambientePer-environment service configuration settings

Il modello applicativo di Service Fabric consente ai servizi di includere pacchetti di configurazione che contengono coppie chiave-valore personalizzate leggibili in fase di esecuzione.The Service Fabric application model enables services to include configuration packages that contain custom key-value pairs that are readable at run time. È anche possibile differenziare i valori di queste impostazioni in base all'ambiente, specificando un valore ConfigOverride nel manifesto dell'applicazione.The values of these settings can also be differentiated by environment by specifying a ConfigOverride in the application manifest.

Si supponga di avere la seguente impostazione nel file Config\Settings.xml per il servizio Stateful1:Suppose that you have the following setting in the Config\Settings.xml file for the Stateful1 service:

  <Section Name="MyConfigSection">
     <Parameter Name="MaxQueueSize" Value="25" />
  </Section>

Per eseguire l'override di questo valore per una coppia applicazione/ambiente specifica, creare un valore ConfigOverride durante l'importazione del manifesto del servizio nel manifesto dell'applicazione.To override this value for a specific application/environment pair, create a ConfigOverride when you import the service manifest in the application manifest.

  <ConfigOverrides>
     <ConfigOverride Name="Config">
        <Settings>
           <Section Name="MyConfigSection">
              <Parameter Name="MaxQueueSize" Value="[Stateful1_MaxQueueSize]" />
           </Section>
        </Settings>
     </ConfigOverride>
  </ConfigOverrides>

Questo parametro può quindi essere configurato dall'ambiente, come illustrato in precedenza,This parameter can then be configured by environment as shown above. dichiarandolo nella sezione Parameters del manifesto dell'applicazione e definendo i valori specifici per il singolo ambiente nel file di parametri dell'applicazione.You can do this by declaring it in the parameters section of the application manifest and specifying environment-specific values in the application parameter files.

Nota

Nel caso delle impostazioni di configurazione del servizio, è possibile impostare il valore di una chiave in tre posizioni, ovvero nel pacchetto di configurazione del servizio, nel manifesto dell'applicazione e nel file di parametri dell'applicazione.In the case of service configuration settings, there are three places where the value of a key can be set: the service configuration package, the application manifest, and the application parameter file. Service Fabric sceglierà sempre prima di tutto dal file di parametri dell'applicazione, se specificato, quindi dal manifesto dell'applicazione e infine dal pacchetto di configurazione.Service Fabric will always choose from the application parameter file first (if specified), then the application manifest, and finally the configuration package.

Impostazione e uso delle variabili di ambienteSetting and using environment variables

È possibile specificare e impostare le variabili di ambiente nel file ServiceManifest.xml e quindi sostituire tali impostazioni nel file ApplicationManifest.xml per ogni istanza.You can specify and set environment variables in the ServiceManifest.xml file and then override these in the ApplicationManifest.xml file on a per instance basis. L'esempio seguente illustra due variabili di ambiente, una con un valore impostato e l'altra sostituita.The example below shows two environment variables, one with a value set and the other is overridden. È possibile usare i parametri dell'applicazione per impostare i valori delle variabili di ambiente in modo analogo a come verrebbero usati per le sostituzioni di configurazione.You can use application parameters to set environment variables values in the same way that these were used for config overrides.

<?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>

Per sostituire le variabili di ambiente nel file ApplicationManifest.xml, fare riferimento al pacchetto di codice in ServiceManifest con l'elemento EnvironmentOverrides.To override the environment variables in the ApplicationManifest.xml, reference the code package in the ServiceManifest with the EnvironmentOverrides element.

  <ServiceManifestImport>
    <ServiceManifestRef ServiceManifestName="FrontEndServicePkg" ServiceManifestVersion="1.0.0" />
    <EnvironmentOverrides CodePackageRef="MyCode">
      <EnvironmentVariable Name="MyEnvVariable" Value="mydata"/>
    </EnvironmentOverrides>
  </ServiceManifestImport>

Dopo aver creato l'istanza del servizio denominato, è possibile accedere alle variabili di ambiente dal codice.Once the named service instance is created you can access the environment variables from code. In C# è possibile ad esempio eseguire queste operazionie.g. In C# you can do the following

    string EnvVariable = Environment.GetEnvironmentVariable("MyEnvVariable");

Variabili di ambiente di Service FabricService Fabric environment variables

Service Fabric dispone di variabili di ambiente predefinite, impostate per ciascuna istanza di servizio.Service Fabric has built in environment variables set for each service instance. Di seguito viene riportato l'elenco completo delle variabili di ambiente. Quelle in grassetto verranno usate nel servizio, le altre sono usate dal runtime di Service Fabric.The full list of environment variables is below, where the ones in bold are the ones that you will use in your service, the other being used by Service Fabric runtime.

  • Fabric_ApplicationHostIdFabric_ApplicationHostId
  • Fabric_ApplicationHostTypeFabric_ApplicationHostType
  • Fabric_ApplicationIdFabric_ApplicationId
  • Fabric_ApplicationNameFabric_ApplicationName
  • Fabric_CodePackageInstanceIdFabric_CodePackageInstanceId
  • Fabric_CodePackageNameFabric_CodePackageName
  • Fabric_Endpoint_[NomeDelServizio]TypeEndpointFabric_Endpoint_[YourServiceName]TypeEndpoint
  • Fabric_Folder_App_LogFabric_Folder_App_Log
  • Fabric_Folder_App_TempFabric_Folder_App_Temp
  • Fabric_Folder_App_WorkFabric_Folder_App_Work
  • Fabric_Folder_ApplicationFabric_Folder_Application
  • Fabric_NodeIdFabric_NodeId
  • Fabric_NodeIPOrFQDNFabric_NodeIPOrFQDN
  • Fabric_NodeNameFabric_NodeName
  • Fabric_RuntimeConnectionAddressFabric_RuntimeConnectionAddress
  • Fabric_ServicePackageInstanceIdFabric_ServicePackageInstanceId
  • Fabric_ServicePackageNameFabric_ServicePackageName
  • Fabric_ServicePackageVersionInstanceFabric_ServicePackageVersionInstance
  • FabricPackageFileNameFabricPackageFileName

Il codice seguente mostra come elencare le variabili di ambiente di Service FabricThe code belows shows how to list the Service Fabric environment variables

   foreach (DictionaryEntry de in Environment.GetEnvironmentVariables())
   {
       if (de.Key.ToString().StartsWith("Fabric"))
       {
           Console.WriteLine(" Environment variable {0} = {1}", de.Key, de.Value);
       }
   }

Di seguito sono riportati esempi di variabili di ambiente per un tipo di applicazione chiamato GuestExe.Application con un tipo di servizio denominato FrontEndService, in esecuzione sul computer di sviluppo locale.The following are examples of environment variables for an application type called GuestExe.Application with a service type called FrontEndService when run on your local dev machine.

  • Fabric_ApplicationName = fabric:/GuestExe.ApplicationFabric_ApplicationName = fabric:/GuestExe.Application
  • Fabric_CodePackageName = CodeFabric_CodePackageName = Code
  • Fabric_Endpoint_FrontEndServiceTypeEndpoint = 80Fabric_Endpoint_FrontEndServiceTypeEndpoint = 80
  • Fabric_NodeIPOrFQDN = localhostFabric_NodeIPOrFQDN = localhost
  • Fabric_NodeName = _Node_2Fabric_NodeName = _Node_2

File di parametri dell'applicazioneApplication parameter files

Il progetto di applicazione di Service Fabric può includere uno o più file di parametri dell'applicazione,The Service Fabric application project can include one or more application parameter files. ognuno dei quali definisce i valori specifici per i parametri definiti nel manifesto dell'applicazione:Each of them defines the specific values for the parameters that are defined in the application manifest:

    <!-- ApplicationParameters\Local.xml -->

    <Application Name="fabric:/Application1" xmlns="http://schemas.microsoft.com/2011/01/fabric">
        <Parameters>
            <Parameter Name ="Stateful1_MinReplicaSetSize" Value="3" />
            <Parameter Name="Stateful1_PartitionCount" Value="1" />
            <Parameter Name="Stateful1_TargetReplicaSetSize" Value="3" />
        </Parameters>
    </Application>

Per impostazione predefinita, una nuova applicazione include tre file di parametro dell'applicazione, denominati Local.1Node.xml, Local.5Node.xml e Cloud.xml:By default, a new application includes three application parameter files, named Local.1Node.xml, Local.5Node.xml, and Cloud.xml:

File di parametri dell'applicazione in Esplora soluzioni

Per creare un file di parametri, è sufficiente copiarne e incollarne uno esistente e specificare un nuovo nome.To create a parameter file, simply copy and paste an existing one and give it a new name.

Identificazione di parametri specifici per il singolo ambiente durante la distribuzioneIdentifying environment-specific parameters during deployment

In fase di distribuzione è necessario scegliere il file di parametri appropriato da usare con l'applicazione.At deployment time, you need to choose the appropriate parameter file to apply with your application. È possibile eseguire questa operazione nella finestra di dialogo Pubblica in Visual Studio o in PowerShell.You can do this through the Publish dialog in Visual Studio or through PowerShell.

Eseguire una distribuzione da Visual StudioDeploy from Visual Studio

Si può scegliere dall'elenco dei file di parametri disponibili quando si pubblica l'applicazione in Visual Studio.You can choose from the list of available parameter files when you publish your application in Visual Studio.

Scelta di un file di parametri nella finestra di dialogo Pubblica

Distribuire da PowerShellDeploy from PowerShell

Lo script Deploy-FabricApplication.ps1 di PowerShell incluso nel modello del progetto dell'applicazione accetta un profilo di pubblicazione come parametro e PublishProfile contiene un riferimento al file dei parametri dell'applicazione.The Deploy-FabricApplication.ps1 PowerShell script included in the application project template accepts a publish profile as a parameter and the PublishProfile contains a reference to the application parameters file.

  ./Deploy-FabricApplication -ApplicationPackagePath <app_package_path> -PublishProfileFile <publishprofile_path>

Passaggi successiviNext steps

Per altre informazioni su alcuni concetti di base illustrati in questo argomento, vedere Panoramica della terminologia di Service Fabric.To learn more about some of the core concepts that are discussed in this topic, see the Service Fabric technical overview. Per informazioni su altre funzionalità di gestione delle app disponibili in Visual Studio, vedere Usare Visual Studio per semplificare la scrittura e la gestione delle applicazioni di Service Fabric.For information about other app management capabilities that are available in Visual Studio, see Manage your Service Fabric applications in Visual Studio.