יצירת חבילות עבור הכלי Package Deployer

Package Deployer מאפשר למנהלי מערכת לפרוס חבילות במופעי Microsoft Dataverse. חבילת Package Deployer יכולה להיות מורכבת מאחת או מכל הבאות:

• קובצי פתרון, אחד או יותר, של Dataverse.
• קבצים שטוחים או קובץ נתוני תצורה מיוצא מהכלי 'מעבר תצורה'. לקבלת מידע נוסף על הכלי, ראה העברת נתוני התצורה בין מופעים וארגונים באמצעות הכלי 'מעבר תצורה'.
• קוד מותאם אישית שניתן להפעיל לפני, במהלך או אחרי פריסת החבילה במופע של Dataverse.
• תוכן HTML ספציפי לחבילה שניתן להציג בהתחלה ובסוף של תהליך הפריסה. תוכן יכול לשמש לאספקת תיאור של פתרונות וקבצים הנפרסים בחבילה.

הערה

יש עוד סוג חבילה שנקרא חבילת יישום plug-in. סוג זה של חבילה מיועד למכלולים תלויי יישום plug-in ואין להם שום קשר לחבילות Package Deployer.

‏‫דרישות מוקדמות‬

• ודא שכל הפתרונות והקבצים הנוספים שברצונך לכלול בחבילה מוכנים.
• Visual Studio ‏2019 (או מאוחר יותר), או Visual Studio Code

מבט כולל על התהליך

ליצירת חבילת Package Deployer, בצע את השלבים הבאים.

• יצירת פרויקט Visual Studio או MSBuild
• הוסף פתרונות וקבצים אחרים לפרויקט
• עדכון קובצי HTML שסופקו (אופציונלי)
• קביעת ערכי התצורה עבור החבילה
• הגדרת קוד מותאם אישית עבור החבילה
• בנה ופרוס את החבילה

שלבים אלה מתוארים בפירוט במאמר זה.

צור פרויק חבילה

הצעד הראשון הוא ליצור פרויקט Visual Studio או MSBuild עבור החבילה. כדי לעשות זאת, עליך להתקין אחת משתי הרחבות כלים זמינות במחשב הפיתוח שלך. אם אתה משתמש Visual Studio Code, התקן את Microsoft Power Platform CLI . אחרת, אם אתה משתמש ב- Visual Studio 2019 ואילך, התקן את Power Platform Tools עבור Visual Studio.

בחר את הכרטיסייה המתאימה למטה כדי לגלות כיצד ליצור פרויקט באמצעות הרחבת הכלי הרצויה. שני הכלים מוציאים את הפרויקט בפורמט דומה.

Power Platform CLI

הפעל את הפקודה pac package init ליצירת החבילה הראשונית. מידע נוסף: חבילת pac

pac package init help
pac package init --outputDirectory DeploymentPackage

פלט CLI המתקבל מכיל את התיקיות והקבצים המוצגים להלן. שם התיקיה DeploymentPackage שימש כאן כדוגמה.

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

בפרויקט שנוצר, מצא את קובץ התצורה ImportConfig.xml בתיקיית PkgAssets ואת הקובץ PackageImportExtension.cs. תשנה את הקבצים האלה כמתואר בהמשך מאמר זה.

Power Platform כְּלֵי עֲבוֹדָה

ניתן ליצור פרויקט Visual Studio באמצעות תבנית הפתרון Power Platform ובהמשך להוסיף פרויקט חבילה באמצעות התבנית 'פרויקט פריסת חבילה' של Power Platform, או ליצור פרויקט ישירות באמצעות התבנית 'פרויקט פריסת חבילה' של Power Platform.

הערה

אל תבחר את תבנית החבילה של Power Platform. התבנית הזו מיועדת לחבילות של יישומי plug-in.

פרויקט ופתרון Visual Studio המתקבל מכיל את התיקיות והקבצים המוצגים להלן. שם התיקיה 'חבילת פריסה' שימש כאן כדוגמה. התוכן של תיקיית התוכן אינו מוצג כאן לשם קיצור.

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

בפרויקט שנוצר, מצא את קובץ התצורה ImportConfig.xml בתיקיית PkgFolder ואת הקובץ PackageTemplate.cs. תשנה את הקבצים האלה כמתואר בהמשך מאמר זה.

מידע נוסף על השימוש בהרחבות Power Platform Tools: התחלה מהירה: צור פרויקט של Power Platform Tools

הוספת קובצי חבילה

לאחר שיצרת פרויקט חבילה, תוכל להתחיל להוסיף פתרונות וקבצים אחרים לפרויקט זה.

Power Platform CLI

