Sample: Create and update entity metadata

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

This sample code is for Microsoft Dynamics 365 (online & on-premises). Download the Microsoft Dynamics CRM SDK package. It can be found in the following location in the download package:

SampleCode\CS\Metadata\Entities\CreateUpdateEntityMetadata.cs

Requirements

For more information about the requirements for running the sample code provided in this SDK, see Use the sample and helper code.

Demonstrates

This sample shows how to create a custom entity by using the CreateEntityRequest message. It also uses the CreateAttributeRequest to add several different types of attributes to the entity.

Example

using System;
using System.ServiceModel;
using System.ServiceModel.Description;
using System.Diagnostics;
using System.Xml.Linq;

// These namespaces are found in the Microsoft.Xrm.Sdk.dll assembly
// found in the SDK\bin folder.
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Client;
using Microsoft.Xrm.Sdk.Query;
using Microsoft.Xrm.Sdk.Discovery;
using Microsoft.Xrm.Sdk.Messages;
using Microsoft.Xrm.Sdk.Metadata;

// This namespace is found in Microsoft.Crm.Sdk.Proxy.dll assembly
// found in the SDK\bin folder.
using Microsoft.Crm.Sdk.Messages;

namespace Microsoft.Crm.Sdk.Samples
{
    public class CreateUpdateEntityMetadata
    {
        #region Class Level Members
        /// <summary>
        /// Stores the organization service proxy.
        /// </summary>
        private OrganizationServiceProxy _serviceProxy;

        private const String _customEntityName = "new_bankaccount";

        #endregion Class Level Members

