Distribuire e rimuovere applicazioni con il client FabricDeploy and remove applications using FabricClient


Dopo aver creato il pacchetto di un tipo di applicazione, è possibile distribuirlo in un cluster di Azure Service Fabric.Once an application type has been packaged, it's ready for deployment into an Azure Service Fabric cluster. La distribuzione prevede i tre passaggi seguenti:Deployment involves the following three steps:

  1. Caricamento del pacchetto dell'applicazione nell'archivio di immaginiUpload the application package to the image store
  2. Registrare il tipo di applicazioneRegister the application type
  3. Rimuovere il pacchetto applicazione da Image Store.Remove the application package from the image store
  4. Creare l'istanza dell'applicazioneCreate the application instance

Dopo che un'applicazione è stata distribuita e un'istanza è in esecuzione nel cluster, è possibile eliminare l'istanza dell'applicazione e il tipo di applicazione corrispondente.After an application is deployed and an instance is running in the cluster, you can delete the application instance and its application type. Per rimuovere completamente un'applicazione dal cluster, sono necessari i passaggi seguenti:To completely remove an application from the cluster involves the following steps:

  1. Rimuovere (o eliminare) l'istanza dell'applicazione in esecuzioneRemove (or delete) the running application instance
  2. Annullare la registrazione del tipo di applicazione se non è più necessarioUnregister the application type if you no longer need it

Se si usa Visual Studio per eseguire la distribuzione e il debug delle applicazioni nel cluster di sviluppo locale, tutti i passaggi precedenti vengono gestiti automaticamente tramite uno script di PowerShell.If you use Visual Studio for deploying and debugging applications on your local development cluster, all the preceding steps are handled automatically through a PowerShell script. Questo script è disponibile nella cartella Scripts del progetto dell'applicazione.This script is found in the Scripts folder of the application project. Questo articolo illustra le operazioni eseguite da tali script per consentirne l'esecuzione anche all'esterno di Visual Studio.This article provides background on what that script is doing so that you can perform the same operations outside of Visual Studio.

Connettersi al clusterConnect to the cluster

Connettersi al cluster tramite la creazione di un'istanza client Fabric prima di eseguire uno degli esempi di codice forniti in questo articolo.Connect to the cluster by creating a FabricClient instance before you run any of the code examples in this article. Per esempi di connessione a un cluster di sviluppo locale, un cluster remoto o un cluster protetto usando Azure Active Directory, certificati X509 o Windows Active Directory, vedere Connettersi a un cluster sicuro.For examples of connecting to a local development cluster or a remote cluster or cluster secured using Azure Active Directory, X509 certificates, or Windows Active Directory see Connect to a secure cluster. Per connettersi al cluster di sviluppo locale eseguire le operazioni seguenti:To connect to the local development cluster, run the following:

// Connect to the local cluster.
FabricClient fabricClient = new FabricClient();

Caricare il pacchetto applicazioneUpload the application package

Si supponga di compilare e assemblare un'applicazione denominata MyApplication in Visual Studio.Suppose you build and package an application named MyApplication in Visual Studio. Per impostazione predefinita, il nome del tipo di applicazione elencato nel file ApplicationManifest.xml è "MyApplicationType".By default, the application type name listed in the ApplicationManifest.xml is "MyApplicationType". Il pacchetto dell'applicazione, che contiene il manifesto dell'applicazione necessario, i manifesti dei servizi e i pacchetti di codice, configurazione e dati, si trova in C:\Users<username>\Documents\Visual Studio 2017\Projects\MyApplication\MyApplication\pkg\Debug.The application package, which contains the necessary application manifest, service manifests, and code/config/data packages, is located in C:\Users<username>\Documents\Visual Studio 2017\Projects\MyApplication\MyApplication\pkg\Debug.

