Description

The Microsoft Azure DevOps source configuration plugin automates importing version artifacts from a Azure DevOps server.

Quick Info

Product
HCL Launch
Type
plugin
Compatibility
HCL Launch 6.0.1 or later
Created by
HCL Software
Version Name Action

1.1112501

launch-sourceconfig-azure-1.1112501.zip

launch-sourceconfig-azure-1.1112501.zip

1.1112501


Summary

The Microsoft Azure Devops source configuration plugin automates importing version artifacts from a Azure Devops.

Compatibility

The HCL Launch Deploy source configuration plugin for Microsoft Azure Devops Server works with Team Foundation Server, Team Explorer Everywhere, and Visual Studio Online. This plugin supports Team Foundation Server 2010, 2012, 2013, 2015 and 2017.

This plugin requires HCL Launch version 6.0.1 or later.

This plugin supports agents that are running on Microsoft Windows.

This plugin requires Microsoft .NET Framework 3.5 to be installed on the agent computer where the plugin is installed.

Installation

See Installing plugins in HCL Launch for installing and removing plugins.

History

The following table describes the changes made in each plugin version.

Plugin history details
Version Description
1 Initial release

Usage

The Microsoft Azure Devops source configuration plugin can be used to import artifacts from a Azure DevOps projects repository. This plugin retrieves artifacts from Azure DevOps version control, code that is not compiled or built, and .zip file types from a TFS build process. The agent must have access to the tf tool.

To use this plugin, create a component to define the Azure DevOps artifacts to be used. The component contains the information for importing the artifacts and any processes to perform on the artifacts.

Before you begin

tf Tool

The agent must have access to the tf.exe or tf.cmd file. This file is needed for retrieving all artifacts from TFS. It must either be located on the PATH environment variable or supplied through a direct path in the plugin configuration. The tf executable is located in the install directory of Visual Studio or Team Explorer Everywhere. Note that the tf tool is not located in the TFS install directory. For more information, see Use Team Foundation version control commands.

Visual Studio Online Connection

Visual Studio Online (VSO) an SaaS offering of Azure DevOps requires enabling the alternate authentication credential option. To learn how to enable alternate authentication credentials, login to VSO and navigate to the Settings page. Under the sidebar to the left, there is an Alternate authentication credentials. Enable and create new alternate authentication credentials. These credentials must then be supplied in the plugins configuration. Because these credentials are used by many deployments create a functional VSO account that is used for these types of automated process. The following screen capture shows where to create alternate authentication credentials.

Create a component

To create a component, complete the following steps. For more information, see Creating components
topic in the product documentation.

  1. In the HCL user interface, click Components and then click Create Component.
  2. In the Create Component window, specify a name and description for the component.
  3. In the Teams fields, specify the access information for the new component.
  4. To use a template for the new component, select a template from the Template list. In this case, the component inherits source configuration, properties, and processes from the template.
  5. In the Source Config Type list, select Azure.

  6. Specify the properties for the component. See the Setting tab for descriptions.
  7. Click Save.

Import a version

When the artifacts are imported, a component version is created using the version of the package. You can specify to import a specific package version or import all versions. If importing all versions, a component version is created for each version.

  1. Click the Versions tab for the component.
  2. Click Import New Versions.
  3. Specify a specific version of the package to import, or leave blank to import the latest version of the package available in the repository. Additionally, enable Import All Versions to import all versions of a package.
  4. Click Save.

Step palette

To access this plugin in the palette, click Source and Repositories > Azure.

Configuration

The TFS_SCM plugin contains four required properties that support the default use case of an unsecured or local TFS server with the tf tool available on the PATH environment variable. By default, the most recent Changeset is imported.

Required properties

  • Collection URL: The URL of the Azure Devops team project collection. For example: https://dev.azure.com/xxx. The desired project artifacts are placed underneath this collection. The collection URL is a subset of the projects URL.
  • Server Project Folder: The variable assigned to the project folder on your VSO or the TFS server. By default, this value begins with $/ and is followed by the name of the project.

  • Workspace: The name of the local TFS or VSO workspace. This value can be identified in Visual Studios Team Explorer side bar. All possible Workspaces can be found under the Solution section.
  • Local Workspace Folder: The full path to the local Workspace folder. This folder contains local code resolved by Visual Studio. The easiest way to identify the workspace is by clicking the Open link in the Team Explorer side bar. This brings you directly to the workspace folder.
    Default Location: C:\Users\\Source\Workspaces\Workspace

    Azure Devops Server Workspace and Local Workspace Folder

    Note: You may also notice the Collection URL can be identified from Visual Studio as well.

