in implementation guides ~ read.
Salesforce Developer Environment Dotnet Tipsheet

Salesforce Developer Environment Dotnet Tipsheet

DOWNLOAD

First things first !
To download this implementation guide, click the download button below.
If you need more information about the implementation guide, you can read the Table of Contents below.

Download

SETTING UP YOUR NET DEVELOPER

ENVIRONMENT

Summary
Configure your local dev
environment for integrating

with Salesforce using NET

This tipsheet describes how to set up your local environment so that you can start using Salesforce APIs

such as SOAP API or REST API

Note If youre setting up a local environment to develop Salesforce applications using Apex and

custom Metadata API components take a look at the Forcecom IDE

This tipsheet focuses on tools and configurations youll need to set up your local development system It

assumes you already have a working Salesforce organization with the API Enabled permission API is

enabled by default on Developer Edition Enterprise Edition Unlimited Edition and Performance Edition
organizations
If you are not already a member of the Lightning Platform developer community go to
developersalesforcecomsignup and follow the instructions for signing up for a Developer
Edition organization Even if you already have Enterprise Edition Unlimited Edition or Performance Edition
use Developer Edition for developing staging and testing your solutions against sample data to protect
your organizations live data This is especially true for applications that insert update or delete data as
opposed to simply reading data
If you have a Salesforce organization you can use for development but need to set up a sandbox for
development and testing see Deploy Enhancements from Sandboxes in Salesforce Help

Installing Microsoft Visual Studio
Youll need to install Microsoft Visual Studio to use Salesforce APIs Visual Studio is a development

environment that enables you to create robust NET applications

To install Microsoft Visual Studio youll need a Windows system with Internet access Depending on your
system you might also need administratorlevel access to install Visual Studio
Microsoft Visual Studio provides the necessary development tools and SDKs that are required to build
Windows applications There are several versions and editions of Visual Studio each with different features
and different Windows platform requirements See
httpwwwvisualstudiocomproductscomparevisualstudioproductsvs to compare current editions
For this tip sheet we use Visual Studio Express for Windows on a Windows system
Navigate to httpwwwvisualstudiocomdownloadsdownloadvisualstudiovs in your browser
Follow the instructions to download the version of Visual Studio that fits your development needs
Doubleclick the installer executable and follow the steps to install Visual Studio

Picking a Path Based on Which API You Use

The next steps for setting up your development environment depend on which Salesforce API you want

to use

To use SOAP API CRUDbased Metadata API or any other WSDLbased Salesforce API complete the steps

in the following tasks

Download Developer WSDL Files WSDLBased APIs on page

Last updated February

Setting Up Your NET Developer Environment

Download Developer WSDL Files WSDLBased APIs

Verify the WSDL Environment WSDLBased APIs on page

To use REST API Bulk API Chatter API or any other RESTbased Salesforce APIs complete the steps in the

following tasks
Setting Up Connected App Access RESTBased APIs on page

Verify the REST Environment RESTBased APIs on page

Tooling API provides SOAP and REST interfaces so depending on your needs you can set up your

environment by using one of the paths above

Download Developer WSDL Files WSDLBased APIs

Salesforce Web Services Definition Language WSDL files provide API details that you use in your developer

environment to make API calls

To download WSDL files directly from your Salesforce organization

Log in to your Salesforce developer organization in your browser

From Setup enter API in the Quick Find box then select API

Download the appropriate WSDL files for the API you want to use

a If you want to use SOAP API youll need either the Enterprise or Partner WSDL See Choosing a

WSDL in the SOAP API Developer Guide to determine which WSDL to download

b If you want to use Metadata API youll need the Metadata WSDL To login and authenticate with

Salesforce youll also need either the Enterprise or Partner WSDL

c If you want to use Tooling API youll need the Tooling WSDL To login and authenticate with

Salesforce youll also need either the Enterprise or Partner WSDL

Verify the WSDL Environment WSDLBased APIs

You can verify your developer environment with a simple C test application in Visual Studio

You should have Visual Studio installed and have the WSDL files that you need to use available Youll

need the Enterprise or Partner WSDL to follow the verification steps

Start Visual Studio
Click File New Project

In the New Project window navigate to Installed Templates Visual C Windows Select

Console Application
In the New Project window under Name name the project VerifyWSDLTest Under Solution
name name the solution VerifyWSDLTest Under Location pick a file location that youll

remember Click Ok A solution is created and Programcs is opened for editing

Click Project Add Service Reference

In the Add Service Reference window under Address enter the file URL path to your Enterprise or

Partner WSDL file For example if enterprisewsdl is saved in cwsdls enter

filecwsdlsenterprisewsdl Click Go The Services list is populated with an entry
that is named SforceService
Select SforceService Under Namespace enter sforce Your Add Service Reference window should
look something like the following image