Quando si carica il pacchetto dell'applicazione, lo si inserisce in un percorso accessibile ai componenti interni di Service Fabric.Uploading the application package puts it in a location that's accessible by the internal Service Fabric components. Service Fabric verifica il pacchetto dell'applicazione durante la registrazione.Service Fabric verifies the application package during the registration of the application package. Tuttavia, se si desidera verificare il pacchetto dell'applicazione in locale, ad esempio prima di caricarlo, usare il cmdlet Test-ServiceFabricApplicationPackage.However, if you want to verify the application package locally (i.e., before uploading), use the Test-ServiceFabricApplicationPackage cmdlet.

L'API CopyApplicationPackage carica il pacchetto dell'applicazione nell'archivio immagini del cluster.The CopyApplicationPackage API uploads the application package to the cluster image store.

Se il pacchetto dell'applicazione è di grandi dimensioni e/o è costituito da numerosi file, è possibile comprimerlo e copiarlo nell'archivio immagini con PowerShell.If the application package is large and/or has many files, you can compress it and copy it to the image store using PowerShell. La compressione riduce le dimensioni e il numero di file.The compression reduces the size and the number of files.

Per informazioni agguntive sull'archivio di immagini e ImageStoreConnectionString, vedere Understand the image store connection string (Comprendere la stringa di connessione dell'archivio di immagini).See Understand the image store connection string for supplementary information about the image store and image store connection string.

Registrare il pacchetto applicazioneRegister the application package

Quando si registra il pacchetto dell'applicazione, il tipo e la versione dell'applicazione dichiarati nel manifesto di quest'ultima diventano disponibili per l'uso.The application type and version declared in the application manifest become available for use when the application package is registered. Il sistema leggerà il pacchetto caricato al passaggio precedente, lo verificherà, ne elaborerà il contenuto e infine copierà il pacchetto elaborato in un percorso di sistema interno.The system reads the package uploaded in the previous step, verifies the package, processes the package contents, and copies the processed package to an internal system location.

L'API ProvisionApplicationAsync registra il tipo di applicazione nel cluster e la rende disponibile per la distribuzione.The ProvisionApplicationAsync API registers the application type in the cluster and make it available for deployment.

L'API GetApplicationTypeListAsync fornisce informazioni su tutti i tipi di applicazioni registrati correttamente.The GetApplicationTypeListAsync API provides information about all successfully registered application types. È possibile usare questa API per determinare quando viene eseguita la registrazione.You can use this API to determine when the registration is done.

Rimuovere il pacchetto di un'applicazione dall'archivio di immaginiRemove an application package from the image store

Al termine della registrazione dell'applicazione, è consigliabile rimuovere il pacchetto dell'applicazione.It's recommended that you remove the application package after the application is successfully registered. L'eliminazione dei pacchetti di applicazioni dall'archivio immagini consente di liberare risorse di sistema.Deleting application packages from the image store frees up system resources. Se si conservano i pacchetti dell'applicazione non usati, viene utilizzato spazio di archiviazione su disco e sorgono problemi di prestazioni dell'applicazione.Keeping unused application packages consumes disk storage and leads to application performance issues. Eliminare il pacchetto dell'applicazione dall'archivio immagini usando l'API RemoveApplicationPackage.Delete the application package from the image store using the RemoveApplicationPackage API.

Creare un'istanza dell'applicazioneCreate an application instance

