Элементы сборки

Элементы сборки управляют созданием проекта приложения или библиотеки .NET для Android.

Они указываются в файле проекта, например MyApp.csproj, в MSBuild ItemGroup.

Примечание.

В .NET для Android технически нет различий между приложением и проектом привязок, поэтому элементы сборки будут работать в обоих. На практике настоятельно рекомендуется создавать отдельные проекты приложений и привязок. Элементы сборки, которые в основном используются в проектах привязок, описаны в справочном руководстве по элементам проекта msBuild.

Дополнительный манифест Java для Android

<AndroidAdditionalJavaManifest> используется в сочетании с решением зависимостей Java для указания дополнительных файлов POM, которые потребуются для проверки зависимостей. Часто это родительские или импортированные POM-файлы, на которые ссылается POM-файл библиотеки Java.

<ItemGroup>
  <AndroidAdditionalJavaManifest Include="mylib-parent.pom" JavaArtifact="com.example:mylib-parent" JavaVersion="1.0.0" />
</ItemGroup>

Требуются следующие метаданные MSBuild:

  • %(JavaArtifact): идентификатор группы и артефакта библиотеки Java, соответствующий спецификации POM-файла в форме {GroupId}:{ArtifactId}.
  • %(JavaVersion): версия библиотеки Java, соответствующая указанному файлу POM.

Дополнительные сведения см. в документации по разрешению зависимостей Java.

Это действие сборки было введено в .NET 9.

AndroidAsset

Поддерживает ресурсы Android, то есть файлы, которые включаются в папку assets в проекте Android на Java.

Начиная с .NET 9 @(AndroidAsset) действие сборки также поддерживает дополнительные метаданные для создания Asset Packs. Метаданные %(AndroidAsset.AssetPack) можно использовать для автоматического создания пакета ресурсов с этим именем. Эта функция поддерживается только в том случае, если $(AndroidPackageFormat) задано значение .aab. В следующем примере movie2.mp4 и movie3.mp4 будут размещены в отдельных пакетах активов.

<ItemGroup>
   <AndroidAsset Update="Asset/movie.mp4" />
   <AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
   <AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>

Эту функцию можно использовать для включения больших файлов в приложение, которые обычно превышают максимальный размер пакета Google Play.

Если у вас есть большое количество ресурсов, это может быть более эффективным, чтобы использовать base пакет ресурсов. В этом сценарии вы обновляете все ресурсы, чтобы включить их в один пакет ресурсов. Затем используйте метаданные AssetPack="base" для указания, какие конкретные ресурсы входят в базовый файл .aab. С помощью этого можно использовать подстановочные знаки для перемещения большинства ресурсов в пакет ресурсов.

<ItemGroup>
   <AndroidAsset Update="Assets/*" AssetPack="assets1" />
   <AndroidAsset Update="Assets/movie.mp4" AssetPack="base" />
   <AndroidAsset Update="Assets/some.png" AssetPack="base" />
</ItemGroup>

В этом примере movie.mp4 и some.png в конечном итоге будут в файле base aab, а все остальные ресурсы будут в пакете assets1 ресурсов.

Дополнительные метаданные поддерживаются только в .NET для Android 9 и более поздних версий.

AndroidAarLibrary

Действие сборки AndroidAarLibrary следует использовать для прямой ссылки на файлы .aar. Действие сборки будет наиболее часто использоваться компонентами Xamarin. А именно, чтобы включить ссылки на .aar файлы, необходимые для работы Google Play и других служб.

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

AndroidAotProfile

Используется для предоставления профиля AOT для использования с AOT с поддержкой профилей.

Его также можно использовать из Visual Studio, установив параметр действия сборки AndroidAotProfile на файл, содержащий профиль AOT.

AndroidAppBundleMetaDataFile (Файл Метаданных Пакета Приложения на Android)

Указывает файл, который будет включен в пакет приложений Android в качестве метаданных. Формат значения флага — это <bundle-path>:<physical-file>, где bundle-path обозначает расположение файла в каталоге метаданных пакета приложений, а physical-file является существующим файлом, содержащим необработанные данные для хранения.

<ItemGroup>
  <AndroidAppBundleMetaDataFile
    Include="com.android.tools.build.obfuscation/proguard.map:$(OutputPath)mapping.txt"
  />
</ItemGroup>

См. документацию bundletool для получения более подробной информации.

AndroidBoundLayout

Указывает, что для файла макета должен быть автоматически создан связанный код в случае, если для свойства задано значение . Во всех остальных аспектах он идентичен AndroidResource.

Это действие может использоваться только с файлами макета:

<AndroidBoundLayout Include="Resources\layout\Main.axml" />

AndroidEnvironment

Файлы с действием сборки AndroidEnvironment используются для инициализации переменных среды и свойств системы во время запуска процесса. Действие сборки AndroidEnvironment может быть применено к нескольким файлам, и они будут оцениваться без какого либо порядка (поэтому не указывайте одну и ту же переменную среды или системное свойство в нескольких файлах).

AndroidGradleProject

<AndroidGradleProject> можно использовать для сборки и использования выходных данных проектов Android Gradle, созданных в Android Studio или elsewehere.

Метаданные Include должны указывать на верхний уровень build.gradle или build.gradle.kts файл, который будет использоваться для сборки проекта. Это будет найдено в корневом каталоге проекта Gradle, который также должен содержать gradlew скрипты оболочки.

<ItemGroup>
  <AndroidGradleProject Include="path/to/project/build.gradle.kts" ModuleName="mylibrary" />
</ItemGroup>

Поддерживаются следующие метаданные MSBuild:

  • %(Configuration): имя конфигурации, используемой для сборки или компоновки указанного проекта или модуля проекта. Значение по умолчанию — Release.
  • %(ModuleName): имя модуля или подпроекта, который должен быть создан. Значение по умолчанию — пусто.
  • %(OutputPath): можно задать для переопределения выходного пути сборки проекта Gradle. Значение по умолчанию — $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}.
  • %(CreateAndroidLibrary): выходные файлы AAR будут добавлены в проект AndroidLibrary . Метаданные, поддерживаемые <AndroidLibrary>, например %(Bind) или %(Pack), будут перенаправлены, если задано. Значение по умолчанию — true.

Это действие сборки было введено в .NET 9.

AndroidJavaLibrary

Файлы с действием сборки AndroidJavaLibrary — это архивы Java ( .jar файлы), которые будут включены в окончательный пакет Android.

ЗависимостьJava,ИгнорируемаяAndroid

<AndroidIgnoredJavaDependency> используется в сочетании с разрешением зависимостей Java.

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

<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidIgnoredJavaDependency Include="com.google.errorprone:error_prone_annotations" Version="2.15.0" />
</ItemGroup>

Требуются следующие метаданные MSBuild:

  • %(Version): версия библиотеки Java, соответствующая указанному %(Include).

Дополнительные сведения см. в документации по разрешению зависимостей Java.

Это действие сборки было введено в .NET 9.

AndroidJavaSource

Файлы с действием сборки AndroidJavaSource — это исходный код Java, который будет включен в окончательный пакет Android.

Начиная с .NET 7, все **\*.java файлы в каталоге проекта автоматически имеют действие сборки AndroidJavaSource, и будут привязаны до сборки. Позволяет коду C# легко использовать типы и члены, присутствующих в файлах **\*.java .

Установите значение %(AndroidJavaSource.Bind) False, чтобы отключить это поведение.

AndroidLibrary

AndroidLibrary — это новое действие сборки для упрощения процесса включения файлов .jar и .aar в проекты.

Можно указать любой проект:

<ItemGroup>
  <AndroidLibrary Include="foo.jar" />
  <AndroidLibrary Include="bar.aar" />
</ItemGroup>

Результат приведенного выше фрагмента кода имеет разные последствия для каждого типа проекта .NET для Android:

  • Проекты библиотеки приложений и классов:
  • Проекты привязки Java:

Это упрощение означает, что вы можете использовать AndroidLibrary везде.

AndroidLintConfig

Действие сборки 'AndroidLintConfig' следует использовать в сочетании со свойством Свойство $(AndroidLintEnabled). Файлы с этим действием сборки объединяются друг с другом и передаются инструментам Android lint. Они должны быть XML-файлами, содержащими сведения о тестах для включения и отключения.

Дополнительные сведения см. в документации по Lint.

AndroidManifestOverlay

AndroidManifestOverlay Действие сборки можно использовать для предоставления AndroidManifest.xml файлов средству слияния манифестов. Файлы с этим действием компиляции будут переданы в инструмент объединения манифестов вместе с основным AndroidManifest.xml файлом и файлами манифеста из ссылочных зависимостей. Затем они будут объединены в окончательный манифест.

Это действие сборки можно использовать для предоставления изменений и параметров в приложении в зависимости от конфигурации сборки. Например, если требуется определенное разрешение только во время отладки, можно использовать наложение, чтобы внедрить это разрешение при отладке. Например, имеется следующее содержимое файла наложения:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.CAMERA" />
</manifest>

Чтобы добавить наложение манифеста для отладочной сборки, можно использовать следующее:

<ItemGroup>
  <AndroidManifestOverlay Include="DebugPermissions.xml" Condition=" '$(Configuration)' == 'Debug' " />
</ItemGroup>

AndroidInstallModules

Указывает модули, которые устанавливаются командой bundletool при установке пакетов.

AndroidMavenLibrary

<AndroidMavenLibrary> позволяет указать артефакт Maven, который будет автоматически скачан и добавлен в проект привязки .NET для Android. Это может быть полезно для упрощения обслуживания привязок .NET для Android для артефактов, размещенных в Maven.

<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidMavenLibrary Include="com.squareup.okhttp3:okhttp" Version="4.9.3" />
</ItemGroup>

Поддерживаются следующие метаданные MSBuild:

  • %(Version): требуемая версия библиотеки Java, %(Include)на которую ссылается.
  • %(Repository): Это необязательный репозиторий Maven для использования. Поддерживаемые значения: Central (по умолчанию) Googleили https URL-адрес репозитория Maven.

Элемент <AndroidMavenLibrary> преобразуется в AndroidLibrary, поэтому любые метаданные, поддерживаемые <AndroidLibrary>, такие как %(Bind) или %(Pack), также поддерживаются.

Дополнительные сведения см. в документации по AndroidMavenLibrary.

Это действие сборки было введено в .NET 9.

AndroidNativeLibrary

Собственные библиотеки можно добавить в сборку, указав для них действие сборки AndroidNativeLibrary.

Обратите внимание, что так как Android поддерживает несколько интерфейсов прикладного программирования (ABI), система сборки должна знать, для какой ABI создается собственная библиотека. Можно указать ABI двумя способами:

  1. Сканирование пути.
  2. Использование метаданных элемента %(Abi).

При сканировании пути имя родительского каталога собственной библиотеки используется для указания целевого ABI библиотеки. Таким образом при добавлении lib/armeabi-v7a/libfoo.so к сборке ABI будет сканироваться как armeabi-v7a.

Имя атрибута элемента

Abi — задает ABI собственной библиотеки.

<ItemGroup>
  <AndroidNativeLibrary Include="path/to/libfoo.so">
    <Abi>armeabi-v7a</Abi>
  </AndroidNativeLibrary>
</ItemGroup>

AndroidNativeLibraryNoJniPreload

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

Некоторые библиотеки платформы, которые должны быть загружены при запуске приложения, не будут затронуты, если они включены в эту группу элементов.

См. также $(AndroidIgnoreAllJniPreload)

ПараметрыУпаковкиAndroidИсключить

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

<ItemGroup>
	<AndroidPackagingOptionsExclude Include="DebugProbesKt.bin" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.kotlin_*')" />
</ItemGroup>

Элементы могут использовать символы-шаблоны для подстановочных знаков, таких как * и ?. Однако эти элементы должны быть закодированы в формате URL или использовать $([MSBuild]::Escape('')). Это сделано, чтобы MSBuild не пытался интерпретировать их как действительные подстановочные знаки для файлов.

Например.

<ItemGroup>
	<AndroidPackagingOptionsExclude Include="%2A.foo_%2A" />
  <AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.foo')" />
</ItemGroup>

ПРИМЕЧАНИЕ: *, ? и . будут заменены в задаче BuildApk на соответствующие шаблоны файлов.

Если глобб файла по умолчанию слишком ограничивающий, его можно удалить, добавив в csproj следующую команду.

<ItemGroup>
	<AndroidPackagingOptionsExclude Remove="$([MSBuild]::Escape('*.kotlin_*')" />
</ItemGroup>

Добавлено в .NET 7.

ПараметрыУпаковкиAndroidВключают

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

<ItemGroup>
	<AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.kotlin_builtins')" />
</ItemGroup>

Элементы могут использовать символы-шаблоны для подстановочных знаков, таких как * и ?. Однако эти элементы ДОЛЖНЫ использовать URL-кодирование или $([MSBuild]::Escape('')). Это сделано, чтобы MSBuild не пытался интерпретировать их как действительные подстановочные знаки для файлов. Например.

<ItemGroup>
	<AndroidPackagingOptionsInclude Include="%2A.foo_%2A" />
  <AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.foo')" />
</ItemGroup>

ПРИМЕЧАНИЕ: *, ? и . будут заменены в задаче BuildApk на соответствующие шаблоны файлов.

Добавлено в .NET 9.

AndroidResource

Все файлы с действием AndroidResource компилируются в ресурсы Android во время процесса сборки и становятся доступными с помощью $(AndroidResgenFile).

<ItemGroup>
  <AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>

Более опытным пользователям может потребоваться использовать разные ресурсы в разных конфигурациях, но с тем же эффективным путем. Этого можно достичь за счет наличия нескольких каталогов ресурсов и файлов с одинаковыми относительными путями в этих каталогах и благодаря использованию условий MSBuild для условного включения разных файлов в различные конфигурации. Например:

<ItemGroup Condition=" '$(Configuration)' != 'Debug' ">
  <AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>
<ItemGroup  Condition=" '$(Configuration)' == 'Debug' ">
  <AndroidResource Include="Resources-Debug\values\strings.xml"/>
</ItemGroup>
<PropertyGroup>
  <MonoAndroidResourcePrefix>Resources;Resources-Debug</MonoAndroidResourcePrefix>
</PropertyGroup>

LogicalName — явно указывает путь к ресурсу. Позволяет "псевдонимировать" файлы, чтобы они были доступны в виде нескольких разных имен ресурсов.

<ItemGroup Condition="'$(Configuration)'!='Debug'">
  <AndroidResource Include="Resources/values/strings.xml"/>
</ItemGroup>
<ItemGroup Condition="'$(Configuration)'=='Debug'">
  <AndroidResource Include="Resources-Debug/values/strings.xml">
    <LogicalName>values/strings.xml</LogicalName>
  </AndroidResource>
</ItemGroup>

Содержимое

Обычное действие сборки Content не поддерживается (потому что мы не выяснили, как его поддерживать без затратного шага первого запуска).

Попытка использовать действие сборки @(Content) приведет к предупреждению XA0101 .

EmbeddedJar

В проекте привязки .NET для Android сборочное действие EmbeddedJar связывает библиотеку Java/Kotlin и встраивает файл .jar в библиотеку. Когда проект приложения .NET для Android использует библиотеку, он будет иметь доступ к API Java/Kotlin из C# и включить код Java/Kotlin в окончательное приложение Android.

Вместо этого следует использовать действие сборки AndroidLibrary в качестве альтернативы, например:

<Project>
  <ItemGroup>
    <AndroidLibrary Include="Library.jar" />
  </ItemGroup>
</Project>

EmbeddedNativeLibrary

В библиотеке классов .NET для Android или в проекте привязки Java действие сборки EmbeddedNativeLibrary объединяет собственную библиотеку, такую как lib/armeabi-v7a/libfoo.so, в библиотеку. Когда приложение .NET для Android использует библиотеку, libfoo.so файл будет включен в окончательное приложение Android.

Действие сборки AndroidNativeLibrary можно использовать в качестве альтернативы.

EmbeddedReferenceJar

В проекте привязки .NET для Android действие сборки EmbeddedReferenceJar внедряет файл в библиотеку, но не создает привязку C#, как это делает .jar. Когда проект приложения .NET для Android использует библиотеку, он будет включать код Java/Kotlin в окончательное приложение Android.

Действие сборки AndroidLibrary можно использовать в качестве альтернативы, например<AndroidLibrary Include="..." Bind="false" />:

<Project>
  <ItemGroup>
    <!-- A .jar file to bind & embed -->
    <AndroidLibrary Include="Library.jar" />
    <!-- A .jar file to only embed -->
    <AndroidLibrary Include="Dependency.jar" Bind="false" />
  </ItemGroup>
</Project>

JavaSourceJar

В проекте привязки .NET для Android действие сборки JavaSourceJar применяется к .jar файлам, содержащим исходный код Java и документационные комментарии Javadoc.

Вместо этого Javadoc будет преобразован в комментарии XML-документации C# в созданном исходном коде биндинга.

$(AndroidJavadocVerbosity) определяет, насколько "подробным" или "полным" будет импортированный Javadoc.

Поддерживаются следующие метаданные MSBuild:

  • %(CopyrightFile): путь к файлу, содержащему сведения об авторских правах для содержимого Javadoc, которое будет добавлено ко всей импортированной документации.

  • %(UrlPrefix): префикс URL-адреса для поддержки ссылки на интерактивную документацию в импортированной документации.

  • %(UrlStyle): стиль URL-адресов, создаваемых при связывании с интерактивной документацией. В настоящее время поддерживается только один стиль: developer.android.com/reference@2020-Nov.

  • %(DocRootUrl): префикс URL-адреса, используемый вместо всех экземпляров {@docroot} в экспортированной документации.

LibraryProjectZip

Действие сборки LibraryProjectZip привязывает библиотеку Java/Kotlin и внедряет файл .zip или .aar в библиотеку. Когда проект приложения .NET для Android использует библиотеку, он будет иметь доступ к API Java/Kotlin из C# и включить код Java/Kotlin в окончательное приложение Android.

Описание ссылки

Файлы с типом действия сборки LinkDescription используются для управления поведением компоновщика.

ProguardConfiguration

Файлы с действием сборки ProguardConfiguration содержат параметры, которые используются для управления поведением proguard. Дополнительные сведения об этом действии см. в разделе ProGuard.

Эти файлы игнорируются, если свойство MSBuild не установлено. $(EnableProguard) Свойство MSBuild имеет значение True.

  • Last updated on