Pakettien luominen Package Deployer -työkalua varten

Package Deployerin avulla järjestelmänvalvojat voivat ottaa paketteja käyttöön Microsoft Dataverse esiintymissä. Package Deployer -paketti voi sisältää minkä tahansa tai kaikki seuraavista:

• Yhden tai useamman Dataverse ratkaisutiedoston.
• Tasatiedostot tai määrityksensiirtotyökalusta viety määritystietotiedosto. Lisätietoja työkalusta on kohdassa Määritystietojen siirtäminen esiintymien ja organisaatioiden välillä määrityksen siirtotyökalun avulla.
• Mukautettua koodia, joka voidaan suorittaa ennen paketin käyttöönottoa Dataverse -esiintymässä, sen aikana tai sen jälkeen.
• Pakettikohtaista HTML-sisältöä, joka voidaan näyttää käyttöönottoprosessin aluksi ja lopuksi. Tämä sisältö voi olla hyödyllistä, jotta saadaan tarjottua kuvaus ratkaisuista ja tiedostoista, jotka on otettu käyttöön paketissa.

Edellytykset

• Varmista, että sinulla on kaikki pakettiin lisättävät ratkaisutiedostot ja muut tiedostot.
• Visual Studio 2019 tai uudempi tai Visual Studio Code.

Prosessin yleiskuvaus

Voit luoda Package Deployer -paketin suorittamalla seuraavat vaiheet:

Tässä artikkelissa kuvataan nämä vaiheet yksityiskohtaisesti.

Luo pakettiprojekti

Luo ensin paketille Visual Studio- tai MSBuild-projekti. Jos haluat luoda projektin, asenna kehitystietokoneeseen kaksi työkalulaajennusta. Jos käytät Visual Studio Code, asenna Microsoft Power Platform CLI. Jos käytät Visual Studio 2019 tai uudempaa versiota, asenna Power Platform -työkalut Visual Studio varten.

Voit luoda projektin haluamallasi työkalulaajennuksella valitsemalla haluamasi välilehden seuraavassa osassa. Molemmat työkalut tulostavat projektin samassa muodossa.

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

Lisää pakettitiedostot

Kun olet luonut pakettiprojektin, voit aloittaa ratkaisujen ja muiden tiedostojen lisäämisen tähän projektiin.

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

Paketin määrittäminen

Määritä paketin määritys lisäämällä tietoja paketistasi projektin ImportConfig.xml-tiedostoon. Katso esimerkki ja kelvollisten elementtien ja määritteiden kuvaukset kohdasta TuontiMääritysviittaus.

Lisää mukautettu koodi

Voit lisätä mukautetun koodin, joka suoritetaan ennen paketin ympäristöön tuomista, sen aikana ja sen jälkeen. Jos haluat lisätä mukautetun koodin, toimi seuraavasti:

1. Muokkaa PackageTemplate.cs tai PackageImportExtension.cs -tiedostoa projektin pääkansiossa.