        #region How To Sample Code
        /// <summary>
        /// Create a custom entity.
        /// Update the custom entity.
        /// Optionally delete the custom entity.
        /// </summary>
        /// <param name="serverConfig">Contains server connection information.</param>
        /// <param name="promptForDelete">When True, the user will be prompted to delete all
        /// created entities.</param>
        public void Run(ServerConnection.Configuration serverConfig, bool promptForDelete)
        {
            try
            {

                // Connect to the Organization service. 
                // The using statement assures that the service proxy will be properly disposed.
                using (_serviceProxy = new OrganizationServiceProxy(serverConfig.OrganizationUri, serverConfig.HomeRealmUri, serverConfig.Credentials, serverConfig.DeviceCredentials))
                {
                    // This statement is required to enable early-bound type support.
                    _serviceProxy.EnableProxyTypes();


                    // Create the custom entity.
                    CreateEntityRequest createrequest = new CreateEntityRequest
                    {

                        //Define the entity
                        Entity = new EntityMetadata
                        {
                            SchemaName = _customEntityName,
                            DisplayName = new Label("Bank Account", 1033),
                            DisplayCollectionName = new Label("Bank Accounts", 1033),
                            Description = new Label("An entity to store information about customer bank accounts", 1033),
                            OwnershipType = OwnershipTypes.UserOwned,
                            IsActivity = false,

                        },

                        // Define the primary attribute for the entity
                        PrimaryAttribute = new StringAttributeMetadata
                        {
                            SchemaName = "new_accountname",
                            RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
                            MaxLength = 100,
                            FormatName = StringFormatName.Text,
                            DisplayName = new Label("Account Name", 1033),
                            Description = new Label("The primary attribute for the Bank Account entity.", 1033)
                        }

                    };
                    _serviceProxy.Execute(createrequest);
                    Console.WriteLine("The Bank Account custom entity has been created.");


                    // Add some attributes to the Bank Account entity
                    CreateAttributeRequest createBankNameAttributeRequest = new CreateAttributeRequest
                    {
                        EntityName = _customEntityName,
                        Attribute = new StringAttributeMetadata
                        {
                            SchemaName = "new_bankname",
                            RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
                            MaxLength = 100,
                            FormatName = StringFormatName.Text,
                            DisplayName = new Label("Bank Name", 1033),
                            Description = new Label("The name of the bank.", 1033)
                        }
                    };

                    _serviceProxy.Execute(createBankNameAttributeRequest);
                    Console.WriteLine("\nA Bank Name attribute has been added to the Bank Account entity.");

                    CreateAttributeRequest createBalanceAttributeRequest = new CreateAttributeRequest
                    {
                        EntityName = _customEntityName,
                        Attribute = new MoneyAttributeMetadata
                        {
                            SchemaName = "new_balance",
                            RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
                            PrecisionSource = 2,
                            DisplayName = new Label("Balance", 1033),
                            Description = new Label("Account Balance at the last known date", 1033),

                        }
                    };

                    _serviceProxy.Execute(createBalanceAttributeRequest);
                    Console.WriteLine("A Balance attribute has been added to the Bank Account entity.");

                    CreateAttributeRequest createCheckedDateRequest = new CreateAttributeRequest
                    {
                        EntityName = _customEntityName,
                        Attribute = new DateTimeAttributeMetadata
                        {
                            SchemaName = "new_checkeddate",
                            RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
                            Format = DateTimeFormat.DateOnly,
                            DisplayName = new Label("Date", 1033),
                            Description = new Label("The date the account balance was last confirmed", 1033)

                        }
                    };

                    _serviceProxy.Execute(createCheckedDateRequest);
                    Console.WriteLine("A date attribute has been added to the Bank Account entity.");


                    //Create a customer lookup attribute to link the bank account with an account or a contact record.
                    CreateCustomerRelationshipsRequest createCustomerReq = new CreateCustomerRelationshipsRequest
                    {
                        Lookup = new LookupAttributeMetadata
                        {
                            Description = new Label("The owner of the bank account", 1033),
                            DisplayName = new Label("Account owner", 1033),
                            RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.ApplicationRequired),
                            SchemaName = "new_customerid"
                        },
                        OneToManyRelationships = new OneToManyRelationshipMetadata[]
                        {
                            new OneToManyRelationshipMetadata()
                            {
                                ReferencedEntity = "account",
                                ReferencingEntity = _customEntityName,
                                SchemaName = "new_bankaccount_customer_account",
                            },
                            new OneToManyRelationshipMetadata()
                            {
                                ReferencedEntity = "contact",
                                ReferencingEntity = _customEntityName,
                                SchemaName = "new_bankaccount_customer_contact",
                            }
                        },
                    };
                    _serviceProxy.Execute(createCustomerReq);
                    Console.WriteLine("A customer lookup attribute has been added to the Bank Account entity \nto link it with the Account or Contact entity.");


                    //Create a lookup attribute to link the bank account with a contact record.
                    CreateOneToManyRequest req = new CreateOneToManyRequest()
                    {
                        Lookup = new LookupAttributeMetadata()
                        {
                            Description = new Label("The referral (lead) from the bank account owner", 1033),
                            DisplayName = new Label("Referral", 1033),
                            LogicalName = "new_parent_leadid",
                            SchemaName = "New_Parent_leadId",
                            RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.Recommended)
                        },
                        OneToManyRelationship = new OneToManyRelationshipMetadata()
                        {
                            AssociatedMenuConfiguration = new AssociatedMenuConfiguration()
                            {
                                Behavior = AssociatedMenuBehavior.UseCollectionName,
                                Group = AssociatedMenuGroup.Details,
                                Label = new Label("Bank Accounts", 1033),
                                Order = 10000
                            },
                            CascadeConfiguration = new CascadeConfiguration()
                            {
                                Assign = CascadeType.Cascade,
                                Delete = CascadeType.Cascade,
                                Merge = CascadeType.Cascade,
                                Reparent = CascadeType.Cascade,
                                Share = CascadeType.Cascade,
                                Unshare = CascadeType.Cascade
                            },
                            ReferencedEntity = "lead",
                            ReferencedAttribute = "leadid",
                            ReferencingEntity = _customEntityName,
                            SchemaName = "new_lead_new_bankaccount"
                        }
                    };
                    _serviceProxy.Execute(req);
                    Console.WriteLine("A lookup attribute has been added to the Bank Account entity \nto link it with the Lead entity.");

                    //Create an Image attribute for the custom entity
                    // Only one Image attribute can be added to an entity that doesn't already have one.
                    CreateAttributeRequest createEntityImageRequest = new CreateAttributeRequest
                    {
                        EntityName = _customEntityName,
                        Attribute = new ImageAttributeMetadata
                        {
                            SchemaName = "EntityImage", //The name is always EntityImage
                            RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
                            DisplayName = new Label("Image", 1033),
                            Description = new Label("An image to represent the bank account.", 1033)

                        }
                    };

                    _serviceProxy.Execute(createEntityImageRequest);
                    Console.WriteLine("An image attribute has been added to the Bank Account entity.");


                    RetrieveEntityRequest retrieveBankAccountEntityRequest = new RetrieveEntityRequest
                    {
                        EntityFilters = EntityFilters.Entity,
                        LogicalName = _customEntityName
                    };
                    RetrieveEntityResponse retrieveBankAccountEntityResponse = (RetrieveEntityResponse)_serviceProxy.Execute(retrieveBankAccountEntityRequest);
                    EntityMetadata BankAccountEntity = retrieveBankAccountEntityResponse.EntityMetadata;

                    // Disable Mail merge
                    BankAccountEntity.IsMailMergeEnabled = new BooleanManagedProperty(false);
                    // Enable Notes
                    UpdateEntityRequest updateBankAccountRequest = new UpdateEntityRequest
                    {
                        Entity = BankAccountEntity,
                        HasNotes = true
                    };



                    _serviceProxy.Execute(updateBankAccountRequest);

                    Console.WriteLine("\nThe Bank Account entity has been updated");


                    //Update the entity form so the new fields are visible
                    UpdateEntityForm(_customEntityName);

                    // Customizations must be published after an entity is updated.
                    PublishAllXmlRequest publishRequest = new PublishAllXmlRequest();
                    _serviceProxy.Execute(publishRequest);
                    Console.WriteLine("\nCustomizations were published.");

                    //Provides option to view the entity in the default solution
                    ShowEntityInBrowser(promptForDelete, BankAccountEntity);
                    //Provides option to view the entity form with the fields added
                    ShowEntityFormInBrowser(promptForDelete, BankAccountEntity);

                    DeleteRequiredRecords(promptForDelete);
                }
            }

