Inserire un'applicazione in un pacchettoPackage an application

L'articolo descrive come inserire un'applicazione di Service Fabric in un pacchetto e prepararla per la distribuzione.This article describes how to package a Service Fabric application and make it ready for deployment.

Layout del pacchettoPackage layout

Il manifesto dell'applicazione, uno o più manifesti dei servizi e gli altri file del pacchetto necessari devono essere organizzati in un layout specifico per la distribuzione in un cluster di Service Fabric.The application manifest, one or more service manifests, and other necessary package files must be organized in a specific layout for deployment into a Service Fabric cluster. I manifesti di esempio di questo articolo dovrebbero essere organizzati nella struttura di directory seguente:The example manifests in this article would need to be organized in the following directory structure:

PS D:\temp> tree /f .\MyApplicationType

D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat

Le cartelle sono denominate in modo da corrispondere agli attributi Name di ogni elemento corrispondente.The folders are named to match the Name attributes of each corresponding element. Se ad esempio il manifesto del servizio contenesse due pacchetti di codice denominati MyCodeA e MyCodeB, dovrebbero esistere due cartelle con gli stessi nomi contenenti i file binari necessari per ogni pacchetto di codice.For example, if the service manifest contained two code packages with the names MyCodeA and MyCodeB, then two folders with the same names would contain the necessary binaries for each code package.

Usare SetupEntryPointUse SetupEntryPoint

Gli scenari tipici per l'utilizzo di SetupEntryPoint sono quando è necessario eseguire un file eseguibile prima dell'avvio del servizio o quando è necessario eseguire un'operazione con privilegi elevati.Typical scenarios for using SetupEntryPoint are when you need to run an executable before the service starts or you need to perform an operation with elevated privileges. Ad esempio: For example:

  • Impostazione e inizializzazione di variabili di ambiente necessari per il file eseguibile del servizio.Setting up and initializing environment variables that the service executable needs. Questo non è limitato solo agli eseguibili scritti tramite i modelli di programmazione di Service Fabric.It is not limited to only executables written via the Service Fabric programming models. Ad esempio, npm.exe richiede alcune variabili di ambiente configurate per la distribuzione di un'applicazione node.js.For example, npm.exe needs some environment variables configured for deploying a node.js application.
  • Impostazione del controllo di accesso mediante l'installazione di certificati di sicurezza.Setting up access control by installing security certificates.

Per altre informazioni su come configurare SetupEntryPoint, vedere Configurare i criteri per il punto di ingresso dell'installazione del servizioFor more information on how to configure the SetupEntryPoint, see Configure the policy for a service setup entry point

ConfigurareConfigure

Creare un pacchetto mediante Visual StudioBuild a package by using Visual Studio

Se si usa Visual Studio 2015 per creare un'applicazione, è possibile usare il comando Pacchetto per creare automaticamente un pacchetto corrispondente al layout descritto precedentemente.If you use Visual Studio 2015 to create your application, you can use the Package command to automatically create a package that matches the layout described above.

Per creare un pacchetto, fare clic con il pulsante destro sul progetto dell'applicazione in Esplora soluzioni e scegliere il comando Pacchetto, come mostrato di seguito:To create a package, right-click the application project in Solution Explorer and choose the Package command, as shown below:

Inserire un'applicazione in un pacchetto con Visual Studio

Dopo avere completato la creazione del pacchetto, è possibile vedere la posizione del pacchetto nella finestra Output .When packaging is complete, you can find the location of the package in the Output window. Il passaggio di creazione del pacchetto viene eseguito automaticamente con la distribuzione o il debug di un'applicazione in Visual Studio.The packaging step occurs automatically when you deploy or debug your application in Visual Studio.

Creare un pacchetto dalla riga di comandoBuild a package by command line

È anche possibile creare un pacchetto dell'applicazione a livello di codice usando msbuild.exe.It is also possible to programmatically package up your application using msbuild.exe. Tale operazione viene eseguita da Visual Studio e quindi l'output è lo stesso.Under the hood, Visual Studio is running it so the output is same.

D:\Temp> msbuild HelloWorld.sfproj /t:Package

Testare il pacchettoTest the package

