Deploy an agent on Windows

Https://www.visualstudio.com/zh-cn/docs/build/actions/agents/v2-windows

Last update:6/27/2017In this article

• Learn about Agents
• Check Prerequisites
• Prepare Permissions
  • Decide which user you ' ll use
  • Confirm the user has permission
• Download and configure the agent
  • Server URL
  • Authentication type
• Choose Interactive or service mode
• Replace an agent
• Remove and re-configure an agent
• Help on the other options
• Capabilities
• Q&a
  • I ' m running a firewall and my code is in Team Services. What is the does the agent need to communicate with?
  • How does I configure the agent to work through a Web proxy and connect to Team Services?
  • How does I configure the agent to bypass a Web proxy and connect to Team Services?
  • I ' m using TFS and the URLs in the sections above don ' t work for me. Where can I get help?
  • I use the Team Foundation Server on-premises and I don ' t see some of these features. Why isn't?

Team Services | TFS 2017 | TFS 2015 | Previous versions (XAML builds)

To build and deploy Windows, Azure, and other Visual Studio solutions you'll need at least one Windows agent. Windows agents can also build Java and Android apps.

Before you begin:

• If your code is in Visual Studio Team Services and the hosted agent meets your needs, you can skip setting up a private Wi Ndows Agent.
• If your code is in a on-premises Team Foundation server (TFS) server, see Deploy a agent on Windows for on-premises TFS 2015.
• Otherwise, you ' ve come to the right place to set up a agent on Windows. Continue to the next section.

Learn about Agents

If you are already know what's an agent are and how it works, feel free to jump right in to the following sections. But if you're like some more background on what they does and how they work, see Build and release agents.

Check Prerequisites

Make sure your machine are prepared with our Windows system prerequisites.

If you ' re building from a subversion repo, you must install the Subversion client on the machine.

Prepare permissionsdecide which user you ' ll use

Decide which user account you ' re going-to-use to register the agent.

Authenticate with a personal access token (PAT) to Team Services or TFS 2017

