www.dntips.ir
مطالب	۳۶۹۴
نویسندگان	۲۷۶
گروه‌های مطالب	۱۰۲۴
نقشه‌های راه	۱۱۹
دوره‌ها	۱۴
اشتراک‌ها	۱۷۹۱۴

عنوان:

‫ساخت بسته‌های نیوگت مخصوص NET Core.

نویسنده: وحید نصیری
تاریخ: ۱۳۹۵/۰۶/۱۹ ۱۴:۱۵
آدرس: www.dntips.ir

فایل‌های nuspec مخصوص سایر نگارش‌های دات نت، در NET Core. ندید گرفته شده و پردازش نمی‌شوند. در اینجا نیز تمام تنظیمات تولید بسته‌های نیوگت، در فایل project.json درج می‌شوند که در ادامه آن‌ها را بررسی خواهیم کرد.

فعالسازی تولید خودکار بسته‌های نیوگت در پروژه‌های NET Core.

پس از تهیه‌ی یک کتابخانه‌ی مبتنی بر NET Core.، تنها کاری که در جهت تولید خودکار بسته‌های نیوگت باید انجام شود، افزودن مدخل postcompile ذیل به فایل project.json است:

    "scripts": {
        "postcompile": [
            "dotnet pack --no-build --configuration %compile:Configuration%"
        ]
    }

پس از آن هربار که پروژه کامپایل شود، به صورت خودکار فایل nupkg نهایی در پوشه‌ی bin\Release تشکیل می‌شود.
در این‌حالت اگر فایل nupkg تولیدی را توسط برنامه‌های zip باز کنید، مشاهده خواهید کرد که فایل nuspec خودکاری نیز در آن درج شده‌است؛ اما ... مشخصات ثبت شده‌ی در آن ناقص هستند و شامل مواردی مانند نام پروژه، نام نویسنده، مجوز استفاده‌ی از پروژه، آدرس پروژه و امثال آن‌ها نیستند. در نگارش‌های دیگر دات نت، این مشخصات از فایل nuspec تهیه شده‌ی توسط ما جمع آوری و درج می‌شود. اما در اینجا خیر.

تکمیل فایل project.json برای درج مشخصات پروژه و تکمیل اطلاعات فایل nuspec

هرچند به ظاهر دیگر فایل nuspec دستی تهیه شده در اینجا پردازش نمی‌شود، اما تمام اطلاعات آن‌را در فایل project.json نیز می‌توان درج کرد:

{
    "version": "1.1.1.0",
    "authors": [ "Vahid Nasiri" ],
    "packOptions": {
        "owners": [ "Vahid Nasiri" ],
        "tags": [ "PdfReport", "Excel", "Export", "iTextSharp", "PDF", "Report", "Reporting", "Persian", ".NET Core" ],
        "licenseUrl": "http://www.gnu.org/licenses/old-licenses/lgpl-2.0-standalone.html",
        "projectUrl": "https://github.com/VahidN/iTextSharp.LGPLv2.Core"
    },
    "description": " iTextSharp.LGPLv2.Core  is an unofficial port of the last LGPL version of the iTextSharp (V4.1.6) to .NET Core.",

    "scripts": {
        "postcompile": [
            "dotnet pack --no-build --configuration %compile:Configuration%"
        ]
    }
}

در اینجا یک نمونه از مشخصات فایل project.json ایی را مشاهده می‌کنید که در آن مواردی مانند نویسندگان، برچسب‌هایی که در سایت نیوگت لیست خواهند شد، آدرس مجوز پروژه، آدرس مخزن کد پروژه و توضیحات آن، تکمیل شده‌اند. قسمت postcompile، دقیقا همین اطلاعات را جهت تولید فایل خودکار nuspec نهایی، استفاده می‌کند.

تکمیل تنظیمات Build پروژه

بهتر است کتابخانه‌های خود را در حالت release و همچنین بهینه سازی شده، توزیع کنید. به همین منظور نیاز است مدخل ذیل را نیز به فایل project.json اضافه کرد:

    "configurations": {
        "Release": {
            "buildOptions": {
                "optimize": true,
                "platform": "anycpu"
            }
        }
    },

افزودن مستندات XML ایی کتابخانه

