Схема определения рабочей роли для Облачной службы Azure (расширенная поддержка)

Рабочая роль Azure используется для обобщенной разработки. Она может выполнять фоновую обработку для веб-роли.

По умолчанию определения службы хранятся в файле с расширением .csdef.

Базовая схема определения службы для рабочей роли

Ниже приведен базовый формат файла с определением службы для рабочей роли.

<ServiceDefinition …>
  <WorkerRole name="<worker-role-name>" vmsize="<worker-role-size>" enableNativeCodeExecution="[true|false]">
    <Certificates>
      <Certificate name="<certificate-name>" storeLocation="[CurrentUser|LocalMachine]" storeName="[My|Root|CA|Trust|Disallow|TrustedPeople|TrustedPublisher|AuthRoot|AddressBook|<custom-store>" />
    </Certificates>
    <ConfigurationSettings>
      <Setting name="<setting-name>" />
    </ConfigurationSettings>
    <Endpoints>
      <InputEndpoint name="<input-endpoint-name>" protocol="[http|https|tcp|udp]" localPort="<local-port-number>" port="<port-number>" certificate="<certificate-name>" loadBalancerProbe="<load-balancer-probe-name>" />
      <InternalEndpoint name="<internal-endpoint-name" protocol="[http|tcp|udp|any]" port="<port-number>">
         <FixedPort port="<port-number>"/>
         <FixedPortRange min="<minimum-port-number>" max="<maximum-port-number>"/>
      </InternalEndpoint>
     <InstanceInputEndpoint name="<instance-input-endpoint-name>" localPort="<port-number>" protocol="[udp|tcp]">
         <AllocatePublicPortFrom>
            <FixedPortRange min="<minimum-port-number>" max="<maximum-port-number>"/>
         </AllocatePublicPortFrom>
      </InstanceInputEndpoint>
    </Endpoints>
    <Imports>
      <Import moduleName="[RemoteAccess|RemoteForwarder|Diagnostics]"/>
    </Imports>
    <LocalResources>
      <LocalStorage name="<local-store-name>" cleanOnRoleRecycle="[true|false]" sizeInMB="<size-in-megabytes>" />
    </LocalResources>
    <LocalStorage name="<local-store-name>" cleanOnRoleRecycle="[true|false]" sizeInMB="<size-in-megabytes>" />
    <Runtime executionContext="[limited|elevated]">
      <Environment>
         <Variable name="<variable-name>" value="<variable-value>">
            <RoleInstanceValue xpath="<xpath-to-role-environment-settings>"/>
          </Variable>
      </Environment>
      <EntryPoint>
         <NetFxEntryPoint assemblyName="<name-of-assembly-containing-entrypoint>" targetFrameworkVersion="<.net-framework-version>"/>
         <ProgramEntryPoint commandLine="<application>" setReadyOnProcessStart="[true|false]"/>
      </EntryPoint>
    </Runtime>
    <Startup priority="<for-internal-use-only>">
      <Task commandLine="" executionContext="[limited|elevated]" taskType="[simple|foreground|background]">
        <Environment>
         <Variable name="<variable-name>" value="<variable-value>">
            <RoleInstanceValue xpath="<xpath-to-role-environment-settings>"/>
          </Variable>
        </Environment>
      </Task>
    </Startup>
    <Contents>
      <Content destination="<destination-folder-name>" >
        <SourceDirectory path="<local-source-directory>" />
      </Content>
    </Contents>
  </WorkerRole>
</ServiceDefinition>

Элементы схемы

Файл определения службы содержит эти элементы, описанные в последующих разделах этой статьи:

WorkerRole

ConfigurationSettings

Параметр

LocalResources

LocalStorage

Конечные точки

InputEndpoint

InternalEndpoint

InstanceInputEndpoint

AllocatePublicPortFrom

FixedPort

FixedPortRange

Сертификаты

Certificate

Imports

Импорт

Среда выполнения

Среда

EntryPoint

NetFxEntryPoint

ProgramEntryPoint

Переменная

RoleInstanceValue

Startup

Задача

Contents

Содержимое

SourceDirectory

WorkerRole

Элемент WorkerRole описывает роль для обобщенной разработки, которая может выполнять фоновую обработку для веб-роли. Служба может содержать любое число рабочих ролей либо не содержать ни одной.

