Настройка проекта и первые шаги с Ant

alexander.bogomaz · 24.10.2018 14:05:47

В этой статье я покажу какие файлы нужно создать для работы с ant migration tool. Мы пройдём через CRUD операции на примере Apex класса. Работать будем с обычной Dev org.

1. Настройка build.properties файла
2. Настройка build.xml файла
3. Настройка package.xml файла
4. Написание Apex класса в организации
5. Получение метадаты Apex класса
6. Добавление и обновление Apex класса
7. Удаление Apex класса

Настройка build.properties файла

1.Создайте файл build.properties. Если вы откроете файл build.properties, который прилагался к sf ant архиву, то увидите что там уже написаны все возможные варианты для аутентификации.

Давайте пройдём детально по каждой из частей.
(1) - это вариант аутентификации для которого необходимы username и password с security token написанным сразу после пароля без отступа. В этой статье вы сможете найти как получить Security Token.
(2) - это вариант аутентификации для которого необходимы sessionId от актуальной сессии или OAuth token
(3) - url по которому будет происходить аутентификация.

Я решил аутентифицироваться через первый вариант. username и password с security token.
В итоге мой файл имеет такой вид.

Настройка build.xml файла

Создаём файл build.xml файл. Если вы откроете файл build.xml, который прилагался к sf ant архиву, в файле будут описаны все возможные виды команд таких как deploy, retrieve. Мы с вам создадим стандартный набор команд.Я разобью разбор этого файла на две части. Шапка файла будет иметь такой вид.

Давайте детальнее рассмотрим каждую часть кода:

(1) - указываем имя вашего проекта и указываем пространство имён.
(2) - подключаем библиотеку, sf jar файл который мы добавили в папку с ant
(3) - подключаем наш build.properties файл в котором хранятся credentials для организации
(4) - создаём переменные которые будут использоваться для выполнения команд, так как аутентификация происходит в момент отправка запроса на организацию.

Из пункта (4) можно понять что если вы укажите несколько организаций в build.properties файле, то это даст вам возможность переключаться между организациями. Например получать данные из dev org, но деплой делать на production.

Далее, буду следовать описание команд, но к ним мы вернёмся позже.

Настройка package.xml файла

Создаём package.xml файл. В этом файле мы будем описывать компоненты которые мы ходим получить. Пока что ваш файл будет выглядеть таким образом, так как мы ещё не указали какие компоненты мы будем получать.

Написание Apex класса в организации

В удобном для вас окружении создайте Apex класс.Класс мы создаём естественно на той организации с которой мы потом будем его получать в своё локальное хранилище. Иметь он будет такой вид.

public with sharing class MyClassForAnt {
    public MyClassForAnt(){
        System.debug('Hello Ant');
    }    
  }

Так же не стоит забывать что для этого класса нам необходим UnitTest, так как для успешного деплоя класс нужно покрыть на 75% тестами и 100% из них должны пройти.

UnitTest

Создадим UnitTest для 100% покрытия MyClassForAnt класса.
Я создам простой тестовый класс без проверок, так как функционала у нас в нём нет, то и проверять нечего. Только в целях примера я создал такой класс, никогда не повторяйте это на практике.

@IsTest
private class MyClassForAntTest {
    @IsTest
    static  void testBehavior() {
        MyClassForAnt myClassForAnt = new MyClassForAnt();
    }
}

Получение метаданных Apex класса

И так, на этом этапе у нас уже есть всё необходимое что бы получить метаданные нашего класса в наше локальное хранилище. Но перед написанием команды для получения этих данных, необходимо указать какие именно компоненты мы хотим запросить.

Настраиваем package.xml файл. Необходимо добавить в него тип и имя компонента хранящегося на нашей организации. Указываем тип(name) : ApexClass, и имя компонента(members): MyClassForAnt, имя ранее созданного класса. Таким же образом пишем и для test класса. Теперь ваш package.xml файл будет иметь такой вид.
Добавляем в build.xml файл target компонент сразу после объявления переменных для логина и пароля.