به احتمال زیاد XML-Docهای هر متد (کامنت‌های مخصوص دات نتی هر متد یا خاصیت عمومی) را نیز به کدهای خود افزوده‌اید. برای اینکه فایل XML نهایی آن به صورت خودکار تولید شده و همچنین در بسته‌ی نیوگت نهایی درج شود، نیاز است مدخل xmlDoc را به buildOptions اضافه کنید:

    "buildOptions": {
        "xmlDoc": true
    },

در این حالت هر عنصری با سطح دسترسی public، باید دارای کامنت باشد. اگر می‌خواهید مجبور به انجام اینکار نشوید و کامپایلر اخطار صادر نکند، می‌توانید از اخطار شماره‌ی 1591 صرفنظر کنید:

    "buildOptions": {
        "xmlDoc": true,
        "nowarn": [ "1591" ] // 1591: missing xml comment for publicly visible type or member
    },

برای مطالعه‌ی بیشتر
project.json reference

مطالب مشابه

مطالبقالبی خودکار برای تهیه‌ی بسته‌های نیوگت

مطالبارتقاء به ASP.NET Core 1.0 - قسمت 2 - بررسی ساختار جدید Solution

مطالببررسی روش ارتقاء به NET Core 1.1.

مطالببررسی تغییرات Reflection در NET Core.

مطالباستفاده از GitHub Actions برای Build و توزیع خودکار پروژه‌های NET Core.

مطالبتبدیل قالب‌های سفارشی پروژه‌های NET Core. به بسته‌های NuGet

نظرات مطالبساخت بسته‌های نیوگت مخصوص NET Core.

نظرات مطالبارتقاء به ASP.NET Core 1.0 - قسمت 2 - بررسی ساختار جدید Solution

نظرات مطالبساخت بسته‌های نیوگت مخصوص NET Core.

نظرات

وحید نصیری در ۱۳۹۵/۱۲/۰۸ ۱۳:۲۰
ساخت بسته‌ی نیوگت مخصوص NET Core. و همچنین NET 4.x. (در قالب یک فایل و یک بسته‌ی نیوگت)

نکته‌ی آن‌را در اینجا می‌توانید مطالعه کنید و خلاصه‌ی آن به صورت ذیل است:
```
    "frameworks": {
        "net40": {
            "frameworkAssemblies": {
            }
        },

        "net45": {
            "frameworkAssemblies": {
            }
        },

        "net46": {
            "frameworkAssemblies": {
            }
        },

        "netstandard1.3": {
            "imports": "dnxcore50",
            "dependencies": {
                "NETStandard.Library": "1.6.1",
                "System.Globalization.Extensions": "4.3.0",
                "System.Reflection": "4.3.0",
                "System.Reflection.TypeExtensions": "4.3.0"
            }
        }
    },
```
قسمت dependencies واقع در ریشه‌ی فایل project.json حذف شده و به ذیل قسمت netstandard انتقال پیدا می‌کند. همچنین به ازای فریم‌ورک‌های مختلف 4x مدنظر، یک مدخل مرتبط در قسمت frameworks اضافه می‌شود.
همین مقدار تغییر به همراه نکته‌ی scripts -> postcompile ابتدای بحث جاری، سبب خواهد شد تا کتابخانه‌ی جاری برای تمام فریم ورک‌های یاد شده به صورت مجزا کامپایل شده و درون بسته‌ی نیوگت نهایی قرار گیرد:

در این حالت ممکن است قسمتی از کدها مثلا برای دات نت 4 قابل استفاده نباشند و نیاز به تغییر داشته باشند. برای این حالت باید از if directives# جهت شرطی کردن کامپایلر کمک گرفت:
```
#if NET40
// This only compiles for the .NET Framework 4 targets
#else
// This compiles for all other targets
#endif
```

وحید نصیری در ۱۳۹۶/۰۱/۱۰ ۱۱:۹

به روز رسانی
با حذف فایل project.json در VS 2017، اکنون با کلیک راست بر روی گروه نام پروژه (فایل csproj)، گزینه‌ی Edit آن ظاهر شده و مداخل ذکر شده‌ی در مطلب فوق، چنین تعاریفی را پیدا می‌کنند:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <Description>desc.</Description>
    <VersionPrefix>1.0.0</VersionPrefix>
    <Authors>name</Authors>
    <TargetFramework>netstandard1.6</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <AssemblyName>name</AssemblyName>
    <PackageId>name</PackageId>
    <PackageTags>MVC;aspnetcore</PackageTags>
    <PackageProjectUrl>https://github.com/proj</PackageProjectUrl>
    <PackageLicenseUrl>https://github.com/proj/blob/master/LICENSE.md</PackageLicenseUrl>
    <PackageTargetFallback>$(PackageTargetFallback);dnxcore50</PackageTargetFallback>
    <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
    <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
    <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Core" Version="1.1.2" />
  </ItemGroup>
  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
    <PlatformTarget>anycpu</PlatformTarget>
  </PropertyGroup>
  <Target Name="PostcompileScript" AfterTargets="Build">
    <Exec Command="dotnet pack --no-build --configuration $(Configuration)" />
  </Target>
