با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
یک پروژه را برای استفاده از برنامه افزودنی توسعه بازی اندروید پیکربندی کنید.
برنامه افزودنی توسعه بازی Android از MSBuild فراخوانی می کند تا کد منبع C/C++ را در کتابخانه های مشترک ( .so ) و کتابخانه های ثابت ( .a ) بسازد. به عنوان بخشی از فرآیند ساخت، یک کار سفارشی MSBuild از Gradle برای کامپایل کد منبع جاوا و Kotlin، دارایی‌های بسته و ایجاد یک فایل APK برای استقرار فراخوانی می‌کند. هنگامی که پروژه خود را پیکربندی می کنید، باید اطمینان حاصل کنید که MSBuild اطلاعات لازم برای ساختن برای پلتفرم اندروید را دارد.
ساخت C/C++ با MSBuild
یک پروژه معمولی اندروید با Gradle ساخته می‌شود، جایی که کد بومی داخل پروژه توسط یک پاس Gradle ساخته می‌شود که CMake یا ndk-build را اجرا می‌کند. با افزونه توسعه بازی اندروید برای ویژوال استودیو، روند ساخت معکوس شده است. اکنون MSBuild نقطه شروع فرآیند ساخت است. تمام کد منبع C/C++ ابتدا توسط MSBuild برای پلتفرم‌های اندروید جدید نصب شده روی سیستم شما به عنوان بخشی از برنامه افزودنی ساخته شده است (به عنوان مثال، "Android-x86_64"). سپس MSBuild از Gradle فراخوانی می‌کند تا فایل‌های کتابخانه مشترک که حاوی منطق C/C++ شما هستند را در یک APK بسته بندی کند.
ابتدا باید منطق ساخت موجود پروژه خود را در CMake یا ndk-build در MSBuild تکرار کنید. پلتفرم های هدف را به صورت زیر تنظیم کنید:
Android-x86
Android-x86_64
Android-armeabi-v7a
Android-arm64-v8a
این پلتفرم ها همگی توسط افزونه توسعه بازی اندروید ارائه شده اند.
گزینه های کامپایل و پیوند خود را تنظیم کنید
AGDE از NDK انتخابی شما برای تعیین گزینه های پیش فرض کامپایل و پیوند هنگام ساخت بخش C/C++ برنامه شما استفاده می کند.
اگر نیاز به شخصی سازی این گزینه های کامپایل یا پیوند دارید، می توانید آنها را با استفاده از Project Properties تنظیم کنید. می توانید رایج ترین گزینه ها را در گروه های C/C++ (برای کامپایل)، Librarian (برای بایگانی کتابخانه ایستا) و Linker (برای پیوند کتابخانه های پویا) پیدا کنید. اگر نیاز به پاس کردن هر گزینه سفارشی دیگری دارید، می توانید آنها را به بخش Command Line اضافه کنید. برای مثال، اگر از NDK قدیمی‌تر از r28 استفاده می‌کنید، ممکن است بخواهید پرچم پیوند دهنده را تنظیم کنید تا برنامه شما از اندازه صفحه 16 کیلوبایت پشتیبانی کند .
یک پلتفرم اندروید اضافه کنید
در حالی که پروژه نمونه قوری شامل پلتفرم های اندروید است، شما باید به صورت دستی یک پلتفرم اندروید را به پروژه موجود اضافه کنید. برای افزودن پلتفرم جدید، در ویژوال استودیو مراحل زیر را انجام دهید:
Build > Configuration Manager را انتخاب کنید.
در زیر پلت فرم راه حل فعال ، <جدید> را انتخاب کنید.
یکی از موارد زیر را برای پلتفرم جدید تایپ کنید:
Android-armeabi-v7a
Android-arm64-v8a
Android-x86
Android-x86_64
در کادر کپی تنظیمات از ، پلتفرم اندروید موجود دیگری را انتخاب کنید یا اگر هنوز هیچ پلتفرم اندرویدی ندارید <Empty> را انتخاب کنید. مطمئن شوید که ایجاد پلتفرم های پروژه جدید را فعال کرده اید.
یک مورد Android APK اضافه کنید
Add > New Item > Visual C++ > Android > Android APK را انتخاب کنید و روی Add کلیک کنید. برنامه اندروید را در گفتگوی زیر پیکربندی کنید.
نام برنامه : نام قابل خواندن برای انسان برنامه اندروید شما.
Solution Explorer Location : محل پوشه مجازی که حاوی فایل های پشتیبانی بسته بندی اندروید اضافه شده است. به طور پیش فرض، این فایل ها نیز در پروژه در پوشه ای با همین نام قرار دارند. می‌توانید با انتخاب کادر تأیید قرار دادن فایل‌های پشتیبانی در مکان سفارشی و تعیین یک مکان سفارشی، مکان را سفارشی کنید. پوشه مجازی همچنان تحت پروژه فعلی در Solution Explorer خواهد بود.
MSBuild را برای ساختن APK به Gradle فراخوانی کنید
MSBuild نمی تواند Gradle را فراخوانی کند مگر اینکه مکان پروژه Gradle را بداند. همانطور که در شکل 1 نشان داده شده است، این مکان را با استفاده از ویژگی Gradle Build Directory تنظیم کنید.
شکل 1 . ویژگی Gradle Build Directory
علاوه بر این، ویژگی‌های Application Module ، Application Variant و APK Name (همانطور که در تصویر قبلی نشان داده شده است) را تنظیم کنید تا MSBuild بداند چه چیزی را بسازد.
ماژول کاربردی : نام زیر پروژه Gradle. این پروژه اصلی تنظیم شده در فایل settings.gradle است. معمولاً به آن app برای پروژه هایی گفته می شود که مستقیماً با استفاده از Android Studio ایجاد می شوند.
Application Variant : نوع اندرویدی که باید ساخته شود. این مقدار باید بر اساس تنظیمات MSBuild تنظیم شود. به عنوان مثال، یک ساخت اشکال زدایی باید مقداری برای نوع اشکال زدایی داشته باشد. اگر نام پیکربندی MSBuild پروژه شما با نام انواع Gradle مطابقت دارد، کافیست از مقدار پیش فرض $(Configuration) استفاده کنید.
نام APK : نام فایل APK تولید شده که برای اشکال زدایی و نمایه سازی در رایانه برنامه نویسی شما استفاده می شود. این نام به Gradle منتقل شده است و اسکریپت ساخت Gradle شما باید به آن احترام بگذارد (ویژگی MSBUILD_ANDROID_OUTPUT_APK_NAME در بخش زیر ببینید).
اسکریپت های ساخت Gradle خود را تغییر دهید
در طول ساخت، MSBuild اطلاعات زیر را به عنوان ویژگی های پروژه به اسکریپت Gradle ارسال می کند. اسکریپت های ساخت موجود پروژه خود را (که معمولاً build.gradle نام دارند) را برای خواندن این ویژگی ها تغییر دهید.
MSBUILD_MIN_SDK_VERSION : حداقل نسخه SDK برای ساختن APK به صورت رشته ای. این مقدار را در کادر Minimum Android SDK Version در صفحه ویژگی پروژه نشان داده شده در شکل 2 تنظیم کنید.
شکل 2 . حداقل ویژگی نسخه SDK Android
اسکریپت ساخت Gradle باید minSdkVersion یا minSdk روی این مقدار رشته تنظیم کند و در صورت لزوم یک تبدیل نوع toInteger() داشته باشد.
MSBUILD_ANDROID_OUTPUT_APK_NAME : نام مورد انتظار APK که Gradle می‌سازد. برنامه افزودنی توسعه بازی اندروید به دنبال APK منطبق با این نام می گردد و سپس آن را در دستگاه های متصل (برای اشکال زدایی و نمایه سازی) مستقر می کند. این مقدار را در کادر APK Name در صفحه ویژگی پروژه نشان داده شده در شکل 3 تنظیم کنید.
شکل 3 . ویژگی نام APK
اسکریپت ساخت Gradle باید به این ویژگی احترام بگذارد. به عنوان مثال، مثال زیر نام APK خروجی را برای همه انواع به نام انتخاب شده توسط MSBuild تنظیم می کند.
MSBUILD_JNI_LIBS_SRC_DIR : دایرکتوری حاوی کتابخانه های مشترک (فایل های .so ) ساخته شده توسط MSBuild. این مقدار را در کادر Output Directory در صفحه ویژگی پروژه نشان داده شده در زیر تنظیم کنید. به طور پیش فرض، همانطور که در شکل 4 نشان داده شده است، این مقدار ویژگی دایرکتوری خروجی برای پروژه ویژوال استودیو است.
شکل 4 . ویژگی Output Directory
Gradle باید فایل های کتابخانه اشتراکی را در این پوشه در داخل APK بسته بندی کند تا برنامه اندروید آنها را در زمان اجرا بارگیری کند.
علاوه بر این، از آنجایی که هر کد C/C++ اکنون توسط MSBuild ساخته شده است، بخش های externalNativeBuild را در اسکریپت های ساخت Gradle خود حذف کنید. این بخش‌ها برای فراخوانی CMake یا ndk-build برای کامپایل کد C/C++ شما استفاده می‌شوند، اما دیگر مورد نیاز نیستند.
MSBUILD_NDK_VERSION : نسخه ای از NDK که برای ساخت پروژه خود استفاده می کنید. این مقدار را در کادر Android NDK Version در صفحه ویژگی پروژه نشان داده شده در شکل 5 تنظیم کنید.
شکل 5 . ویژگی Android NDK Version
اسکریپت ساخت Gradle باید ndkVersion روی این مقدار تنظیم کند، همانطور که نشان داده شده است:
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Configure a project to use the Android Game Development Extension.\n\nThe Android Game Development Extension invokes MSBuild to build C/C++ source code into shared\nlibraries (`.so`) and static libraries (`.a`). As part of the build process, a\ncustom MSBuild task invokes Gradle to compile Java and Kotlin source code,\npackage assets, and generate an APK file for deployment. When you configure your\nproject, you must ensure that MSBuild has the information it needs to build for\nthe Android platform.\n\nBuild C/C++ with MSBuild\n------------------------\n\nA typical Android project is built with Gradle, where the native code inside the\nproject is built by a Gradle pass that runs either [CMake](/ndk/guides/cmake) or\n[ndk-build](/ndk/guides/ndk-build). With the Android Game Development Extension for Visual\nStudio, the build process is inverted. Now MSBuild is the starting point of the\nbuild process. All C/C++ source code is built first by MSBuild for the new\nAndroid platforms installed on your system as part of the extension (for\nexample, \"Android-x86_64\"). MSBuild then invokes Gradle to package the shared\nlibrary files that contain your C/C++ logic into an APK.\n\nYou should first replicate your project's existing build logic in CMake or\nndk-build in MSBuild. Set the target platforms to the following:\n\n- Android-x86\n- Android-x86_64\n- Android-armeabi-v7a\n- Android-arm64-v8a\n\nThese platforms are all provided by the Android Game Development Extension.\n\n### Set your compile and link options\n\nAGDE uses the NDK you select to determine the default compile and link options\nwhen building the C/C++ part of your app.\n\nIf you need to customize these compile or link options, you can set them using\nProject Properties. You can find the most common options in the C/C++\n(for compilation), Librarian (for static library archiving) and Linker (for\ndynamic library linking) groups. If you need to pass any other custom\noptions, you can add them to the Command Line section. For example,\nif you are using an NDK older than r28, you might want to set the linker flag\nto make your app [support 16 KB page sizes](/guide/practices/page-sizes#compile-16-kb-alignment).\n\n### Add an Android Platform\n\nWhile the teapot sample project includes Android platforms, you must manually\nadd an Android platform to an existing project. To add a new platform, do the\nfollowing in Visual Studio:\n\n1. Select **Build \\\u003e Configuration Manager**.\n2. Under **Active solution platform** , select **\\\u003cNew\\\u003e**.\n3. Type one of the following for the new platform:\n\n - **Android-armeabi-v7a**\n - **Android-arm64-v8a**\n - **Android-x86**\n - **Android-x86_64**\n4. In the **Copy settings from** box, select another existing Android\n platform, or **\\\u003cEmpty\\\u003e** if you do not have any Android platforms yet.\n Make sure you enabled **Create new project platforms**.\n\n### Add an Android APK item\n\nSelect **Add \\\u003e New Item \\\u003e Visual C++ \\\u003e Android \\\u003e Android APK** and click\n**Add**. Configure the Android application on the following dialog.\n\n- **Application Name**: The human-readable name of your Android application.\n- **Application ID** : The [unique identifier](/studio/build/configure-app-module#set_the_application_id) for your Android application.\n- **Solution Explorer Location** : Location of the virtual folder that contains the added Android packaging support files. By default, these files are also located in the project in a folder with the same name. You can customize the location by selecting the **Put support files in a custom location** checkbox and specifying a custom location. The virtual folder will still be under the current project in the Solution Explorer.\n\nMake MSBuild invoke Gradle to build an APK\n------------------------------------------\n\nMSBuild cannot invoke Gradle unless it knows the location of the Gradle project.\nSet this location using the **Gradle Build Directory** property, as\nshown in figure 1.\n\n\u003cbr /\u003e\n\n\n**Figure 1** . **Gradle Build Directory** property\n\nIn addition, set the **Application Module** , **Application Variant** , and **APK\nName** properties (as shown in the previous image) in order for MSBuild to know\nwhat to build.\n\n- **Application Module** : The name of the Gradle subproject. This is the main project set in the `settings.gradle` file. It is usually called `app` for projects directly created using Android Studio.\n- **Application Variant** : The Android variant to build. This value should be set according to the MSBuild configurations. For example, a debug build should have a value set to the debug variant. If your project's MSBuild configuration name matches the Gradle variant names, then just use the default value of `$(Configuration)`.\n- **APK Name** : The name of the generated APK file used for debugging and profiling on your development computer. This name is passed to Gradle and your Gradle build script should respect this (see the property `MSBUILD_ANDROID_OUTPUT_APK_NAME` in the following section).\n\n### Modify your Gradle build scripts\n\nDuring the build, MSBuild passes the following information as project properties\nto the Gradle script. Change your project's existing build scripts (typically\nnamed `build.gradle`) to read these properties.\n\n- `MSBUILD_MIN_SDK_VERSION`: The minimum SDK version for building the APK, as a\n string. Set this value in the **Minimum Android SDK Version** box on the\n project property page shown in figure 2.\n\n \u003cbr /\u003e\n\n\n **Figure 2** . **Minimum Android SDK Version** property\n\n The Gradle build script should set `minSdkVersion` or `minSdk` to this\n string value, with a `toInteger()` type conversion when necessary. \n\n ### Groovy\n\n ```groovy\n android {\n // ...\n\n defaultConfig {\n applicationId \"com.yourcompany.yourapp\"\n minSdkVersion MSBUILD_MIN_SDK_VERSION\n // Or: minSdk MSBUILD_MIN_SDK_VERSION.toInteger()\n // ...\n }\n\n // ...\n }\n ```\n\n ### Kotlin\n\n ```kotlin\n android {\n // ...\n\n defaultConfig {\n applicationId = \"com.yourcompany.yourapp\"\n minSdkVersion(MSBUILD_MIN_SDK_VERSION)\n // Or: minSdk = MSBUILD_MIN_SDK_VERSION.toInteger()\n // ...\n }\n\n // ...\n }\n ```\n- `MSBUILD_ANDROID_OUTPUT_APK_NAME`: The expected name of the APK that Gradle\n builds. The Android Game Development Extension will look for an APK matching this name and\n then deploy it to connected devices (for debugging and profiling). Set this\n value in the **APK Name** box on the project property page shown in figure 3.\n\n \u003cbr /\u003e\n\n\n **Figure 3** . **APK Name** property\n\n The Gradle build script must respect this property. For example, the\n following example sets the output APK name for all variants to the name\n chosen by MSBuild. \n\n ### Groovy\n\n ```groovy\n android {\n // ...\n\n applicationVariants.all { variant -\u003e\n variant.outputs.all {\n outputFileName = MSBUILD_ANDROID_OUTPUT_APK_NAME\n }\n }\n\n // ...\n }\n ```\n\n ### Kotlin\n\n ```kotlin\n android {\n // ...\n\n applicationVariants.all { variant -\u003e\n variant.outputs.all {\n outputFileName = MSBUILD_ANDROID_OUTPUT_APK_NAME\n }\n }\n\n // ...\n }\n ```\n- `MSBUILD_JNI_LIBS_SRC_DIR`: The directory containing the shared libraries\n (`.so` files) built by MSBuild. Set this value in the **Output Directory**\n box on the project property page shown below. By default, this value is the\n output directory property for the Visual Studio project, as shown in figure 4.\n\n \u003cbr /\u003e\n\n\n **Figure 4** . **Output Directory** property\n\n Gradle should package the shared library files in this folder inside the APK\n in order for the Android application to load them at runtime. \n\n ### Groovy\n\n ```groovy\n android {\n // ...\n\n sourceSets {\n main {\n jniLibs.srcDirs += [MSBUILD_JNI_LIBS_SRC_DIR]\n }\n }\n\n // ...\n }\n ```\n\n ### Kotlin\n\n ```kotlin\n android {\n // ...\n\n sourceSets.getByName(\"main\") {\n jniLibs.srcDir(MSBUILD_JNI_LIBS_SRC_DIR)\n }\n\n // ...\n }\n ```\n\n In addition, since any C/C++ code is now built by MSBuild, remove the\n `externalNativeBuild` sections in your Gradle build scripts. These sections\n were used to invoke CMake or ndk-build to compile your C/C++ code, but are\n no longer needed.\n- `MSBUILD_NDK_VERSION`: The version of the NDK to use to build your\n project. Set this value in the **Android NDK Version** box on the\n project property page shown in figure 5.\n\n \u003cbr /\u003e\n\n\n **Figure 5** . **Android NDK Version** property\n\n The Gradle build script should set `ndkVersion` to this value, as shown: \n\n ### Groovy\n\n ```groovy\n android {\n // ...\n\n ndkVersion MSBUILD_NDK_VERSION\n\n // ...\n }\n ```\n\n ### Kotlin\n\n ```kotlin\n android {\n // ...\n\n ndkVersion = MSBUILD_NDK_VERSION\n\n // ...\n }\n ```\n\n For more information, see the Android Studio topic\n [Install and configure the NDK and CMake](/studio/projects/install-ndk)."]]
