Как работают SDK и API

SDK и API – это инструменты, которые позволяют интегрировать ИТ-продукты с внешними системами. В этой статье мы расскажем, чем отличаются эти два понятия и как разработчики применяют их для своих задач.

Начнём с определений.

API (application programming interface, программный интерфейс приложения) – это набор протоколов и инструментов, которые обеспечивают обмен данными между разными компонентами информационных систем.

Благодаря API мобильные приложения могут легко использовать «Яндекс.Карты» или «Календарь» от Google – обе корпорации предоставляют сторонним разработчикам готовые инструменты, чтобы встраивать эти модули в новые продукты. Это именно интерфейс для подключения к внешней инфраструктуре (в нашем примере – к сервисам Яндекса и Google), который позволяет решать прикладные задачи набором HTTP-запросов.

SDK (software development kit, средства для разработки ПО) решает более масштабную задачу: не просто обеспечить обмен данными между приложением и сторонней инфраструктурой, а реализовать полноценный процесс. Он может включать в себя рабочие компоненты для получения пользовательских данных, их безопасной обработки и хранения, изменения состояний.

В SDK могут входить несколько API, куски вспомогательного кода, обширная документация. Это не просто интерфейс для работы с системой, а готовый набор инструментов для реализации некой бизнес-логики.

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

Попросту говоря, если API – это рецепт блюда, то SDK – это рецепт, нарезанные продукты, чётко отмеренные специи и набор всех кастрюль-сковородок, которые вам понадобятся в готовке.

В любом нашем продукте используются API заказчиков, чтобы получать данные из клиентской инфраструктуры.

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

Это прикладные задачи «местного значения», которые не включают в себя сложную бизнес-логику. Поэтому они решаются посредством API.

Пример, когда возникла необходимость в SDK – это проект по созданию единого модуля для оформления ДТП для страховых приложений. Этот сложный сценарий объединяет авторизацию через ЕСИА, регистрацию происшествия с оформлением европротокола, обмен данными с СТ-ГЛОНАСС АИС ОСАГО, ГИБДД и другими компетентными органами.

Используя SDK, мы можем заключить всю сложную логику в готовый к использованию набор, который затем можно встраивать в любые приложения. Такой модуль включает в себя API для работы с ЕСИА и системами Российского союза автостраховщиков, средства защиты и проверки данных, компоненты для работы с камерой.

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

Пакеты SDK для проектов .NET .NET project SDKs

Проекты .NET Core и NET 5.0 и более поздних версий связаны с пакетом средств разработки программного обеспечения (SDK). .NET Core and .NET 5.0 and later projects are associated with a software development kit (SDK). Каждый пакет SDK для проекта является набором целевых объектов MSBuild и связанных задач, которые отвечают за компиляцию, упаковку и публикацию кода. Each project SDK is a set of MSBuild targets and associated tasks that are responsible for compiling, packing, and publishing code. Проект, который ссылается на пакет SDK для проекта, иногда называется проектом в стиле пакета SDK. A project that references a project SDK is sometimes referred to as an SDK-style project.

Доступные пакеты SDK Available SDKs

Доступны следующие пакеты SDK: The following SDKs are available:

ID ID	Описание Description	Репозиторий Repo
Microsoft.NET.Sdk	Пакет SDK для .NET The .NET SDK	https://github.com/dotnet/sdk
Microsoft.NET.Sdk.Web	Веб-пакет SDK для .NET The .NET Web SDK	https://github.com/dotnet/sdk
Microsoft.NET.Sdk.Razor	Пакет SDK Razor для .NET The .NET Razor SDK
Microsoft.NET.Sdk.Worker	Пакет SDK для службы рабочей роли в .NET The .NET Worker Service SDK
Microsoft.NET.Sdk.WindowsDesktop	Пакет SDK для настольных систем в .NET, который включает Windows Forms (WinForms) и Windows Presentation Foundation (WPF).* The .NET Desktop SDK, which includes Windows Forms (WinForms) and Windows Presentation Foundation (WPF).*	https://github.com/dotnet/winforms и https://github.com/dotnet/wpf https://github.com/dotnet/winforms and https://github.com/dotnet/wpf

Пакет SDK для .NET является базовым пакетом SDK для .NET. The .NET SDK is the base SDK for .NET. Другие пакеты SDK ссылаются на пакет SDK для .NET, а проекты, связанные с другими пакетами SDK, имеют все доступные им свойства пакета SDK для .NET. The other SDKs reference the .NET SDK, and projects that are associated with the other SDKs have all the .NET SDK properties available to them. Например, веб-пакет SDK зависит от пакета SDK для .NET и пакета SDK для Razor. The Web SDK, for example, depends on both the .NET SDK and the Razor SDK.

