This is documentation for the current major version Apprenda 7.
Documentation for older versions are also available.

The Apprenda Visual Studio® Extension

Information in this guide pertains to the 0.9.1 and later version of the Apprenda Visual Studio Extension to be used with Platform versions 6.5.1 and later.

This guide explains how to use the Apprenda Visual Studio Extension to create and publish .NET applications on your Platform using Microsoft Visual Studio. This extension provides Developers with the ability to accomplish tasks on the Platform without having to leave Visual Studio. Before you begin, you should be familiar with Microsoft Visual Studio, the Platform's application lifecycle, and creating an application on the Platform.

Download the Extension

The Apprenda Visual Studio Extension is available for download from the Downloads page of our documentation. Please download the version of the extension that is compatible with your Platform version.

Prerequisites

In order to follow this tutorial, you must have the following

Getting Started

Enabling the Apprenda Extension

The Apprenda Extension should be enabled by default after install. To check that the extension is enabled:

  1. In Visual Studio click Tools -> Extensions and Updates... 
  2. From the Extensions and Updates window, find Apprenda Development Tools in the list of extensions.
  3. Click Enable to activate Apprenda Development Tools (if it is not already enabled).

Setting up Visual Studio to see the Apprenda Development Tools

  1. From the top menu, click on View -> Apprenda Explorer
  2. The Apprenda Explorer view should now be docked on the left hand side of Visual Studio (Figure 1).

Figure 1

Connecting to an Apprenda Cloud

In order to connect to your Apprenda instance you must provide the Apprenda Extension with Cloud and user information. Through Apprenda Explorer you can save multiple Apprenda Clouds' connection information and one or more user for each Apprenda Cloud. You can only connect as one user to a single Cloud at a time.

Add an Apprenda Instance

  1. In the Apprenda Explorer, click the green plus sign. This is the Add Apprenda Instance button (outlined in red in Figure 2).

           Figure 2

  1. Fill out the Add an Apprenda Cloud dialog box with the information for your Apprenda environment (shown in Figure 3).
  • In the Url field, type the URL assigned to your Apprenda environment. See more about finding your Cloud URI.
  • In the Alias field, type the alias of your choice to refer to this connection. For this tutorial we will use MyCloud.
  1. Click Test Connection. If the connection succeeds, a green check mark will appear. If the connection does not succeed, make sure the URL is correct and test the connection again.

Figure 3

  1. Once the test connection has succeeded, click the Save button.
  2. MyCloud will appear in the Cloud drop-down list in Apprenda Explorer.

Add Users

For every Apprenda Cloud added to the Apprenda Explorer, one or more users can be added and used to connect to the Platform instance. You can use the Cloud drop down to switch between different Clouds and add different users to each Cloud.

  1. Once an Cloud has been added, users can be added to the instance by clicking on the Add User button (outlined in Figure 4).

Figure 4

  1. Fill out the Add User dialog box with your User Name and Password.
  2. Click Save.

Figure 5

Connect to a Cloud

  1. From the Cloud and User drop-down lists, make sure that the instance you wish to connect to and the user you wish to connect as are selected.
  2. Click Connect in the Apprenda Explorer. If the connection is successful, the Apprenda Explorer will show the instance alias with a picture of a cloud next to it (see Figure 6).

If you are using extension version 1.0.0 or before, the Apprenda Explorer will show only the applications managed by your Development Team. When connected, all available applications will be show under the Cloud alias along with a solution open in Visual Studio that you can create as an application on the Platform.

If you are use extension version 1.2.0 or later, the Apprenda Explorer will show Applications and Add-Ons available to your Development Team. When connected, all available applications and Add-ons will be show under the Cloud alias along with a solution open in Visual Studio that you can create as an application on the Platform.

Deploying a New Application

After connecting to an Cloud, you are now ready to deploy applications.

  1. In Visual Studio, open an application solution that meets Platform requirements. This tutorial uses TimeCard.sln from the sample applications section of the Downloads page.
  2. Click the Refresh button (outlined in red in Figure 6) in the Apprenda Explorer. This allows the Apprenda Explorer to recognize that an application is available for deployment.

Figure 6

  1. Right-click on your Apprenda Cloud connection, MyCloud, and then right-click on New Application from the context menu.
  2. Fill out the New Application: Details dialog-box with information about the application:
  • Application Name is the application label that customers will see during self-provisioning or any time application information is displayed.
  • Application Alias is a system-unique, domain-friendly name assigned to your application. This will be used by the Platform to uniquely identify your application among all applications deployed on your Platform.
  • Optionally, the Description field can be used to provide information about an application.
  1. Ensure that the checkbox for Remember These Settings for this Solution is checked.
  2. The dropdown menu for Initial Stage allows you to set the stage of the Application Lifecycle the application will be in once uploaded (Definition, Sandbox, or Published). For the purposes of this tutorial, set the Initial Stage to Definition.
  3. Click Next.
  4. In the next screen, New Application: Binaries, you can set configuration options for the application archive.
  5. For the Config option, ensure that Debug is selected and make sure Rebuild before packaging is checked.

 Figure 7