В таблице ниже описаны атрибуты элемента WorkerRole.

Атрибут Тип Description
name строка Обязательный. Имя рабочей роли. Это имя должно быть уникальным.
enableNativeCodeExecution boolean Необязательно. Значение по умолчанию — true. Выполнение машинного кода и полный уровень доверия включены по умолчанию. Установите для этого атрибута значение false, чтобы отключить для рабочей роли выполнение машинного кода и использовать частичное доверие Azure.
vmsize строка Необязательно. Это значение используется для изменения размера виртуальной машины, выделяемой для роли. Значение по умолчанию — Small. Список возможных размеров виртуальной машины и их атрибутов см. в статье Размеры для облачных служб.

ConfigurationSettings

Элемент ConfigurationSettings описывает коллекцию параметров конфигурации для рабочей роли. Этот элемент является родительским для элемента Setting.

Параметр

Элемент Setting описывает пару "имя — значение", которая определяет параметр конфигурации для экземпляра роли.

В таблице ниже описаны атрибуты элемента Setting.

Атрибут Тип Description
name строка Обязательный. Уникальное имя параметра конфигурации.

Параметры конфигурации для роли в формате пар "имя — значение", которые объявляются в файле определения службы и настраиваются в файле конфигурации службы.

LocalResources

Элемент LocalResources описывает коллекцию локальных ресурсов хранилища для рабочей роли. Этот элемент является родительским для элемента LocalStorage.

LocalStorage

Элемент LocalStorage определяет локальный ресурс хранилища, который предоставляет для место в файловой системе в среде выполнения. Для роли можно не определить ни одного или определить несколько локальных ресурсов хранилища.

Примечание.

Элемент LocalStorage может отображаться как дочерний для элемента WorkerRole. Это нужно для обеспечения совместимости с предыдущими версиями пакета Azure SDK.

В таблице ниже описаны атрибуты элемента LocalStorage.

Атрибут Тип Description
name строка Обязательный. Уникальное имя локального хранилища.
cleanOnRoleRecycle boolean Необязательно. Указывает, должно ли очищаться локальное хранилище при перезапуске роли. Значение по умолчанию: true.
sizeInMb INT Необязательно. Требуемый объем дискового пространства, выделяемого для локального хранилища (МБ). Если значение не указано, по умолчанию выделяется 100 МБ. Минимальный объем выделяемого дискового пространства составляет 1 МБ.

Максимальный размер локальных ресурсов зависит от размера виртуальной машины. Дополнительные сведения см. в статье Размеры для облачных служб.

Имя каталога, выделенного для локального ресурса хранилища, соответствует значению, указанному в атрибуте имени.

Конечные точки

Элемент Endpoints описывает для роли коллекцию, состоящую из входных (внешних) и внутренних конечных точек, а также входных конечных точек экземпляров. Этот элемент является родительским для элементов InputEndpoint, InternalEndpoint и InstanceInputEndpoint.

Входные и внутренние конечные точки выделяются раздельно. Служба может иметь в общей сложности 25 входных, внутренних и экземплярных входных конечных точек, которые можно выделить между 25 ролями, разрешенными в службе. Например, если у вас пять ролей, можно выделить пять входных конечных точек для каждой роли или выделить 25 входных конечных точек для одной роли или выделить одну входную конечную точку для 25 ролей.

Примечание.

Для каждой развернутой роли требуется один экземпляр. Подготовка по умолчанию для подписки ограничена 20 ядрами, и, соответственно, 20 экземплярами роли. Если приложению требуется больше экземпляров, чем обеспечивается подготовкой по умолчанию, вы можете повысить это ограничение. Подробнее см. сведения на странице службы поддержки.

InputEndpoint

Элемент InputEndpoint описывает внешнюю конечную точку рабочей роли.

Вы можете определить несколько конечных точек в любой комбинации из следующего набора: HTTP, HTTPS, UDP и TCP. Для входной конечной точки можно задать любой номер порта на ваш выбор, но номера портов, указанные для каждой роли в службе, должны быть уникальными. Например, если вы укажете, что веб-роль использует порт 80 для HTTP и порт 443 для HTTPS, вы можете назначить для второй веб-роли порт 8080 для HTTP и порт 8043 для HTTPS.

