Current scope of the extension
Prerequisites to building a DocuSign integration
Developing with DocuSign video on how to use this extension
Installing this extension
To install the DocuSign Visual Studio Extension, simply download the file and double-click it; it will be installed automatically. For more information, see Managing extensions in Visual Studio in the Visual Studio documentation.
Creating a new DocuSign project
From the Visual Studio menu, choose FILE > New > Project.
In the Visual Studio Create a new project dialog box, enter DocuSign in the search box.
Select one of the four DocuSign available project templates and click Next.
In the Configure your new project dialog box, enter a name for your project and click Create.
In the Configure DocuSign eSignature for a project dialog box, select the authentication type you wish to use for the DocuSign eSignature API, either Authorization Code Grant or JSON Web Token (JWT). Note that if you use Authorization Code Grant, your app will need to include a link where end users enter their credentials to authenticate to DocuSign. If you choose JWT, you can impersonate a single user to make all API calls, but you'll need the user ID that you wish to impersonate.
In the same dialog box, you also choose the list of one or more APIs you wish to use. This selection will be used for two things: First, it will be used to set the authentication scopes your app will need. Second, it will determine the list of code examples you get to choose from.
If you choose Authorization Code Grant, you'll need the integration key (also known as a client ID), redirect URI, and secret key (also known as a client secret) to configure the authentication to DocuSign. See Building an eSignature Integration in the DocuSign Developer Center to learn more about how to set up a new DocuSign integration and to configure these settings. Click Finish to create the project.
If you choose JWT, use the next dialog box to add the three configuration elements—integration key, DocuSign user ID, and RSA private key (part of the RSA key pair)—required to use JWT authentication. See JSON Web Token (JWT) Grant in the Developer Center to find out how to set up JWT authentication. Click Finish to create the project.
The DocuSign Visual Studio Extension creates your project, adds the necessary NuGet packages, and modifies your configuration file (appsettings.json) to include all the necessary configuration data to make DocuSign API calls.
Note: it is not recommended to deploy an application to your production environment with any secret, sensitive, or personal information in the configuration files. Instead, we recommend you use a secure vault, environment variables, or some other secure mechanism to ensure the privacy of your data.
In the DocuSign code examples dialog box, you can choose one or more code examples that you wish to use in your application and click Add. (You may need to expand the different API sections to see the entire list of code examples.)
At this point your project includes all the necessary files to integrate DocuSign functionality in your application. You will still need to modify your code to call the DocuSign code as follows:
Authorization Code Grant, ASP.NET Core Web Application:
- In startup.cs, in the ConfigureServices() method, you will need to add a call to:
DocuSign.eSignature.DocuSignWebAppExtensions.ConfigureDS(services, this.Configuration);
- In startup.cs, in the Configure() method, you will need to add a call to:
DocuSign.eSignature.DocuSignWebAppExtensions.ConfigureDS(app);
- In the controller class where you wish to invoke DocuSign functionality, add this private method:
protected bool CheckToken(int bufferMin = 60)
{
return HttpContext.User.Identity.IsAuthenticated
&& (DateTime.Now.Subtract(TimeSpan.FromMinutes(bufferMin)) <
RequestItemsService.User.ExpireIn.Value);
}
- In the controller, add this code inside the method where you want to invoke DocuSign functionality:
string accessToken = RequestItemsService.User.AccessToken;
string basePath = RequestItemsService.Session.BasePath + "/restapi";
string accountId = RequestItemsService.Session.AccountId;
- Once you have the accessToken, accountId, and basePath values, you can make calls to any of the code examples that you have added.
Authorization Code Grant, ASP.NET Web Application (.NET Framework):
- Update your web.config file to include the following line:
<add key ="AppUrl" value ="{YourAppURL}"/>
making sure to replace {YourAppURL} with the URL where your app is running.
- In FilterConfig.cs, add the following lines:
at the top:
using <YourNamespace>.DocuSign.eSignature;
making sure to replace <YourNamespace> with the namespace of your project.
in the RegisterGlobalFilters() method:
filters.Add(new LocalsFilter(DSConfiguration.Instance, RequestItemsService.Instance));
- In DSOwinStartup.cs, add the following line above the namespace declaration:
[assembly: Microsoft.Owin.OwinStartupAttribute(typeof(<YourNamespace>.DocuSign.eSignature.DSOwinStartup))]
making sure to replace <YourNamespace> with the namespace of your project.
- In the controller class where you wish to invoke DocuSign functionality, add this code:
if (RequestItemsService.Instance.User == null)
return new DSChallengeResult();
string accessToken = RequestItemsService.Instance.User.AccessToken;
string basePath = RequestItemsService.Instance.Session.BasePath + "/restapi";
string accountId = RequestItemsService.Instance.Session.AccountId;
- Once you have the accessToken, accountId, and basePath values, you can make calls to any of the code examples that you have added.
If you chose JWT Grant authentication, you need to add the following code to the location in your project where you wish to invoke DocuSign functionality:
var auth = DocuSign.eSignature.JWTAuth.AuthenticateWithJWT();
The auth object is a tuple that contains the accessToken, the accountId, and the basePath (in that order) that are required to make calls to any of the code examples that you have added.
Configuring an existing project to use DocuSign
The DocuSign Visual Studio Extension can also be used to modify your existing projects to include DocuSign functionality. To do that, you will have to right-click your project in Visual Studio to open the context menu and find the DocuSign popup menu.
Click Configure Project from the DocuSign menu and proceed to follow the steps from the Creating a new DocuSign project instructions above, beginning with step 5.
Adding additional code examples to your project
Once a project is configured to use DocuSign functionality, you can always add new code examples to it. To do so, right-click the desired folder in your project (where you wish to add the new code example) to open the context menu and find the DocuSign popup menu.
Click Add code Examples from the DocuSign menu and then proceed to select one or more code examples to add to your project. Note that by default, code examples will be added to the DocuSign\eSignature folder if you don't specify a folder where you wish to add them.
For additional information about DocuSign APIs and developer tools, please check out the DocuSign Developer Center.
| |
