Quick start with sample code

Use the code samples available with Microsoft Dynamics Marketing SDK package to get a demonstration of how to work with Microsoft Dynamics Marketing entities. More information: Sample code

Note

The code samples use shared helper code to perform common tasks. The helper code, which you might find useful in your applications, is available in the following folder in the SDK package:

Samples\CS\Client

For more information about running the samples, see the Readme file that is available with each sample code.

Prerequisites

• Install Microsoft Visual Studio 2012 or Visual Studio 2013.

• Install the NuGetVisual Studio extension that’s compatible with your Visual Studio version. More information: Installing NuGet

• Install Microsoft.ServiceBus package version 2.1.0.0

• Set up Microsoft Azure Service Bus queues for the SDK. To learn how to view and configure Microsoft Azure Service Bus, see Site configuration and integration settings.

• Enable SDK and the required permission set for entities. To learn how to configure SDK Service Settings, see Site configuration and integration settings.

• Enable authentication for the sample:

  • In the sample, if you use the default QueueClientProvider for authentication, apply the Default Rule Group to the queue in Microsoft Azure Active Directory Access Control Service (ACS). For more information on applying Rule Groups, see Configuring Rules with the ACS Management Portal.

  • If you use a different authentication in the sample, you also need to re-implement IQueueClientProvider and update its instantiation in SdkSample.CreatQueueClientProviderFromArgs.

• Open the folder where you installed the Microsoft Dynamics Marketing SDK and then open Samples\CS\HowToSamples.sln in Visual Studio. When you press F6 to build the solution, a NuGet package for the Microsoft Azure Service Bus will be automatically downloaded.

Install and build the sample code

Install and build using default authentication

1. Locate and open the Samples\CS\ folder, and then open the corresponding sample folder.

2. Open the csproject in Visual Studio.

3. Select Build > Build Solution or press F6 to start building the sample.

Install and build using custom authentication

1. Open the sample in Visual Studio.

2. If you have your own implementation of IQueueClientProvider:

   1. Add your QueueClientProvider to the SdkClient project.

   2. Open the SdkSample.cs file in the SdkSample project and update the CreateQueueClientProviderFromArgs to instantiate your new QueueClientProvider.

3. Select Build > Build Solution or press F6 to start building the sample.

Run the sample

1. Locate and open the Samples\CS folder, and then open the corresponding sample folder.

2. Open the project file (*csproject).

3. On the Project Properties for the sample project, switch to the Debug page and fill in the appropriate command-line arguments for the authentication you chose. If you are using the default QueueClientProvider, enter the following command-line arguments:

   • ServiceBusNamespace: Namespace of the Service Bus where you have created the queues for communicating to Microsoft Dynamics Marketing using the SDK.

   • ServiceBusIssuerName: Issuer name for the service bus authentication.

   • ServiceBusIssuerKey: Issuer secret key for service bus authentication.

   • RequestQueueName: Queue that has been set up for sending requests from a third-party client to Microsoft Dynamics Marketing.

   • ResponseQueueName: Queue that has been set up for a third-party client.

Next Steps

After running the program, select the options from the menu. Depending on the sample code you choose to run, the menu options will differ.

Sample code	Options	Demonstrates
Sample: Create and update external entities	Create or update external entity	CreateOrUpdateExternalEntityRequest class and CreateOrUpdateExternalEntityResponse class.
	Retrieve entity	RetrieveExternalEntityRequest class and RetrieveExternalEntityResponse class.
	Retrieve entity types	RetrieveExternalEntityTypesRequest class and RetrieveExternalEntityTypesResponse class.
	Retrieve entity IDs	RetrieveExternalIdsRequest class and RetrieveExternalIdsResponse class.
	Delete single entity	DeleteExternalEntityRequest class and DeleteExternalEntityResponse class.
	Delete category	DeleteExternalEntityTypeRequest class and DeleteExternalEntityTypeResponse class.