È possibile verificare la struttura del pacchetto in modalità locale tramite PowerShell usando il comando Test-ServiceFabricApplicationPackage .You can verify the package structure locally through PowerShell by using the Test-ServiceFabricApplicationPackage command. Questo comando consente di verificare i problemi di analisi dei manifesti e tutti i riferimenti.This command checks for manifest parsing issues and verify all references. Questo comando si limita a verificare la correttezza strutturale delle directory e i file nel pacchetto.This command only verifies the structural correctness of the directories and files in the package. Non verifica il codice o i contenuti del pacchetto di dati oltre a controllare che tutti i file necessari siano presenti.It doesn't verify any of the code or data package contents beyond checking that all necessary files are present.

PS D:\temp> Test-ServiceFabricApplicationPackage .\MyApplicationType
False
Test-ServiceFabricApplicationPackage : The EntryPoint MySetup.bat is not found.
FileName: C:\Users\servicefabric\AppData\Local\Temp\TestApplicationPackage_7195781181\nrri205a.e2h\MyApplicationType\MyServiceManifest\ServiceManifest.xml

Questo errore indica che il file MySetup.bat a cui viene fatto riferimento nel manifesto del servizio SetupEntryPoint manca nel pacchetto di codice.This error shows that the MySetup.bat file referenced in the service manifest SetupEntryPoint is missing from the code package. Dopo aver aggiunto il file mancante, la verifica dell'applicazione ha esito positivo:After the missing file is added, the application verification passes:

PS D:\temp> tree /f .\MyApplicationType

D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │       MySetup.bat
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat

PS D:\temp> Test-ServiceFabricApplicationPackage .\MyApplicationType
True
PS D:\temp>

Se l'applicazione include parametri applicazione definiti, è possibile passarli in Test-ServiceFabricApplicationPackage per una convalida appropriata.If your application has application parameters defined, you can pass them in Test-ServiceFabricApplicationPackage for proper validation.

Se si conosce il cluster in cui verrà distribuita l'applicazione, si consiglia di passarlo nel parametro ImageStoreConnectionString.If you know the cluster where the application will be deployed, it is recommended you pass in the ImageStoreConnectionString parameter. In questo caso, il pacchetto viene convalidato rispetto alle versioni precedenti dell'applicazione già in esecuzione nel cluster.In this case, the package is also validated against previous versions of the application that are already running in the cluster. Ad esempio, la convalida può rilevare se sia già stato distribuito un pacchetto con la stessa versione ma con contenuti differenti.For example, the validation can detect whether a package with the same version but different content was already deployed.

Dopo aver correttamente inserito l'applicazione nel pacchetto e aver eseguito la convalida, può essere opportuno comprimere il pacchetto per velocizzare le operazioni di distribuzione.Once the application is packaged correctly and passes validation, consider compressing the package for faster deployment operations.

Comprimere un pacchettoCompress a package

Quando un pacchetto è di grandi dimensioni o dispone di molti file, è possibile comprimerlo per velocizzare la distribuzione.When a package is large or has many files, you can compress it for faster deployment. La compressione riduce il numero di file e le dimensioni del pacchetto.Compression reduces the number of files and the package size. Nel caso di un pacchetto dell'applicazione compresso, il relativo caricamento può richiedere tempi più lunghi rispetto al caso di un pacchetto non compresso, soprattutto se la compressione viene eseguita durante la copia.For a compressed application package, uploading the application package may take longer compared to uploading the uncompressed package, especially if compression is done as part of copy. Con la compressione, le operazioni di registrazione e annullamento della registrazione del tipo di applicazione sono più veloci.With compression, registering and un-registering the application type are faster.

Il meccanismo di distribuzione è lo stesso per i pacchetti compressi e non.The deployment mechanism is same for compressed and uncompressed packages. Se il pacchetto è compresso, viene archiviato come tale nell'archivio immagini del cluster e viene decompresso nel nodo prima dell'esecuzione dell'applicazione.If the package is compressed, it is stored as such in the cluster image store and it's uncompressed on the node before the application is run. La compressione sostituisce il pacchetto di Service Fabric valido con la versione compressa.The compression replaces the valid Service Fabric package with the compressed version. La cartella deve fornire le autorizzazioni di scrittura.The folder must allow write permissions. La compressione di un pacchetto già compresso non apporta modifiche.Running compression on an already compressed package yields no changes.

È possibile comprimere un pacchetto eseguendo il comando Copy-ServiceFabricApplicationPackage con lo switch CompressPackage.You can compress a package by running the Powershell command Copy-ServiceFabricApplicationPackage with CompressPackage switch. È possibile decomprimere il pacchetto con lo stesso comando, usando lo switch UncompressPackage.You can uncompress the package with the same command, using UncompressPackage switch.

