Creació de paquets per a l'eina Package Deployer

El Package Deployer permet que els administradors puguin implementar paquets en instàncies del Microsoft Dataverse. Un paquet de Package Deployer pot consistir en algun o tots els elements següents:

• Un o més fitxers de la solució del Dataverse.
• Fitxers plans o de dades de configuració exportades des de l'eina Migració de la configuració. Per obtenir més informació sobre l'eina, vegeu Moure dades de configuració entre les instàncies i organitzacions amb l'eina Migració de la configuració.
• El codi personalitzat que es pot executar abans, durant o després d'implementar el paquet a la instància del Dataverse.
• Contingut HTML específic pel paquet que es pot mostrar al principi i al final del procés d'implementació. Aquest contingut pot ser útil per proporcionar una descripció de les solucions i fitxers que s'implementen en el paquet.

Requisits previs

• Assegureu-vos que teniu totes les solucions i altres fitxers preparats que voleu incloure al paquet.
• Visual Studio 2019 o posterior, o Visual Studio Codi.

Informació general del procés

Per crear un Package Deployer paquet, seguiu els passos següents.

Aquests passos es descriuen detalladament en aquest article.

Crear un projecte de paquet

El primer pas és crear un projecte de Visual Studio o MSBuild per al paquet. Per fer-ho, heu de tenir instal·lada una de les dues extensions d'eines disponibles a l'ordinador de desenvolupament. Si utilitzeu el Visual Studio Code, instal·leu la CLI de Microsoft Power Platform. En cas contrari, si utilitzeu Visual Studio 2019 o posterior, instal·leu Power Platform eines per a Visual Studio.

Seleccioneu la pestanya següent per esbrinar com crear un projecte amb l'extensió d'eines desitjada. Ambdues eines generen el projecte en un format semblant.

pac package init help
pac package init --outputDirectory DeploymentPackage

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

Afegir fitxers de paquet

Un cop creat un projecte de paquet, podeu començar a afegir-hi solucions i altres fitxers.

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

Configuració del paquet

Definiu la configuració dels paquets afegint informació sobre el vostre paquet al fitxer ImportConfig.xml del projecte. Consulteu Referència d'ImportConfig per obtenir un exemple i descripcions dels elements i atributs vàlids que s'utilitzaran.

Afegir codi personalitzat

Podeu afegir codi personalitzat que s'executi abans, durant i després d'importar el paquet a un entorn. Per a fer-ho, seguiu aquestes instruccions.

1. Editeu el fitxer PackageTemplate.cs (o PackageImportExtension.cs) a la carpeta arrel del projecte.