Sample: Create, read, and update a category	Create/Update user-defined categories	CreateOrUpdateCustomFieldCategoriesRequest class and CreateOrUpdateCustomFieldCategoriesResponse class.
Sample: Create, read, update, and delete a company (including UDF custom fields)	Retrieve a company	RetrieveCompanyRequest class and RetrieveCompanyResponse class.
	Create a company	CreateOrUpdateCompanyRequest class and CreateOrUpdateCompanyResponse class.
	Update a company	CreateOrUpdateCompanyRequest class and CreateOrUpdateCompanyResponse class.
	Delete a company	DeleteCompanyRequest class and DeleteCompanyResponse class.
	Retrieve multiple companies	RetrieveCompaniesRequest class and RetrieveCompaniesResponseclass.
Sample: Create, read, update, and delete contact (including custom fields)	Retrieve a contact	RetrieveContactRequest class and RetrieveContactResponse class.
	Create a contact	CreateOrUpdateContactRequest class and CreateOrUpdateContactResponse class.
	Update a contact	CreateOrUpdateContactRequest class and CreateOrUpdateContactResponse class.
	Delete a contact	DeleteContactRequest class and DeleteContactResponse class.
	Retrieve a list of salutations	RetrieveSalutationsRequest class and RetrieveSalutationsResponse class.
	Retrieve a list of currencies	RetrieveCurrenciesRequest class RetrieveCurrenciesResponse class.
	Retrieve a list of languages	RetrieveLanguagesRequest class and RetrieveLanguagesResponse class.
	Retrieve multiple contacts	RetrieveContactsRequest class and RetrieveContactsResponse class.
	Create multiple contacts	CreateOrUpdateContactsRequest class and CreateOrUpdateContactsResponse class.
Sample: Create, read, update, and cancel event attendance	Retrieve an event attendance	RetrieveEventAttendanceRequest class and RetrieveEventAttendanceResponse class.
	Create an event attendance	CreateOrUpdateEventAttendanceRequest class and CreateOrUpdateEventAttendanceResponse class.
	Update an event attendance	CreateOrUpdateEventAttendanceRequest class and CreateOrUpdateEventAttendanceResponse class.
	Cancel an event attendance	CancelEventAttendanceRequest class and CancelEventAttendanceResponse class.
	Retrieve a list of event attendance statuses	RetrieveEventAttendanceStatusesRequest class and RetrieveEventAttendanceStatusesResponse class.
Sample: Create, read, update, and cancel event registration	Retrieve an event registration	RetrieveEventRegistrationRequest class and RetrieveEventRegistrationResponse class.
	Create an event registration	CreateOrUpdateEventRegistrationRequest class and CreateOrUpdateEventRegistrationResponse class.
	Update an event registration	CreateOrUpdateEventRegistrationRequest class and CreateOrUpdateEventRegistrationResponse class.
	Cancel an event registration	CancelEventRegistrationRequest class and CancelEventRegistrationResponse class.
Sample: Create, read, update, and delete lead (including UDF custom fields)	Retrieve a lead	RetrieveLeadRequest class and RetrieveLeadResponse class.
	Create a lead	CreateOrUpdateLeadRequest class and CreateOrUpdateLeadResponse class.
	Update a lead	CreateOrUpdateLeadRequest class and CreateOrUpdateLeadResponse class.
	Delete a lead	DeleteLeadRequest class and DeleteLeadResponse class.
	Retrieve a list of priorities	RetrieveLeadPrioritiesRequest class and RetrieveLeadPrioritiesResponse class.
	Retrieve a list of statuses	RetrieveLeadStatusesRequest class and RetrieveLeadStatusesResponse class.
	Retrieve a list of territories	RetrieveTerritoriesRequest class and RetrieveTerritoriesResponse class.
	Retrieve a list of sales ratings	RetrieveSalesRatingsRequest class and RetrieveSalesRatingsResponse class.
	Retrieve multiple leads	RetrieveLeadsRequest class and RetrieveLeadsResponse class.
Sample: Create, read, update, and delete marketing results	Retrieve a marketing result	RetrieveMarketingResultRequest class and RetrieveMarketingResultResponse class.
	Create a marketing result	CreateOrUpdateMarketingResultRequest class and CreateOrUpdateMarketingResultResponse class.
	Update a marketing result	CreateOrUpdateMarketingResultRequest class and CreateOrUpdateMarketingResultResponse class.
	Delete a marketing result	DeleteMarketingResultRequest class and DeleteMarketingResultResponse class.
	Retrieve a list of marketing result types	RetrieveMarketingResultTypesRequest class and RetrieveMarketingResultTypesResponse class.
	Retrieve multiple marketing results	RetrieveMarketingResultsRequest class and RetrieveMarketingResultsResponse class.