Il comando seguente comprime il pacchetto senza copiarlo nell'archivio immagini.The following command compresses the package without copying it to the image store. È possibile copiare un pacchetto compresso in uno o più cluster Service Fabric, in base alle esigenze, us il comando Copy-ServiceFabricApplicationPackage senza il flag SkipCopy.You can copy a compressed package to one or more Service Fabric clusters, as needed, using Copy-ServiceFabricApplicationPackage without the SkipCopy flag. Ora il pacchetto include i file compressi per i pacchetti code, config e data.The package now includes zipped files for the code, config, and data packages. Il manifesto dell'applicazione e i manifesti del servizio non vengono compressi, perché sono necessari per molte operazioni interne.The application manifest and the service manifests are not zipped, because they are needed for many internal operations. Ad esempio, la condivisione del pacchetto e l'estrazione del nome e della versione del tipo di applicazione per determinate convalide sono tutte operazioni che richiedono l'accesso ai manifesti.For example, package sharing, application type name and version extraction for certain validations all need to access the manifests. La compressione dei manifesti renderebbe inefficienti tali operazioni.Zipping the manifests would make these operations inefficient.

PS D:\temp> tree /f .\MyApplicationType

D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
    │   ServiceManifest.xml
    │
    ├───MyCode
    │       MyServiceHost.exe
    │       MySetup.bat
    │
    ├───MyConfig
    │       Settings.xml
    │
    └───MyData
            init.dat
PS D:\temp> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath .\MyApplicationType -CompressPackage -SkipCopy

PS D:\temp> tree /f .\MyApplicationType

D:\TEMP\MYAPPLICATIONTYPE
│   ApplicationManifest.xml
│
└───MyServiceManifest
       ServiceManifest.xml
       MyCode.zip
       MyConfig.zip
       MyData.zip

In alternativa è possibile comprimere e copiare il pacchetto con Copy-ServiceFabricApplicationPackage in un unico passaggio.Alternatively, you can compress and copy the package with Copy-ServiceFabricApplicationPackage in one step. Se il pacchetto è grande, specificare un timeout sufficiente per consentire la compressione del pacchetto e il caricamento nel cluster.If the package is large, provide a high enough timeout to allow time for both the package compression and the upload to the cluster.

PS D:\temp> Copy-ServiceFabricApplicationPackage -ApplicationPackagePath .\MyApplicationType -ApplicationPackagePathInImageStore MyApplicationType -ImageStoreConnectionString fabric:ImageStore -CompressPackage -TimeoutSec 5400

Internamente, Service Fabric calcola i checksum per la convalida dei pacchetti dell'applicazione.Internally, Service Fabric computes checksums for the application packages for validation. Quando si usa la compressione, i checksum vengono calcolati nelle versioni compresse di ciascun pacchetto.When using compression, the checksums are computed on the zipped versions of each package. La generazione di un nuovo file zip dal pacchetto dell'applicazione crea checksum diversi.Generating a new zip from the same application package creates different checksums. Per evitare errori di convalida, usare il provisioning di un pacchetto Diff.To prevent validation errors, use diff provisioning. Con questa opzione, non includere nella nuova versione i pacchetti rimasti invariati.With this option, do not include the unchanged packages in the new version. Al contrario, fare riferimento a questi pacchetti direttamente dal nuovo manifesto del servizio.Instead, reference them directly from the new service manifest.

Se il provisioning del pacchetto Diff non è un'opzione percorribile ed è necessario includere i pacchetti, generare nuove versioni per i pacchetti code, config e data per evitare checksum non corrispondenti.If diff provisioning is not an option and you must include the packages, generate new versions for the code, config, and data packages to avoid checksum mismatch. La generazione di nuove versioni dei pacchetti rimasti invariati è necessaria quando si usa un pacchetto compresso, indipendentemente dal fatto che la versione precedente usi o meno la compressione.Generating new versions for unchanged packages is necessary when a compressed package is used, regardless of whether previous version uses compression or not.

Il pacchetto è ora corretto, convalidato e compresso (se necessario). Pertanto, è pronto per la distribuzione in uno o più cluster di Service Fabric.The package is now packaged correctly, validated, and compressed (if needed), so it is ready for deployment to one or more Service Fabric clusters.

Comprimere i pacchetti quando si distribuisce con Visual StudioCompress packages when deploying using Visual Studio

