Jaa

Pakettien luominen Package Deployer -työkalua varten

  • Artikkeli

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

  • Yhden tai useamman Dataverse ratkaisutiedoston.
  • Tietuetiedostot tai viety määritystietotiedosto määrityksensiirtotyökalusta. 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.

Muistiinpano

Mukana on toinen laajennuspaketiksi kutsuttu pakettityyppi. Tällainen paketti on laajennuksista riippuville kokoonpanoille, eikä sillä ole suhdetta Package Deployer -paketteihin.

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 yleiskatsaus

Luo Package Deployer -paketti seuraavasti.

  • Luo Visual Studio- tai MSBuild-projekti
  • Ratkaisujen ja muiden tiedostojen lisääminen projektiin
  • Toimitettujen HTML-tiedostojen päivittäminen (valinnainen)
  • Määritä paketin määritysarvot
  • Määritä paketille mukautettu koodi
  • Paketin muodostaminen ja käyttöönotto

Nämä vaiheet on kuvattu tarkemmin tässä artikkelissa.

Luo pakettiprojekti

Ensimmäinen vaihe on luoda paketille Visual Studio- tai MSBuild-projekti. Tätä varten kehitystietokoneeseen on oltava asennettuna toinen käytettävissä olevista työkalulaajennuksista. Jos käytät Visual Studio Codea, asenna Microsoft Power Platform CLI. Muussa tapauksessa, jos käytät Visual Studio 2019 -versiota tai uudempaa versiota, asenna Visual Studion Power Platform Tools -työkalut.

Valitsemalla alla soveltuvan välilehden voit selvittää, miten projekti luodaan halutun työkalulaajennuksen avulla. Molemmat työkalut tulostavat projektin samassa muodossa.

Suorita pac package init -komento luodaksesi ensimmäisen paketin. Lisätietoja: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Tuloksena saatu CLI-tulos sisältää alla näkyvät kansiot ja tiedostot. Tässä käytettiin esimerkkinä DeploymentPackage-kansion nimeä.

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

Etsi luodussa projektissa määritystiedosto (ImportConfig.xml) kansiossa PkgAssets sekä tiedosto PackageImportExtension.cs. Voit muokata näitä tiedostoja myöhemmin tässä artikkelissa kuvatulla tavalla.

Lisää pakettitiedostot

Kun olet luonut pakettiprojektin, voit alkaa lisätä projektiin ratkaisuja ja muita tiedostoja.

Kun käytät CLI:tä voit lisätä ulkoisia paketteja, ratkaisuja ja viittauksia pakettiprojektiin käyttämällä jotain add-alikomentoa. Kirjoita pac package help, jos haluat nähdä alikomentojen luettelon. Lisätään pakettiin ratkaisu.

> 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. ImportConfig-viittauksessa on esimerkki ja kuvaukset kelvollisia elementtejä ja määritteitä varten.

Lisää mukautettu koodi