1. Sign in with the either your Visual Studio team Services account ( https://{your-account}.visualstudio.com ) or your team Foun Dation Server Web portal ( https://{your-server}:8080/tfs/ ).

2. From your home page, open your profile. Go to your security details.

3. Create a personal access token.

4. For the scope select Agent pools (read, manage) and Make sure all the other boxes is cleared. If its a deployment group agent, for the scope Select Deployment Group (read, manage) and make sure all the other Boxes is cleared.

5. Copy the token. You'll use this token when you configure the agent.

Authenticate as TFS user

• TFS: You can use the either a domain user or a local Windows user on each of the Your TFS application tiers.

• TFS (applies only to OSX and Linux): We recommend that you create a local Windows user on each of the Your TFS application tiers and dedicate that user for the PUR Pose of deploying build agents.

Confirm the user has permission

Make sure the user account so you ' re going to use have permission to register the agent.

is, the user plan to use was a Team Services account owner or a TFS server administrator? If So and then skip these steps. Otherwise you might see a message like this: Sorry, we couldn ' t add the identity. Please try a different identity.

2. Open a browser and navigate to the Agent Pools tab for your Team Services account or TFS server:
   • Team Services:https://{your_account}.visualstudio.com/_admin/_AgentPool
   • TFS 2017:https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
   • TFS 2015:http://{your_server}:8080/tfs/_admin/_AgentPool

   The TFS URL doesn ' t work for me. How can I get the correct URL?

4. Click the pool on the left side of the page and then click Roles.
6. If the user account of you ' re going to use are not shown, then get a administrator to add it. The administrator can be a agent pool administrator, a Team Services account owner, or a TFS server administrator. If its a deployment group agent, the administrator can is a deployment group administrator, a Team Services account owner , or a TFS server administrator. You can add a user to the deployment group adminstrator role in the Security tab on the deployment groups page of the Build & Release hub.

Q: I ' m concerned about security. How are this account used? A: Agent communication.

Download and configure the agent

1. Log on to the machine using the account for which you ' ve prepared permissions as explained above.
2. In your web-browser, sign-to-Team Services or TFS, and navigate to the Agent Pools tab:
   • Team Services:https://{your_account}.visualstudio.com/_admin/_AgentPool
   • TFS 2017:https://{your_server}/tfs/DefaultCollection/_admin/_AgentPool
   • TFS 2015:http://{your_server}:8080/tfs/_admin/_AgentPool

   The TFS URL doesn ' t work for me. How can I get the correct URL?

3. Click Download Agent.
4. On the Get Agent dialog box, click Windows.
5. Click the Download button.
6. Follow the instructions on the page.

Server URL

• Team Services:https://{your-account}.visualstudio.com

• TFS 2017:https://{your_server}/tfs

• TFS 2015:http://{your-server}:8080/tfs

Authentication Typeteam Services

Choose Pat, and then paste the PAT token of your created into the command Prompt window.

Tfsimportant

Make sure your server are configured to support the authentication method for you want to use.

When you configure your agent to connect to TFS, you ' ve got the following options:

• Alternate Connect to TFS using Basic authentication. After you select Alternate, you are prompted for your credentials.

• Negotiate Connect to TFS as a user other than the signed-in user via a Windows authentication scheme such as NTLM or Kerberos. After you select Negotiate, you are prompted for credentials.

• Integrated (Default) Connect a Windows agent to TFS using the credentials of the signed-in user via a Windows authentication scheme such as NTL M or Kerberos. You won ' t is prompted for credentials after you choose this method.

• PAT Supported only on Team Services and TFS or newer. After you choose Pat, paste the pat of the created into the Command Prompt window.

NOTE

When using PAT as the authentication method, the PAT token was used only for the initial configuration of the agent. Learn more at communication with Team Services or TFS.

Choose Interactive or service mode

For guidance on whether to run the agent in interactive mode or as a service, see Agents:interactive vs. service.

IF you configured the agent to run interactively, to run it:

.\run.cmd

IF you configured the agent to run as a service, it starts automatically. You can view and control the agent running status from the services snap-in. Run, and look for services.msc "VSTS agent (name of your agent) ".

If you need-to-change the logon account, don ' t does it from the services snap-in. Instead, see the information below to re-configure the agent.

Replace an agent

When you configure a agent using the same name as an agent so already exists, you ' re asked if you want to replace the E Xisting agent. If you answer Y and then make sure you remove the agent (see below) so you ' re replacing. Otherwise after a few minutes of conflicts, one of the agents would shut down.

Remove and re-configure an agent

To remove the agent:

.\config remove

After your ' ve removed the agent, you can configure it again.

Help on the other options

To learn on other options:

.\config --help

The help provides information on authentication alternatives and unattended configuration.

Capabilities

Your agent ' s capabilities is cataloged and advertised in the pool so that's only the builds and releases it can handle is Assigned to it. See Build and release agent capabilities.

In many cases after you deploy an agent, you'll need to install software or utilities. Generally you should the install on your agents whatever software and tools to use on your dev machine.

For example, if your build includes the NPM task and then the build won ' t run unless there ' s a build agent in the pool that H As NPM installed.

IMPORTANT

After your install new software on a agent, you must restart the agent for the new capability to show up in the pool so tha T the build can run.

Q&ai ' m running a firewall and my code is in Team Services. What is the does the agent need to communicate with?

If you ' re running an agent in a secure network behind a firewall, make sure the agent can initiate communication with the Following URLs:

https://login.microsoftonline.comhttps://app.vssps.visualstudio.com https://{accountname}.visualstudio.comhttps://{accountname}.vsrm.visualstudio.com

How does I configure the agent to work through a Web proxy and connect to Team Services?

In the agent root directory, create a. proxy file with your proxy server URL.

echo http://name-of-your-proxy-server:8888 | Out-File .proxy

If your proxy doesn ' t require authentication, then your ' re ready to configure and run the agent as explained above.

NOTE

For backwards compatibility, if the proxy was not specified as described above, the agent also checks for a proxy URL from The VSTS_HTTP_PROXY environment variable.

If your proxy requires authentication, the simplest to handle it's to grant permissions to the user under which the A Gent runs. Otherwise, you can provide credentials through environment variables. When you provide credentials through environment variables, the agent keeps the credentials secret by masking them in job and diagnostic logs. To grant credentials through environment variables, set the following variables:

$env:VSTS_HTTP_PROXY_USERNAME = "proxyuser"$env:VSTS_HTTP_PROXY_PASSWORD = "proxypassword"

NOTE

This procedure enables the agent infrastructure to operate behind a Web proxy. Your build definition and scripts must still handle proxy configuration for each task and tool you run in Your build. For example, if is using a task that is makes a REST API call, you must configure the proxy for that task.

How does I configure the agent to bypass a Web proxy and connect to Team Services?

If you want the agent to bypass your proxies and connect to Team Services directly, then you should configure your Web proxy To enable the agent to access the following URLs:

• https://management.core.windows.net

• *.visualstudio.com

• https://login.microsoftonline.com

• https://app.vsspsext.visualstudio.com

NOTE

This procedure enables the agent to bypass a Web proxy. Your build definition and scripts must still handle bypassing Your Web proxy for each task and tool you run in Your build.

For example, if your is using a NuGet task, you must configure your Web proxy to support bypassing the URL for the server That hosts the NuGet feeds you ' re using.

I ' m using TFS and the URLs in the sections above don ' t work for me. Where can I get help?

WEB Site Settings and security

I use the Team Foundation Server on-premises and I don ' t see some of these features. Why isn't?

Some of these features is available only on Visual Studio Team Services and not yet available on-premises. Some Features is available on-premises if you had upgraded to the latest version of TFS.

Deploy an agent on Windows