salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

我们在做项目时经常会使用changeset作为部署工具，但是某些场景使用changeset会比较难操作，比如当我们在sandbox将apex class更改名字想要部署到生产的org或者其他环境的org，使用changeset是没法实现的，这个时候我们需要使用Ant Migration Tool还是更好的。

salesforce基于metadata进行管理，Ant Migration Tool 是一个基于 Java/Ant的命令行工具用于将metadata从本地迁移至Sales Org. Migration Tool通常用于以下场景：

开发的项目有很多的改动点，这些改动点使用Web界面可能需要花费很长时间；
多个阶段Release的发布：开发过程需要重复的构建，测试等才能发布到生产，脚本化的组件检索和部署会更高效；
重复部署相同的参数：可以检索出所有的metadata，进行更改，以及部署组件的子集；
IT进行迁移到生产的操作：Force.com Migration Tool对于喜欢脚本化操作的人来说是一个很熟悉的过程；
定时调度部署。

Migration Tool基于Metadata API, Metadata API 包含了一组对象，这些对象用于管理你的org的系统预置的以及自定义的metadata，我们可以使用SOAP calls来操作这些对象。下面介绍 Migration Tool 如何使用。

Migration Tool 使用前的准备工作

在我们使用Migration Tool时，我们需要保证电脑中已经安装了java的运行环境以及ant。由于salesforce对TLS1.0已经弃用，所以建议java JDK使用1.8（曾经java项目使用1.7，尽管按照要求各种配置了 tls信息仍然会有各种位置错误，使用1.8以后便一点问题没有了，所以推荐使用1.8）。

1. JDK 1.8 下载地址：https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html 按照要求下载以后正常安装即可，安装完如果想确认电脑中是否已经就绪JDK 1.8环境，可以打开命令行，输入 java -version 回车即可(需要配置java的jdk的环境变量，网上找一大堆，如果不配置，ant运行会有问题，因为找不到jdk位置)；

salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

2. 下载和配置 Ant: Ant下载地址： http://ant.apache.org/bindownload.cgi ，官方建议下载1.6 及以上版本，目前版本最高为1.10.5，我这里下载的是这个版本，解压后我放在了C:\ant\apache-ant-1.10.5文件夹下面了。当我们解压以后运行 ant -version后，会发现ant指令是未识别的命令

salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

原因是bin目录以及lib目录用于运行ant指令，我们没有将bin目录放在path中。我们右键计算机，选择属性，选择高级，下面系统变量栏new一个，name为ANT_HOME，value为你解压的ant的根目录；

salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

找到你的path的信息，新增%ANT_HOME%\bin即可，如果你的环境是win7，在最后需要加;然后输入下面信息

salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

重新运行 ant -version，如果提示你安装的ant 安装的版本，说明安装成功。

salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

3. 下载 Migration Tool，可以在你的org的setup 搜索出搜索 Tools,然后选择 Lightning Platform Tools and Toolkits.在跳转的页面选择下载Ant Migration Tools即可

salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

二. Ant Migration Tool的使用

可以通过以下的步骤去实现 Ant Migration Tool的使用。

1. 配置 Salesforce Connection 信息

我们目的是为了检索和部署metadata组件，所以我们需要源及目标的登陆salesforce的账号以及密码等信息，这些信息配置在build.properties，这个文件存在于解压的 Ant Migration Tool 文件中。

配置信息主要有以下内容：

sf.username ：用于配置的salesforce的账号名称；
sf.password ：用于配置的salesforce的账号密码，如果存在security token，将token放在密码后面填写；
sf.sessionId ：用于配置的salesforce的sessionId，如果配置sessionId，则不用配置username以及password，两者写一个就好，不能同时存在；
sf.serverurl ：根据生产或者测试环境，分别对应于：https://login.salesforce.com / https://test.salesforce.com。

2.构建项目检索/部署清单

在package.xml中，我们主要需要配置以下的节点的信息：

fullName：server端想要部署的package的名字，如果不指定则默认unpackage这个package；
types：这个元素包含了一个name的标签以及多个members标签，用于逻辑哪些类型的哪些metadata组件需要被检索或者部署；
members：组件元素的API名称；
name：salesforce 规定的metadata type，可用的metadata type的取值需要参看：https://developer.salesforce.com/docs/atlas.en-us.200.0.api_meta.meta/api_meta/meta_types_list.htm
version：文件用于检索和部署的metadata API的版本号。

上面的具体怎么使用，后面会给一个例子进行简单说明。

3. 使用Migration Tool 的指令从salesforce org检索/ 部署 / 移除 metadata组件

Ant的jar包里面封装了好多的soap的标准方法，常见的有 retrieve / deploy等等。通过ant指令在cmd中进行操作即可实现通过ant 部署salesforce的metadata组件。

三. Ant Migration Tool实际操作

下面通过一个例子来进行演示，例子浅入浅出，描述的是将我一个org里面的custom label全部迁移至另外一个org里面，然后再将指定的custom label从我的新的org删除(检索、部署以及删除操作的简单描述)。想要了解更多使用的小伙伴欢迎查看Ant Migration Tool的官方文档：https://resources.docs.salesforce.com/218/latest/en-us/sfdc/pdf/salesforce_migration_guide.pdf

salesforce零基础学习（九十二）使用Ant Migration Tool 实现Metadata迁移

上图中的内容为例子中的层级结构： My First Test中包含了两个文件夹：remove(用于指定移除的 destructureChanges.xml的metadata结构)、retrieve(用于指定需要检索部署的metadata结构)。

build.properties配置了登陆salesforce org A的账号信息，build.xml中用来配置你的操作指令。这里主要有三个部分：

retrieveOperation：配置的检索的指令，当使用ant执行这个指令以后，会生成一个retrieveFolder的文件夹，并且读取retrieve/package.xml里面的metadata文件信息生成到retrieveFolder中
deployOperation：配置的执行的指令，当使用ant执行这个指令以后，会将retrieveFolder中的文件内容部署到你指定的salesforce org中；
removeOperation：配置的删除的指令，当使用ant执行这个指令以后，会将 destructiveChanges.xml中的metadata移除。

 <project name="Sample usage of Salesforce Ant tasks" default="test" basedir="." xmlns:sf="antlib:com.salesforce">

     <property file="build.properties"/>

     <property environment="env"/>

     <!-- Setting default value for username, password and session id properties to empty string

          so unset values are treated as empty. Without this, ant expressions such as ${sf.username}

          will be treated literally.

     -->

     <condition property="sf.username" value=""> <not> <isset property="sf.username"/> </not> </condition>

     <condition property="sf.password" value=""> <not> <isset property="sf.password"/> </not> </condition>

     <condition property="sf.sessionId" value=""> <not> <isset property="sf.sessionId"/> </not> </condition>

     <taskdef resource="com/salesforce/antlib.xml" uri="antlib:com.salesforce">

         <classpath>

             <pathelement location="../ant-salesforce.jar" />

         </classpath>

     </taskdef>

     <target name="retrieveOperation">

       <mkdir dir="retrieveFolder"/>

       <sf:retrieve username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" retrieveTarget="retrieveFolder" pollWaitMillis="10000" unpackaged="retrieve/package.xml"/>

     </target>

     <target name="deployOperation">

       <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="retrieveFolder" rollbackOnError="true"/>

     </target>

   <target name="removeOperation">

       <sf:deploy username="${sf.username}" password="${sf.password}" sessionId="${sf.sessionId}" serverurl="${sf.serverurl}" maxPoll="${sf.maxPoll}" deployRoot="remove"/>

     </target>

 </project>