Optional properties

  • Username: The Username to authenticate with Azure Devops.
  • Password: The Password to authenticate with Azure Devops.
    The Username and Password properties are not required if the agent is installed on the TFS server. Follow the alternate authentication credentials if use VSO.
  • tf.exe or tf.cmd Path: The canonical path to the tf.exe or tf.cmd file. This file is located in the Visual Studio installation directory and the path is not standardized between Visual Studio versions. Example for Visual Studio 2017: C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer\tf.exe
  • If a value is not specified for this property, the environment PATH variable is used to locate the tf command. If the PATH variable is not set, the following error occurs: Error Creating New Version: Cannot run program "tf": CreateProcess error=2, The system cannot find the file specified.

Manual import properties

By default, the TFS_SCM plugin imports the latest changeset. If the import is initiated manually, you can import specific changesets. If a value is specified for the Label property, the Changeset property is ignored.

  1. Label: The label assigned to a past changeset.
  2. Changeset: The number assigned to a past changeset.

Steps

The following process steps are available in the in the Azure plugin.

Import Version

Import a new version from Azure DevOps .

This step has no input properties.

Roles

The plugin adds these roles automatically to resources. You cannot add these roles manually.

AzureComponentProperties

Properties for the AzureComponentProperties role
Name Type Description Required Property
Collection URL String The URL of the AzureDevops collection, for example: https://dev.azure.com/. Y ${p:component/AzureComponentProperties/url}
Extensions of files to convert String The list of file extensions to be converted, if text-type files must be converted into another character set. Matching file types are converted into the default or system character set of the system where the agent is located. Separate each list item with a comma. N ${p:component/AzureComponentProperties/extensions}
Local Workspace Folder String The path to the local workspace folder of the computer with the agent. If the folder does not exist, it is created to the specified path. This value is only used if the Workspace property is specified. Otherwise, a temporary folder is created in the agent working directory. Y ${p:component/AzureComponentProperties/localFolder}
Password Password The password for the account that has access to the Azure DevOps Server. N
Path to tf.exe or tf.cmd String The full path to the Visual Studio or Team Explorer Everywhere tf.exe or tf.cmd file. If a value is not specified, the tf executable file must be available on the agent’s PATH environment variable. N ${p:component/AzureComponentProperties/tfExePath}
Preserve execute permissions Boolean For Linux and UNIX operating systems, retain the execute permissions for each file. N ${p:component/AzureComponentProperties/saveFileExecuteBits}
Server Project Folder String The path variable to the project folder on Visual Studio Online or the Team Foundation
Server server. The default is $/ followed by the name of the project.
N ${p:component/AzureComponentProperties/serverFolder}
User String The user name for the account that has access to the Azure DevOps Server. N ${p:component/AzureComponentProperties/username}
Workspace String The name of the Team Foundation Server or Azure DevOps Online workspace. To get a list of workspace names from the server, run the following command: TF workspaces /collection:Repository_URL /login:user,password. For Azure DevOps Online, alternate authentication credentials must be enabled. Y ${p:component/AzureComponentProperties/workspace}

AzureImportProperties

Properties for the AzureImportProperties role
Name Type Description Required
Changeset String The version integer of the Azure DevOps Server changeset to load. No
Label String The name of the version label to load. No

Troubleshooting

Unable to delete temporary workspace

The server does not have the privileges that are required to delete the local temp file. This error message does not affect the standard operation of the plug-in.

Error Creating New Version: TFS Map Workspace Error: An argument error occurred: The workspace name <workspace_name> matches more than one cached workspace. Try adding the workspace owner to the workspace spec to match a specific workspace.

tf workspaces /remove:* to clear the cache. If you created more than one workspace with the same name, delete the redundant workspace and then clear the cache.

Error Creating New Version: Error retrieving latest build.

Install Microsoft .NET Framework 3.5 on the agent computer where the plug-in is installed.