Setting Up Your NET Developer Environment

Verify the WSDL Environment WSDLBased APIs

Click Ok The WSDL services are imported under the sforce namespace in your project

Replace the code in Programcs as described in the following section

Use the following simple login example code for your Programcs contents Replace YOUR DEVORG

USERNAME with your developer organization username and replace YOUR DEVORG PASSWORD

AND SECURITY TOKEN with your developer organization password appended with your security

token If you did not set a security token in your organization just provide your password A GitHub Gist

of this code is available here httpsgistgithubcomanonymousdcfbfb
using
using
using
using
using
using
using

System
SystemCollectionsGeneric
SystemLinq
SystemText
SystemThreadingTasks
SystemServiceModel
VerifyWSDLTestsforce

namespace VerifyWSDLTest

class Program

private static SoapClient client
private static LoginResult loginResult
private static bool login

client new SoapClient

string acctName YOUR DEVORG USERNAME

string acctPw YOUR DEVORG PASSWORD AND SECURITY TOKEN

Setting Up Your NET Developer Environment

Verify the WSDL Environment WSDLBased APIs

try

loginResult clientloginnull acctName acctPw

catch Exception e

ConsoleWriteLineUnexpected login error
eMessage
ConsoleWriteLineeStackTrace
return false

return true success

static void Mainstring args

if login

display some current login settings
ConsoleWriteService endpoint
loginResultserverUrl n
ConsoleWriteUsername
loginResultuserInfouserName n
ConsoleWriteSessionId loginResultsessionId
n
ConsoleWritePress any key to continuen
ConsoleReadKey

The following example output shows a typical successful run of this code
Service endpoint

httpsyourInstancesalesforcecomservicesSoapcDUTfDFUXpB

Username myUsermydeveditioncom
SessionId

DULfARoAQOYUBIRHntDOCfzESyoJJwHNovyYvIPTGjcvnC

Press any key to continue

If the verification project runs and displays output that matches your organization your developer

environment is set up and you can start developing NET applications that integrate with Salesforce If you

have additional WSDL files you can add them to your project via the Add Service Reference dialog as

described in steps and above
If you are using Microsoft Visual Studio or earlier in step Add Service Reference might be unavailable

Use Add Web Reference instead Under URL enter the file path to your WSDL such as

filecwsdlsenterprisewsdl Name the web reference sforce and click Add
Reference If you have to use a web reference use an instance of SforceService to call
SforceServicelogin instead of SoapClientlogin

Setting Up Your NET Developer Environment

Setting Up Connected App Access RESTBased APIs

Setting Up Connected App Access RESTBased APIs

Because Salesforce REST APIs use OAuth authentication youll need to create a connected app to integrate

your application with Salesforce

A connected app integrates an application with Salesforce using APIs Connected apps use standard SAML

and OAuth protocols to authenticate provide single signon and provide tokens for use with Salesforce
APIs In addition to standard OAuth capabilities connected apps allow Salesforce admins to set various
security policies and have explicit control over who can use the corresponding apps
The New Connected App wizard walks you through creating a connected app
Next specify basic information about your app
Enter the connected apps name This name is displayed in the App Manager and on its App Launcher
tile
Note The connected app name must be unique for the connected apps in your org If the
connected app was created using the Spring release or later you can reuse the name of a
deleted connected app

Enter the API name used when referring to your app from a program It defaults to a version of the

name without spaces Only letters numbers and underscores are allowed so if the original app name
contains any other characters edit the default name
Enter the contact email for Salesforce to use when contacting you or your support team This address
isnt given to Salesforce admins who install the app
Enter the contact phone for Salesforce to use in case we want to contact you This number isnt given
to Salesforce admins who install the app

To display your logo on the App Launcher tile enter a logo image URL Your logo also appears on the

consent page that users see when authenticating The URL must use HTTPS Use a GIF JPG or PNG

file and a file size thats preferably under KB but at most KB We resize the image to pixels

by pixels so be sure that you like how it looks If you dont supply a logo Salesforce generates
one for you using the apps initials
You can upload your own logo image by clicking Upload logo image Select an image from your
local file system that meets the size requirements for the logo When your upload is successful

meets the size requirements
You can also select a logo from the Salesforce samples by clicking Choose one of our sample
logos The logos include ones for Salesforce apps thirdparty apps and standards bodies Click

the logo you want and then copy and paste the URL into the Logo Image URL field

You can use a logo hosted publicly on Salesforce servers by uploading an image as a document

from the Documents tab To get the URL view the image Then enter the URL into the Logo Image

URL field

If you have a web page with more information about your app provide an info URL

To display a description on the connected apps App Launcher tile enter up to characters If you
dont supply a description just the name appears on the tile
Next provide OAuth settings by selecting Enable OAuth Settings and providing the following information
If youre setting up OAuth for applications on devices with limited input or display capabilities such
as TVs appliances or commandline applications select Enable for Device Flow