В таблице ниже описаны атрибуты элемента InputEndpoint.

Атрибут Тип Description
name строка Обязательный. Уникальное имя внешней конечной точки.
protocol строка Обязательный. Транспортный протокол для внешней конечной точки. Для рабочей роли возможными значениями могут быть HTTP, HTTPS, UDP или TCP.
port INT Обязательный. Порт для внешней конечной точки. Можно задать любой номер порта на ваш выбор, но номера портов, указанные для каждой роли в службе, должны быть уникальными.

Возможный диапазон значений — от 1 до 65 535 включительно (пакет Azure SDK версии 1.7 и выше).
сертификат строка Обязательный для конечной точки HTTPS. Имя сертификата, определенное элементом Certificate.
localPort INT Необязательно. Указывает порт, используемый для внутренних подключений к конечной точке. Атрибут localPort сопоставляет внешний порт конечной точки с внутренним портом в роли. Этот атрибут полезен в сценариях, когда роль должна взаимодействовать с внутренним компонентом на порту, который отличается от того, который предоставляется внешним образом.

Если значение localPort не указано, оно совпадает со значением атрибута port. Установите для параметра localPort значение *, чтобы автоматически назначить любой свободный порт. Номер этого порта можно узнать через API среды выполнения.

Возможный диапазон значений — от 1 до 65 535 включительно (пакет Azure SDK версии 1.7 и выше).

Атрибут localPort доступен только при использовании пакета Azure SDK версии 1.3 или выше.
ignoreRoleInstanceStatus boolean Необязательно. Если задано trueзначение этого атрибута, состояние службы игнорируется, а конечная точка не будет удалена подсистемой балансировки нагрузки. Присвоение этому параметру значения true будет полезно для отладки занятых экземпляров службы. Значение по умолчанию — false. Примечание. Конечная точка по-прежнему может получать трафик, даже если роль не находится в состоянии готовности.
loadBalancerProbe строка Необязательно. Имя подсистемы балансировки нагрузки, связанной со входной конечной точкой. Дополнительные сведения см. в статье Azure Cloud Services Definition LoadBalancerProbe Schema (Определение облачных служб Azure. Схема LoadBalancerProbe).

InternalEndpoint

Элемент InternalEndpoint описывает внутреннюю конечную точку рабочей роли. Внутренняя конечная точка доступна только другим экземплярам ролей, работающим в службе; он недоступен клиентам за пределами службы. Рабочая роль может иметь до пяти внутренних конечных точек HTTP, UDP или TCP.

В таблице ниже описаны атрибуты элемента InternalEndpoint.

Атрибут Тип Description
name строка Обязательный. Уникальное имя внутренней конечной точки.
protocol строка Обязательный. Транспортный протокол для внутренней конечной точки. Возможные значения: HTTP, TCP, UDP или ANY.

Значение ANY указывает, что допустим любой протокол и любой порт.
port INT Необязательно. Порт, используемый для внутренних подключений с балансировкой нагрузки на конечной точке. Конечная точка с балансировкой нагрузки использует два порта. Один из них используется для общедоступного IP-адреса, а другой — для частного IP-адреса. Как правило, эти значения имеют одинаковые значения, но вы можете использовать разные порты.

Возможный диапазон значений — от 1 до 65 535 включительно (пакет Azure SDK версии 1.7 и выше).

Атрибут Port доступен только при использовании пакета Azure SDK версии 1.3 или выше.

InstanceInputEndpoint

Элемент InstanceInputEndpoint описывает входную конечную точку экземпляра для рабочей роли. Входная конечная точка экземпляра связана с конкретным экземпляром роли с помощью переадресации портов в подсистеме балансировки нагрузки. Каждая входная конечная точка экземпляра сопоставляется с конкретным портом из диапазона возможных портов. Этот элемент является родительским для элемента AllocatePublicPortFrom.

Элемент InstanceInputEndpoint доступен только при использовании пакета Azure SDK версии 1.7 или выше.

В таблице ниже описаны атрибуты элемента InstanceInputEndpoint.