בעת שימוש ב- CLI, אתה יכול להוסיף חבילות חיצוניות, פתרונות והפניות לפרויקט החבילה שלך באמצעות אחת מפקודות המשנה הוסף. הזן את pac package help כדי לראות את רשימת פקודות המשנה. בואו נוסיף פתרון לחבילה שלנו.

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

Power Platform כְּלֵי עֲבוֹדָה

1. בחלונית סייר הפתרונות, הוסף את הפתרונות ה- Dataverse שלך וקבצים האחרים בתיקיה PkgFolder. קבצי HTML שייכים לתיקיה תוכן. עוד על תוכן HTML זה מאוחר יותר.
2. עבור כל קובץ שתוסיף בחלונית מאפיינים, הגדר את הערך העתק לספריית פלט להעתק תמיד. הגדרת הערך הזה מבטיחה שהקבצים זמינים בחבילה שנוצרה.

לאחר מכן, עדכן את הקבצים הספציפיים בשפת HTML.

1. בחלונית סייר הפתרונות, הרחב את PkgFolder>תוכן>en-us. מצא שתי תיקיות: EndHTML ו- WelcomeHTML. תיקיות אלה מכילות את קבצי ה- HTML והקבצים המשויכים שמאפשרים לך להציג (למשתמש) מידע בסוף ובהתחלה של תהליך פריסת החבילה. ערוך את הקבצים בתיקיית ה- HTML של תיקיות אלה כדי להוסיף מידע לתצוגה לחבילה שלך.

2. ניתן להוסיף את קבצי ה- HTML בחבילה גם בשפות אחרות, כך שהתוכן ב- HTML יופיע בשפה המבוססת על הגדרות האזור של מחשב המשתמש. לשם כך:

   1. צור עותק של התיקיה en-us תחת PkgFolder>תוכן.
   2. שנה את שם התיקיה שהועתקה לשפה המתאימה. לדוגמה, עבור עברית, שנה את שמה ל- he-IL.
   3. שנה את תוכן קבצי ה- HTML כדי להוסיף תוכן בעברית.

קבע את תצורה של החבילה

הגדר את תצורת החבילה על-ידי הוספת מידע לגבי החבילה בקובץ ImportConfig.xml בפרויקט. עיין ב- ImportConfig Reference לדוגמה ותיאורים של הרכיבים והתכונות החוקיים לשימוש.

הוספת קוד מותאם אישית

אתה יכול להוסיף קוד מותאם אישית שפועל לפני, במהלך ואחרי שהחבילה מיובאת לסביבה. לשם כך, בצע את ההנחיות האלה.

1. ערוך את הקובץ PackageTemplate.cs (אוֹ PackageImportExtension.cs) בתיקיית הבסיס של הפרויקט.

