DOCSEARCHbyAlgolia
Submit Docs

PACX (Greg.Xrm.Command)

repository·master·Indexed 41 days ago

https://github.com/neronotte/greg.xrm.command

An open-source command-line utility belt for Microsoft Dataverse that extends the Power Platform CLI (PAC CLI). It provides automation commands for managing Dataverse organizations, solution components, Custom API lifecycles, and plugin steps, as well as tools for querying records via FetchXML, SQL, and OData.

Tokens
49.1K
Snippets
170
Records
202
Agent score
99%

What's inside PACX

  2. Overview of Greg.Xrm.Command (PACX)

    master
    Greg.Xrm.Command (also known as PACX) is a command-line utility belt designed for Microsoft Dataverse. It provides a set of specialized commands to perform operations that are not currently supported by the standard Power Platform CLI, such as performing dependency checks and manipulating the Dataverse datamodel.

  3. How field type conversion works in `pacx data create`

    master

    The pacx data create command automatically converts raw input strings into the appropriate Dataverse SDK types by inspecting the target table's metadata.

    Supported Conversions

    • Strings/Memo: Handled as standard strings.
    • Numbers: IntegerAttribute (int), DecimalAttribute (decimal), DoubleAttribute (double), and MoneyAttribute (new Money object).
    • Booleans: Parsed as bool.
    • Date/Time:
      • If the attribute is configured as DateOnly, it parses as DateOnly (time set to 00:00:00).
      • Otherwise, it parses as DateTime using ISO 8601 format.
    • Picklists (Choices):
      • Single-select: If the input is an integer, it creates an OptionSetValue(int). If it is a string, it searches for a matching label in the OptionMetadata.
      • Multi-select: Input values separated by commas are converted into an OptionSetValueCollection.
    • Lookups: Resolved via the LookupReferenceParser into an EntityReference.

    Limitations

    • File/Image Fields: Fields of type FileAttribute or ImageAttribute are skipped and cannot be set via this command. You will see a non-blocking warning: Field 'x' is of type File/Image and will be skipped.

  4. Resolve lookup references in `pacx data create`

    master

    When creating records, you can resolve lookup fields using two different syntaxes. This allows you to either provide a direct GUID or query for a record based on a specific field value.

    Syntax Options

    1. Direct GUID: Use entity(GUID) to point directly to a known record.
    2. Field-based Query: Use entity(fieldname='value') to resolve a record where the specified field matches the value. The command performs a RetrieveMultipleAsync query to find the record.

    Rules and Constraints

    • Ambiguity: If a field-based query returns 0 records, the command fails. If it returns 2 or more records, the command fails with an 'ambiguous value' error. It must return exactly 1 record.
    • Escaping: To include a single quote within a field value, use two single quotes (''). For example, name='Riccardo''s Corp'.
    • Polymorphic Lookups: For fields like customerid (which can be an account or a contact), specify the target entity name explicitly, e.g., account(accountnumber='ACME001') or contact(emailaddress1='user@example.com').
    pacx data create -t account --plain "name=Acme Corp;ownerid=systemuser(domainname='mario.rossi@contoso.com')"

pacx data create -t incident --plain "title=Support Case;customerid=account(accountnumber='ACME001')"

  5. Compare `data create` vs `data update`

    master

    While both commands share the same parsing and lookup resolution logic via the RecordPayloadProcessor, they differ in several key ways:

    Aspectdata createdata update
    --id parameterOptional (assigns GUID to new record)Mandatory (identifies record to update)
    SDK OperationIOrganizationService.Create()IOrganizationService.Update()
    Read-only fieldsIsValidForCreate == false → warning + skipIsValidForUpdate == false → warning + skip
    OutputGUID of created recordGUID of updated record
    --returnRetrieve after CreateRetrieve after Update

  6. Extend PACX with custom Tools

    master

    PACX is designed with a plugin-based approach similar to XrmToolbox. You can extend its capabilities by creating your own Tools.

    A Tool is a set of PACX commands packaged into a single .dll file. These can be:

    1. Deployed locally for specific single-use scenarios.
    2. Published to NuGet to make them available to the community.

    This is the recommended method for adding context-specific commands to the platform.

  7. Use PACX in Interactive mode

    master

    PACX features an interactive mode that provides a CLI-style UI for easier command discovery and execution.

    Key features of interactive mode include:

    • Navigation: Move through the command tree (upwards and downwards).
    • Search: Find specific commands and namespaces.
    • Execution: Run commands directly from the UI.
    • Help: Access inline help for commands/namespaces and on-demand help for specific options using /?.
    • Readability: Colorized output.
    pacx --interactive

  8. Manage Dataverse organization and languages

    master

    Use the pacx org command group to manage your Dataverse environment settings without using the Maker Portal. You can retrieve environment summaries with org info and manage supported languages programmatically using org language. This is useful for automated environment setup and managing multilingual deployments.

    Key commands:

    • pacx org info: Get a summary of the current environment.
    • pacx org language list: List current languages.
    • pacx org language add --lcid <LCID>: Add a language using its Locale ID.
    • pacx org language remove --lcid <LCID>: Remove a language.
    pacx org info
pacx org language list
pacx org language add --lcid 1040
pacx org language remove --lcid 1040

  9. Manage solution components

    master

    The pacx solution component command group allows for programmatic management of components within Dataverse solutions. This is ideal for scripting solution reorganizations or automated deployments.

    Key commands:

    • pacx solution component addTable --solution <Name> --table <TableName>: A convenience wrapper to add an entire table to a solution.
    • pacx solution component moveAll --fromSolution <Src> --toSolution <Dest> --componentType <Type>: Moves all components of a specific type between solutions.
    • pacx solution component types: Lists the numeric component type codes recognized by PACX.
    • pacx solution component add/remove/move: Standard operations for individual components using their GUIDs.
    pacx solution component add --solution MySolution --componentType 1 --componentId <guid>
pacx solution component move --fromSolution SolutionA --toSolution SolutionB --componentId <guid>
pacx solution component moveAll --fromSolution SolutionA --toSolution SolutionB --componentType 1
pacx solution component remove --solution MySolution --componentId <guid>
pacx solution component removeAll --solution MySolution --componentType 1
pacx solution component types
pacx solution component addTable --solution MySolution --table contact

  10. Manage user settings

    master

    Manage Dataverse user settings via the CLI. This is useful for toggling specific settings across environments during deployment or testing.

    Key commands:

    • pacx usersettings list: List all available user setting definitions.
    • pacx usersettings set --uilanguageid <ID>: Change a value for the current user in the current environment.
    pacx usersettings list
pacx usersettings set --uilanguageid 1040

  11. Manage the Custom API lifecycle

    master

    The pacx customapi command group provides full lifecycle management for Custom APIs, which are essential for exposing business logic to agents and connectors.

    Creation

    • Global API: pacx customapi create --unique-name <Name> --display-name <Name> --solution <Name>
    • Bound API: pacx customapi create --unique-name <Name> --display-name <Name> --binding-type Entity --bound-entity <EntityName> --solution <Name>
      • Note: --unique-name is optional; if omitted, PACX infers it from the display name and solution prefix.

    Evolution and Inspection

    • Parameters/Responses: Use add-param/remove-param and add-response/remove-response to evolve the API contract incrementally.
    • Inspection: pacx customapi list --full shows the complete signature (names, types, directions).
    • Documentation: pacx customapi describe --unique-name <Name> --generate-input-file --generate-schema-file creates local JSON templates and schemas.

    Execution and Binding

    • Run: pacx customapi run --unique-name <Name> --input-file <Path>
    • Bind: pacx customapi bind --api <Name> --plugin <PluginType>
    • Delete: pacx customapi delete --unique-name <Name>
    # Create a global Custom API
pacx customapi create --unique-name myp_MyAction --display-name "My Action" --solution MySolution

# Create a bound Custom API (entity binding)
pacx customapi create --unique-name myp_MyAction --display-name "My Action" \
  --binding-type Entity --bound-entity contact --solution MySolution

# Add parameters and response properties
pacx customapi add-param --api myp_MyAction --param InputName:String
pacx customapi add-response --api myp_MyAction --response OutputResult:String

# Inspect it
pacx customapi list --full
pacx customapi describe --unique-name myp_MyAction --generate-input-file --generate-schema-file

# Execute it
pacx customapi run --unique-name myp_MyAction --input-file input.json

# Bind to a plugin
pacx customapi bind --api myp_MyAction --plugin MyPlugin.MyType

# Clean up
pacx customapi remove-param --api myp_MyAction --name InputName
pacx customapi delete --unique-name myp_MyAction

  12. Manage Web Resource environment images

    master

    The pacx wr setEnvImage command (aliases: setLogo, setOrgImage) manages environment branding using the modern CustomThemeDefinition flow. This allows for version-controlled environment configurations.

    Key commands:

    • Set Org Logo: pacx wr setEnvImage --name <FileName> --color <HexColor>
    • Set App Logo: pacx wr setEnvImage --name <FileName> --appName <AppName>
    • Sync to Local File: pacx wr setEnvImage --file <FileName> --localThemeFile <Path>
      • Use --localThemeFile to keep a local XML theme file in sync with the deployed environment, enabling reproducible themes across environments.
    # Set the org-level logo for the first time
pacx wr setEnvImage --name mylogo.png --color "#0078D4"

# Update the logo for a specific app
pacx wr setEnvImage --name mylogo.png --appName "My Model App"

# Sync the theme to a local file for version control
pacx wr setEnvImage --file mylogo.png --localThemeFile ./theme.xml