Атрибут Тип Description
name строка Обязательный. Уникальное имя конечной точки.
localPort INT Обязательный. Указывает внутренний порт, к которому будут прослушиваться все экземпляры ролей, чтобы получать входящий трафик, переадресованный из подсистемы балансировки нагрузки. Возможный диапазон значений — от 1 до 65 535 включительно.
protocol строка Обязательный. Транспортный протокол для внутренней конечной точки. Возможные значения: udp или tcp. Используйте tcp для трафика на основе HTTP и HTTPS.

AllocatePublicPortFrom

Элемент AllocatePublicPortFrom описывает диапазон общедоступных портов, который внешние клиенты могут использовать для доступа к каждой конечной точке ввода экземпляра. Из этого диапазона выделяется номер общедоступного порта (на виртуальном IP-адресе), который назначается каждой конечной точке экземпляра роли во время развертывания и обновления клиента. Этот элемент является родительским для элемента FixedPortRange.

Элемент AllocatePublicPortFrom доступен только при использовании пакета Azure SDK версии 1.7 или выше.

FixedPort

Элемент FixedPort указывает порт для внутренней конечной точки, который обеспечивает подключения к конечной точке с балансировкой нагрузки.

Элемент FixedPort доступен только при использовании пакета Azure SDK версии 1.3 или выше.

В таблице ниже описаны атрибуты элемента FixedPort.

Атрибут Тип Описание
port INT Обязательный. Порт для внутренней конечной точки. Этот атрибут имеет тот же эффект, что и установка минимального FixedPortRange и максимального значения на тот же порт.

Возможный диапазон значений — от 1 до 65 535 включительно (пакет Azure SDK версии 1.7 и выше).

FixedPortRange

Элемент FixedPortRange указывает диапазон портов, назначаемых внутренней конечной точке или входной конечной точке экземпляра. Он также устанавливает порт, используемый для подключений к конечной точке с балансировкой нагрузки.

Примечание.

Элемент FixedPortRange работает по-разному в зависимости от того, в каком элементе он находится. Если элемент FixedPortRange находится в элементе InternalEndpoint, он открывает все порты подсистемы балансировки нагрузки в диапазоне от верхнего до нижнего значения соответствующих атрибутов для всех виртуальных машин, на которых выполняется эта роль. Если элемент FixedPortRange находится в элементе InstanceInputEndpoint, он открывает только один порт в диапазоне от верхнего до нижнего значения соответствующих атрибутов на каждой виртуальной машине, выполняющей эту роль.

Элемент FixedPortRange доступен только при использовании пакета Azure SDK версии 1.3 или выше.

В таблице ниже описаны атрибуты элемента FixedPortRange.

Атрибут Тип Описание
мин INT Обязательный. Минимальный номер порта в диапазоне. Возможный диапазон значений — от 1 до 65 535 включительно (пакет Azure SDK версии 1.7 и выше).
макс. строка Обязательный. Максимальный номер порта в диапазоне. Возможный диапазон значений — от 1 до 65 535 включительно (пакет Azure SDK версии 1.7 и выше).

Сертификаты

Элемент Certificates описывает коллекцию сертификатов для рабочей роли. Этот элемент является родительским для элемента Certificate. Роль может иметь любое число связанных сертификатов. Дополнительные сведения об использовании элементов certificate см. в разделе Шаг 2. Изменение файлов определения службы и конфигурации.

Сертификат

Элемент Certificate описывает сертификат, связанный с рабочей ролью.

В таблице ниже описаны атрибуты элемента Certificate.

Атрибут Тип Description
name строка Обязательный. Имя этого сертификата, которое используется для ссылки на него при сопоставлении с элементом HTTPS InputEndpoint .
storeLocation строка Обязательный. Расположение хранилища сертификатов, в котором размещается этот сертификат на локальном компьютере. Возможные значения: CurrentUser и LocalMachine.
storeName строка Обязательный. Имя хранилища сертификатов, в котором размещается этот сертификат на локальном компьютере. Возможные значения включают стандартные имена хранилищ My, Root, CA, Trust, Disallowed, TrustedPeople, TrustedPublisher, AuthRoot, AddressBook или любое пользовательское имя хранилища. Если указано пользовательское имя хранилища, хранилище создается автоматически.
permissionLevel строка Необязательно. Указывает права доступа, предоставленные процессам роли. Если вы хотите, чтобы только процессы с повышенными привилегиями имели доступ к закрытому ключу, укажите разрешение elevated. Разрешение limitedOrElevated позволяет всем процессам роли получать доступ к закрытому ключу. Возможные значения: limitedOrElevated или elevated. Значение по умолчанию — limitedOrElevated.