2. C#-tiedostossa voit:

   1. Anna mukautettu koodi, joka suoritetaan, kun paketin alustaa ohitusmenetelmän InitializeCustomExtensionmäärityksessä .

      Tämän menetelmän avulla voit antaa käyttäjien käyttää suorituksenaikaisia parametreja paketin suorittamisen aikana. Kehittäjänä voit lisätä tuen mille tahansa suoritusparametrille pakettiisi RuntimeSettings-ominaisuuden avulla, kunhan sinulla on koodi sen käsittelemiseksi käyttäjäsyötteen perusteella.

      Esimerkiksi seuraava mallikoodi ottaa käyttöön paketille suoritusparametrin, jonka nimi on SkipChecks ja jolla on kaksi mahdollista arvoa: tosi ja epätosi. Mallikoodi tarkistaa, määrittääkö käyttäjä mitään suorituksenaikaisia parametreja Package Deployerin suorittamisen aikana (joko komentorivin tai PowerShellin avulla), ja käsittelee sitten tiedot vastaavasti. Jos käyttäjä ei määritä suorituksenaikaista parametria paketin suorittamisen aikana, ominaisuuden RuntimeSettings arvo on tyhjäarvo.

      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");
        }  
      } 
      

      Tämän koodin avulla järjestelmänvalvoja voi käyttää komentoriviä tai Import-CrmPackage cmdlet-komentoa sen määrittämiseen, ohitetaanko suojaustarkistukset, kun Package Deployer -työkalua suoritetaan paketin tuomiseksi. Katso lisätietoja kohdasta Pakettien käyttöönotto Package Deployerilla ja Windows PowerShellillä.

   2. Kirjoita mukautettu koodi, joka suoritetaan ennen ratkaisujen tuomista ohitusmenetelmämääritelmässä PreSolutionImport. Tämän menetelmän avulla voit määrittää, haluatko ylläpitää tai korvata mukautuksia päivitettäessä määritettyä ratkaisua Dataverse-kohdeesiintymässä ja aktivoida laajennukset ja työnkulut automaattisesti.

   3. Käytä kohteen ohitusmenetelmämääritystä RunSolutionUpgradeMigrationStep tietojen muuntamiseen tai päivittämiseen ratkaisun kahden version välille. Tämä menetelmä suoritetaan vain, jos tuomassasi ratkaisussa on jo Dataverse-kohdeesiintymä.

      Tämä toiminto edellyttää seuraavia parametreja:

      Parametri	Description
      solutionName	Ratkaisun nimi
      oldVersion	Vanhan ratkaisun versionumero
      newVersion	Uuden ratkaisun versionumero
      oldSolutionId	Vanhan ratkaisun GUID
      newSolutionId	Uuden ratkaisun GUID

   4. Ohita menetelmä OverrideSolutionImportDecision , jolla palautetaan UserRequestedImportAction-luettelointi , joka määrittää, ohitetaanko, päivitetäänkö vai päivitetäänkö ratkaisun tuonti (oletusarvo).

      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. Anna mukautettu koodi, joka suoritetaan, ennen kuin ratkaisun tuonti valmistuu -menetelmän ohitusmäärityksessä BeforeImportStage . Työkalu tuo mallitiedot ja joitakin tietuetiedostoja tiedostossa ImportConfig.xml määritetyille ratkaisuille ennen ratkaisun tuomisen valmistumista.

   6. Ohita tällä hetkellä valittu kieli tietojen tuonnissa käyttämällä ohitusmenetelmän määritystä OverrideConfigurationDataFileLanguage. Jos määritetyn kielen määritettyä aluekohtaisten asetusten tunnusta (LCID) ei löydy paketin käytettävissä olevien kielten luettelosta, datatiedoston oletustuonti.

      Määritystietojen käytettävissä olevat tiedot määritetään <cmtdatafiles>-tiedoston ImportConfig.xml-solmussa. Määrität oletusarvoiset määritystietojen tuontitiedoston crmmigdataimportfile tiedoston määritteessä ImportConfig.xml .

      Tietojen tarkistuksen ohitus ( OverrideDataImportSafetyChecks = tosi) voi olla hyödyksi tässä, jos olet varma, että kohteena oleva Dataverse -esiintymä ei sisällä tietoja.

   7. Anna mukautettu koodi, joka suoritetaan sen jälkeen, kun tuonti on suoritettu -metodin ohituksen määrityksessä AfterPrimaryImport . Työkalu tuo jäljellä olevat tietuetiedostot, joita ei ollut tuotu aiemmin, ennen ratkaisun tuonnin aloittamista.

   8. Muuta pakettikansiosi oletusnimi haluamaasi muotoon. Voit tehdä tämän nimeämällä PkgFolder uudelleen- tai PkgAssets-kansion ratkaisunhallinta-ruudussa ja muokkaalla sitten -ominaisuuden alla olevaa palautusarvoaGetImportPackageDataFolderName.

      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. Muuta paketin nimeä muokkaamalla GetNameOfImport -ominaisuuden alaista palautusarvoa.

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

      Tämä palautettu arvo on paketin nimi, joka näkyy paketin valintasivulla ohjatussa Dynamics 365 Package Deployer -toiminnossa.

   10. Muuta paketin kuvausta muokkaamalla GetImportPackageDescriptionText -ominaisuuden alaista palautusarvoa.

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

       Tämä palautettu arvo on se paketin kuvaus, joka tulee näkyviin paketin nimen vieressä ohjatun Package Deployer -toiminnon paketinvalintasivulla.

   11. Muuta paketin pitkää nimeä muokkaamalla GetLongNameOfImport -ominaisuuden alaista palautusarvoa.

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

       Paketin pitkä nimi tulee näkyviin seuraavalla sivulla, kun olet valinnut asennettavan paketin.