If your Apprenda instance has Resource Throttling enabled, please refer to Deploying a Throttled Application for the alternate workflow. If not, continue on to step 10.

  1. Click Next. A summary of the new application will appear, showing the name, alias, and stage.
  2. Click Finish to begin deploying the application.

In the Output view of Visual Studio, you should see the progress of the creation of the your application. Once creation of your application is finished, there will be a confirmation message stating the app creation was successful.

Figure 8

The Apprenda Explorer should now show your application under MyCloud. If you click the arrow to the left, Version 1 will appear with the Definition icon next to it.

Figure 9

Promoting an Application

Once your application has been created and its settings and Resource Policies have been configured, you can promote it to the Sandbox stage.

  1. In the Apprenda Explorer, right-click on Version 1 of your application and select Promote.

Figure 10

  1. In the dialog box labeled Promote Version 1 that opens, make sure that Sandbox is selected from the Stage drop-down menu.
  2. Click OK.
  3. If Visual Studio’s Output view is open, you should see a message indicating the promotion has started. If the promotion is successful, “Promotion successful!” will appear.
  4. Once the promotion has completed, you may need to click the green refresh icon to the right of Show Archived Versions to see the change. The tree menu for your app will collapse, but if you click on the arrow you will see that Version 1 now has the yellow Sandbox icon next to it (Figure 11).

Figure 11

Launching an Application

Now that your application has been promoted to the Sandbox stage, you are able to launch the application.

  1. In the Apprenda Explorer, right-click on Version 1 and select Launch.
  2. The application will be launched in your default browser.

Publishing an Application

  1. In the Apprenda Explorer, right-click on Version 1 of your application and select Promote.
  2. The Promote Version 1 dialog box will appear with the Stage set to Published. Click OK.
  3. When the promotion is complete, a “Promotion successful!” confirmation message will appear in the Output view of Visual Studio.
  4. You may need to click the Refresh button in the Apprenda Explorer to see the change.

Create a New Version

  1. In the Apprenda Explorer, right-click your application and select New Version.
  2. Fill out the New Application Version: Details dialog-box with the application information for the new version:
  • In the Version Alias field, type v2.
  • In the Version Name field, type Version 2.
  • Make sure that Remember These Settings for this Solution is checked.
  • Set the Initial Stage to Definition.
  1. Click Next.
  2. In the New Application Version: Binaries dialog box you are able to change some configuration settings for the new version.
  3. Click Next.
  4. A summary of your application Version 2 will appear. Click Finish.

Figure 12

Once Version 2 has been created successfully, "Version 2" will appear in Apprenda Explorer with the Definition icon next to it.

Figure 13

Demoting an Application

In some cases you may need to make additional changes to applications before promoting them to Published. It may be necessary to demote an application from the Sandbox stage to the Definition stage in order to make the needed changes. Applications cannot be demoted from the the Published stage. To demote an application back to the Definition stage:

  1. In the Apprenda Explorer, right-click the application version and select Demote.
  2. Click Yes in the confirmation dialog box. The Output view of Visual Studio will show the progress of the demotion and will display “Demotion succeeded” when finished.
  3. You may need to click the Refresh icon in the Apprenda Explorer and then click the arrow next to your application to see the changes. Your application version will now have the red Definition icon next to it.

Deleting an Application

To delete an application:

  1. In the Apprenda Explorer, right-click the application and select Delete
  2. A confirmation dialog box will appear. Click Yes to confirm.
  3. The Visual Studio Output view will display “Application deleted successfully” when the application is deleted. The app name should no longer be visible in the Apprenda Explorer.

Creating and Archive

Through the Visual Studio extension, you also have the ability to generate an application archive. This step is carried out automatically when using the Apprenda Extension to deploy your application to your Platform, but can be done manually if you want the archive outside of the Platform.

  1. In the Solution Explorer view of Visual Studio, right-click the application solution.
  2. In the context menu, click on Apprenda-->Create Archive.
  3. From the Create Archive dialog box you can map your application artifacts to an Apprenda Archive.
  • In the Archive Output Path field, specify the directory to which your archive will be placed and the name of the archive. The default location for the archive is the folder where your solution resides; the default name is Archive.zip.
  1. Click Finish. The Output view of Visual Studio will display the progress of the archive being created. If successful, the message “Archive created successfully!” will be displayed.

