Creació de paquets per a l'eina Package Deployer

Package Deployer permet als administradors desplegar paquets en instàncies de 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.

Nota

Hi ha un altre tipus de paquet anomenat paquet de complements. Aquest tipus de paquet és per a conjunts dependents de complements i no té relació amb els paquets del Package Deployer.

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 Code.

Informació general sobre el procés

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

  • Crea un projecte de Visual Studio o MSBuild
  • Afegir solucions i altres fitxers al projecte
  • Actualitzar els fitxers HTML proporcionats (opcional)
  • Especificar els valors de configuració del paquet
  • Definir el codi personalitzat per al paquet
  • Crear i implementar el paquet

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 utilitzes Visual Studio Code, instal·la Microsoft Power Platform CLI. Si no, si utilitzes Visual Studio 2019 o posterior, instal·la les eines Power Platform 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.

Executeu l'ordre pac package init per crear el paquet inicial. Més informació: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

La sortida resultant de CLI conté les carpetes i els fitxers que es mostren a continuació. El nom de la carpeta "DeploymentPackage" s'utilitza aquí com a exemple.

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

Al projecte creat, cerqueu el fitxer de configuració ImportConfig.xml a la carpeta PkgAssets i el fitxer PackageImportExtension.cs. Modificareu aquests fitxers tal com es descriu més endavant en aquest article.

Afegir fitxers de paquet

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

Quan utilitzeu la CLI, podeu afegir paquets, solucions i referències externes al vostre projecte de paquet mitjançant una de les subordres add. Introduïu pac package help per veure la llista de subordres. Afegiu una solució al paquet.

> 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()  
{
  // 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ó: Desplega paquets utilitzant Package Deployer i 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. Substituïu el mètode OverrideSolutionImportDecision per retornar una enumeració UserRequestedImportAction controlant si la importació d'una solució s'ometrà, s'actualitzarà o s'actualitzarà (per defecte).

      public override UserRequestedImportAction OverrideSolutionImportDecision(
  string solutionUniqueName, Version organizationVersion,
  Version packageSolutionVersion, Version inboundSolutionVersion,
  Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
{
  return systemSelectedImportAction == 
      ImportAction.Import ? UserRequestedImportAction.ForceUpdate
      : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
      packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
      systemSelectedImportAction);
}

    5. 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ó.

    6. 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.

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

    8. Canvieu el nom per defecte de la carpeta de paquets al nom del paquet que vulgueu. Per fer-ho, reanomena la carpeta PkgFolder (o PkgAssets) al panell Solution Explorer, i després edita el valor de retorn sota la propietat GetImportPackageDataFolderName.

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

    9. 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 teu paquet que apareix a la pàgina de selecció de paquets a l'assistent Dynamics 365 Package Deployer.

    10. 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 .

    11. 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 Tipus 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ó.
    IsRoleAssociatedWithTeam(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 CrmServiceClient classe que permet que un paquet Dynamics 365'adreçi des de dins 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 Especifica si Dynamics 365 Package Deployer salta totes les operacions d'importació de dades, com ara importar dades de mostra de Dataverse, dades de fitxers plans i dades exportades des de l'eina de Migració de Configuració. Especifiqueu true o false. Per defecte és false.
    OverrideDataImportSafetyChecks Propietat Especifica 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.

Per construir un paquet creat amb la CLI, podries carregar el fitxer .csproj a Visual Studio, però en canvi utilitzarem la comanda dotnet i MSBuild. L'exemple següent assumeix que el directori de treball conté el fitxer *.csproj.

> dotnet publish

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

Si voleu, podeu consultar els detalls del paquet integrat.

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

Nota

Pots veure una carpeta .NET (per exemple, net472) que conté una carpeta pdpublie. Els fitxers DLL i altres fitxers de projecte són a la carpeta pdpublish.

  • <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-ho

Després de crear un paquet, pots desplegar-lo a la instància de Dataverse utilitzant l'eina Package Deployer, Windows PowerShell o una comanda 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ó, segueix la informació detallada sobre el desplegament de paquets a l'article Desplega paquets utilitzant 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

  • Last updated on