Импорт

Элемент Imports описывает коллекцию модулей импорта для рабочей роли, которые добавляют компоненты в гостевую ОС. Этот элемент является родительским для элемента Import. Он является необязательным, и в роли может быть только один блок среды выполнения.

Элемент Imports доступен только при использовании пакета Azure SDK версии 1.3 или выше.

Import

Элемент Import указывает модуль для добавления в гостевую ОС.

Элемент Import доступен только при использовании пакета Azure SDK версии 1.3 или выше.

В таблице ниже описаны атрибуты элемента Import.

Атрибут Тип Описание
moduleName строка Обязательный. Имя модуля, который нужно импортировать. Допустимыми модулями являются:

— RemoteAccess
— RemoteForwarder
— Diagnostics

Модули RemoteAccess и RemoteForwarder позволяют настроить экземпляр роли для подключения удаленного рабочего стола. Дополнительные сведения см. в разделе "Расширения".

Модуль Diagnostics позволяет собирать диагностические данные экземпляра роли.

Параметры выполнения

Элемент Runtime описывает коллекцию параметров переменных среды для рабочей роли, которые управляют средой выполнения хост-процесса Azure. Этот элемент является родительским для элемента Environment. Он является необязательным, и в роли может быть только один блок среды выполнения.

Элемент Runtime доступен только при использовании пакета Azure SDK версии 1.3 или выше.

В таблице ниже описаны атрибуты элемента Runtime.

Атрибут Тип Описание
executionContext строка Необязательно. Указывает контекст, в котором запускается процесс роли. Контекст по умолчанию — limited.

- limited — процесс запускается без прав администратора.
- elevated — процесс запускается с правами администратора.

Среда

Элемент Environment описывает коллекцию параметров переменных среды для рабочей роли. Этот элемент является родительским для элемента Variable. Роль может иметь любое число заданных переменных среды.

«Переменная»

Элемент Variable указывает переменную среды, которая будет установлена ​​в гостевой ОС.

Элемент Variable доступен только при использовании пакета Azure SDK версии 1.3 или выше.

В таблице ниже описаны атрибуты элемента Variable.

Атрибут Тип Description
name строка Обязательный. Имя переменной среды для установки.
значение строка Необязательно. Задаваемое значение для переменной среды. Необходимо включить либо атрибут значения, либо элемент RoleInstanceValue.

RoleInstanceValue

Элемент RoleInstanceValue указывает путь xPath, из которого извлекается значение переменной.

В таблице ниже описаны атрибуты элемента RoleInstanceValue.

Атрибут Тип Описание
xpath строка Необязательно. Путь расположения параметров развертывания для экземпляра. Дополнительные сведения см. в статье Предоставление параметров конфигурации ролей как переменной среды с помощью XPath.

Необходимо включить либо атрибут значения, либо элемент RoleInstanceValue.

EntryPoint

Элемент EntryPoint указывает точку входа для роли. Этот элемент является родительским для элементов NetFxEntryPoint. Эти элементы позволяют указать в качестве точки входа роли приложение, отличное от стандартного WaWorkerHost.exe.

Элемент EntryPoint доступен только при использовании пакета Azure SDK версии 1.5 или выше.

NetFxEntryPoint

Элемент NetFxEntryPoint указывает программу, которую следует запустить для роли.

Примечание.

Элемент NetFxEntryPoint доступен только при использовании пакета Azure SDK версии 1.5 или выше.

В таблице ниже описаны атрибуты элемента NetFxEntryPoint.

Атрибут Тип Описание
аssemblyName строка Обязательный. Путь и имя файла сборки, содержащей точку входа. Путь относительно папки \%ROLEROOT%\Approot (не указывайте \%ROLEROOT%\Approot в командной строке; предполагается). %ROLEROOT% — это переменная среды, поддерживаемая Azure и представляющая расположение корневой папки для роли. Папка \%ROLEROOT%\Approot представляет папку приложения для вашей роли.
targetFrameworkVersion строка Обязательный. Версия .NET Framework, в которой создана сборка. Например, targetFrameworkVersion="v4.0".

ProgramEntryPoint