3. Paketilla on myös pääsy seuraaviin funktioihin ja muuttujiin:

   Nimi	Kirjoita	Description
   CreateProgressItem(String)	Toiminto	Luo uuden edistymiskohteen käyttöliittymään.
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Toiminto	Päivittää -kutsun CreateProgressItem(String)luoman edistymisen. ProgressPanelItemStatus on luettelo, jolla on seuraavat arvot: Työskentelee = 0 Valmis = 1 Epäonnistui = 2 Varoitus = 3 Tuntematon = 4
   RaiseFailEvent(String, Exception)	Toiminto	Epäonnistuu nykyisen tilan tuonnissa poikkeussanoman kanssa.
   IsRoleAssociatedWithTeam(Guid, Guid)	Toiminto	Määrittää, liittyykö rooli määritettyyn tiimiin.
   IsWorkflowActive(Guid)	Toiminto	Määrittää, onko määritetty työnkulku aktiivinen.
   PackageLog	Luokkaosoitin	Osoitin paketin alustettuun kirjausrajapintaan. Paketti käyttää tätä liittymää viestien ja poikkeusten kirjaamiseen pakettilokitiedostoon.
   RootControlDispatcher	Attribuutti	Lähetysliittymä, jota ohjausobjektisi käyttää oman käyttöliittymän hahmontamiseen paketin käyttöönoton aikana. Tällä rajapinnalla voit paketoida mitä tahansa käyttöliittymän elementtejä tai komentoja. Tarkista tämä muuttuja nolla-arvojen osalta ennen sen käyttämistä, koska sitä ei ehkä ole määritetty arvoon.
   CrmSvc	Attribuutti	Osoitin CrmServiceClient luokkaan, jonka avulla paketti voi käsitellä Dynamics 365 paketin sisältä. Tämän osoittimen avulla voit suorittaa SDK-menetelmiä ja muita toimintoja ohitetuissa menetelmissä.
   DataImportBypass	Attribuutti	Määritä, ohittaako Dynamics 365 Package Deployer kaikki tietojen tuontitoiminnot, kuten Dataverse-mallitietojen tuonnin, tietuetiedostotiedot ja Määritysten siirto -työkalusta viedyt tiedot. Määritä true tai false. Oletusarvo on false.
   OverrideDataImportSafetyChecks	Attribuutti	Määritä, ohittaako Dynamics 365 Package Deployer osan turvallisuustarkistuksistaan, mikä auttaa parantamaan tuonnin suorituskykyä. Määritä true tai false. Oletusarvo on false. Määritä tämän ominaisuuden arvoksi true vain, jos Dataverse-kohdeesiintymä ei sisällä mitään tietoja.

4. Tallenna projekti. Seuraavana vaiheena on paketin koonti.

Koonti ja käyttöönotto

Seuraavissa osissa kuvaillaan paketin rakentamista ja käyttöönottoa.

Muodosta

Seuraavissa osioissa kuvataan, miten voit luoda paketin käyttämästäsi työkalusta riippuen.

> 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

Paketti koostuu seuraavista -kansiossa olevista *<Project>*\Bin\Debug tiedostoista:

• <PackageName> kansio: Kansion nimi vastaa nimeä, jonka valitsit pakettikansiollesi Lisää mukautettu koodi -osion vaiheessa 2.g. Tämä kansio sisältää kaikki ratkaisut, määritystiedot, tietuetiedostot ja pakettisi sisällön.

• <PackageName>.dll: Kokoonpano sisältää paketin mukautetun koodin. Kokoonpanon nimi vastaa oletusarvoisesti projektin nimeä.

Ota käyttöön

Kun olet luonut paketin, ota se käyttöön Dataverse-esiintymässä käyttämällä Package Deployer -työkalua, Windows PowerShelliä tai komentoa CLI.

• Jos haluat ottaa käyttöönoton käyttöön Package Deployer -työkalun avulla, lataa ensin työkalu Kohdassa Dataversen kehitystyökalut kuvatulla tavalla. Seuraa seuraavaksi paketin käyttöönottoa koskevia yksityiskohtaisia tietoja artikkelissa Deploy-paketit, joissa on käytössä Package Deployer tai Windows PowerShell.

• Käytä komentoa käyttöönottoon komentorivikäyttöliittymän pac package deploy avulla.

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

  Muistio

  Jotta voit ottaa paketin käyttöön kohdeympäristössä komentorivikäyttöliittymän avulla, sinun on ensin määritettävä todennusprofiili ja valittava organisaatio. Lisätietoja on kohdassa pac auth create ja pac org select.

Parhaat käytännöt

Alla on lueteltu muutamia pakettien käyttöönoton parhaiden käytäntöjen vihjeitä, joita on hyvä noudattaa Package Deployer -paketteja käsiteltäessä.

Pakettien luonti

Kun luodaan paketteja, sovelluskehittäjien on

• Varmista, että pakettikokoonpanot on allekirjoitettu.

Pakettien käyttöönottaminen

Pakettien käyttöönoton aikana Dataverse-järjestelmänvalvojien pitää:

• Vaadi allekirjoitettuja pakettikokoonpanoja , jotta voit jäljittää kokoonpanon takaisin sen lähteeseen.
• Testaa pakettia tuotantoa edeltävässä esiintymässä, mieluiten tuotantoesiintymän peilikuvassa, ennen kuin suoritat sen tuotantoesiintymässä.
• Varmuuskopioi tuotantoesiintymä ennen paketin käyttöönottoa.

Myös katso

SolutionPackager -työkalu