Setting Up Your NET Developer Environment

Setting Up Connected App Access RESTBased APIs

Note When enabled the value for the callback URL defaults to a placeholder unless you specify

your own URL You can specify your own callback URL as needed such as when this same

consumer is being used for a different flow A callback URL isnt used in the device authentication

flow

Enter the callback URL endpoint that Salesforce calls back to your application during OAuth Its the

OAuth redirect URI

Depending on which OAuth flow you use the URL is typically the one that a users browser is redirected

to after successful authentication Because this URL is used for some OAuth flows to pass an access

token the URL must use secure HTTPS or a custom URI scheme If you enter multiple callback URLs

at run time Salesforce matches the callback URL value specified by the app with one of the values in

Callback URL It must match one of the values to pass validation Separate multiple callback URLs with

line breaks

The callback URL field has a limit of characters cumulatively If you enter several URLs and they

exceed this limit create another connected app to manage more callback URLs

If youre using the JWT OAuth flow select Use Digital Signatures If the app uses a certificate click

Choose File and browse your system for the certificate
Under Selected OAuth Scopes add all supported OAuth scopes to These scopes refer to permissions
the user gives to the connected app while its running The OAuth token name is in parentheses
Access and manage your Chatter feed chatterapi

Allows access to Chatter REST API resources only

Access and manage your data api

Allows access to the loggedin users account using APIs such as REST API and Bulk API This value

also includes chatter api which allows access to Chatter REST API resources

Access your basic information id profile email address phone

Allows access to the Identity URL service

Access custom permissions custompermissions
Allows access to the custom permissions in an org associated with the connected app It shows
whether the current user has each permission enabled
Allow access to your unique identifier openid

Allows access to the loggedin users unique identifier for OpenID Connect apps

Full access full
Allows access to the loggedin users data and encompasses all other scopes Full doesnt return
a refresh token You must explicitly request the refreshtoken scope to get one
Perform requests on your behalf at any time refreshtoken offlineaccess
If the app is eligible to receive a refresh token allows one to be returned This scope lets the app
interact with the users data while the user is offline The refreshtoken scope is synonymous with
offlineaccess
Provide access to custom applications visualforce
Allows access to Visualforce pages
Provide access to your data via the Web web
Allows use of the accesstoken on the web It includes Visualforce which allows access to
Visualforce pages

Setting Up Your NET Developer Environment

Setting Up Connected App Access RESTBased APIs

If youre setting up OAuth for a client app that cant keep the client secret confidential and it must
use the web server flow deselect Require Secret for Web Server Flow We still generate a client
secret for your app but this setting instructs the web server flow not to require the clientsecret
parameter in the access token request If your app can use the user agent flow we recommend user
agent as a more secure option than web server flow without the secret
To authorize a single connected app to introspect all access and refresh tokens within the entire org
select Introspect all tokens By default all connected apps can introspect their own tokens In
addition an OAuth client that registers child OAuth connected apps through the dynamic client

registration endpoint can check the tokens for itself and its child apps See OpenID Connect Token

Introspection Endpoint

To control how the OAuth request handles the ID token select Configure ID token If the OAuth

request includes the Allow access to your unique identifier openid scope the returned token

can include the ID token

The ID token is always included in access token responses

With the primary ID token setting enabled configure the secondary settings that control the ID

token contents in both access and refresh token responses Specify these settings
Token Valid for

The length of time that the ID token is valid for after its issued The period can be from to

minutes The default is minutes

ID Token Audiences

The intended consumers of the ID token For example the target service where you use the

ID token such as httpsyourservicecom

Include Standard Claims
Include the standard claims that contain information about the user such as the users name

profile phone number and address The OpenID Connect specifications define a set of standard

claims to be returned in the ID token

Include Custom Attributes

If your app has specified custom attributes include them in the ID token

Include Custom Permissions

If your app has specified custom permissions include them in the ID token

To configure asset token settings if youre setting up your app to issue asset tokens for connected
devices select Enable Asset Tokens
Specify these settings
Token Valid for
The length of time that the asset token is valid after its issued
Asset Signing Certificate
The selfsigned certificate that youve already created for signing asset tokens
Asset Audiences
The intended consumers of the asset token For example the backend service for your
connected device such as httpsyourdevicebackendcom
Include Custom Attributes
If your app has specified custom attributes include them in the asset token

Setting Up Your NET Developer Environment

Verify the REST Environment RESTBased APIs

Include Custom Permissions
If your app has specified custom permissions include them in the asset token

Specify the callback URL endpoint For example

httpsyourdevicebackendcomcallback

Make sure that you select these OAuth scopes which are required for asset tokens
Access and manage your data api
Allow access to your unique identifier openid
To allow users to be automatically logged out of the connected app service provider when they log
out of Salesforce as an identity provider select Enable Single Logout

