הכלי SolutionPackager
SolutionPackager הוא כלי שיכול לפרק באופן הפיך קובץ פתרון דחוס של Microsoft Dataverse למספר קובצי XML וקבצים נוספים. לאחר מכן תוכל לנהל בקלות קבצים אלה באמצעות מערכת בקרת מקור. הסעיפים הבאים מראים כיצד להפעיל את הכלי וכיצד להשתמש בכלי עם פתרונות מנוהלים ולא מנוהלים.
חשוב
הכלי SolutionPackager הוא כבר לא הדרך המומלצת לפרק ולארוז פתרונות. היכולות של הכלי SolutionPackager שולבו ב- Power Platform CLI. לפקודה pac solution יש מספר פעלים כולל unpack, pack, clone ו- sync המשלבים את אותן יכולות בסיסיות של הכלי SolutionPackager.
היכן ניתן למצוא את הכלי SolutionPackager
הכלי SolutionPackager מופץ כחלק מהחבילה Microsoft.CrmSdk.CoreTools של NuGet. כדי להתקין את התוכנה, בצע את השלבים הבאים.
- הורד את חבילת ה- NuGet.
- שנה את שם סיומת שם הקובץ של החבילה מ- .nupkg ל-zip.
- חלץ את התוכן של קובץ ה- zip הדחוס.
מצא את קובץ ההפעלה SolutionPackager.exe בתיקייה <extracted-folder-name>/contents/bin/coretools. הפעל את התוכנה מהתיקייה של coretools או הוסף את התיקיה ל-PATH שלך.
ארגומנטי שורת פקודה של SolutionPackager
SolutionPackager הוא כלי שורת פקודה שניתן להפעילו באמצעות הפרמטרים המזוהים בטבלה הבאה.
| ארגומנט | תיאור |
|---|---|
| /action: {Extract|Pack} | נדרש. הפעולה שיש לבצע. הפעולה יכולה להיות חילוץ קובץ .zip לתיקיה או אריזת תיקיה בקובץ .zip |
| /zipfile: <file path> | נדרש. הנתיב והשם של קובץ .zip של פתרון. בעת חילוץ, הקובץ חייב להיות קיים וניתן לקריאה. בעת אריזה, הקובץ מוחלף. |
| /folder: <folder path> | נדרש. הנתיב לתיקיה. בעת חילוץ, תיקיה זו נוצרת ומאוכלסת בקבצי רכיבים. בעת אריזה, תיקיה זו חייבת כבר להיות קיימת ולהכיל קבצי רכיבים שחולצו קודם לכן. |
| /packagetype: {Unmanaged|Managed|Both} | אופציונלי. סוג החבילה שיש לעבד. ערך ברירת המחדל הוא Unmanaged. ניתן להשמיט טיעון זה ברוב המקרים מכיוון שניתן לקרוא את סוג החבילה מתוך קובץ ה- .zip או קבצי הרכיבים. בעת חילוץ, כאשר צוין Both, קבצי .zip של פתרונות מנוהלים ולא מנוהלים חייבים להיות קיימים, והם מעובדים לתיקיה אחת. בעת אריזה, כאשר צוין Both, קבצי .zip של פתרונות מנוהלים ולא מנוהלים נוצרים מתיקיה אחת. לקבלת מידע נוסף, עיין בסעיף בנושא עבודה עם פתרונות מנוהלים ולא מנוהלים בהמשך מאמר זה. |
| /allowWrite:{Yes|No} | אופציונלי. ערך ברירת המחדל הוא Yes. בארגומנט זה נעשה שימוש רק במהלך חילוץ. כאשר צוין /allowWrite:No, הכלי מבצע את כל הפעולות, אך אין לו אפשרות לכתוב או למחוק קבצים. ניתן להעריך את פעולת החילוץ בבטחה מבלי להחליף או למחוק קבצים קיימים. |
| /allowDelete:{Yes|No|Prompt} | אופציונלי. ערך ברירת המחדל הוא Prompt. בארגומנט זה נעשה שימוש רק במהלך חילוץ. כאשר צוין /allowDelete:Yes, כל הקבצים שקיימים בתיקיה שצוינה על-ידי הפרמטר /folder אשר אינם צפויים נמחקים באופן אוטומטי. כאשר צוין /allowDelete:No, לא מתבצעות פעולות מחיקה. כאשר צוין /allowDelete:Prompt, המשתמש מתבקש דרך המסוף לאפשר או לדחות את כל פעולות המחיקה. אם צוין /allowWrite:No, לא מתבצעות פעולות מחיקה אפילו אם צוין גם /allowDelete:Yes. |
| /clobber | אופציונלי. בארגומנט זה נעשה שימוש רק במהלך חילוץ. כאשר צוין /clobber, קבצים שהוגדרה בהם התכונה לקריאה בלבד מוחלפים או נמחקים. כאשר הוא לא צוין, קבצים עם התכונה לקריאה בלבד אינם מוחלפים או נמחקים. |
| /errorlevel: {Off|Error|Warning|Info|Verbose} | אופציונלי. ערך ברירת המחדל הוא Info. ארגומנט זה מציין את רמת פרטי הרישום שיש ליצור כפלט. |
| /map: <file path> | אופציונלי. הנתיב והשם של קובץ .xml שמכיל הוראות למיפוי קבצים. כאשר נעשה בו שימוש במהלך חילוץ, קבצים שנקראים בדרך כלל מתוך התיקיה שצוינה על-ידי פרמטר /folder נקראים ממיקומים חלופיים כמפורט בקובץ המיפוי. במהלך פעולת אריזה, קבצים שתואמים להוראות אינם נכתבים. |
| /nologo | אופציונלי. מעלים את הכרזה בזמן ריצה. |
| /log: <file path> | אופציונלי. נתיב ושם עבור קובץ יומן רישום. אם הקובץ כבר קיים, פרטי רישום חדשים מצורפים לקובץ. |
| @ <file path> | אופציונלי. נתיב ושם עבור קובץ שמכיל ארגומנטי שורת פקודה עבור הכלי. |
| /sourceLoc: <string> | אופציונלי. ארגומנט זה יוצר קובץ משאבים של תבנית, והוא חוקי רק בחילוץ. הערכים האפשריים הם auto או קוד ISO/LCID עבור השפה שברצונך לייצא. כאשר נעשה שימוש בארגומנט זה, משאבי המחרוזת מהאזור הנתון מחולצים כקובץ .resx ניטראלי. אם צוין auto או אם צוינה רק הצורה הארוכה או הקצרה של המתג, נעשה שימוש באזור הבסיס או בפתרון. ניתן להשתמש בצורה הקצרה של הפקודה: /src. |
| /localize | אופציונלי. חילוץ או מיזוג של כל משאבי המחרוזת לקבצי .resx ניתן להשתמש בצורה הקצרה של הפקודה: /loc. אפשרות ההתאמה לשפות אחרות תומכת ברכיבים משותפים עבור קבצי .resx. מידע נוסף: שימוש במשאבי אינטרנט של RESX |
שימוש בארגומנט הפקודה /map
הדיון הבא מפרט את השימוש בארגומנט /map עבור הכלי SolutionPackager.
קבצים הבנויים במערכת בנייה אוטומטית, כגון קבצי Silverlight מסוג .xap והכללות של יישומי Plug-in, אינם מוכנסים בדרך כלל לבקרת מקור. ייתכן שמשאבי אינטרנט כבר יהיו קיימים בבקרת מקור במיקומים שאינם תואמים ישירות לכלי SolutionPackager. על-ידי הכללת הפרמטר /map, ניתן להפנות את הכלי SolutionPackager לקריאה ולאריזה של קבצים כאלה ממיקומים חלופיים ולא מתוך התיקיה Extract, כפי שנעשה בדרך כלל. הפרמטר /map חייב לציין את השם והנתיב לקובץ XML המכיל הנחיות מיפוי. הנחיות אלו מורה ל- SolutionPackager להתאים קבצים לפי שמם והנתיב שלהם, ולציין את המיקום החלופי כדי למצוא את הקובץ המותאם. המידע הבא חל על כל ההוראות באופן שווה.
ניתן לפרט הוראות מרובות, כוללות הוראות שמתאימות קבצים זהים. ההוראות המפורטות בתחילת הקובץ מקבלות עדיפות על-פני ההוראות המפורטות לאחר מכן.
אם קובץ מותאם להוראה כלשהי, הוא חייב להימצא במיקום חלופי אחד לפחות. אם לא נמצאו חלופות תואמות, SolutionPackager מפיק שגיאה.
נתיבי התיקיות והקבצים עשויים להיות מוחלטים או יחסיים. נתיבים יחסיים מוערכים תמיד מהתיקיה שצוינה על-ידי הפרמטר /folder.
ניתן לציין משתני סביבה באמצעות תחביר %variable%.
ניתן להשתמש בתווים הכלליים "**" עבור תיקיות, כשפירושם הוא "בכל תיקיית משנה". ניתן להשתמש בו רק כחלק הסופי של נתיב. לדוגמה: “c:\folderA\**”.
ניתן להשתמש בתווים כלליים עבור שמות קבצים רק בצורות *.ext או “*.*”. אף תבנית אחרת אינה נתמכת.
שלושת הסוגים של מיפויי ההוראות מתוארים כאן, יחד עם דוגמה שמראה כיצד להשתמש בהם.
מיפוי תיקיה
המידע הבא מספק מידע מפורט על מיפוי תיקיות.
תבנית Xml
<Folder map="folderA" to="folderB" />
תיאור
נתיבי קבצים שמתאימים ל- folderA מוחלפים ל- folderB.
הירארכיית תיקיות המשנה מתחת לכל תיקיה חייבת להתאים באופן מדויק.
אין תמיכה בתווים כלליים עבור תיקיות.
לא ניתן לציין שמות קבצים.
דוגמאות
<Folder map="folderA" to="folderB" /> <Folder map="folderA\folderB" to="..\..\folderC\" /> <Folder map="WebResources\subFolder" to="%base%\WebResources" />
מיפוי קובץ לקובץ
המידע שלהלן מספק פרטים נוספים על מיפוי קובץ לקובץ.
תבנית Xml
<FileToFile map="path\filename.ext" to="path\filename.ext" />
תיאור
כל קובץ שמתאים לפרמטר map נקרא מהשם והנתיב שצוינו בפרמטר to.
עבור הפרמטר map:
יש לציין שם קובץ. הנתיב הוא אופציונלי. אם לא צוין נתיב, תיתכן התאמה של קבצים מכל תיקיה.
אין תמיכה בתווים כלליים עבור שמות קבצים.
קיימת תמיכה בתווים כלליים עבור תיקיות.
עבור הפרמטר
to:יש לציין שם קובץ ונתיב.
שם הקובץ עשוי להיות שונה מהשם בפרמטר
map.אין תמיכה בתווים כלליים עבור שמות קבצים.
קיימת תמיכה בתווים כלליים עבור תיקיות.
דוגמאות
<FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />
<FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />
<FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />
<FileToFile
map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
to="myplg\bin\Debug\myplg.1.0.0.nupkg" />
בדוגמה לחבילה NuGet, cr886_PluginPackageTest.nupkg אינו מוחלף אם הקובץ כבר קיים במיקום שצוין.
מיפוי קובץ לנתיב
להלן מידע מפורט על מיפוי קובץ לנתיב.
תבנית Xml
<FileToPath map="path\filename.ext" to="path" />
תיאור
כל קובץ שמתאים לפרמטר map ייקרא מהנתיב שצוין בפרמטר to.
עבור הפרמטר map:
יש לציין שם קובץ. הנתיב הוא אופציונלי. אם לא צוין נתיב, תיתכן התאמה של קבצים מכל תיקיה.
קיימת תמיכה בתווים כלליים עבור שמות קבצים.
קיימת תמיכה בתווים כלליים עבור תיקיות.
עבור הפרמטר to:
יש לציין נתיב.
קיימת תמיכה בתווים כלליים עבור תיקיות.
לא ניתן לציין שם קובץ.
דוגמאות
<FileToPath map="assembly.dll" to="c:\path\folder" />
<FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />
<FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />
<FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />
מיפוי לדוגמה
קוד ה- XML לדוגמה שלהלן מציג קובץ מיפוי שלם שמאפשר לכלי SolutionPackager לקרוא כל משאב אינטרנט ואת שתי ההכללות שנוצרות כברירת מחדל מפרוייקט של ערכת כלים למפתחים בשם CRMDevTookitSample.
<?xml version="1.0" encoding="utf-8"?>
<Mapping>
<!-- Match specific named files to an alternate folder -->
<FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />
<FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />
<!-- Match any file in and under WebResources to an alternate set of subfolders -->
<FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />
<FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />
</Mapping>
פתרונות מנוהלים ופתרונות לא מנוהלים
ניתן לייצא קובץ פתרון דחוס (.zip) של Dataverse באחד משני סוגים, כמוצג כאן.
פתרון מנוהל
פתרון שלם שמוכן לייבוא לארגון. לאחר הייבוא, לא ניתן להוסיף או להסיר רכיבים, למרות שהם עשויים לאפשר התאמה אישית נוספת. מומלץ כאשר פיתוח הפתרון הושלם.
פתרון לא מנוהל
פתרון פתוח ללא הגבלות לגבי הפריטים שניתן להוסיף, להסיר או לשנות. מומלץ במהלך פיתוח פתרון.
התבנית של קובץ פתרון דחוס תשתנה בהתאם לסוג שלו: מנוהל או לא מנוהל. SolutionPackager יכול לעבד קבצי פתרונות דחוסים משני הסוגים. עם זאת, לכלי אין אפשרות להמיר סוג אחד לסוג השני. הדרך היחידה להמיר קבצי פתרונות לסוג אחר – לדוגמה, מפתרון לא מנוהל לפתרון מנוהל – היא לייבא את קובץ ה- .zip של הפתרון הלא מנוהל לתוך שרת של Dataverse ולאחר מכן לייצא את הפתרון כפתרון מנוהל.
SolutionPackager יכול לעבד קבצי .zip של פתרונות מנוהלים ולא מנוהלים כערכה משולבת באמצעות הפרמטר /PackageType:Both. כדי לבצע פעולה זו, עליך לייצא את הפתרון שלך פעמיים ככל אחד מהסוגים ולאחר מכן לתת לקבצי ה- .zip את השמות הבאים.
| קובץ .zip לא מנוהל: AnyName.zip | קובץ .zip מנוהל: AnyName_managed.zip |
הכלי יניח שקובץ ה- zip המנוהל נמצא באותה תיקיה כמו הקובץ הלא מנוהל ויחלץ את שני הקבצים לתיקיה בודדת, תוך שמירה על ההבדלים כאשר קיימים רכיבים מנוהלים ולא מנוהלים.
לאחר חילוץ פתרון גם כלא מנוהל וגם כמנוהל, ניתן – מהתיקיה הבודדת – לארוז את שניהם, או כל סוג בנפרד, באמצעות הפרמטר /PackageType כדי לציין את הסוג שיש ליצור. אם שני הקבצים צוינו, ייווצרו שני קבצי .zip באמצעות המוסכמה למתן שמות המתוארת לעיל. אם הפרמטר /PackageType חסר בעת האריזה מתיקיה כפולה – מנוהלת ולא מנוהלת – ברירת המחדל היא ליצור קובץ .zip לא מנוהל אחד.
פתרון בעיות
אם אתה משתמש ב- Visual Studio כדי לערוך קבצי משאבים שנוצרו על-ידי Solution Packager, ייתכן שתקבל בעת האריזה מחדש את ההודעה הבאה: “Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process.” מצב זה מתרחש מכיוון ש- Visual Studio מחליף את תגי המטה-נתונים של קובץ המשאבים בתגי נתונים.
פתרון
פתח את קובץ המשאבים בעורך הטקסט המועדף עליך ולאחר מכן אתר ועדכן את התגים הבאים:
<data name="Source LCID" xml:space="preserve"> <data name="Source file" xml:space="preserve"> <data name="Source package type" xml:space="preserve"> <data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">שנה את שם הצומת מ-
<data>ל-<metadata>.לדוגמה, מחרוזת זו:
<data name="Source LCID" xml:space="preserve"> <value>1033</value> </data>תשתנה ל:
<metadata name="Source LCID" xml:space="preserve"> <value>1033</value> </metadata>באופן זה, Solution Packager יכול לקרוא ולייבא את קובץ המשאבים. בעיה זו נצפתה רק בעת השימוש בעורך המשאבים של Visual Studio.