È possibile creare un'istanza di un'applicazione da qualsiasi tipo di applicazione registrato correttamente usando l'API CreateApplicationAsync.You can instantiate an application from any application type that has been registered successfully by using the CreateApplicationAsync API. Il nome di ogni applicazione deve iniziare con lo schema "fabric:" e deve essere univoco per ogni istanza dell'applicazione (all'interno di un cluster).The name of each application must start with the "fabric:" scheme and must be unique for each application instance (within a cluster). Vengono creati anche i servizi predefiniti specificati nel manifesto dell'applicazione del tipo di applicazione di destinazione.Any default services defined in the application manifest of the target application type are also created.

Per qualsiasi versione di un tipo di applicazione registrato, è possibile creare più istanze dell'applicazione.Multiple application instances can be created for any given version of a registered application type. Ogni istanza dell'applicazione viene eseguita in isolamento, con una propria directory di lavoro e un proprio set di processi.Each application instance runs in isolation, with its own working directory and set of processes.

Per vedere quali applicazioni e servizi denominati sono in esecuzione nel cluster, eseguire le API GetApplicationListAsync e GetServiceListAsync.To see which named applications and services are running in the cluster, run the GetApplicationListAsync and GetServiceListAsync APIs.

Creare un'istanza del servizioCreate a service instance

È possibile creare un'istanza di un servizio da un tipo di servizio usando l'API CreateServiceAsync.You can instantiate a service from a service type using the CreateServiceAsync API. Se il servizio è dichiarato come servizio predefinito nel manifesto dell'applicazione, viene creata un'istanza del servizio durante la creazione dell'istanza dell'applicazione.If the service is declared as a default service in the application manifest, the service is instantiated when the application is instantiated. La chiamata all'API CreateServiceAsync per un servizio di cui è già stata creata un'istanza restituirà un'eccezione di tipo FabricException contenente un codice di errore con un valore di FabricErrorCode.ServiceAlreadyExists.Calling the CreateServiceAsync API for a service that is already instantiated will return an exception of type FabricException containing an error code with a value of FabricErrorCode.ServiceAlreadyExists.

Rimuovere un'istanza del servizioRemove a service instance

Quando un'istanza del servizio non è più necessaria, è possibile rimuoverla dall'istanza dell'applicazione in esecuzione tramite la chiamata all'API DeleteServiceAsync.When a service instance is no longer needed, you can remove it from the running application instance by calling the DeleteServiceAsync API.

Avviso

Tale operazione non può essere annullata e lo stato del servizio non può essere recuperato.

Rimuovere un'istanza dell'applicazioneRemove an application instance

Quando un'istanza dell'applicazione non è più necessaria, è possibile rimuoverla definitivamente in base al nome tramite la chiamata all'API DeleteApplicationAsync.When an application instance is no longer needed, you can permanently remove it by name using the DeleteApplicationAsync API. Il metodo DeleteApplicationAsync rimuove automaticamente anche tutti i servizi che appartengono all'applicazione, rimuovendo così in modo permanente lo stato di tutti i servizi.DeleteApplicationAsync automatically removes all services that belong to the application as well, permanently removing all service state.

Avviso

Tale operazione non può essere annullata e lo stato dell'applicazione non può essere recuperato.

Annullare la registrazione di un tipo di applicazioneUnregister an application type

Quando una determinata versione di un tipo di applicazione non è più necessaria, è consigliabile annullare la registrazione di quella specifica versione del tipo di applicazione usando l'API Unregister-ServiceFabricApplicationType.When a particular version of an application type is no longer needed, you should unregister that particular version of the application type using the Unregister-ServiceFabricApplicationType API. L'annullamento della registrazione delle versioni inutilizzate dei tipi di applicazioni rilascia lo spazio di archiviazione usato dall'archivio immagini.Unregistering unused versions of application types releases storage space used by the image store. È possibile annullare la registrazione di una versione di un tipo di applicazione solo se non sono state create istanze di applicazioni basate su quella versione del tipo di applicazione e non vi sono aggiornamenti di applicazioni in sospeso che fanno riferimento a quella versione del tipo di applicazione.A version of an application type can be unregistered as long as no applications are instantiated against that version of the application type and no pending application upgrades are referencing that version of the application type.

risoluzione dei problemiTroubleshooting

Copy-ServiceFabricApplicationPackage chiede un parametro ImageStoreConnectionStringCopy-ServiceFabricApplicationPackage asks for an ImageStoreConnectionString

Nell'ambiente Service Fabric SDK dovrebbero già essere configurate le impostazioni predefinite corrette.The Service Fabric SDK environment should already have the correct defaults set up. Tuttavia, se necessario, ImageStoreConnectionString per tutti i comandi deve corrispondere al valore che viene usato dal cluster Service Fabric.But if needed, the ImageStoreConnectionString for all commands should match the value that the Service Fabric cluster is using. È possibile trovare ImageStoreConnectionString nel manifesto del cluster, recuperato tramite i comandi Get-ServiceFabricClusterManifest e Get-ImageStoreConnectionStringFromClusterManifest:You can find the ImageStoreConnectionString in the cluster manifest, retrieved using the Get-ServiceFabricClusterManifest and Get-ImageStoreConnectionStringFromClusterManifest commands:

PS C:\> Get-ImageStoreConnectionStringFromClusterManifest(Get-ServiceFabricClusterManifest)

Il cmdlet Get-ImageStoreConnectionStringFromClusterManifest , che fa parte del modulo PowerShell Service Fabric SDK, viene usato per ottenere la stringa di connessione dell'archivio immagini.The Get-ImageStoreConnectionStringFromClusterManifest cmdlet, which is part of the Service Fabric SDK PowerShell module, is used to get the image store connection string. Per importare il modulo SDK, eseguire:To import the SDK module, run:

Import-Module "$ENV:ProgramFiles\Microsoft SDKs\Service Fabric\Tools\PSModule\ServiceFabricSDK\ServiceFabricSDK.psm1"

ImageStoreConnectionString è disponibile nel manifesto del cluster:The ImageStoreConnectionString is found in the cluster manifest:

<ClusterManifest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Name="Server-Default-SingleNode" Version="1.0" xmlns="http://schemas.microsoft.com/2011/01/fabric">

    [...]

    <Section Name="Management">
      <Parameter Name="ImageStoreConnectionString" Value="file:D:\ServiceFabric\Data\ImageStore" />
    </Section>

    [...]

Per informazioni agguntive sull'archivio di immagini e ImageStoreConnectionString, vedere Understand the image store connection string (Comprendere la stringa di connessione dell'archivio di immagini).See Understand the image store connection string for supplementary information about the image store and image store connection string.