If you selected Enable Single Logout enter a single logout URL which is where Salesforce sends

logout requests when users log out of Salesforce The single logout URL must be an absolute URL

starting with https
When youre finished entering the information click Save You can now publish your app make further
edits or delete it If youre using OAuth saving your app gives you two new values that the app uses to
communicate with Salesforce

Consumer Key A value used by the consumer to identify itself to Salesforce Referred to as

clientid in OAuth

Consumer Secret A secret used by the consumer to establish ownership of the consumer key Referred

to as clientsecret in OAuth
See Create a Connected App in the Salesforce online help for more for more information on connected
apps

Verify the REST Environment RESTBased APIs

You can verify your developer environment with a simple C test application in Visual Studio

You must have Visual Studio installed to create a C test application

Start Visual Studio
Click File New Project

In the New Project window navigate to Installed Templates Visual C Windows Select

Console Application
In the New Project window under Name name the project VerifyRESTTest Under Solution
name name the solution VerifyRESTTest Under Location pick a file location that youll

remember Click Ok A solution is created and Programcs is opened for editing

Click Project Add Reference
In the Reference Manager window navigate to Assemblies Framework Select
SystemRuntimeSerialization Ensure that the checkbox is selected and click Ok
Replace the code in Programcs as described in the following section

Use the following simple login example code for your Programcs file Replace YOUR DEVORG

USERNAME with your developer organization username and replace YOUR DEVORG PASSWORD

SECURITY TOKEN with your developer organization password appended with your security token

If you did not set a security token in your organization just provide your password Replace YOUR OAUTH

Setting Up Your NET Developer Environment

Verify the REST Environment RESTBased APIs

CONSUMER KEY with the consumer key from your development organizations connected app Replace

YOUR OAUTH CONSUMER SECRET with the consumer secret from your development organizations

connected app A GitHub Gist of this code is available here

httpsgistgithubcomanonymousdbeefaab
using
using
using
using
using
using
using
using

System
SystemCollectionsGeneric
SystemLinq
SystemText
SystemThreadingTasks
SystemNet
SystemRuntimeSerialization
SystemRuntimeSerializationJson

namespace VerifyRESTTest

class Program

Class used for serializing the OAuth JSON response

DataContract
public class OAuthUsernamePasswordResponse

DataMember
public string accesstoken get set
DataMember
public string id get set
DataMember
public string instanceurl get set
DataMember
public string issuedat get set
DataMember
public string signature get set

private static string accessToken
private static string instanceUrl
private static void login

string acctName YOUR DEVORG USERNAME

string acctPw YOUR DEVORG PASSWORD AND SECURITY TOKEN

string consumerKey YOUR OAUTH CONSUMER KEY

string consumerSecret YOUR OAUTH CONSUMER SECRET

Just for testing the developer environment we use the
simple usernamepassword OAuth flow
In production environments make sure to use a stronger
OAuth flow such as UserAgent
string strContent granttypepassword
clientid consumerKey
clientsecret consumerSecret
username acctName
password acctPw

Setting Up Your NET Developer Environment

Verify the REST Environment RESTBased APIs

string urlStr
httpsloginsalesforcecomservicesoauthtoken strContent
HttpWebRequest request WebRequestCreateurlStr as
HttpWebRequest

requestMethod POST

try

using HttpWebResponse response requestGetResponse
as HttpWebResponse

if responseStatusCode HttpStatusCodeOK

throw new ExceptionStringFormat

Server error HTTP

responseStatusCode
responseStatusDescription

Parse the JSON response and extract the access

token and instance URL

DataContractJsonSerializer jsonSerializer new
DataContractJsonSerializertypeofOAuthUsernamePasswordResponse
OAuthUsernamePasswordResponse objResponse
jsonSerializerReadObjectresponseGetResponseStream as
OAuthUsernamePasswordResponse
accessToken objResponseaccesstoken
instanceUrl objResponseinstanceurl

catch Exception e

ConsoleWriteLinenException Caught
ConsoleWriteLineMessage eMessage

static void Mainstring args

login
if accessToken

display some current login settings

ConsoleWriteInstance URL instanceUrl n

ConsoleWriteAccess Token accessToken n
ConsoleWritePress any key to continuen
ConsoleReadKey

Setting Up Your NET Developer Environment

Verify the REST Environment RESTBased APIs

The following example output shows a typical successful run of this code

Instance URL httpsyourInstancesalesforcecom

Access Token

DULfARoAQKlrimMZkhQpvHvVreCvYJafmsCdMgBMUltPflQ

Press any key to continue

If the verification C project runs and displays output that matches your organization your developer

environment is set up and you can start developing NET applications that integrate with Salesforce REST

APIs

***