Элемент ProgramEntryPoint указывает программу, которую следует запустить для роли. Элемент ProgramEntryPoint позволяет указать точку входа программы, которая не основана на сборке .NET.

Примечание.

Элемент ProgramEntryPoint доступен только при использовании пакета Azure SDK версии 1.5 или выше.

В таблице ниже описаны атрибуты элемента ProgramEntryPoint.

Атрибут Тип Описание
commandLine строка Обязательный. Путь, имя файла и все аргументы командной строки для выполнения программы. Путь относится к папке %ROLEROOT%\Approot (не указывайте %ROLEROOT%\Approot в командной строке; предполагается). %ROLEROOT% — это переменная среды, поддерживаемая Azure и представляющая расположение корневой папки для роли. Папка %ROLEROOT%\Approot представляет папку приложения для вашей роли.

Роль очищается, когда завершается программа, поэтому программу следует создавать для продолжительной работы, а не просто для выполнения ограниченной по времени задачи.
setReadyOnProcessStart boolean Обязательный. Указывает, ожидает ли экземпляр роли сигнал программы командной строки при запуске. Сейчас этот аргумент должен иметь значение true. Возможность установить значение false зарезервирована для будущего использования.

Запуск

Элемент Startup описывает коллекцию задач, выполняемых при запуске роли. Этот элемент может являться родительским для элемента Variable. Дополнительные сведения об использовании задач запуска роли см. в статье Как настроить и выполнить задачи запуска для облачной службы. Этот элемент является необязательным, и в роли может быть только один блок запуска.

В таблице ниже описаны атрибуты элемента Startup.

Атрибут Тип Описание
priority INT Только для внутреннего пользования.

Задача

Элемент Task указывает задачу запуска, которая выполняется при запуске роли. Задачи запуска могут использоваться для выполнения задач, которые подготавливают роль для запуска, таких как установка программных компонентов или запуск других приложений. Задачи выполняются в порядке их размещения в блоке элементов Startup.

Элемент Task доступен только при использовании пакета Azure SDK версии 1.3 или выше.

В таблице ниже описаны атрибуты элемента Task.

Атрибут Тип Описание
commandLine строка Обязательный. Скрипт, например CMD-файл, содержащий команды для выполнения. Команда запуска и пакетные файлы должны быть сохранены в формате ANSI. Форматы файлов, которые задают маркер порядка байтов в начале процессов файлов неправильно.
executionContext строка Задает контекст, в котором будет выполняться скрипт.

- limited (по умолчанию) — выполняется с теми же привилегиями, что и роль, в которой размещается процесс.
- elevated — запуск с правами администратора.
taskType строка Задает поведение выполнения команды.

- simple (по умолчанию) — система ждет завершения задачи перед запуском других задач.
- background — система не ожидает завершения задачи.
- foreground — Аналогично фоновому режиму, за исключением того, что роль не перезапускается до завершения всех задач переднего плана.

Содержимое

Элемент Contents описывает коллекцию содержимого для рабочей роли. Этот элемент является родительским для элемента Content.

Элемент Contents доступен только при использовании пакета Azure SDK версии 1.5 или выше.

Содержимое

Элемент Content определяет исходное расположение содержимого, копируемого на виртуальную машину Azure, и путь назначения, в который он копирует.

Элемент Content доступен только при использовании пакета Azure SDK версии 1.5 или выше.

В таблице ниже описаны атрибуты элемента Content.

Атрибут Тип Описание
destination строка Обязательный. Расположение на виртуальной машине Azure, куда помещается содержимое. Это расположение указывается относительно папки %ROLEROOT%\Approot.

Этот элемент является родительским для элемента SourceDirectory.

SourceDirectory

Элемент SourceDirectory определяет локальный каталог, из которого копируется содержимое. Он используется для определения локального содержимого, которое копируется на виртуальную машину Azure.

Элемент SourceDirectory доступен только при использовании пакета Azure SDK версии 1.5 или выше.

В таблице ниже описаны атрибуты элемента SourceDirectory.

Атрибут Тип Описание
path строка Обязательный. Относительный или абсолютный путь к локальному каталогу, содержимое которого копируется на виртуальную машину Azure. В пути к каталогу поддерживается использование переменных среды.

См. также

Схема определения для Облачной службы (с расширенной поддержкой).