Disconnecting from a Platform

To disconnect from your Apprenda instance, simply click the Disconnect button in the Apprenda Explorer.

Figure 14

Once disconnected, the Disconnect button will change back to Connect with a green arrow next to it. Also, the Cloud and User fields and control buttons will no longer be greyed out.

Figure 15

Deploying a Throttled Application

If your Apprenda instance has Resource Throttling enabled, you have to assign Resource Policies to your application components before you can promote it ot the Sandbox or Published stage. The Visual Studio extension integrates this into the application deployment workflow, making the process easy and straightforward by including some additional steps for assigning policies.

The below steps pick up from step 9 in the Deploying an Application section of this tutorial.

  1. From the New Application: Binaries dialog box, click Next.
  2. In the New Application: Resource Policies section, assign Resource Policies to the different components of your application. For each component type there will be a New Application: Resource Policies step so that you can apply Resource Policies to every component in the application. For example, the tutorial application, TimeCard, has a User Interface and Windows Service and will have two separate New Application: Resource Policies steps to apply Resource Policies for each component type:
  • Chose the desired policy for each component by selecting the corresponding radio button under Selection (outlined in red in Figure 16). All applicable Resource Policies will be listed for each component type.
  • Use the drop-down list (outlined in blue in Figure 16) to assign Resource Policies to different components of the same type in an application. For example, if an application has two User Interfaces, use the drop-down list to switch between components and assign Resource Policies to each.
  • Change the number in the box at the bottom of the window labeled Initial Instances to change how many instances of a specific component are deployed. The default value is 1.

Figure 16

  1. Click Next to assign policies to each component type in the application.
  2. Once you are finished assigning policies for application components, in the New Application: Data Resource Policies assign policies for your application's data tier:
  • Chose the policy that should be used for CPU and Memory Limits.
  • Chose the policy that should be used as a Storage Quota.
  1. Once you are finished assigning policies, the New Application: Summary dialog box will give a brief description of your application and its components (Figure 17).

Figure 17

  1. Click Finish.
  2. Once the app has been created successfully, the Output view of Visual Studio will display the message success message and your application will appear under MyCloud in the Apprenda Explorer.

Launching the Developer and Account Portals

In addition to performing Platform functionality from Visual Studios, you are also able to launch the Developer and Account Portals from Visual Studio.

  1. In the Apprenda Explorer, right-click your Apprenda Cloud Connection (MyCloud) and select Launch Developer Portal.

Figure 18

The Developer Portal login screen will be loaded in your default browser. Your can launch the Account Portal in the same way by selecting Launch Account Portal from the menu.

Viewing Add-On Connection Information

As of extension version 1.2.0, you can view Platform Add-Ons available to your Development Team in the Apprenda Explorer window. Listed under Add-Ons, you can view your available Add-Ons as well as any deployed instances of an Add-On on the Platform. If the Add-Ons section is blank, then your Development team does not have access to any Add-Ons. Additionally, an Add-On may be listed, but have no deployed instances. Contact your Platform Operator about getting access to a needed Add-On or provision a new Add-On instance in the Developer Portal if your Development Team already has access to it.

For any instance listed, you can get the connection data to the deployed instance and the Add-On instance token. Connection data is the current connection information to the provisioned instance of an Add-On. You can use this information for testing your application that consumes the Add-On. The Instance Token is the Platform token you should use in your app.config or other token switch enabled configuration file, when creating the application on the Platform. Since an Add-On instance may change locations on the Platform, this token allows the Platform to insert the correct connection information for an Add-on instance when the application is promoted and deployed on the Platform. See more about how to use an Add-On instance token.

Copy Connection Information

  1. Right click on the Add-On instance you want the connection information for
  2. Select Copy Connection Data to Clipboard or Copy Instance Token to Clipboard.

Figure 19

Known Issues

Here is a list of known issues:

  • Visual Studio's embedded browser is not supported and the Apprenda Extension will use your default browser when launching applications.
  • TLS 1.0, 1.1, and 1.2 must be enabled on the Platform and the client computer when connecting to a Platform over https.
  • The Apprenda Manifest Editor will only open the Deployment Manifest of the first solution opened in Visual Studio.
  • Intermittently, new application creation will fail when the 'Initial Stage' is set to Sandbox or Published and Resource Policies are assigned. If this happens, deploy the application to the Definition stage and then promote to the desired stage after the app is created.

Visual Studio® is a registered trademark or trademark of the Microsoft group of companies.