2. בקובץ C‎#‎, באפשרותך:

   1. להזין קוד מותאם אישית שיבוצע בעת אתחול החבילה בהגדרת פעולת השירות לעקיפה של InitializeCustomExtension.

      ניתן להשתמש בפעולת שירות זו כדי לאפשר למשתמשים להשתמש בפרמטרי זמן הריצה בעת הפעלת חבילה. כמפתח, תוכל להוסיף לחבילה שלך תמיכה עבור כל פרמטר זמן ריצה באמצעות המאפיין RuntimeSettings, כל עוד יש לך קוד כדי לעבד אותו על בסיס קלט המשתמש.

      למשל, הקוד לדוגמה הבא הופך פרמטר זמן ריצה בשם SkipChecks לזמין עבור החבילה עם שני ערכים אפשריים: true או false. הקוד לדוגמה בודק אם המשתמש ציין פרמטרי זמן ריצה בעת הפעלת Package Deployer (באמצעות שורת הפקודה או PowerShell), ולאחר מכן מעבד את המידע בהתאם. אם המשתמש לא ציין פרמטר זמן ריצה בעת הפעלת החבילה, ערך המאפיין RuntimeSettings יהיה Null.

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

      קוד זה מאפשר למנהל המערכת להשתמש בשורת הפקודה או ב- cmdlet‏ Import-CrmPackage כדי לציין אם יש לדלג על בדיקות הבטיחות בעת הפעלת הכלי Package Deployer כדי לייבא את החבילה. מידע נוסף: פריסת חבילות באמצעות Package Deployer ו- Windows PowerShell.

   2. להזין קוד מותאם אישית שיבוצע לפני ייבוא הפתרונות בהגדרת פעולת השירות לעקיפה של PreSolutionImport כדי לציין אם יש לשמור או להחליף התאמות אישיות בעת עדכון הפתרון שצוין במופע יעד של Dataverse, ואם יש להפעיל באופן אוטומטי יישומי Plug-in וזרימות עבודה.

   3. להשתמש בהגדרת פעולת השירות לעקיפה של RunSolutionUpgradeMigrationStep כדי לבצע שינוי נתונים או שדרוג בין שתי גרסאות של פתרון. המערכת מבצעת קריאה לפעולת שירות זו רק אם הפתרון שאתה מייבא כבר קיים במופע יעד של Dataverse.

      פונקציה זו מצפה לפרמטרים הבאים:

      פרמטר	תיאור
      solutionName	שם הפתרון
      oldVersion	מספר הגירסה של הפתרון הישן
      newVersion	מספר הגירסה של הפתרון החדש
      oldSolutionId	ה- GUID של הפתרון הישן
      newSolutionId	ה- GUID של הפתרון החדש.

   4. להזין קוד מותאם אישית שיבוצע לפני השלמת ייבוא הפתרון בהגדרת העקיפה של פעולת השירות BeforeImportStage. הנתונים לדוגמה וכמה קבצים שטוחים עבור הפתרונות שצוינו בקובץ ImportConfig.xml מיובאים לפני השלמת ייבוא הפתרון.

   5. לעקוף את השפה שנבחרה כעת עבור ייבוא נתוני התצורה באמצעות הגדרת פעולת השירות לעקיפה של OverrideConfigurationDataFileLanguage. אם מזהה האזור (LCID) שצוין של השפה שצוינה לא נמצא ברשימת השפות הזמינות בחבילה, המערכת מייבאת את קובץ הנתונים המוגדר כברירת מחדל.

      עליך לציין את השפות הזמינות עבור נתוני התצורה בצומת <cmtdatafiles> בקובץ ImportConfig.xml. קובץ הייבוא של נתוני התצורה המוגדר כברירת מחדל מצוין בתכונה crmmigdataimportfile בקובץ ImportConfig.xml.

      דילוג על בדיקות נתונים (OverrideDataImportSafetyChecks ‏= true‏) יכול להיות שימושי כאן אם אתה בטוח שמופע היעד של Dataverse אינו מכיל נתונים.

   6. הזן קוד מותאם אישית שיבוצע אחרי השלמת הייבוא בהגדרת העקיפה של פעולת השירות AfterPrimaryImport>. שאר הקבצים השטוחים שלא יובאו קודם לכן, לפני תחילת ייבוא הפתרון, מיובאים כעת.

   7. לשנות את שם ברירת המחדל של תיקיית החבילה שלך לשם החבילה הרצוי. לשם כך, שנה את שם התיקיה PkgFolder (או PkgAssets‎) בחלונית סייר הפתרונות ולאחר מכן ערוך את ערך ההחזרה תחת המאפיין 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. לשנות את שם החבילה על-ידי עריכת ערך ההחזרה תחת המאפיין GetNameOfImport.

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

      הערך המוחזר הוא שם החבילה שמופיע בעמוד בחירת החבילה באשף Package Deployer של Dynamics 365.

   9. לשנות את תיאור החבילה על-ידי עריכת ערך ההחזרה תחת המאפיין GetImportPackageDescriptionText.

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

      ערך מוחזר זה הוא תיאור החבילה שמופיע לצד שם החבילה בעמוד בחירת החבילה באשף Package Deployer.

   10. לשנות את השם הארוך של החבילה על-ידי עריכת ערך ההחזרה תחת המאפיין GetLongNameOfImport.

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

       השם הארוך של החבילה מופיע בעמוד הבא לאחר בחירת החבילה להתקנה.

