Usando o Rest PKI em .NET
Rest PKI pode ser usado em aplicações .NET (C#, VB.NET, C++.NET) usando uma ampla gama de tecnologias e plataformas. Para começar, escolha uma dos exemplos de projetos disponíveis:
Biblioteca do cliente
Todos os projetos de exemplo em .NET usam o pacote Lacuna.RestPki.Client do NuGet para acessar o Rest PKI.
Versões e plataformas suportadas
O pacote tem duas linhas de versões, sem nenhuma versão entre a 1.24.1 e a 2.2.0:
| Versões | Frameworks de destino |
|---|---|
| 1.24.1, a última versão 1.x | .NET Framework 3.5, 4.0, 4.5 e 4.6; .NET Standard 1.3 e 2.0 |
| 2.2.0 e seguintes | Só .NET Standard 2.0 |
Desde a 2.2.0, o pacote é publicado junto com o Rest PKI Core: os números de versão dele são os mesmos
do pacote cliente do Rest PKI Core, o Lacuna.RestPkiCore.Client, que depende dele. As duas linhas têm as mesmas classes e enviam as
mesmas requisições à API do Rest PKI, então as duas funcionam com o pki.rest. Escolha pelo framework de destino da sua aplicação:
- .NET Framework 4.6.1 ou superior, .NET Core 2.0 ou superior ou .NET 5 ou superior (plataformas que implementam o .NET Standard 2.0): use a versão mais recente.
- .NET Framework 3.5 a 4.6, ou uma plataforma que implementa só o .NET Standard 1.3: use a 1.24.1.
Se a sua aplicação também usa o Lacuna.RestPkiCore.Client 2.2.0 ou superior, mantenha os dois pacotes na mesma versão: o cliente do
Rest PKI Core exige no mínimo a própria versão do Lacuna.RestPki.Client.
O que muda depois da 1.24.1: desde a 2.2.0, RestPkiException.ErrorCodeStr traz o código de erro como texto, inclusive para códigos
que o enum ErrorCodes não lista. A 5.0.0 acrescenta um construtor do RestPkiClient que recebe tags de requisição, um recurso do
Rest PKI Core que o pki.rest ignora, e o construtor que recebe um Uri deixa de ser público; por isso, passe o endpoint como string.
As dependências do pacote são de propriedade da Microsoft ou da própria Lacuna Software. Nenhum pacote de terceiros é necessário (exceto o pacote Newtonsoft.Json, o padrão de fato para manipular JSON no .NET).
Veja este pacote referência API.
Erros
Toda exceção que o cliente lança deriva de RestException:
| O que aconteceu | Exceção | O que ela informa |
|---|---|---|
O Rest PKI devolveu HTTP 422 com o código de erro ValidationError: um certificado não passou na validação | ValidationException | ValidationResults |
O Rest PKI devolveu HTTP 422 com outro código de erro, como SecurityContextRequired | RestPkiException | ErrorCode, Detail |
| O Rest PKI devolveu HTTP 401 (o token de acesso não é válido), 500 ou outro código de status de erro | RestErrorException | StatusCode, ErrorMessage |
| Nenhuma resposta chegou: falha de rede, erro de resolução de nome ou de TLS, ou timeout | RestUnreachableException | InnerException, a causa |
ValidationException e RestPkiException ficam no namespace Lacuna.RestPki.Client; RestException, RestErrorException e
RestUnreachableException ficam em Lacuna.RestClient, do pacote Lacuna.RestClient, uma dependência deste. Para HTTP 400, 403 e
404, o Lacuna.RestClient lança uma subclasse mais específica de RestException quando o corpo da resposta descreve o erro. Para os
códigos de status e os códigos de erro, veja Códigos de retorno.