TeamHiPo.Dynamics.WebApi 1.0.6

Helper classes to access the Dynamics 365 web API from C#. Mainly used for demostration purposes.

There is a newer version of this package available.
See the version list below for details.
Install-Package TeamHiPo.Dynamics.WebApi -Version 1.0.6
dotnet add package TeamHiPo.Dynamics.WebApi --version 1.0.6
<PackageReference Include="TeamHiPo.Dynamics.WebApi" Version="1.0.6" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add TeamHiPo.Dynamics.WebApi --version 1.0.6
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Simple Query with results

Step 1:

Create a class to hold the entity data you want. For example a contact.

        [DynamicsEntity("contact")]
        public class Contact : BaseEntity
        {
            [JsonProperty("fullname")]
            [DynamicsIncludeInQuery]
            public string FullName { get; set; }
            [JsonProperty("firstname")]
            [DynamicsIncludeInQuery]
            public string FirstName { get; set; }
            [JsonProperty("contactid")]
            [DynamicsId]
            public string ContactId { get; set; }
        }

Use the "DynamicsEntity" attribute on the class and extend the BaseEntity class to get some static helpers for use later in the example. Also use the "DynamicsIncludeInQuery" attribute to flag properties that you wanted included in the result set. Use the NewtonSoft "JsonProperty" attributes to tell the parser what name to expect in the json for this property. The BaseEntity helper functions will use these attributes to process results for its functions. Finally use the "DynamicsId" attribute to indicate which field is the Id field for this entity.

Step 2:

Create the D365WebService class passing it settings for which environment you want to connect to:

         D365WebService service = new D365WebService(Settings);

An instance of the DynamicsConnectionSettings class is passed into the constructor of the D365WebService to create it. The connection and DynmaicsConnectionSettings class assume that server to server authentication is being used. The following link provides instructions on how to create a AppId and Password for server to server authentication.

https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/walkthrough-multi-tenant-server-server-authentication

Step 3:

Create a query as follows:

        //create a new QueryFilter object
        QueryFilter filter = new QueryFilter();
        //Add filter criteria using the AddCriteria method
        //in this example a string is used for the field name. The base class static helpers can also be used as follows
        //so a string need not be used. For example Contact.GetSchemaName<Contact>(nameof(Contact.OwnerId))                 

        filter.AddCriteria("_ownerid_value", ComparisonOperators.Equal, "45AAEF1C-68AA-E711-A94E-000D3AF3538A");

        //create a retrieve multiple request and provide the entity name, fields and filter
        //if no filter is provided then all records are returned
        //notice the static help functions provided by the base class are used to get the entity name and list of fields
        //Alternately you can provide a list of fields to retrieve ad hoc as follows:
        //Fields = new SelectFieldList(new string[] {"fullname"})
        D365RetreiveMultipleRequest request = new D365RetreiveMultipleRequest()
        {
            EntityName = Contact.GetEntityName<Contact>(),
            Fields = Contact.GetSelectFields<Contact>(),
            Filter = filter,
            //optional if this is not 0 then it will limit the amount of records returned
            RetrieveTop = 2
        };
        //optionally you can set the sort order of the results
        request.AddOrderBy("firstname", ResultsOrder.Descending);
        //optionally you can include the record count. If not included the Count property will be null
        request.IncludeCount = true;

        D365ServiceResponse response = null;

        //Useful for debugging. The operation property is query component of the API request URL represented by the      retrieve  multiple request
        //from the above code
        Console.WriteLine($"Operation: {request.Operation}");
        //pass the request to the service
        response = service.RetreiveMultipleAsync(request).Result;

        //check for success
        if (response.Success)
        {
            List<Contact> contacts = null;
            //get the list of contacts returned from the response by using the generic GetData method
            contacts = response.GetData<List<Contact>>();
            //for debug the Json returned by Dynamics 365 is in the Json property
            Console.WriteLine(response.Json);
            Console.WriteLine($"Count: {response.Count}");
            if (contacts.Count > 0)
            {
                Console.WriteLine($"Id: {contacts.First().Id}");
                //the BaseEntity provides a property to get the URL of the Form for this record
                Console.WriteLine($"Relative Url: {contacts.First().RelativeUrl}");
            }
        }

To create a record

        Contact contact = new Contact()
        {
            FirstName = "Fred",
            LastName = "Flintstone"
        };
        D365WebService service = new D365WebService(Settings);

        D365CreateResponse response = service.CreateAsync(contact).Result;
        if (response.Success)
        {
            Console.WriteLine($"RecordId: {response.Id}");
        }

You may want to leave out some fields from the create message if they are null. Use the following:

        [DynamicsEntity("contact")]
        public class Contact : BaseEntity
        {
             [JsonProperty("fullname", NullValueHandling = NullValueHandling.Ignore)]
             public string FullName { get; set; }
        }

Simple Query with results

Step 1:

Create a class to hold the entity data you want. For example a contact.

        [DynamicsEntity("contact")]
        public class Contact : BaseEntity
        {
            [JsonProperty("fullname")]
            [DynamicsIncludeInQuery]
            public string FullName { get; set; }
            [JsonProperty("firstname")]
            [DynamicsIncludeInQuery]
            public string FirstName { get; set; }
            [JsonProperty("contactid")]
            [DynamicsId]
            public string ContactId { get; set; }
        }

Use the "DynamicsEntity" attribute on the class and extend the BaseEntity class to get some static helpers for use later in the example. Also use the "DynamicsIncludeInQuery" attribute to flag properties that you wanted included in the result set. Use the NewtonSoft "JsonProperty" attributes to tell the parser what name to expect in the json for this property. The BaseEntity helper functions will use these attributes to process results for its functions. Finally use the "DynamicsId" attribute to indicate which field is the Id field for this entity.

Step 2:

Create the D365WebService class passing it settings for which environment you want to connect to:

         D365WebService service = new D365WebService(Settings);

An instance of the DynamicsConnectionSettings class is passed into the constructor of the D365WebService to create it. The connection and DynmaicsConnectionSettings class assume that server to server authentication is being used. The following link provides instructions on how to create a AppId and Password for server to server authentication.

https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/walkthrough-multi-tenant-server-server-authentication

Step 3:

Create a query as follows:

        //create a new QueryFilter object
        QueryFilter filter = new QueryFilter();
        //Add filter criteria using the AddCriteria method
        //in this example a string is used for the field name. The base class static helpers can also be used as follows
        //so a string need not be used. For example Contact.GetSchemaName<Contact>(nameof(Contact.OwnerId))                 

        filter.AddCriteria("_ownerid_value", ComparisonOperators.Equal, "45AAEF1C-68AA-E711-A94E-000D3AF3538A");

        //create a retrieve multiple request and provide the entity name, fields and filter
        //if no filter is provided then all records are returned
        //notice the static help functions provided by the base class are used to get the entity name and list of fields
        //Alternately you can provide a list of fields to retrieve ad hoc as follows:
        //Fields = new SelectFieldList(new string[] {"fullname"})
        D365RetreiveMultipleRequest request = new D365RetreiveMultipleRequest()
        {
            EntityName = Contact.GetEntityName<Contact>(),
            Fields = Contact.GetSelectFields<Contact>(),
            Filter = filter,
            //optional if this is not 0 then it will limit the amount of records returned
            RetrieveTop = 2
        };
        //optionally you can set the sort order of the results
        request.AddOrderBy("firstname", ResultsOrder.Descending);
        //optionally you can include the record count. If not included the Count property will be null
        request.IncludeCount = true;

        D365ServiceResponse response = null;

        //Useful for debugging. The operation property is query component of the API request URL represented by the      retrieve  multiple request
        //from the above code
        Console.WriteLine($"Operation: {request.Operation}");
        //pass the request to the service
        response = service.RetreiveMultipleAsync(request).Result;

        //check for success
        if (response.Success)
        {
            List<Contact> contacts = null;
            //get the list of contacts returned from the response by using the generic GetData method
            contacts = response.GetData<List<Contact>>();
            //for debug the Json returned by Dynamics 365 is in the Json property
            Console.WriteLine(response.Json);
            Console.WriteLine($"Count: {response.Count}");
            if (contacts.Count > 0)
            {
                Console.WriteLine($"Id: {contacts.First().Id}");
                //the BaseEntity provides a property to get the URL of the Form for this record
                Console.WriteLine($"Relative Url: {contacts.First().RelativeUrl}");
            }
        }

To create a record

        Contact contact = new Contact()
        {
            FirstName = "Fred",
            LastName = "Flintstone"
        };
        D365WebService service = new D365WebService(Settings);

        D365CreateResponse response = service.CreateAsync(contact).Result;
        if (response.Success)
        {
            Console.WriteLine($"RecordId: {response.Id}");
        }

You may want to leave out some fields from the create message if they are null. Use the following:

        [DynamicsEntity("contact")]
        public class Contact : BaseEntity
        {
             [JsonProperty("fullname", NullValueHandling = NullValueHandling.Ignore)]
             public string FullName { get; set; }
        }

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
1.0.20 158 10/11/2018
1.0.19 145 9/19/2018
1.0.18 158 9/19/2018
1.0.17 137 9/19/2018
1.0.16 153 9/4/2018
1.0.14 142 8/31/2018
1.0.13 134 8/31/2018
1.0.12 183 7/12/2018
1.0.11 193 6/7/2018
1.0.10 171 6/7/2018
1.0.9 211 6/5/2018
1.0.8 185 6/5/2018
1.0.7 204 5/10/2018
1.0.6 205 5/1/2018
1.0.5 243 5/1/2018
1.0.4 197 4/30/2018
1.0.3 164 4/30/2018
1.0.2 210 4/30/2018
1.0.1 218 4/30/2018
1.0.0 205 4/30/2018
Show less