Bewerken

Share via

pac modelbuilder

  • Artikel

Code Generator for Dataverse APIs and Tables

Use the pac modelbuilder build command to generate early-bound .NET classes for Dataverse tables, custom messages, and a class that is derived from the OrganizationServiceContext Class. Learn more about using this command to generate early bound classes

The class derived from OrganizationServiceContext:

  • Maintains state on the client to support features such as change management.
  • Implements the System.Linq.IQueryable Interface and a .NET Language-Integrated Query (LINQ) query provider so you can write LINQ queries using Dataverse data.

For more information about the capabilities that this code generation tool enables:

Note

The pac modelbuilder build command replaces the CrmSvcUtil.exe distributed with the Microsoft.CrmSdk.CoreTools NuGet package.

Commands

Command Description
pac modelbuilder build Builds a code model for Dataverse APIs and Tables

pac modelbuilder build

Builds a code model for Dataverse APIs and Tables

Note

Before you can use the build command you must first connect to Dataverse using the pac auth create command. If you have multiple connections, use the pac auth select to choose the Dataverse environment you want to generate code for.

Example

The following example shows how to use the build command with a command prompt.

pac modelbuilder build ^
  --entitynamesfilter account;contact ^
  --generatesdkmessages ^
  --messagenamesfilter examp_* ^
  --emitfieldsclasses ^
  --emitVirtualAttributes ^
  --namespace MyApps.Model ^
  --outdirectory c:\src\MyApps\Model ^
  --writesettingsTemplateFile ^
  --serviceContextName OrgContext

And the same command using PowerShell:

pac modelbuilder build `
  --entitynamesfilter 'account;contact' `
  --generatesdkmessages `
  --messagenamesfilter 'examp_*' `
  --emitfieldsclasses `
  --emitVirtualAttributes `
  --namespace 'MyApps.Model' `
  --outdirectory 'c:\src\MyApps\Model' `
  --writesettingsTemplateFile `
  --serviceContextName 'OrgContext'

Important

You need to surround any string parameters with single quotes when using PowerShell.

The result of this command is that the following files are written to the c:\src\MyApps\Model folder.

C:\src\MyApps\Model\
|---Entities\
|    |--account.cs
|    |--contact.cs
|---OptionSets\
|    |--addresstypes.cs
|---Messages\
|    |--examp_myapi.cs
|---EntityOptionSetEnum.cs
|---builderSettings.json
|---OrgContext.cs

builderSettings.json contains the parameters you specified for the command. You can use it to quickly regenerate the files as things change. The following example shows using the generated buildersettings.json file from the first command using the settingsTemplateFile:

pac modelbuilder build `
  --outdirectory c:\src\MyApps\Model `
  --settingsTemplateFile c:\src\MyApps\Model\builderSettings.json

You can also choose to create a builderSettings.json file and use that instead of passing all the parameters to the command. The following is an example that is equivalent to the first example above:

{
  "suppressINotifyPattern": false,
  "suppressGeneratedCodeAttribute": false,
  "language": "CS",
  "namespace": "MyApps.Model",
  "serviceContextName": "OrgContext",
  "generateSdkMessages": true,
  "generateGlobalOptionSets": false,
  "emitFieldsClasses": true,
  "entityTypesFolder": "Entities",
  "messagesTypesFolder": "Messages",
  "optionSetsTypesFolder": "OptionSets",
  "entityNamesFilter": [
    "account",
    "contact"
  ],
  "messageNamesFilter": [
    "examp_*"
  ],
  "emitEntityETC": false,
  "emitVirtualAttributes": true
}

If you pass parameters to the command while using the settingsTemplateFile parameter, the parameters passed to the command will override those set in the builderSettings.json file.

You can't use the settingsTemplateFile parameter and the writesettingsTemplateFile parameter at the same time.

Required Parameters for modelbuilder build

--outdirectory -o

Write directory for entity, message, and optionset files.

Optional Parameters for modelbuilder build

--emitentityetc -etc

When set, includes the entity ETC ( entity type code ) in the generated code.

This parameter requires no value. It's a switch.

--emitfieldsclasses -efc

Generate a constants structure that contains all of the field names by entity at the time of code generation.

This parameter requires no value. It's a switch.

--emitvirtualattributes -eva

When set, includes supporting name attributes for lookups that enable filtering on the primary name attribute values of lookup attributes.

This parameter requires no value. It's a switch.

--entitynamesfilter -enf

Filters the list of entities are retrieved when reading data from Dataverse. Passed in as a semicolon separated list. Using the form <entitylogicalname>;<entitylogicalname>

--entitytypesfolder -etf

Folder name that contains entities. The default name is 'Entities'.

--environment -env

Specifies the target Dataverse. The value may be a Guid or absolute https URL. When not specified, the active organization selected for the current auth profile will be used.

--generateGlobalOptionSets -go

Emit all Global OptionSets. Note: If an entity contains a reference to a global optionset, it is emitted even if this switch is not present.

--generatesdkmessages -a

When set, emits Sdk message classes as part of code generation.

This parameter requires no value. It's a switch.

--language -l

The language to use for the generated proxy code. This value can be either 'CS' or 'VB'. The default language is 'CS'.

--logLevel -ll

Log level. The default value is 'Off'.

Use one of these values:

  • Off
  • Critical
  • Error
  • Warning
  • Information
  • Verbose
  • ActivityTracing
  • All

--messagenamesfilter -mnf

Filters the list of messages that are retrieved when reading data from Dataverse. Passed in as a semicolon separated list, required messages (Create, Update, Delete, Retrieve, RetrieveMultiple, Associate and Disassociate) are always included. Use a trailing or leading asterisk (*) with the names of the messages to allow for all messages starting with or ending with a string. Using the form <messagename>;<messagename>.

--messagestypesfolder -mtf

Folder name that contains messages. The default name is 'Messages'.

--namespace -n

The namespace for the generated code. The default namespace is the global namespace.

--optionsetstypesfolder -otf

Folder name that contains option sets. The default name is 'OptionSets'.

--serviceContextName -sctx

The name for the generated service context. If a value is passed in, it's used for the Service Context. If not, no Service Context is generated.

--settingsTemplateFile -stf

Contains Settings to be used for this run of the Dataverse Model Builder, overrides any duplicate parameters on command line. Can't be set when --writesettingstemplate is used.

--suppressGeneratedCodeAttribute -sgca

When set, this suppress all generated objects being tagged with the code generation engine and version

This parameter requires no value. It's a switch.

--suppressINotifyPattern

When enabled, doesn't write the INotify wrappers for properties and classes.

--writesettingsTemplateFile -wstf

When set, writes a settings file out to the output directory with the current passed settings or default settings.

Remarks

The following are recommendations for using the pac modelbuilder build command.

Set the entitynamesfilter and messagenamesfilter parameters

Caution

We strongly recommend that you use the entitynamesfilter and messagenamesfilter parameters to limit the generated files to those you will use in your project. Otherwise, the build command will attempt to generate code for all tables and messages from Dataverse. This will take a significant amount of time to process.

Classes for the messages found in the Microsoft.Crm.Sdk.Messages and Microsoft.Xrm.Sdk.Messages namespace are not generated using this command. You should only include messages not found there in the messagenamesfilter parameter, such as custom actions.

Set suppressINotifyPattern if you aren't building a WPF application

The INotify wrappers that are suppressed by this command are used for databinding scenarios with WPF applications. If you aren't building a WPF application with the generated code, you don't need them. Use the suppressINotifyPattern parameter to suppress them.

Include serviceContextName when generating message classes

If you are generating message classes, you should always include the serviceContextName parameter to generate a OrganizationServiceContext, even if you aren't using it. The generated message classes require a property set in this file. Learn more about the error that occurs if you don't set this.

See also

Microsoft Power Platform CLI Command Groups
Microsoft Power Platform CLI overview