ApiSurface 4.1.13
See the version list below for details.
dotnet add package ApiSurface --version 4.1.13
NuGet\Install-Package ApiSurface -Version 4.1.13
<PackageReference Include="ApiSurface" Version="4.1.13" />
paket add ApiSurface --version 4.1.13
#r "nuget: ApiSurface, 4.1.13"
// Install ApiSurface as a Cake Addin #addin nuget:?package=ApiSurface&version=4.1.13 // Install ApiSurface as a Cake Tool #tool nuget:?package=ApiSurface&version=4.1.13
ApiSurface
<picture> <source media="(prefers-color-scheme: dark)" srcset="logos/text-white.png"> <source media="(prefers-color-scheme: light)" srcset="logos/text-darkblue.png"> <img alt="ApiSurface logo: a minimalistic cube, dimetric projection, composed of three stacked layers which are joined at some edges so as to suggest the letter S. The visible parts of the stacked layers inside the cube are light blue; the outer surface is white in dark mode, or dark blue in light mode. To the right is the text 'ApiSurface' in the same colour as the cube's exterior." src="logos/text-darkblue.png"> </picture>
This library provides several modules for ensuring the consistency and documentation coverage of an F# assembly's public API. It also integrates with NerdBank.GitVersioning to help you adhere to Semantic Versioning principles.
Quick-start overview
(A more fully worked example appears later in this README.)
By the end of this overview, you have:
- automatically populated a file with a listing of your assembly's public API surface;
- run a test to assert that your assembly conforms to the API surface in that listing;
- run a test to assert that your assembly's public API surface is fully documented;
- run a test to assert that your assembly's version number differs from that in any accessible NuGet repositories by an acceptable amount.
- Create an empty
SurfaceBaseline.txt
file next to your assembly's.fsproj
file. (.csproj
files are not officially supported, but have been observed to work.) - Add an
<EmbeddedResource Include="SurfaceBaseline.txt" />
entry to that.fsproj
file. - Similarly, place a
version.json
file next to your project, using the NerdBank.GitVersioning format, and include it as anEmbeddedResource
. - Add tests asserting that, for example,
ApiSurface.assertIdentical (assemblyUnderTest : Assembly)
. (See this repository'sApiSurface.Test.TestSurface
for a more precise example.) - Run
ApiSurface.writeAssemblyBaseline (assemblyUnderTest : Assembly)
, to populate the emptySurfaceBaseline.txt
file you made earlier. (See this repository'sApiSurface.Test.TestSurface
.) - Observe that
ApiSurface.assertIdentical assembly
,ApiSurface.assertFullyDocumented assembly
, andMonotonicVersion.validate assembly "NuGet.PackageName"
all now run without throwing.
The modules of ApiSurface
ApiSurface
module
The ApiSurface
module enforces that the public API surface does not change.
The public API is serialised in a 'SurfaceBaseline.txt' file that is embedded in the assembly.
Unit tests can then ensure that the API surface of the assembly under test matches that which is encoded in the baseline text file.
You can use ApiSurface.writeAssemblyBaseline
to manually update the SurfaceBaseline.txt
file.
Common practice is to call this function inside a unit test which is marked Explicit
- this ensures that the public API is easy to update with a single click, but that it is not accidentally extended (or reduced) simply by running your normal tests.
DocCoverage
module
The DocCoverage
module provides a function to ensure that the entirety of the public API surface is documented. Note that there are some exceptions to this rule:
- Class constructors never need to be documented. These tend to never be more useful than 'Instantiates the type' anyway.
- All discriminated union case constructors have to be documented.
- Modules which have the same name as a type do not have to be documented. It is self-explanatory that the module simply contains function that construct/act upon the type they are named after.
It is possible to explicitly annotate a type or member as not needing documentation by adding the [<Undocumented>]
attribute.
When applied to a type, all members of that type inherit the [<Undocumented>]
attribute.
This can be overridden with [<Undocumented(MembersInherit=false)>]
.
MonotonicVersion
module
The MonotonicVersion
module provides a function to ensure that the version
field in the version.json
file is always increasing.
This check can fail if a change which increments the major or minor version is reverted.
Semantic Versioning
Along with monitoring a project's public API, this library can be used to encourage semantic versioning.
When running the explicit test (see below) to update a project's SurfaceBaseline file, the test will also look for a version.json
file (in the same location as the SurfaceBaseline file).
If the version.json
file is not found, an error will be raised.
If the version.json
file is found, the version.json
file will be updated with a newer version using the following logic (from https://semver.org/):
- MAJOR version is incremented when backwards incompatible API changes are detected (i.e. API members are changed or removed)
- MINOR version is incremented when added backwards-compatible functionality changes are detected (i.e. API members are added only)
If no API changes are detected, the version will not be incremented by the test. If you are using NerdBank.GitVersioning then the PATCH version will be incremented as required for any change, in combination with the above.
Important!
This isn't intended to replace a real human thinking about the version number.
Breaking behaviour changes (without API changes) still require a major version bump, but no tool can make this judgement for you; ApiSurface
only detects the most obvious cases, where the API surface has changed.
There are not any currently known changes you can make to the API surface of your library that "should" be recognisably major version bumps but which do not result in ApiSurface
flagging the change.
Please raise an issue if you find one.
Different API surfaces on different frameworks
ApiSurface
supports the rare situation of APIs which are different between .NET Framework and .NET Core, or between different versions of the .NET runtime.
Instead of giving the default SurfaceBaseline.txt
file, you can override any given framework with one or more specially-named SurfaceBaseline-FRAMEWORKNAME.txt
files; for example, SurfaceBaseline-Net5.txt
or SurfaceBaseline-NetFramework.txt
.
Note that ApiSurface.writeAssemblyBaseline
will only write a SurfaceBaseline.txt
, and it will only do so for the currently-executing framework.
If you wish to make this specific to .NET Framework or .NET Core, you should then manually rename the file.
For the complete list of supported frameworks and file names, see the private frameworkBaselineFile : string
in the ApiSurface
module.
Compatibility notes
This project is untested on older versions of the .NET Framework and of .NET Core; check the GitHub Actions test matrix to see the platforms on which the tests run.
Fully worked end-to-end example
Assumptions for this example:
- You have set up a project defining a namespace
MyLibrary
; - You have set up a unit test project with a reference to that project, using NUnit;
- Your library defines a type called
SomeDefinedType
; - Your library is published to a NuGet repository as
MyCompany.MyLibraryNuGetPackage
. - After integration with ApiSurface, you are happy to let NerdBank.GitVersioning handle your version numbers.
If you are using a different test framework, you will need to adjust the test file accordingly.
If you are not currently publishing your library to NuGet, then you should skip the "Ensure version is monotonic" test.
SurfaceBaseline.txt
Create an empty file called SurfaceBaseline.txt
next to your main project file.
This example will eventually use ApiSurface to populate that file.
version.json
Create a file called version.json
next to your main project file, in the NerdBank.GitVersioning format.
(Currently only a subset of this format is actually supported; see this repository's VersionFile.fs
for the precise schema.)
{
"version": "1.0",
"publicReleaseRefSpec": [
"^refs/heads/main$"
],
"pathFilters": null
}
If your release branch is called something other than main
, or you use release tags instead, then adjust the publicReleaseRefSpec
accordingly.
Similarly, if an updated version of your library should be published only when certain files within the repository change, set pathFilters
to a list of Git pathspecs.
Within the main project file
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
<ItemGroup>
<Compile Include="MyLibrary.fs" />
<EmbeddedResource Include="SurfaceBaseline.txt" />
<EmbeddedResource Include="version.json" />
</ItemGroup>
</Project>
If you are multi-targetting and you wish for different SurfaceBaseline.txt
files for each target, you should generate SurfaceBaseline
files for each target (renaming them to follow the naming schema as described in this README's description of the ApiSurface
module), and include them all in the project file.
Within the unit test project
Add a reference to the ApiSurface
NuGet package.
Then create a new test file (here we've chosen the name TestSurface.fs
) within your test project, with the following contents:
namespace MyLibrary.Test
open NUnit.Framework
open ApiSurface
[<TestFixture>]
module TestSurface =
let assembly = typeof<MyLibrary.SomeDefinedType>.Assembly
[<Test>]
let ``Ensure API surface has not been modified`` () =
ApiSurface.assertIdentical assembly
[<Test; Explicit>]
let ``Update API surface`` () =
ApiSurface.writeAssemblyBaseline assembly
[<Test>]
let ``Ensure public API is fully documented`` () =
DocCoverage.assertFullyDocumented assembly
[<Test>]
let ``Ensure version is monotonic`` () =
MonotonicVersion.validate assembly "MyCompany.MyLibraryNuGetPackage"
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- FSharp.Core (>= 4.3.4)
- NuGet.Packaging (>= 6.12.1)
- NuGet.Protocol (>= 6.12.1)
- System.IO.Abstractions (>= 4.2.13)
- System.Text.Json (>= 8.0.4)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
4.1.15 | 100 | 12/16/2024 |
4.1.14 | 117 | 12/9/2024 |
4.1.13 | 54 | 12/9/2024 |
4.1.12 | 409 | 11/25/2024 |
4.1.11 | 191 | 11/18/2024 |
4.1.9 | 68 | 11/14/2024 |
4.1.8 | 424 | 10/21/2024 |
4.1.7 | 171 | 10/14/2024 |
4.1.6 | 404 | 10/7/2024 |
4.1.5 | 1,416 | 9/2/2024 |
4.1.4 | 84 | 8/28/2024 |
4.1.3 | 77 | 8/28/2024 |
4.1.2 | 253 | 8/21/2024 |
4.1.1 | 86 | 8/20/2024 |
4.0.44 | 441 | 8/13/2024 |
4.0.43 | 1,066 | 7/8/2024 |
4.0.42 | 154 | 7/1/2024 |
4.0.41 | 965 | 6/10/2024 |
4.0.40 | 2,503 | 5/27/2024 |
4.0.39 | 147 | 5/1/2024 |
4.0.38 | 47 | 5/1/2024 |
4.0.37 | 51 | 5/1/2024 |
4.0.36 | 152 | 4/22/2024 |
4.0.35 | 96 | 4/16/2024 |
4.0.34 | 79 | 4/15/2024 |
4.0.33 | 222 | 2/29/2024 |
4.0.32 | 83 | 2/29/2024 |
4.0.31 | 91 | 2/28/2024 |
4.0.30 | 233 | 2/19/2024 |
4.0.29 | 106 | 2/13/2024 |
4.0.28 | 296 | 2/6/2024 |
4.0.27 | 178 | 1/30/2024 |
4.0.26 | 78 | 1/30/2024 |
4.0.25 | 796 | 12/18/2023 |
4.0.24 | 88 | 12/18/2023 |
4.0.23 | 110 | 12/11/2023 |
4.0.22 | 100 | 12/11/2023 |
4.0.21 | 95 | 12/11/2023 |
4.0.20 | 130 | 11/20/2023 |
4.0.19 | 124 | 11/5/2023 |
4.0.18 | 130 | 10/23/2023 |
4.0.16 | 120 | 10/19/2023 |
4.0.15 | 113 | 10/19/2023 |
4.0.14 | 101 | 10/19/2023 |
4.0.13 | 108 | 10/19/2023 |
4.0.12 | 282 | 6/14/2023 |
4.0.11 | 165 | 5/25/2023 |
4.0.10 | 158 | 5/22/2023 |
4.0.9 | 143 | 5/22/2023 |
4.0.8 | 439 | 4/21/2023 |
4.0.7 | 156 | 4/19/2023 |
4.0.6 | 175 | 4/14/2023 |
4.0.5 | 214 | 3/16/2023 |
4.0.4 | 200 | 3/16/2023 |
4.0.3 | 329 | 12/5/2022 |
4.0.2 | 305 | 12/2/2022 |
4.0.1 | 313 | 11/30/2022 |
3.0.15 | 303 | 11/30/2022 |
3.0.14 | 304 | 11/23/2022 |
3.0.13 | 306 | 11/22/2022 |
3.0.12 | 307 | 11/21/2022 |
3.0.11 | 307 | 11/18/2022 |
3.0.10 | 309 | 11/18/2022 |
3.0.9 | 360 | 11/17/2022 |