2. Al fitxer C#, podeu:

   1. Introduir el codi personalitzat que s'executarà en inicialitzar el paquet a la definició del mètode d'anul·lació d'InitializeCustomExtension.

      Aquest mètode es pot utilitzar per permetre als usuaris utilitzar els paràmetres de temps d'execució mentre s'executa un paquet. Com a desenvolupador, podeu afegir suport per a qualsevol paràmetre de temps d'execució al paquet mitjançant l'ús de la propietat RuntimeSettings sempre que tingueu codi per processar-la segons l'entrada de l'usuari.

      Per exemple, el codi de mostra següent habilita un paràmetre de temps d'execució anomenat SkipChecks per al paquet que té dos valors possibles: cert o fals. El codi d'exemple comprova si l'usuari ha especificat algun paràmetre en temps d'execució en executar Package Deployer (ja sigui mitjançant l'ús de la línia d'ordres o el PowerShell) i, a continuació, processa la informació de manera adequada. Si no s'especifica cap paràmetre de temps d'execució per a l'usuari mentre s'executa el paquet, el valor de la propietat RuntimeSettings serà nul.

      public override void InitializeCustomExtension()  
      {  
      // Do nothing.  
      
      // Validate the state of the runtime settings object.  
      if (RuntimeSettings != null)  
      {  
      PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
      foreach (var setting in RuntimeSettings)  
      {  
      PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
      }  
      
      // Check to see if skip checks is present.  
      if ( RuntimeSettings.ContainsKey("SkipChecks") )  
      {  
      bool bSkipChecks = false;  
      if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
      OverrideDataImportSafetyChecks = bSkipChecks;  
      }  
      }  
      else  
      PackageLog.Log("Runtime Settings not populated");  
      }  
      

      Aquest codi permet a l'administrador utilitzar la línia d'ordres o el cmdlet Import-CrmPackage per especificar si s'ometen els controls de seguretat durant l'execució de l'eina Package Deployer per importar el paquet. Més informació: Implementar paquets mitjançant el Package Deployer i el Windows PowerShell

   2. Introduir codi personalitzat per executar abans que les solucions s'importin a la definició de mètode de substitució PreSolutionImport per especificar si voleu mantenir o sobreescriure les personalitzacions mentre s'actualitza la solució especificada en una instància de destinació del Dataverse i si voleu activar automàticament complements i fluxos de treball.

   3. Utilitzeu la definició del mètode de substitució de RunSolutionUpgradeMigrationStep per dur a terme la transformació de dades o l'actualització entre dues versions d'una solució Aquest mètode només es crida si la solució que esteu important ja està present a la instància de destinació Dataverse .

      Aquesta funció espera els paràmetres següents:

      Paràmetre	Descripció
      solutionName	Nom de la solució
      oldVersion	Número de versió de la solució antiga
      newVersion	Número de versió de la solució nova
      oldSolutionId	GUID de la solució antiga.
      newSolutionId	GUID de la solució nova.

   4. Introduïu el codi personalitzat que s'executarà abans de completar-se la importació de la solució a la definició de substitució del mètode BeforeImportStage. Les dades d'exemple i alguns fitxers plans per a les solucions especificades al fitxer ImportConfig.xml s'importen abans que acabi la importació de la solució.

   5. Substituïu l'idioma seleccionat actualment per a la importació de dades de configuració mitjançant la definició del mètode de substitució de OverrideConfigurationDataFileLanguage. Si l'identificador de configuració regional especificat (LCID) de la llengua especificada no es troba a la llista de llengües disponibles del paquet, s'importa el fitxer de dades per defecte.

      Heu d'especificar les llengües disponibles per a les dades de configuració del node <cmtdatafiles> al fitxer ImportConfig.xml. El fitxer d'importació de dades de configuració per defecte s'especifica a l'atribut crmmigdataimportfile del fitxer ImportConfig.xml.

      Ometre les comprovacions de dades (OverrideDataImportSafetyChecks = true) pot ser efectiu aquí si esteu segur que la instància de destinació Dataverse no conté cap dada.

   6. Introduïu el codi personalitzat que s'executarà després de completar-se la importació a la definició de substitució del mètode AfterPrimaryImport>. Els fitxers plans restants que no s'importaven abans, abans que comencés la importació de la solució, s'importen ara.

   7. Canvieu el nom per defecte de la carpeta de paquets al nom del paquet que vulgueu. Per fer-ho, canvieu el nom de la carpeta PkgFolder (o PkgAssets) a la subfinestra Explorador de solucions i, a continuació, editeu el valor retornat a la propietat GetImportPackageDataFolderName.

      public override string GetImportPackageDataFolderName  
      {  
      get  
      {  
      // WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
      // Changing this name requires that you also change the correlating name in the Solution Explorer  
      return "PkgFolder";  
      }  
      }  
      

   8. Canvieu el nom del paquet editant el valor de retorn de la propietat GetNameOfImport.

      public override string GetNameOfImport(bool plural)  
      {  
      return "Package Short Name";  
      }  
      

      Aquest valor retornat és el nom del paquet que apareix a la pàgina de selecció de paquets de l'auxiliar Dynamics 365 Package Deployer .

   9. Canvieu la descripció del paquet editant el valor de retorn de la propietat GetImportPackageDescriptionText.

      
      public override string GetImportPackageDescriptionText  
      {  
      get { return "Package Description"; }  
      }  
      
      

      Aquest valor retornat és la descripció del paquet que apareix al costat del nom del paquet a la pàgina de selecció de paquets de l'auxiliar Package Deployer .

   10. Canvieu el nom llarg del paquet editant el valor de retorn de la propietat GetLongNameOfImport.

       
       public override string GetLongNameOfImport  
       {  
       get { return "Package Long Name"; }  
       }  
       
       

       El nom del paquet llarg apareix a la pàgina següent després d'haver seleccionat el paquet que voleu instal·lar.