</Project>

برای تولید مستندات و کنترل اخطارهای آن:

  <PropertyGroup>
    <NoWarn>$(NoWarn);1591</NoWarn>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

و اگر خواستید دات نت 4.6 یا فریم ورک‌های دیگر را نیز پشتیبانی کنید، ItemGroupهای آن‌ها به این صورت اضافه می‌شوند:

  <PropertyGroup>
    <TargetFrameworks>net46;netstandard1.3</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup Condition=" '$(TargetFramework)' == 'net46' ">
    <Reference Include="System" />
    <Reference Include="System.Core" />
  </ItemGroup>

  <ItemGroup Condition=" '$(TargetFramework)' == 'netstandard1.3' ">
    <PackageReference Include="System.Data.Common" Version="4.3.0" />
  </ItemGroup>

وحید نصیری در ۱۳۹۶/۰۸/۲۱ ۱۰:۲۱
یک نکته‌ی تکمیلی: چگونه فایل README.txt را به بسته‌های نیوگت NET Core. اضافه کنیم؟

Visual Studio اگر فایل README.txt را در پوشه‌ی ریشه‌ی یک بسته‌ی نیوگت پیدا کند، پس از نصب بسته، به صورت خودکار آن‌را نمایش می‌دهد. بنابراین با استفاده از این فایل ویژه می‌توان نکات جدید مرتبط با بسته‌ی نیوگت، راهنما و یا مثال‌هایی را به استفاده کننده نمایش داد. اما در پروژه‌های NET Core.، چگونه می‌توان این فایل را در زمان فراخوانی دستور dotnet pack، به بسته‌ی نهایی تولید شده اضافه کرد؟
```
<Project>
  …
  <ItemGroup>
    <Content Include="README.txt">
      <Pack>true</Pack>
      <PackagePath>README.txt</PackagePath>
    </Content>
  </ItemGroup>
  …
</Project>
```
در اینجا تغییرات لازم فایل csproj را جهت الحاق فایل README.txt مشاهده می‌کنید.
Include به مسیر فایل الحاق شده اشاره می‌کند. این مسیر نسبت به ریشه‌ی پروژه‌ی جاری محاسبه می‌شود.
Pack الحاق و یا عدم الحاق فایل را تنظیم می‌کند.
PackagePath به مسیر نهایی این فایل در بسته‌ی نیوگت اشاره می‌کند و نسبت به ریشه‌ی آن درنظر گرفته خواهد شد.
وحید نصیری در ۱۳۹۶/۰۸/۲۱ ۱۱:۱۲
یک نکته‌ی تکمیلی: تولید خودکار بسته‌ی نیوگت پس از Build

در فایل‌‌های csproj بجای ذکر post build event زیر:
```
<Target Name="PostcompileScript" AfterTargets="Build">
    <Exec Command="dotnet pack --no-build --configuration $(Configuration)" />
</Target>
```
می‌توان خاصیت GeneratePackageOnBuild را true کرد:
```
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp1.1</TargetFramework>
    <Version>1.1.1</Version>
    <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
  </PropertyGroup>
</Project>
```
و یا اگر ترجیح می‌دهید آن‌را توسط NET Core CLI. به صورت مجزا و در زمان مناسبی انجام دهید، دستور نهایی آن به صورت ذیل است:
```
dotnet pack -c release
```
وحید نصیری در ۱۳۹۸/۰۱/۳۰ ۱۸:۵۲

یک نکته‌ی تکمیلی

اگر قصد تولید بسته‌ی نیوگتی را دارید و این بسته برای NET Standard 2.0. تهیه شده‌است، نیوگت اجازه می‌دهد تا این بسته توسط پروژه‌های دات نت فریم ورک 4.6.1 به بعد هم استفاده شود که نباید اینگونه باشد و باید به 4.7.2 یا بیشتر محدود شود.

روش بررسی و تعیین اعتبار فریم ورک مورد استفاده