            // Catch any service fault exceptions that Microsoft Dynamics CRM throws.
            catch (FaultException<Microsoft.Xrm.Sdk.OrganizationServiceFault>)
            {
                // You can handle an exception here or pass it back to the calling method.
                throw;
            }
        }

        /// <summary>
        /// Deletes the custom entity that was created for this sample.
        /// <param name="prompt">Indicates whether to prompt the user to delete the records created in this sample.</param>
        /// </summary>
        public void DeleteRequiredRecords(bool prompt)
        {
            bool deleteEntity = true;

            if (prompt)
            {
                Console.WriteLine("\nDo you want the Bank Account custom entity deleted? (y/n)");
                String answer = Console.ReadLine();

                deleteEntity = (answer.StartsWith("y") || answer.StartsWith("Y"));
            }

            if (deleteEntity)
            {
                DeleteEntityRequest request = new DeleteEntityRequest()
                {
                    LogicalName = _customEntityName,
                };
                _serviceProxy.Execute(request);
                Console.WriteLine("The custom entity has been deleted.");
            }
        }

        public void ShowEntityInBrowser(bool prompt, EntityMetadata BankAccountEntity)
        {

            if (prompt)
            {

                Console.WriteLine("\nDo you want to view the Bank Account custom entity in the default solution? (y/n)");
                String answer = Console.ReadLine();
                if (answer.StartsWith("y") || answer.StartsWith("Y"))
                {

                    try
                    {
                        String webServiceURL = _serviceProxy.EndpointSwitch.PrimaryEndpoint.AbsoluteUri;
                        String entityInDefaultSolutionUrl = webServiceURL.Replace("XRMServices/2011/Organization.svc",
                         String.Format("tools/solution/edit.aspx?def_category=9801&def_type={0}&id=%7bFD140AAF-4DF4-11DD-BD17-0019B9312238%7d", BankAccountEntity.ObjectTypeCode));

                        ProcessStartInfo browserProcess = new ProcessStartInfo("iexplore.exe");
                        browserProcess.Arguments = entityInDefaultSolutionUrl;
                        Process.Start(browserProcess);

                    }
                    catch (SystemException)
                    {
                        Console.WriteLine("\nThere was a problem opening Internet Explorer.");
                    }

                }

            }


        }

        public void ShowEntityFormInBrowser(bool prompt, EntityMetadata BankAccountEntity)
        {
            if (prompt)
            {
                Console.WriteLine("\nDo you want to view the form for this entity? (y/n)");
                String viewFormAnswer = Console.ReadLine();
                if (viewFormAnswer.StartsWith("y") || viewFormAnswer.StartsWith("Y"))
                {
                    try
                    {
                        String webServiceURL = _serviceProxy.EndpointSwitch.PrimaryEndpoint.AbsoluteUri;
                        String entityInDefaultSolutionUrl = webServiceURL.Replace("XRMServices/2011/Organization.svc",
                         String.Format("main.aspx?etn={0}&pagetype=entityrecord", BankAccountEntity.LogicalName));

                        ProcessStartInfo browserProcess = new ProcessStartInfo("iexplore.exe");
                        browserProcess.Arguments = entityInDefaultSolutionUrl;
                        Process.Start(browserProcess);

                    }
                    catch (SystemException)
                    {
                        Console.WriteLine("\nThere was a problem opening Internet Explorer.");
                    }
                }
            }
        }
        /// <summary>
        /// Updates the formXml to add a new tab containing the fields added by this sample.
        /// <param name="entityLogicalName">The logical name of the new_bankaccount entity used in this sample</param>
        /// </summary>
        public void UpdateEntityForm(String entityLogicalName)
        {

            QueryExpression qe = new QueryExpression("systemform");
            qe.Criteria.AddCondition("type", ConditionOperator.Equal, 2); //main form
            qe.Criteria.AddCondition("objecttypecode", ConditionOperator.Equal, entityLogicalName); //for new_bankaccount entity
            qe.ColumnSet.AddColumn("formxml");
            //Retrieve the first main entity form for this entity
            SystemForm bankAccountMainForm = (SystemForm)_serviceProxy.RetrieveMultiple(qe).Entities[0];

            XDocument bankAccountFormXml = XDocument.Parse(bankAccountMainForm.FormXml);
            //Set the showImage attribute so the entity image will be displayed
            bankAccountFormXml.Root.SetAttributeValue("showImage", true);

            // Definition of a custom tab containing the custom attributes created in this sample
            String formTabXmlString = @"<tab name=""custom_attributes""
       id=""{824792c4-ea85-1504-40e2-b780b26dc6ab}""
       IsUserDefined=""0""
       locklevel=""0""
       showlabel=""true""
       expanded=""true"">
   <labels>
    <label description=""Custom Attributes""
           languagecode=""1033"" />
   </labels>
   <columns>
    <column width=""100%"">
     <sections>
      <section name=""custom_section""
               showlabel=""false""
               showbar=""false""
               locklevel=""0""
               id=""{9bda81ec-e41b-7a4d-08b4-4536c5862ce1}""
               IsUserDefined=""0""
               layout=""varwidth""
               columns=""1""
               labelwidth=""115""
               celllabelalignment=""Left""
               celllabelposition=""Left"">
       <labels>
        <label description=""Section""
               languagecode=""1033"" />
       </labels>
       <rows>
        <row>
         <cell id=""{99FF4728-D8D7-47D3-B046-7BEFCBFB4319}""
               showlabel=""true""
               locklevel=""0"">
          <labels>
           <label description=""Account Owner""
                  languagecode=""1033"" />
          </labels>
          <control id=""new_customerid""
                   classid=""{270BD3DB-D9AF-4782-9025-509E298DEC0A}""
                   datafieldname=""new_customerid""
                   disabled=""false"" />
          </cell>
        </row>        
        <row>
         <cell id=""{6e5975d3-64b5-14eb-00e4-064e3dd298b9}""
               showlabel=""true""
               locklevel=""0"">
          <labels>
           <label description=""Bank Name""
                  languagecode=""1033"" />
          </labels>
          <control id=""new_bankname""
                   classid=""{4273EDBD-AC1D-40d3-9FB2-095C621B552D}""
                   datafieldname=""new_bankname""
                   disabled=""false"" />
         </cell>
        </row>
        <row>
         <cell id=""{3b436dba-6156-42e9-697b-e275d373505b}""
               showlabel=""true""
               locklevel=""0"">
          <labels>
           <label description=""Balance""
                  languagecode=""1033"" />
          </labels>
          <control id=""new_balance""
                   classid=""{533B9E00-756B-4312-95A0-DC888637AC78}""
                   datafieldname=""new_balance""
                   disabled=""false"" />
         </cell>
        </row>
        <row>
         <cell id=""{0e9a3d8a-bd69-71ad-4ca4-2dcd10858719}""
               showlabel=""true""
               locklevel=""0"">
          <labels>
           <label description=""Date""
                  languagecode=""1033"" />
          </labels>
          <control id=""new_checkeddate""
                   classid=""{5B773807-9FB2-42db-97C3-7A91EFF8ADFF}""
                   datafieldname=""new_checkeddate""
                   disabled=""false"" />
         </cell>
        </row>
        <row>
         <cell id=""{04b95931-78c7-6913-a005-922d20e521b7}""
               showlabel=""true""
               locklevel=""0"">
          <labels>
           <label description=""Referral""
                  languagecode=""1033"" />
          </labels>
          <control id=""new_parent_leadid""
                   classid=""{270BD3DB-D9AF-4782-9025-509E298DEC0A}""
                   datafieldname=""new_parent_leadid""
                   disabled=""false"" />
         </cell>
        </row>
       </rows>
      </section>
     </sections>
    </column>
   </columns>
  </tab>";

            XDocument formTabXml = XDocument.Parse(formTabXmlString);

            //Adding this tab to the tabs element
            bankAccountFormXml.Root.Element("tabs").Add(formTabXml.Root);
            //Updateing the entity form definition
            bankAccountMainForm.FormXml = bankAccountFormXml.ToString();
            //saving the bank account form
            _serviceProxy.Update(bankAccountMainForm);

        }
        #endregion How To Sample Code

        #region Main
        /// <summary>
        /// Standard Main() method used by most SDK samples.
        /// </summary>
        /// <param name="args"></param>
        static public void Main(string[] args)
        {
            try
            {
                // Obtain the target organization's Web address and client logon 
                // credentials from the user.
                ServerConnection serverConnect = new ServerConnection();
                ServerConnection.Configuration config = serverConnect.GetServerConfiguration();

                CreateUpdateEntityMetadata app = new CreateUpdateEntityMetadata();
                app.Run(config, true);
            }
            catch (FaultException<Microsoft.Xrm.Sdk.OrganizationServiceFault> ex)
            {
                Console.WriteLine("The application terminated with an error.");
                Console.WriteLine("Timestamp: {0}", ex.Detail.Timestamp);
                Console.WriteLine("Code: {0}", ex.Detail.ErrorCode);
                Console.WriteLine("Message: {0}", ex.Detail.Message);
                Console.WriteLine("Plugin Trace: {0}", ex.Detail.TraceText);
                Console.WriteLine("Inner Fault: {0}",
                    null == ex.Detail.InnerFault ? "No Inner Fault" : "Has Inner Fault");
            }
            catch (System.TimeoutException ex)
            {
                Console.WriteLine("The application terminated with an error.");
                Console.WriteLine("Message: {0}", ex.Message);
                Console.WriteLine("Stack Trace: {0}", ex.StackTrace);
                Console.WriteLine("Inner Fault: {0}",
                    null == ex.InnerException.Message ? "No Inner Fault" : ex.InnerException.Message);
            }
            catch (System.Exception ex)
            {
                Console.WriteLine("The application terminated with an error.");
                Console.WriteLine(ex.Message);

                // Display the details of the inner exception.
                if (ex.InnerException != null)
                {
                    Console.WriteLine(ex.InnerException.Message);

                    FaultException<Microsoft.Xrm.Sdk.OrganizationServiceFault> fe = ex.InnerException
                        as FaultException<Microsoft.Xrm.Sdk.OrganizationServiceFault>;
                    if (fe != null)
                    {
                        Console.WriteLine("Timestamp: {0}", fe.Detail.Timestamp);
                        Console.WriteLine("Code: {0}", fe.Detail.ErrorCode);
                        Console.WriteLine("Message: {0}", fe.Detail.Message);
                        Console.WriteLine("Plugin Trace: {0}", fe.Detail.TraceText);
                        Console.WriteLine("Inner Fault: {0}",
                            null == fe.Detail.InnerFault ? "No Inner Fault" : "Has Inner Fault");
                    }
                }
            }
            // Additional exceptions to catch: SecurityTokenValidationException, ExpiredSecurityTokenException,
            // SecurityAccessDeniedException, MessageSecurityException, and SecurityNegotiationException.

            finally
            {

                Console.WriteLine("Press <Enter> to exit.");
                Console.ReadLine();
            }

        }
        #endregion Main

    }
}

See Also

RetrieveAllEntitiesRequest
RetrieveAllEntitiesResponse
Customize entity metadata
Sample: Create a custom activity entity
Use the Organization service with Dynamics 365 metadata

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright