Skip to content

yardarm-sdk.md

Latest commit

 

History

History
178 lines (132 loc) · 5.79 KB

yardarm-sdk.md

File metadata and controls

178 lines (132 loc) · 5.79 KB

Yardarm SDK

The Yardarm SDK is designed to easily integrate SDK generation into your MSBuild pipeline. It provides a familiar .csproj style for defining SDK projects which are then built and managed much like any other C# project.

Features

  • Incremental builds
  • Target one or more frameworks
  • Extension points for dynamically downloading OpenAPI specifications
  • Configure Yardarm extensions
  • Automatic NuGet package references
  • Include the project in Visual Studio solutions
  • Reference the project as a PackageReference from other .NET projects
  • dotnet restore, dotnet build, and dotnet pack support

Example Project

Create the below as a .csproj file and include a .yaml or .json OpenAPI specification file in the same directory.

<Project Sdk="Yardarm.Sdk/0.6.1">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <!--
    Any ".json", ".yaml", or ".yml" file in the same directory is assumed to be the OpenAPI Spec.
    However, if the file is located elsewhere it may be referenced manually.
  -->
  <ItemGroup>
    <OpenApiSpec Include="../my-spec.yaml" />
  </ItemGroup>

</Project>

Multi-targeting

<Project Sdk="Yardarm.Sdk/0.6.1">

  <PropertyGroup>
    <!-- Note that Yardarm doesn't support net4x targets, except via netstandard2.0 -->
    <TargetFrameworks>netstandard2.0;net6.0</TargetFrameworks>
  </PropertyGroup>

</Project>

Yardarm Extensions

<Project Sdk="Yardarm.Sdk/0.6.1">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>

    <JsonMode>Newtonsoft.Json</JsonMode> <!-- Use Newtonsoft.Json instead of the default System.Text.Json. Set to "None" to disable JSON support. -->
    <DependencyInjectionMode>None</DependencyInjectionMode> <!-- Disable the default Microsoft.Extensions.Http DI extension -->
  </PropertyGroup>

  <ItemGroup>
    <!-- Add one or more other extensions -->
    <YardarmExtension Include="Path/To/My/Extension.dll" />
  </ItemGroup>

</Project>

Project Properties

A wide variety of C# project properties are supported as well. These may also be passed as parameters to a command-line build, i.e. dotnet build /p:Version=5.6.7.

<Project Sdk="Yardarm.Sdk/0.6.1">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>

    <AssemblyName>SomeOtherAssemblyName</AssemblyName>
    <RootNamespace>Some.Other.Namespace</RootNamespace>
    <Version>5.6.7</Version>
    <EmbedAllSources>false</EmbedAllSources> <!-- Defaults to true -->
    <IncludeSymbols>false</IncludeSymbols> <!-- Defaults to true -->
    <GenerateDocumentationFile>false</GenerateDocumentationFile> <!-- Defaults to true -->
    <ProduceReferenceAssembly>true</ProduceReferenceAssembly> <!-- Default varies by target framework, follows C# defaults -->
    <KeyFile>Key.snk</KeyFile> <!-- Strong naming key -->

    <!-- All standard settings related to NuGet packaging apply -->
    <PackageId>ClassLibDotNetStandard</PackageId>
    <Authors>your_name</Authors>
    <Company>your_company</Company>
    <PackageTags>tag1;tag2</PackageTags>
    <Description>This is a long description</Description>

    <!--
      ** Properties to control the Yardarm SDK generation behaviors **
    -->

    <!-- May be "System.Text.Json" (default), "Newtonsoft.Json", or "None" -->
    <JsonMode>Newtonsoft.Json</JsonMode>

    <!-- May be "Microsoft.Extensions.Http" (default) or "None" -->
    <DependencyInjectionMode>None</DependencyInjectionMode>

    <!-- Available in 0.7.0, may be "System" (default), "Legacy", or "NodaTime" -->
    <DateTimeMode>NodaTime</DateTimeMode>

    <!-- Available in 0.7.0, may be "ThrowException" (default) or "ReturnNull" -->
    <UnknownDiscriminatorHandling>ReturnNull</UnknownDiscriminatorHandling>

    <!-- Available in 0.7.0, HTTP version used by generated clients, may be "1.1", "2.0", or "3.0", defaults to the runtime default -->
    <DefaultHttpVersion>2.0</DefaultHttpVersion>
    <DefaultHttpVersionPolicy>RequestVersionOrLower</DefaultHttpVersionPolicy>
  </PropertyGroup>

</Project>

Including Additional C# files

Any .cs file in the directory tree with the .csproj file will be compiled and included in the generated SDK. They may freely reference internal types in the generated SDK. However, Intellisense support is limited in IDEs.

Compile items may also be used to include files from other directories.

This feature is available beginning in Yardarm SDK version 0.7.0.

<Project Sdk="Yardarm.Sdk/0.7.0">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <Compile Include="../SharedCode/File1.cs" />
    <Compile Include="../SharedCode/File2.cs" />
  </ItemGroup>
</Project>

Downloading specs dynamically

The OpenAPI spec itself may be coming from an outside source, such as a website or another project in your build tree. The CollectOpenApiSpecs target may be overridden in MSBuild to dynamically collect spec files via any means available within MSBuild. When the target is complete, the OpenApiSpec item should be added to the project.

<Project Sdk="Yardarm.Sdk/0.6.1">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <Target Name="CollectOpenApiSpecs">
    <DownloadFile SourceUrl="https://generator.swagger.io/api/swagger.json"
                  DestinationFolder="$(IntermediateOutputPath)"
                  SkipUnchangedFiles="true">
      <Output TaskParameter="DownloadedFile" ItemName="_DownloadedOpenApiSpec" />
    </DownloadFile>

    <ItemGroup>
      <OpenApiSpec Include="@(_DownloadedOpenApiSpec)" />
      <FileWrites Include="@(_DownloadedOpenApiSpec)" />
    </ItemGroup>
  </Target>

</Project>