<target name="retrieve">
  <mkdir dir="retrieve"/>
  <sf:retrieve 
      username="${sf.username}" 
      password="${sf.password}" 
      serverurl="${sf.serverurl}" 
      retrieveTarget="retrieve" 
      unpackaged="package.xml"/>
</target>

Пройдём по каждой строчке кода.

<target name="retrieve"> - указываем имя команды которая в будущем будет использоваться для её вызова.
<mkdir dir="retrieve"/> - создание папки для дальнейшего использования как хранилища для метаданных.
<sf:retrieve - вызываем 1 из доступных нам команд из библиотеки sf, команда для получения метаданных.
username="${sf.username}" and password="${sf.password}" - используем переменные которые хранят login и password полученные из build.properties файла.
serverurl="${sf.serverurl}" - url по которому будет обращаться ant для аутентификации.
retrieveTarget="retrieve" - указываем в какую папку сохранять метаданные.
unpackaged="package.xml"/> - указываем pacakge.xml в котором хранится список запрашиваемых метаданных, в нашем случае Apex class.

В итоге build.xml файл должен иметь такой вид.

Проверка

Если всё было сделано правильно, то при написании команды ant retrieve команды в консоли, вы получите сообщение об успешном выполнении. Помните что запускать команду нужно находясь в папке с build.xml и т.п файлами
В папке откуда вы запускали ant должна появиться папка retrieve которая будет создана в процессе, и в ней должны находиться папка classes и package.xml файл. В папке classes будут находиться файлы с метаданными класса.

Добавление и обновление Apex класса

Ant migration tool не предоставляет такой команды как Update, обновление данных происходит как deploy, наши компоненты просто перезаписываются. Поэтому в нет никакой разницы между созданием и обновлением. В случае с Apex class нам всегда придется указывать сам класс, тесты для класса, и настраивать их запуск. Не зависимо от того создаём мы или обновляем.

Сделаем несколько изменений в нашем классе через любой текстовый редактор. Допишем текст к нашему Hello ant.
Добавим в build.xml новую команду для отправки класса на организацию.

<target name="deploy">
      <sf:deploy 
	 	 	username="${sf.username}" 
	 	 	password="${sf.password}"  
	  		serverurl="${sf.serverurl}" 
	  		maxPoll="${sf.maxPoll}" 
	  		deployRoot="deploy"
                        testLevel="RunSpecifiedTests">
       <runTest>MyClassForAntTest</runTest>
       </sf:deploy>
</target>

Назовём команду deploy, укажем функцию sf:deploy для отправки.
<runTest>MyClassForAntTest</runTest> - указываем какой тест запускать. Существует способ запустить все тесты.
deployRoot="deploy" - указывает на папку из которой будет взяты метаданные класса для отправки. Давайте создадим эту папку и добавим в неё наши данные полученные ранее, а после изменённые.

Папка проекта будет иметь примерно такой вид после создания папки deploy.

Копируем все файлы из ранее созданной папки retrieve в папку deploy.
.

Проверка

Из папки где расположен ваш build.xml файл запускаем команду ant deploy.

После чего вы должны будете увидеть сообщение об успешном деплое. И если перейдёте на свою организацию, или запросите метаданные снова, то увидите что System.debug будет содержать то сообщение что мы изменили.

Удаление Apex класса

Удаление компонента с организации имеет немного другую структуру.

Создайте папку, назовём её remove. Внутри папки создайте 2 файла: descrutctiveChanges.xml и pacakge.xml.
Структура файла descrutctiveChanges.xml :

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>MyClassForAnt</members>
        <name>ApexClass</name>
    </types>
	
	 <version>43.0</version>
</Package>

Здесь указываем какие компоненты мы ходим удалить.

Структура файла pacakge.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <version>43.0</version>
</Package>

в этом файле не указываем ничего. Просто оставляем версию.

Открываем файл build.xml в корневой папке. И добавляем в него следующее:

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

Как вы заметили тут тоже используется команда sf:deploy. После этого у вас есть всё необходимое для удаления компонентов.

Проверка

Из папки где расположен ваш build.xml файл запускаем команду ant remove.

Можете зайти на вашу организацию и посмотреть что там больше нет MyClassForAnt.

alexander.bogomaz · 27.02.2019 09:07:54