Можно также создать собственный пакет SDK и распространять его с помощью NuGet. You can also author your own SDK that can be distributed via NuGet.

* Начиная с .NET 5.0, в проектах Windows Forms и Windows Presentation Foundation (WPF) необходимо указывать пакет SDK для .NET ( Microsoft.NET.Sdk ), а не Microsoft.NET.Sdk.WindowsDesktop . * Starting in .NET 5.0, Windows Forms and Windows Presentation Foundation (WPF) projects should specify the .NET SDK ( Microsoft.NET.Sdk ) instead of Microsoft.NET.Sdk.WindowsDesktop . Если для параметра TargetFramework в таких проектах установить значение net5.0-windows , а для параметра UseWPF или UseWindowsForms — значение true , импорт пакета SDK для Windows Desktop будет выполняться автоматически. For these projects, setting TargetFramework to net5.0-windows and UseWPF or UseWindowsForms to true will automatically import the Windows desktop SDK. Если проект предназначен для .NET 5.0 или более поздней версии и в нем указан пакет SDK Microsoft.NET.Sdk.WindowsDesktop , при сборке отобразится предупреждение NETSDK1137. If your project targets .NET 5.0 or later and specifies the Microsoft.NET.Sdk.WindowsDesktop SDK, you’ll get build warning NETSDK1137.

Файлы проекта Project files

В основе проектов .NET лежит формат MSBuild. .NET projects are based on the MSBuild format. Файлы проекта с такими расширениями, как CPROJ для проектов C# и FPROJ для проектов F#, имеют формат XML. Project files, which have extensions like .csproj for C# projects and .fsproj for F# projects, are in XML format. Корневым элементом файла проекта MSBuild является элемент Project. The root element of an MSBuild project file is the Project element. Элемент Project имеет необязательный атрибут Sdk , указывающий, какой пакет SDK (и версию) следует использовать. The Project element has an optional Sdk attribute that specifies which SDK (and version) to use. Чтобы использовать средства .NET и выполнить сборку кода, задайте в качестве значения атрибута Sdk один из идентификаторов, указанных в таблицеДоступные пакеты SDK. To use the .NET tools and build your code, set the Sdk attribute to one of the IDs in the Available SDKs table.

Чтобы указать пакет SDK, который содержится в NuGet, добавьте версию в конец имени или укажите имя и версию в файле global.json. To specify an SDK that comes from NuGet, include the version at the end of the name, or specify the name and version in the global.json file.

Другим способом указания пакета SDK является элемент Sdk верхнего уровня. Another way to specify the SDK is with the top-level Sdk element:

Указание пакета SDK одним из этих способов значительно упрощает файлы проекта для .NET. Referencing an SDK in one of these ways greatly simplifies project files for .NET. На этапе оценки проекта MSBuild добавляет неявные директивы импорта для Sdk.props в начале и для Sdk.targets в конце файла проекта. While evaluating the project, MSBuild adds implicit imports for Sdk.props at the top of the project file and Sdk.targets at the bottom.

На компьютере Windows файлы Sdk.props и Sdk.targets можно найти в папке %ProgramFiles%\dotnet\sdk\[версия]\Sdks\Microsoft.NET.Sdk\Sdk. On a Windows machine, the Sdk.props and Sdk.targets files can be found in the %ProgramFiles%\dotnet\sdk\[version]\Sdks\Microsoft.NET.Sdk\Sdk folder.

Предварительная обработка файла проекта Preprocess the project file

Увидеть полностью развернутый проект так, как он отображается в MSBuild, можно после включения пакета SDK и его целевых объектов с помощью команды dotnet msbuild -preprocess . You can see the fully expanded project as MSBuild sees it after the SDK and its targets are included by using the dotnet msbuild -preprocess command. Включите параметр preprocess в команду dotnet msbuild , чтобы просмотреть сведения об импортированных файлах, их источниках, вкладе в сборку без фактического создания проекта. The preprocess switch of the dotnet msbuild command shows which files are imported, their sources, and their contributions to the build without actually building the project.

Если проект имеет несколько требуемых версий .NET Framework, результаты выполнения команды должны касаться только одной из них. Эту версию следует указать в качестве свойства MSBuild. If the project has multiple target frameworks, focus the results of the command on only one framework by specifying it as an MSBuild property. Пример: For example:

dotnet msbuild -property:TargetFramework=netcoreapp2.0 -preprocess:output.xml

Включения и исключения по умолчанию Default includes and excludes

В пакете SDK определены стандартные включения и исключения для элементов Compile , внедренных ресурсов и элементов None . The default includes and excludes for Compile items, embedded resources, and None items are defined in the SDK. В отличие от проектов .NET Framework без пакетов SDK в файле проекта не нужно указывать эти элементы, так как для наиболее распространенных вариантов использования действуют значения по умолчанию. Unlike non-SDK .NET Framework projects, you don’t need to specify these items in your project file, because the defaults cover most common use cases. Такой подход позволяет уменьшить файлы проекта и без труда понимать их, а при необходимости даже вносить правки вручную. This behavior makes the project file smaller and easier to understand and edit by hand, if needed.

В следующей таблице показано, какие элементы и стандартные маски включены в пакет SDK для .NET и исключены из него: The following table shows which elements and which globs are included and excluded in the .NET SDK:

Элемент Element	Стандартная маска включения Include glob	Стандартная маска исключения Exclude glob	Стандартная маска удаления Remove glob
Compile	**/*.cs (или другие расширения языка) **/*.cs (or other language extensions)	**/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.user; **/*.*proj; **/*.sln; **/*.vssscc	Н/Д N/A
EmbeddedResource	**/*.resx **/*.resx	**/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.user; **/*.*proj; **/*.sln; **/*.vssscc	Н/Д N/A
None	**/*	**/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.user; **/*.*proj; **/*.sln; **/*.vssscc	**/*.cs; **/*.resx **/*.cs; **/*.resx

Папки ./bin и ./obj , которые представлены свойствами MSBuild $(BaseOutputPath) и $(BaseIntermediateOutputPath) , исключаются из стандартных масок исключения по умолчанию. The ./bin and ./obj folders, which are represented by the $(BaseOutputPath) and $(BaseIntermediateOutputPath) MSBuild properties, are excluded from the globs by default. Исключения представлены свойством DefaultItemExcludes. Excludes are represented by the DefaultItemExcludes property.

Пакет SDK для настольных систем в .NET имеет больше включений и исключений для WPF. The .NET Desktop SDK has more includes and excludes for WPF. Дополнительные сведения см. в разделе Включения и исключения для WPF. For more information, see WPF default includes and excludes.

Ошибки сборки Build errors

Если вы явным образом определите любой из этих элементов в файле проекта, скорее всего, произойдет ошибка сборки NETSDK1022 с примерно таким сообщением: If you explicitly define any of these items in your project file, you’re likely to get a «NETSDK1022» build error similar to the following:

Duplicate ‘Compile’ items were included. Duplicate ‘Compile’ items were included. The .NET SDK includes ‘Compile’ items from your project directory by default. The .NET SDK includes ‘Compile’ items from your project directory by default. You can either remove these items from your project file, or set the ‘EnableDefaultCompileItems’ property to ‘false’ if you want to explicitly include them in your project file. (Включены повторяющиеся элементы Compile. По умолчанию пакет SDK для .NET включает элементы Compile из каталога проекта. Можно удалить эти элементы из файла проекта или задать для свойства EnableDefaultCompileItems значение false, чтобы явно включить их в файл проекта). You can either remove these items from your project file, or set the ‘EnableDefaultCompileItems’ property to ‘false’ if you want to explicitly include them in your project file.

Duplicate ‘EmbeddedResource’ items were included. Duplicate ‘EmbeddedResource’ items were included. The .NET SDK includes ‘EmbeddedResource’ items from your project directory by default. The .NET SDK includes ‘EmbeddedResource’ items from your project directory by default. You can either remove these items from your project file, or set the ‘EnableDefaultEmbeddedResourceItems’ property to ‘false’ if you want to explicitly include them in your project file. (Включены повторяющиеся элементы Compile. По умолчанию пакет SDK для .NET включает элементы Compile из каталога проекта. Можно удалить эти элементы из файла проекта или задать для свойства EnableDefaultCompileItems значение false, чтобы явно включить их в файл проекта). You can either remove these items from your project file, or set the ‘EnableDefaultEmbeddedResourceItems’ property to ‘false’ if you want to explicitly include them in your project file.

Чтобы устранить такую проблему, выполните любое из следующих действий: To resolve the errors, do one of the following:

Удалите явно заданные элементы Compile , EmbeddedResource или None , которые совпадают с неявно заданными параметрами из предыдущей таблицы. Remove the explicit Compile , EmbeddedResource , or None items that match the implicit ones listed on the previous table.

Присвойте свойству EnableDefaultItems значение false , чтобы отключить все неявные включения файлов: Set the EnableDefaultItems property to false to disable all implicit file inclusion:

Если вы хотите указать файлы, которые нужно публиковать вместе с приложением, для этого можно по-прежнему использовать привычные механизмы MSBuild (например, элемент Content ). If you want to specify files to be published with your app, you can still use the known MSBuild mechanisms for that, for example, the Content element.

Выборочно отключите только стандартные маски Compile , EmbeddedResource или None , присвоив свойствам EnableDefaultCompileItems, EnableDefaultEmbeddedResourceItems или EnableDefaultNoneItems значение false : Selectively disable only Compile , EmbeddedResource , or None globs by setting the EnableDefaultCompileItems, EnableDefaultEmbeddedResourceItems, or EnableDefaultNoneItems property to false :

Если вы отключите только стандартные маски Compile , обозреватель решений в Visual Studio будет по-прежнему отображать элементы *.cs в составе проекта, включая их в виде элементов None . If you only disable Compile globs, Solution Explorer in Visual Studio still shows *.cs items as part of the project, included as None items. Чтобы отключить неявную стандартную маску None , задайте свойству EnableDefaultNoneItems значение false . To disable the implicit None glob, set EnableDefaultNoneItems to false too.

Неявные ссылки на пакет Implicit package references

При использовании .NET Core 1.0–2.2 или .NET Standard 1.0–2.0 пакет SDK для .NET добавляет неявные ссылки на определенные метапакеты. When targeting .NET Core 1.0 — 2.2 or .NET Standard 1.0 — 2.0, the .NET SDK adds implicit references to certain metapackages. Метапакет — это пакет на основе платформы, который состоит только из зависимостей от других пакетов. A metapackage is a framework-based package that consists only of dependencies on other packages. Теперь неявные ссылки на метапакеты указываются в зависимости от целевой платформы, указанной в свойстве TargetFramework или TargetFrameworks файла проекта. Metapackages are implicitly referenced based on the target framework(s) specified in the TargetFramework or TargetFrameworks property of your project file.

При необходимости можно отключить неявные ссылки на пакеты с помощью свойства DisableImplicitFrameworkReferences и добавить явные ссылки только на необходимые платформы или пакеты. If needed, you can disable implicit package references using the DisableImplicitFrameworkReferences property, and add explicit references to just the frameworks or packages you need.

При использовании .NET Framework, .NET Core 1.0–2.2 или .NET Standard 1.0–2.0 не добавляйте явную ссылку на метапакеты Microsoft.NETCore.App или NETStandard.Library через элемент

в файле проекта. When targeting .NET Framework, .NET Core 1.0 — 2.2, or .NET Standard 1.0 — 2.0, don’t add an explicit reference to the Microsoft.NETCore.App or NETStandard.Library metapackages via a

item in your project file. Для проектов .NET Core 1.0–2.2 и .NET Standard 1.0–2.0 ссылка на эти метапакеты неявно присутствует. For .NET Core 1.0 — 2.2 and .NET Standard 1.0 — 2.0 projects, these metapackages are implicitly referenced. Если при использовании проектов .NET Framework и пакета NuGet на основе .NET Standard требуется любая версия NETStandard.Library , NuGet автоматически устанавливает ее. For .NET Framework projects, if any version of NETStandard.Library is needed when using a .NET Standard-based NuGet package, NuGet automatically installs that version.

Если при использовании .NET Core 1.0–2.2 нужна определенная версия среды выполнения, вместо ссылки на метапакет следует использовать свойство в проекте (например, 1.0.4 ). If you need a specific version of the runtime when targeting .NET Core 1.0 — 2.2, use the property in your project (for example, 1.0.4 ) instead of referencing the metapackage. Например, может потребоваться специальная версия LTS среды выполнения 1.0.0, если вы используете автономные развертывания. For example, you might need a specific patch version of 1.0.0 LTS runtime if you’re using self-contained deployments.

Если при использовании .NET Standard 1.0–2.0 вам нужна конкретная версия метапакета NETStandard.Library , можно использовать свойство и установить требуемую версию. If you need a specific version of the NETStandard.Library metapackage when targeting .NET Standard 1.0 — 2.0, you can use the property and set the version you need.

События сборки Build events

Для проектов в стиле пакета SDK используйте целевой объект MSBuild с именем PreBuild или PostBuild и задайте свойство BeforeTargets для PreBuild или свойство AfterTargets для PostBuild . In SDK-style projects, use an MSBuild target named PreBuild or PostBuild and set the BeforeTargets property for PreBuild or the AfterTargets property for PostBuild .

• Для целевых объектов MSBuild можно использовать любые имена. You can use any name for the MSBuild targets. Однако интегрированная среда разработки Visual Studio распознает целевые объекты PreBuild и PostBuild , поэтому с помощью этих имен можно изменять команды в интегрированной среде разработки. However, the Visual Studio IDE recognizes PreBuild and PostBuild targets, so by using those names, you can edit the commands in the IDE.
• Свойства PreBuildEvent и PostBuildEvent не рекомендуется использовать в проектах в стиле пакета SDK, поскольку такие макросы, как $(ProjectDir) , не разрешены. The properties PreBuildEvent and PostBuildEvent are not recommended in SDK-style projects, because macros such as $(ProjectDir) aren’t resolved. Например, приведенный ниже код не поддерживается. For example, the following code is not supported:

Настройка сборки Customize the build

Существует несколько способов настройки сборки. There are various ways to customize a build. Может потребоваться переопределить свойство, передав его в качестве аргумента в команду msbuild или dotnet. You may want to override a property by passing it as an argument to an msbuild or dotnet command. Можно также добавить свойство в файл проекта или в файл Directory.Build.props. You can also add the property to the project file or to a Directory.Build.props file. Список полезных свойств для проектов .NET см. в статье Справочник по MSBuild для проектов пакета SDK для .NET. For a list of useful properties for .NET projects, see MSBuild reference for .NET SDK projects.

Пользовательские целевые объекты Custom targets

В проектах .NET доступна возможность упаковки пользовательских целевых объектов MSBuild и свойств для использования в проектах, применяющих этот пакет. .NET projects can package custom MSBuild targets and properties for use by projects that consume the package. Используйте этот тип расширяемости, если нужно выполнить следующие задачи: Use this type of extensibility when you want to:

• расширить процесс сборки; Extend the build process.
• получить доступ к артефактам процесса сборки, таким как созданные файлы; Access artifacts of the build process, such as generated files.
• проверить конфигурацию, с которой была запущена сборка. Inspect the configuration under which the build is invoked.

Чтобы добавить пользовательские целевые объекты или свойства сборки, нужно поместить файлы в форме

.props (например, Contoso.Utility.UsefulStuff.targets ) в папку build проекта. You add custom build targets or properties by placing files in the form

.props (for example, Contoso.Utility.UsefulStuff.targets ) in the build folder of the project.

Следующий XML-код является фрагментом из файла CPROJ, который указывает команде dotnet pack , что именно нужно упаковать. The following XML is a snippet from a .csproj file that instructs the dotnet pack command what to package. Элемент помещает файлы целевых объектов в папку build в пакете. The element places the targets files into the build folder inside the package. Элемент помещает сборки и файлы JSON в папку build. The element places the assemblies and .json files into the build folder.

Чтобы использовать пользовательский целевой объект в проекте, добавьте элемент PackageReference , указывающий на пакет и его версию. To consume a custom target in your project, add a PackageReference element that points to the package and its version. В отличие от средств пакет пользовательских целевых объектов входит в замыкание зависимостей исходного проекта. Unlike the tools, the custom targets package is included in the consuming project’s dependency closure.

Вы можете настроить способ использования пользовательского целевого объекта. You can configure how to use the custom target. Так как это целевой объект MSBuild, он может зависеть от заданного целевого объекта, запускаться после другого целевого объекта или быть вызван вручную с помощью команды dotnet msbuild -t: . Since it’s an MSBuild target, it can depend on a given target, run after another target, or be manually invoked by using the dotnet msbuild -t: command. Однако для удобства пользователей можно объединить средства для отдельных проектов и пользовательские целевые объекты. However, to provide a better user experience, you can combine per-project tools and custom targets. В этом сценарии средство для отдельного проекта принимает необходимые параметры и преобразует их в требуемый вызов dotnet msbuild , который выполняет целевой объект. In this scenario, the per-project tool accepts whatever parameters are needed and translates that into the required dotnet msbuild invocation that executes the target. Пример подобного типа синергии можно увидеть в репозитории примеров хакатона MVP Summit 2016 в проекте dotnet-packer . You can see a sample of this kind of synergy on the MVP Summit 2016 Hackathon samples repo in the dotnet-packer project.