3. בנוסף, הפונקציה והמשתנים הבאים זמינים עבור החבילה:

   שם	סוג	תיאור
   CreateProgressItem(String)	פונקציה	משמש ליצירת פריט התקדמות חדש בממשק המשתמש (UI).
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	משמש לעדכון ההתקדמות שנוצרה על-ידי הקריאה אל CreateProgressItem(String). ProgressPanelItemStatus הוא הרשימה עם הערכים הבאים: פועל = 0 הושלם = 1 נכשל = 2 אזהרה = 3 לא ידוע = 4
   RaiseFailEvent(String, Exception)	Function	משמש להכשלת ייבוא המצב הנוכחי עם הודעת חריגה.
   IsRoleAssoicatedWithTeam(Guid, Guid)	Function	משמש כדי לקבוע אם תפקיד כלשהו משויך לצוות שצוין.
   IsWorkflowActive(Guid)	Function	משמש כדי לקבוע אם זרימת עבודה שצוינה פעילה.
   PackageLog	מצביע מחלקה	מצביע לממשק הרישום שאותחל עבור החבילה. ממשק זה משמש את החבילה לרישום הודעות וחריגות בקובץ יומן הרישום של החבילה.
   RootControlDispatcher	מאפיין‬	ממשק משגר שבו נעשה שימוש כדי לאפשר לפקד שלך לעבד ממשק משתמש משלו במהלך פריסת החבילה. השתמש בממשק זה כדי לעטוף פקודות או רכיבים של ממשק המשתמש. חשוב לאתר ערכי Null במשתנה זה לפני השימוש בו מכיוון שייתכן שהוא הוגדר לערך.
   CrmSvc	מאפיין‬	מצביע למחלקה של CrmServiceClient שמאפשר לחבילה להפנות אל Dynamics 365 מתוך החבילה. השתמש במצביע זה כדי לבצע פעולות שירות של SDK ופעולות אחרות בפעולות השירות שעקפת.
   DataImportBypass	מאפיין‬	ציין אם Dynamics 365 Package Deployer צריך לדלג על כל פעולות ייבוא הנתונים, כגון ייבוא נתונים לדוגמה של Dataverse, נתוני קבצים שטוחים ונתונים שיוצאו מכלי העברת התצורה. ציין true או false. ברירת המחדל היא false.
   OverrideDataImportSafetyChecks	מאפיין‬	ציין אם Package Deployer של Dynamics 365 יעקוף חלק מבדיקות הבטיחות שלו, לשיפור ביצועי הייבוא. ציין true או false. ברירת המחדל היא false. עליך להגדיר מאפיין זה ל- true רק אם מופע היעד של Dataverse אינו מכיל נתונים.

4. שמור את הפרוייקט שלך. השלב הבא הוא לבנות את החבילה.

בנייה ופריסה

הסעיפים הבאים מתארים כיצד לבנות ולפרוס חבילה.

בנה

בניית החבילה שלך מתוארת להלן בהתאם לכלי שבו אתה משתמש.

Power Platform CLI

כדי לבנות חבילה שנוצרה באמצעות ה-CLI, תוכל לטעון את קובץ ה-csproj ב- Visual Studio, אך במקום זאת נשתמש בפקודה dotnet וב-MSBuild. הדוגמה להלן מניחה שספריית העבודה מכילה את קובץ ה- *csproj.

> 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

Power Platform כְּלֵי עֲבוֹדָה

כדי לבנות את החבילה, לחץ על F5 ב- Visual Studio או בחר בנייה>‏‫בניית פתרון.

החבילה שלך מורכבת מהקבצים הבאים תחת התיקיה ‎<Project>\Bin\Debug.

• <שם חבילה> תיקייה : שם התיקיה זהה לזה ששינית עבור שם תיקיית החבילה שלך ב-צעד 2.g בסעיף זה הוסף קוד מותאם אישית. תיקיה זו מכילה את כל הפתרונות, נתוני התצורה, הקבצים השטוחים והתוכן עבור החבילה.

הערה

ייתכן שתראה תיקיית NET. (למשל, net472) המכילה תיקיית pdpublish. ה- DLL שלך וקבצי פרויקט אחרים נמצאים בתיקיית pdpublish זו.

• <שם חבילה> .DLL : המכלול מכיל את הקוד המותאם אישית עבור החבילה שלך. כברירת מחדל, שם ההרכבה זהה לשם פרויקט שלך.

פרוס

לאחר יצירת חבילה, תוכל לפרוס אותה במופע של Dataverse באמצעות הכלי Package Deployer או באמצעותWindows PowerShell או פקודת CLI.

• לפריסה באמצעות הכלי Package Deployer, תחילה הורד את הכלי כמתואר בכלי הפיתוח של Dataverse. לאחר מכן, עקוב אחר המידע המפורט על פריסת חבילות במאמר פריסת חבילות באמצעות Package Deployer או Windows PowerShell.

• כדי לפרוס באמצעות ה- CLI, השתמש בפקודהpac package deploy.

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

  הערה

  כדי לפרוס חבילה לסביבת יעד באמצעות ה- CLI, תחילה עליך להגדיר פרופיל אימות ולבחור ארגון. מידע נוסף: pac auth create, pac org select

שיטות עבודה מומלצות

להלן מספר טיפים לשיטות עבודה מומלצות שכדאי ליישם בעת העבודה עם חבילות Package Deployer.

יצירת חבילות

בעת יצירת חבילות, מפתחים חייבים:

• ודא שמכלולי החבילה חתומים.

פריסת חבילות

בעת פריסת חבילות, מנהלי מערכת של Dataverse:

• התעקש על הרכבות חבילות חתומות כך שתוכל לעקוב אחר מכלול חזרה למקורו.
• בדוק את החבילה על מופע טרום ייצור, רצוי תמונת מראה של מופע ייצור, לפני הפעלתו על מופע ייצור.
• גבה את מופע ייצור לפני פריסת החבילה.

למידע נוסף

כלי Solution Packager