Voit lisätä mukautettua koodia, joka suoritetaan ennen paketin tuontia ympäristöön, sen aikana ja sen jälkeen. Voit tehdä sen seuraavasti.

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

  2. C#-tiedostossa voit:

    1. antaa mukautetun koodin, joka suoritetaan, kun paketti alustetaan InitializeCustomExtension-menettelyn ohitusmenetelmän määrityksessä.

      Tätä menetelmää voi käyttää sen sallimiseen, että käyttäjät voivat käyttää suoritusparametreja paketin suorittamisen yhteydessä. 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, onko käyttäjä määrittänyt suoritusparametreja Package Deployer suorittamisen aikana (joko komentorivin tai PowerShellin avulla) ja käsittelee tiedot sitten sen mukaan. Jos käyttäjä ei ole määrittänyt suoritusparametreja paketin suorittamisen aikana, RuntimeSettings-ominaisuuden arvo on tyhjäarvo.

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

      Tämän koodin avulla järjestelmänvalvoja voi käyttää komentoriviä tai cmdlet-komentoa Import-CrmPackage määrittääkseen, ohitetaanko suojaustarkistukset, kun Package Deployer -työkalu suoritetaan paketin tuomista varten. Lisätietoja: Pakettien käyttöönotto Package Deployer ja Windows PowerShellin avulla

    2. Anna mukautettu koodi, joka suoritetaan, ennen kuin ratkaisut tuodaan PreSolutionImport-ominaisuuden ohitusmenetelmän määritelmään sen määrittämiseksi, säilytetäänkö vai korvataanko mukautukset, kun määritettyä ratkaisua kohteena olevassa Dataverse -esiintymässä päivitetään, ja aktivoidaanko laajennukset ja työnkulut automaattisesti.

    3. Käytä RunSolutionUpgradeMigrationStep-ominaisuuden ohitusmenetelmän määritelmää suorittaaksesi tiedon muuntamista tai päivittääksesi ratkaisun kahden version välillä. Tätä menetelmää kutsutaan vain, jos tuotava ratkaisu on jo olemassa kohteena olevassa Dataverse-esiintymässä.

      Tämä toiminto edellyttää seuraavia parametreja:

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

    4. Syötä mukautettu koodi, joka suoritetaan, ennen kuin ratkaisun tuonti suoritetaan loppuun BeforeImportStage-menetelmän ohituksen määritelmässä. Mallitiedot ja joitakin ImportConfig.xml -tiedostossa määritettyjen ratkaisujen tietuetiedostoja tuodaan, ennen kuin ratkaisun tuonti valmistuu.

    5. Ohita tällä valittu kieli määritystietojen tuonnissa käyttämällä OverrideConfigurationDataFileLanguage-ominaisuuden ohitusmenetelmää. Jos määritetyn kielen määritettyä kielitunnusta (LCID) ei löydy paketin käytettävissä olevien kielten luettelosta, tuodaan oletusarvoinen tiedosto.

      Määritystietojen käytettävissä olevat tiedot määritetään ImportConfig.xml-tiedoston <cmtdatafiles>-solmussa. Oletusarvoinen määritystietojen tuontitiedosto määritetään ImportConfig.xml-tiedoston crmmigdataimportfile-määritteessä.

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

    6. Syötä mukautettu koodi, joka suoritetaan, kun tuonti valmistuu AfterPrimaryImport>-menetelmän ohituksen määritelmässä. Jäljellä olevat tietuetiedostot, joita ei tuotu aiemmin ennen ratkaisun tuomisen aloittamista, tuodaan nyt.

    7. Muuta pakettikansiosi oletusnimi haluamaasi muotoon. Tee se nimeämällä PkgFolder- (tai PkgAssets) kansio Ratkaisunhallinta-ruudussa uudelleen ja muuttamalla sitten GetImportPackageDataFolderName-ominaisuuden palautusarvoa.

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

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

      Tämä palautettu arvo on se paketin nimi, joka tulee näkyviin ohjatun Dynamics 365 Package Deployer -toiminnon paketinvalintasivulla.

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

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

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

      Paketin pitkä nimi näkyy seuraavalla sivulla sen jälkeen, kun olet valinnut paketin asennettavaksi.

  3. Lisäksi seuraava toiminto ja seuraavat muuttujat ovat käytettävissä pakettia varten:

    Nimi Laji Kuvaus
    CreateProgressItem(String) Function Käytetään uuden edistymiskohteen luomiseen käyttöliittymässä (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Käytetään kutsun luoman edistyksen päivittämiseen CreateProgressItem(String).

    ProgressPanelItemStatus on luettelointi, jolla on seuraavat arvot:

    Käsittelyssä = 0
    Valmis = 1
    Epäonnistui = 2
    Varoitus = 3
    Tuntematon = 4
    RaiseFailEvent(String, Exception) Function Käytetään nykyisen tilan tuonnin hylkäämiseen poikkeussanomalla.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Käytetään sen määrittämiseen, onko rooli määritetty tietylle ryhmälle.
    IsWorkflowActive(Guid) Function Käytetään sen määrittämiseen, onko tietty työnkulku aktiivisena.
    PackageLog Luokkaosoitin Osoitin paketin alustettuun kirjausrajapintaan. Paketti käyttää tätä rajapintaa sanomien ja poikkeuksien kirjaamiseen paketin lokitiedostoon.
    RootControlDispatcher Ominaisuus Lähetysrajapinta, jonka ansiosta ohjausobjekti voi hahmontaa oman käyttöliittymänsä paketin käyttöönoton aikana. Tällä rajapinnalla voit paketoida mitä tahansa käyttöliittymän elementtejä tai komentoja. On tärkeää tarkistaa tämä muuttuja tyhjäarvojen varalta ennen käyttöä, koska sillä ei välttämättä ole arvoa.
    CrmSvc Ominaisuus Osoitin CrmServiceClient-luokkaan, jonka ansiosta paketti voi käyttää Dynamics 365:ttä paketin sisältä. Tämän osoittimen avulla voit suorittaa SDK-menetelmiä ja muita toimintoja ohitetuissa menetelmissä.
    DataImportBypass Ominaisuus Määritä, ohittaako Dynamics 365 Package Deployer kaikki tietojen tuonnin toiminnot, kuten Dataverse-esimerkkitietoja, tietuetiedostoja ja määrityksen siirtotyökalusta vietyjä tietoja. Määritä tosi tai epätosi. Oletuksena on false.
    OverrideDataImportSafetyChecks Ominaisuus Määritä, ohittaako Dynamics 365 Package Deployer osan turvatarkastuksista, jolloin sen tuonnin suorituskyky paranee. Määritä true tai false. Oletuksena on false.

    Määritä tämän ominaisuuden arvoksi true vain, jos kohteena oleva Dataverse -esiintymä ei sisällä tietoja.

  4. Tallenna projekti. Seuraavana vaiheena on paketin koonti.

Koonti ja käyttöönotto

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

Muodosta

Paketin rakentaminen kuvaillaan alla sen mukaan, mitä työkalua käytät.

Jos rakennat CLI:llä luodun paketin, voit ladata .csproj-tiedoston Visual Studioon, mutta käytämme kuitenkin dotnet-komentoa ja MSBuildia. Alla olevassa esimerkissä oletetaan, että työhakemisto sisältää *.csproj-tiedoston.

> dotnet publish

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

Voit myös tarkastella kootun paketin tietoja.

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

Paketti koostuu seuraavista tiedostoista <Project>\Bin\Debug -kansiossa.

  • <PackageName>-kansio: Kansion nimi on sama kuin se, joksi muutit pakettikansion nimen tämän osan vaiheessa 2.g Lisää mukautettu koodi. Tämä kansio sisältää kaikki ratkaisut, määritystiedot, tietuetiedostot ja pakettisi sisällön.

Muistiinpano

Saatat nähdä .NET-kansion (esimerkiksi net472), joka sisältää pdpublish-kansion. DLL-tiedostosi ja muut projektitiedostosi ovat tuossa pdpublish-kansiossa.

  • <PackageName>.dll: Kokoonpano sisältää paketin mukautetun koodin. Kokoonpanon nimi on oletusarvon mukaan sama kuin projektin nimi.

Käyttöönotto

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

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ää:

  • Varmistaa paketin kokoonpanon allekirjoitus niin, että voit seurata kokoonpanoa takaisin sen lähteeseen.
  • Testata pakettia esituotannon esiintymässä (mieluiten peilatussa tuotantoesiintymässä) ennen sen suorittamista tuotantoesiintymässä.
  • Varmuuskopioi tuotantoesiintymä ennen paketin käyttöönottoa.

Katso myös

SolutionPackager -työkalu