È possibile indicare a Visual Studio di comprimere i pacchetti in fase di distribuzione, aggiungendo l'elemento CopyPackageParameters al profilo di pubblicazione, e di impostare l'attributo CompressPackage su true.You can instruct Visual Studio to compress packages on deployment, by adding the CopyPackageParameters element to your publish profile, and set the CompressPackage attribute to true.

    <PublishProfile xmlns="http://schemas.microsoft.com/2015/05/fabrictools">
        <ClusterConnectionParameters ConnectionEndpoint="mycluster.westus.cloudapp.azure.com" />
        <ApplicationParameterFile Path="..\ApplicationParameters\Cloud.xml" />
        <CopyPackageParameters CompressPackage="true"/>
    </PublishProfile>

Creare un file sfpkgCreate an sfpkg

A partire dalla versione 6.1, Service Fabric consente di eseguire il provisioning da un archivio esterno.Starting with version 6.1, Service Fabric allows provisioning from an external store. Con questa opzione, il pacchetto dell'applicazione non deve essere copiato nell'archivio immagini.With this option, the application package doesn't have to be copied to the image store. Al contrario, è possibile creare un file sfpkg e caricarlo in un archivio esterno, quindi specificare l'URI del download in Service Fabric durante il provisioning.Instead, you can create an sfpkg and upload it to an external store, then provide the download URI to Service Fabric when provisioning. È possibile eseguire il provisioning dello stesso pacchetto in più cluster.The same package can be provisioned to multiple clusters. Il provisioning dall'archivio esterno consente di ridurre i tempi necessari per copiare il pacchetto in ogni cluster.Provisioning from the external store saves the time needed to copy the package to each cluster.

sfpkg è un file zip con estensione sfpkg che contiene il pacchetto dell'applicazione iniziale.The sfpkg file is a zip that contains the initial application package and has the extension ".sfpkg". All'interno, il pacchetto dell'applicazione può essere compresso o meno.Inside the zip, the application package can be compressed or uncompressed. La compressione del pacchetto dell'applicazione all'interno del file zip viene eseguita a livello di codice, configurazione e pacchetto dati, come illustrato in precedenza.The compression of the application package inside the zip is done at code, config, and data package levels, as mentioned earlier.

Per creare un file sfpkg, iniziare con una cartella contenente il pacchetto dell'applicazione originale, compresso o meno.To create an sfpkg, start with a folder that contains the original application package, compressed or not. Usare quindi una qualsiasi utilità per comprimere la cartella con estensione sfpkg,Then, use any utility to zip the folder with the extension ".sfpkg". ad esempio ZipFile.CreateFromDirectory.For example, use ZipFile.CreateFromDirectory.

ZipFile.CreateFromDirectory(appPackageDirectoryPath, sfpkgFilePath);

Il file sfpkg deve essere caricato nell'archivio esterno fuori banda, all'esterno di Service Fabric.The sfpkg must be uploaded to the external store out of band, outside of Service Fabric. L'archivio esterno può essere qualsiasi archivio che espone un endpoint REST http o https.The external store can be any store that exposes a REST http or https endpoint. Durante il provisioning, Service Fabric esegue un'operazione GET per scaricare il pacchetto dell'applicazione sfpkg, pertanto l'archivio deve consentire l'accesso in lettura per il pacchetto.During provisioning, Service Fabric executes a GET operation to download the sfpkg application package, so the store must allow READ access for the package.

Per eseguire il provisioning del pacchetto, usare il provisioning esterno, che richiede l'URI del download e le informazioni sul tipo di applicazione.To provision the package, use external provision, which requires the download URI and the application type information.

Nota

Il provisioning basato sul percorso relativo dell'archivio immagini non supporta attualmente i file sfpkg.Provisioning based on image store relative path doesn't currently support sfpkg files. Di conseguenza, il file sfpkg non deve essere copiato nell'archivio immagini.Therefore, the sfpkg should not be copied to the image store.

Passaggi successiviNext steps

Distribuire e rimuovere applicazioni con PowerShell: descrive come usare PowerShell per gestire le istanze dell'applicazioneDeploy and remove applications describes how to use PowerShell to manage application instances

Gestire i parametri dell'applicazione per più ambienti: descrive come configurare parametri e variabili di ambiente per istanze di applicazione diverse.Managing application parameters for multiple environments describes how to configure parameters and environment variables for different application instances.

Configurare i criteri di sicurezza per l'applicazione: descrive come eseguire i servizi nell'ambito dei criteri di sicurezza per limitare l'accesso.Configure security policies for your application describes how to run services under security policies to restrict access.