3. A més, la funció i les variables següents estan disponibles per al paquet:

   Nom	Type	Descripció
   CreateProgressItem(String)	Function	S'utilitza per crear un element de progrés nou a la interfície d'usuari (IU).
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	S'utilitza per actualitzar el progrés creat per la trucada a CreateProgressItem(String). ProgressPanelItemStatus és una enumeració amb els valors següents: En marxa = 0 Completat = 1 Error = 2 Advertiment = 3 Desconegut = 4
   RaiseFailEvent(String, Exception)	Function	S'utilitza per provocar un error en la importació d'estat actual amb un missatge d'excepció.
   IsRoleAssoicatedWithTeam(Guid, Guid)	Function	S'utilitza per determinar si una funció està associada amb un equip especificat.
   IsWorkflowActive(Guid)	Function	S'utilitza per determinar si un flux de treball especificat està actiu.
   PackageLog	Punter de classe	Un punter a la interfície de registre inicialitzada per al paquet. Aquesta interfície s'utilitza en un paquet per registrar els missatges i les excepcions al fitxer d'historial del paquet.
   RootControlDispatcher	Propietat	Una interfície d'enviament utilitzada per permetre que el control pugui representar la seva pròpia interfície d'usuari durant la implementació del paquet. Utilitzeu aquesta interfície per ajustar tots els elements o ordres de la interfície d'usuari. És important comprovar si hi ha valors nuls en aquesta variable abans d'utilitzar-la, ja que pot ser que no estigui definida en un valor.
   CrmSvc	Propietat	Un punter a la classe CrmServiceClient que permet que paquet es dirigeixi al Dynamics 365 des del paquet. Utilitzeu aquest punter per executar els mètodes de l'SDK i altres accions en els mètodes que s'anul·len.
   DataImportBypass	Propietat	Especifiqueu si el Dynamics 365 Package Deployer omet totes les operacions d'importació de dades, com ara la importació de dades d'exemple del Dataverse, les dades planes i les dades exportades des de l'eina Migració de la configuració. Especifiqueu true o false. Per defecte és false.
   OverrideDataImportSafetyChecks	Propietat	Especifiqueu si Dynamics 365 Package Deployer evita algunes de les seves comprovacions de seguretat, cosa que ajuda a millorar el rendiment de la importació. Especifiqueu true o false. Per defecte és false. Heu de definir aquesta propietat true només si la instància de destinació Dataverse no conté cap dada.

4. Deseu el projecte. El pas següent és compilar el paquet.

Compilar i implementar

Les seccions següents descriuen com crear i desplegar un paquet.

Compilació

A continuació es descriu la creació del vostre paquet en funció de l'eina que utilitzeu.

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

El paquet es composa dels fitxers següents a la carpeta <Project>\Bin\Debug.

• <Carpeta> PackageName: El nom de la carpeta és el mateix que heu canviat per al nom de la carpeta del paquet al pas 2.g d'aquesta secció Afegeix codi personalitzat. Aquesta carpeta conté totes les solucions, dades de configuració, fitxers plans i el contingut del vostre paquet.

• <PackageName>.dll: l'assemblatge conté el codi personalitzat del paquet. Per defecte, el nom de l'assemblatge és el mateix que el nom del projecte del .

Implementa

Després de crear un paquet, podeu implementar-lo a la instància del Dataverse mitjançant l'eina Package Deployer, el Windows PowerShell o una ordre de CLI.

• Per implementar-la amb l'eina Package Deployer, primer descarregueu l'eina segons s'indica a les eines de desenvolupament del Dataverse. A continuació, seguiu la informació detallada sobre la implementació de paquets a l'article Implementar paquets mitjançant Package Deployer o Windows PowerShell.

• Per implementar utilitzant la CLI, utilitzeu l'ordre pac package deploy.

  > pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip
  

  Nota

  Per implementar un paquet en un entorn de destinació mitjançant la CLI, primer heu de configurar un perfil d'autenticació i seleccionar una organització. Més informació: pac auth create, pac org select

Procediments recomanats

A continuació es mostren alguns suggeriments de pràctiques recomanades que cal seguir quan es treballa amb paquets de Package Deployer.

Crear paquets

En crear paquets, els desenvolupadors han de:

• Assegureu-vos que els assemblatges de paquets estiguin signats.

Implementar paquets

En implementar paquets, els administradors del Dataverse han de fer el següent:

• Insistiu en els assemblatges de paquets signats per poder fer un seguiment d'un assemblatge fins al seu origen.
• Proveu el paquet en una instància de preproducció, preferiblement una imatge mirall de la instància de producció, abans d'executar-lo en una instància de producció.
• Feu una còpia de seguretat de la instància de producció abans de desplegar el paquet.

Consulteu també

Eina d'empaquetament de solucions