Distribuire un pacchetto dell'applicazione di grandi dimensioniDeploy large application package

Problema: l'API CopyApplicationPackage raggiunge il timeout per un pacchetto dell'applicazione di grandi dimensioni (nell'ordine di GB).Issue: CopyApplicationPackage API times out for a large application package (order of GB). Soluzione:Try:

  • Specificare un timeout maggiore per il metodo CopyApplicationPackage con il parametro timeout.Specify a larger timeout for CopyApplicationPackage method, with timeout parameter. Il timeout è di 30 minuti per impostazione predefinita.By default, the timeout is 30 minutes.
  • Controllare la connessione di rete tra il computer di origine e il cluster.Check the network connection between your source machine and cluster. Se la connessione è lenta, provare a usare una macchina con una connessione di rete più veloce.If the connection is slow, consider using a machine with a better network connection. Se il computer client si trova in un'area diversa dal cluster, si consiglia di usare un computer cliente in un'area più vicina o nella stessa area del cluster.If the client machine is in another region than the cluster, consider using a client machine in a closer or same region as the cluster.
  • Controllare se si stiano raggiungendo le limitazioni esterne.Check if you are hitting external throttling. Ad esempio, quando l'archivio immagini è configurato per usare l'archiviazione di Azure, il caricamento potrebbe essere limitato.For example, when the image store is configured to use azure storage, upload may be throttled.

Problema: il pacchetto è stato caricato completamente, ma si è verificato il timeout dell'API ProvisionApplicationAsync. Soluzione:Issue: Upload package completed successfully, but ProvisionApplicationAsync API times out. Try:

  • Comprimere il pacchetto prima di copiarlo nell'archivio immagini.Compress the package before copying to the image store. La compressione riduce le dimensioni e il numero di file, cosa che a sua volta riduce il traffico e le operazioni di Service Fabric.The compression reduces the size and the number of files, which in turn reduces the amount of traffic and work that Service Fabric must perform. L'operazione di caricamento potrebbe risultare più lenta (specialmente se si include il tempo di compressione), ma registrazione e relativo annullamento del tipo dell'applicazione saranno più veloci.The upload operation may be slower (especially if you include the compression time), but register and un-register the application type are faster.
  • Specificare un timeout maggiore per l'API ProvisionApplicationAsync con il parametro timeout.Specify a larger timeout for ProvisionApplicationAsync API with timeout parameter.

Distribuire un pacchetto di applicazione con numerosi fileDeploy application package with many files

Problema: si verifica un timeout di ProvisionApplicationAsync per un pacchetto di applicazione con molti file (nell'ordine di migliaia).Issue: ProvisionApplicationAsync times out for an application package with many files (order of thousands). Soluzione:Try:

Esempio di codiceCode example

L'esempio seguente copia un pacchetto dell'applicazione nell'archivio immagini, effettua il provisioning del tipo di applicazione, crea un'istanza dell'applicazione, crea un'istanza del servizio, rimuove l'istanza dell'applicazione, annulla il provisioning del tipo di applicazione ed elimina il pacchetto dell'applicazione dall'archivio immagini.The following example copies an application package to the image store, provisions the application type, creates an application instance, creates a service instance, removes the application instance, un-provisions the application type, and deletes the application package from the image store.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Reflection;
using System.Threading.Tasks;

using System.Fabric;
using System.Fabric.Description;
using System.Threading;

namespace ServiceFabricAppLifecycle
{
class Program
{
static void Main(string[] args)
{

    string clusterConnection = "localhost:19000";
    string appName = "fabric:/MyApplication";
    string appType = "MyApplicationType";
    string appVersion = "1.0.0";
    string serviceName = "fabric:/MyApplication/Stateless1";
    string imageStoreConnectionString = "file:C:\\SfDevCluster\\Data\\ImageStoreShare";
    string packagePathInImageStore = "MyApplication";
    string packagePath = "C:\\Users\\username\\Documents\\Visual Studio 2017\\Projects\\MyApplication\\MyApplication\\pkg\\Debug";
    string serviceType = "Stateless1Type";

    // Connect to the cluster.
    FabricClient fabricClient = new FabricClient(clusterConnection);

    // Copy the application package to a location in the image store
    try
    {
        fabricClient.ApplicationManager.CopyApplicationPackage(imageStoreConnectionString, packagePath, packagePathInImageStore);
        Console.WriteLine("Application package copied to {0}", packagePathInImageStore);
    }
    catch (AggregateException ae)
    {
        Console.WriteLine("Application package copy to Image Store failed: ");
        foreach (Exception ex in ae.InnerExceptions)
        {
            Console.WriteLine("HResult: {0} Message: {1}", ex.HResult, ex.Message);
        }
    }

    // Provision the application.  "MyApplicationV1" is the folder in the image store where the application package is located. 
    // The application type with name "MyApplicationType" and version "1.0.0" (both are found in the application manifest) 
    // is now registered in the cluster.            
    try
    {
        fabricClient.ApplicationManager.ProvisionApplicationAsync(packagePathInImageStore).Wait();

        Console.WriteLine("Provisioned application type {0}", packagePathInImageStore);
    }
    catch (AggregateException ae)
    {
        Console.WriteLine("Provision Application Type failed:");

        foreach (Exception ex in ae.InnerExceptions)
        {
            Console.WriteLine("HResult: {0} Message: {1}", ex.HResult, ex.Message);
        }
    }

    // Delete the application package from a location in the image store.
    try
    {
        fabricClient.ApplicationManager.RemoveApplicationPackage(imageStoreConnectionString, packagePathInImageStore);
        Console.WriteLine("Application package removed from {0}", packagePathInImageStore);
    }
    catch (AggregateException ae)
    {
        Console.WriteLine("Application package removal from Image Store failed: ");
        foreach (Exception ex in ae.InnerExceptions)
        {
            Console.WriteLine("HResult: {0} Message: {1}", ex.HResult, ex.Message);
        }
    }

    //  Create the application instance.
    try
    {
        ApplicationDescription appDesc = new ApplicationDescription(new Uri(appName), appType, appVersion);
        fabricClient.ApplicationManager.CreateApplicationAsync(appDesc).Wait();
        Console.WriteLine("Created application instance of type {0}, version {1}", appType, appVersion);
    }
    catch (AggregateException ae)
    {
        Console.WriteLine("CreateApplication failed.");
        foreach (Exception ex in ae.InnerExceptions)
        {
            Console.WriteLine("HResult: {0} Message: {1}", ex.HResult, ex.Message);
        }
    }

    // Create the stateless service description.  For stateful services, use a StatefulServiceDescription object.
    StatelessServiceDescription serviceDescription = new StatelessServiceDescription();
    serviceDescription.ApplicationName = new Uri(appName);
    serviceDescription.InstanceCount = 1;
    serviceDescription.PartitionSchemeDescription = new SingletonPartitionSchemeDescription();
    serviceDescription.ServiceName = new Uri(serviceName);
    serviceDescription.ServiceTypeName = serviceType;

    // Create the service instance.  If the service is declared as a default service in the ApplicationManifest.xml,
    // the service instance is already running and this call will fail.
    try
    {
        fabricClient.ServiceManager.CreateServiceAsync(serviceDescription).Wait();
        Console.WriteLine("Created service instance {0}", serviceName);
    }
    catch (AggregateException ae)
    {
        Console.WriteLine("CreateService failed.");
        foreach (Exception ex in ae.InnerExceptions)
        {
            Console.WriteLine("HResult: {0} Message: {1}", ex.HResult, ex.Message);
        }
    }

    // Delete a service instance.
    try
    {
        DeleteServiceDescription deleteServiceDescription = new DeleteServiceDescription(new Uri(serviceName));

        fabricClient.ServiceManager.DeleteServiceAsync(deleteServiceDescription);
        Console.WriteLine("Deleted service instance {0}", serviceName);
    }
    catch (AggregateException ae)
    {
        Console.WriteLine("DeleteService failed.");
        foreach (Exception ex in ae.InnerExceptions)
        {
            Console.WriteLine("HResult: {0} Message: {1}", ex.HResult, ex.Message);
        }
    }

    // Delete an application instance from the application type.
    try
    {
        DeleteApplicationDescription deleteApplicationDescription = new DeleteApplicationDescription(new Uri(appName));

        fabricClient.ApplicationManager.DeleteApplicationAsync(deleteApplicationDescription).Wait();
        Console.WriteLine("Deleted application instance {0}", appName);
    }
    catch (AggregateException ae)
    {
        Console.WriteLine("DeleteApplication failed.");
        foreach (Exception ex in ae.InnerExceptions)
        {
            Console.WriteLine("HResult: {0} Message: {1}", ex.HResult, ex.Message);
        }
    }

    // Un-provision the application type.
    try
    {
        fabricClient.ApplicationManager.UnprovisionApplicationAsync(appType, appVersion).Wait();
        Console.WriteLine("Un-provisioned application type {0}, version {1}", appType, appVersion);
    }
    catch (AggregateException ae)
    {
        Console.WriteLine("Un-provision application type failed: ");
        foreach (Exception ex in ae.InnerExceptions)
        {
            Console.WriteLine("HResult: {0} Message: {1}", ex.HResult, ex.Message);
        }
    }

    Console.WriteLine("Hit enter...");
    Console.Read();
}        
}
}

Passaggi successiviNext steps

Aggiornamento di un'applicazione di infrastruttura di serviziService Fabric application upgrade

Introduzione all'integrità di Service FabricService Fabric health introduction

Eseguire la diagnosi e la risoluzione dei problemi di un servizio di Service FabricDiagnose and troubleshoot a Service Fabric service

Modellare un'applicazione in Service FabricModel an application in Service Fabric