Sample: Retrieve custom fields by Belongs-To company and entity	Retrieve custom fields	RetrieveCustomFieldsRequest class and RetrieveCustomFieldsResponse class.
Sample: Manage lists and send transactional or commercial email	Retrieve transaction email messages	RetrieveEmailMessagesRequest class and RetrieveEmailMessagesResponse class.
	Retrieve commercial email messages	RetrieveCommercialEmailMessagesRequest class and RetrieveCommercialEmailMessagesResponse class.
	Retrieve message schema for email message	RetrieveMessageSchemaForEmailMessageRequest class and RetrieveMessageSchemaForEmailMessageResponse class.
	Send email message by email	SendEmailMessageByEmailRequest class and SendEmailMessageByEmailResponse class.
	Send email message by ID	SendEmailMessageByIdRequest class and SendEmailMessageByIdResponse class.
	Send commercial email message	SendCommercialEmailMessageByIdRequest class and SendCommercialEmailMessageByIdResponse class.
	Retrieve email message sent status	RetrieveEmailMessagesentStatusRequest class and RetrieveEmailMessagesentStatusResponse class.
	Set contact permissions for an email address	SetContactPermissionsRequest class and SetContactPermissionsResponse class.
	Set contact permissions for multiple email addresses	SetContactsPermissionsRequest class and SetContactsPermissionsResponse class.
	Retrieve contact permissions for an email address	RetrieveContactPermissionsRequest class and RetrieveContactPermissionsResponse class.
	Retrieve a list of email addresses for which contact permissions are missing	RetrieveEmailMessagesRequest class and RetrieveEmailMessagesResponse class.
	Set email hard bounces to processed for a contact	SetEmailHardBouncesToProcessedForContactRequest class and SetEmailHardBouncesToProcessedForContactResponse class.
	Retrieve unprocessed email hard bounces	RetrieveUnprocessedEmailHardBouncesRequest class and RetrieveUnprocessedEmailHardBouncesResponse class.
Sample: Work with marketing lists	Add contact to marketing list by email	AddContactToMarketingListByEmailRequest class and AddContactsToMarketingListByEmailsResponse class.
	Add contacts to marketing lists by emails	AddContactsToMarketingListByEmailsRequest class and AddContactsToMarketingListByEmailsResponse class.
	Add contact to marketing list by ID	AddContactToMarketingListByIdRequest class and AddContactToMarketingListByIdResponse class.
	Add contacts to marketing list by IDs	AddContactsToMarketingListByIdsRequest class and AddContactsToMarketingListByIdsResponse class.
	Copy contacts from marketing list	CopyContactsFromMarketingListRequest class and CopyContactsFromMarketingListResponse class.
	Copy query to marketing list	CopyQueryToMarketingListRequest class and CopyQueryToMarketingListResponse class.
	Create marketing list	CreateMarketingListRequest class and CreateMarketingListResponse class.
	Delete marketing list	DeleteMarketingListRequest class and DeleteMarketingListResponse class.
	Remove all contacts from marketing list	RemoveAllContactsFromMarketingListRequest class and RemoveAllContactsFromMarketingListResponse class.
	Remove all contacts from marketing list by email	RemoveContactFromMarketingListByEmailRequest class and RemoveContactFromMarketingListByEmailResponse class.
	Remove contact from marketing list by ID	RemoveContactFromMarketingListByIdRequest class and RemoveContactFromMarketingListByIdResponse class.
	Retrieve all lists	RetrieveAllListsRequest class and RetrieveAllListsResponse class.
	Retrieve marketing list	RetrieveMarketingListRequest class and RetrieveMarketingListResponse class.
	Retrieve marketing lists	RetrieveMarketingListsRequest class and RetrieveMarketingListsResponse class.
	Update marketing list	UpdateMarketingListRequest class and UpdateMarketingListResponse class.

See Also

Concepts

Developer overview of Microsoft Dynamics Marketing
Getting started with the SDK
Sample code
Assembly included in the Microsoft Dynamics Marketing SDK

Other Resources

Web service and assembly reference

Send comments about this topic to Microsoft.
© 2015 Microsoft. All rights reserved.