Using Rest PKI on .NET
Rest PKI can be used on .NET applications (C#, VB.NET, C++.NET) using a wide range of technologies and platforms. To get started, choose one of the available samples projects:
Client library
All .NET samples projects use the NuGet package Lacuna.RestPki.Client to access Rest PKI.
Versions and supported platforms
The package has two lines of versions, with no version between 1.24.1 and 2.2.0:
| Versions | Target frameworks |
|---|---|
| 1.24.1, the last 1.x version | .NET Framework 3.5, 4.0, 4.5 and 4.6; .NET Standard 1.3 and 2.0 |
| 2.2.0 and later | .NET Standard 2.0 only |
Since 2.2.0, the package is released together with Rest PKI Core: its version numbers match those of
the Rest PKI Core client package, Lacuna.RestPkiCore.Client, which depends on it. Both lines have the same classes and send the same
requests to the Rest PKI API, so both work with pki.rest. Choose by your application's target framework:
- .NET Framework 4.6.1 or later, .NET Core 2.0 or later, or .NET 5 or later (platforms that implement .NET Standard 2.0): use the latest version.
- .NET Framework 3.5 to 4.6, or a platform that implements only .NET Standard 1.3: use 1.24.1.
If your application also uses Lacuna.RestPkiCore.Client 2.2.0 or later, keep both packages on the same version: the Rest PKI Core
client requires at least its own version of Lacuna.RestPki.Client.
What changes after 1.24.1: from 2.2.0, RestPkiException.ErrorCodeStr has the error code as text, also for codes that the
ErrorCodes enum does not list. 5.0.0 adds a RestPkiClient constructor that takes request tags, a Rest PKI Core feature that
pki.rest ignores, and the constructor that takes a Uri is no longer public, so pass the endpoint as a string.
The package's dependencies are all owned by either Microsoft or Lacuna Software itself. No 3rd party packages are necessary (except for the Newtonsoft.Json package, the de-facto standard for handling JSON on .NET)
See the package API reference.
Errors
Every exception the client throws derives from RestException:
| What happened | Exception | What it tells you |
|---|---|---|
Rest PKI returned HTTP 422 with the error code ValidationError: a certificate failed validation | ValidationException | ValidationResults |
Rest PKI returned HTTP 422 with another error code, such as SecurityContextRequired | RestPkiException | ErrorCode, Detail |
| Rest PKI returned HTTP 401 (the access token is not valid), 500 or another error status | RestErrorException | StatusCode, ErrorMessage |
| No response arrived: network failure, name resolution or TLS error, or timeout | RestUnreachableException | InnerException, the cause |
ValidationException and RestPkiException are in the namespace Lacuna.RestPki.Client; RestException, RestErrorException and
RestUnreachableException are in Lacuna.RestClient, from the Lacuna.RestClient package, a dependency of this one. For HTTP 400,
403 and 404, Lacuna.RestClient throws a more specific subclass of RestException when the response body describes the error.
For the status codes and error codes, see Return codes.