Description
The Microsoft Azure DevOps source configuration plugin automates importing version artifacts from a Azure DevOps server.
- Overview
- Documentation
- Version history
Quick Info
Product
DevOps Deploy (HCL Launch)
Type
plugin
Compatibility
HCL Launch 6.0.1 or later
Created by
HCL Software
Website
Published Date
Last Updated
Summary
Usage
Steps
Roles
Troubleshooting
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.
| 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.
- In the HCL user interface, click Components and then click Create Component.
- In the Create Component window, specify a name and description for the component.
- In the Teams fields, specify the access information for the new component.
- 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.
- In the Source Config Type list, select Azure.
- Specify the properties for the component. See the Setting tab for descriptions.
- 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.
- Click the Versions tab for the component.
- Click Import New Versions.
- 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.
- 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\WorkspaceAzure 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
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.
- 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.exeortf.cmdfile. 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
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.
- Label: The label assigned to a past changeset.
- Changeset: The number assigned to a past changeset.
Roles
The plugin adds these roles automatically to resources. You cannot add these roles manually.
AzureComponentProperties
| 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
| 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.
