Este artigo aborda como escrever bibliotecas para .NET usando a CLI do .NET. A CLI fornece uma experiência eficiente e de baixo nível que funciona em qualquer sistema operacional suportado. Você ainda pode criar bibliotecas com o Visual Studio e, se essa for sua experiência preferida, consulte o guia do Visual Studio.
Pré-requisitos
Você precisa do SDK do .NET instalado em sua máquina.
Para as seções deste documento que lidam com versões do .NET Framework, você precisa do .NET Framework instalado em uma máquina Windows.
Além disso, se você deseja oferecer suporte a destinos mais antigos do .NET Framework, você precisa instalar pacotes de segmentação ou pacotes de desenvolvedor da página de downloads do .NET Framework. Consulte esta tabela:
Versão do .NET Framework
O que fazer o download
4.6.1
Pacote de Direcionamento do .NET Framework 4.6.1
4.6
Pacote de Direcionamento do .NET Framework 4.6
4.5.2
Pacote do desenvolvedor do .NET Framework 4.5.2
4.5.1
Pacote do desenvolvedor do .NET Framework 4.5.1
4,5
Kit de Desenvolvimento de Software do Windows para Windows 8
4.0
SDK do Windows para Windows 7 e .NET Framework 4
2.0, 3.0 e 3.5
Tempo de execução do .NET Framework 3.5 SP1 (ou versão Windows 8+)
Como direcionar o .NET 5+ ou o .NET Standard
Você controla a estrutura de destino do seu projeto adicionando-a ao seu arquivo de projeto (.csproj ou .fsproj). Para obter orientação sobre como escolher entre o direcionamento do .NET 5+ ou do .NET Standard, consulte .NET 5+ e .NET Standard.
Se você deseja direcionar o .NET Framework versões 4.0 ou inferiores, ou deseja usar uma API disponível no .NET Framework mas não no .NET Standard (por exemplo, System.Drawing), leia as seções a seguir e saiba como multitarget.
Como direcionar o .NET Framework
Nota
Estas instruções pressupõem que você tenha o .NET Framework instalado em sua máquina. Consulte os Pré-requisitos para instalar dependências.
Lembre-se de que algumas das versões do .NET Framework usadas aqui não são mais suportadas. Consulte as Perguntas frequentes sobre a Política de Ciclo de Vida de Suporte do .NET Framework sobre versões sem suporte.
Se você quiser atingir o número máximo de desenvolvedores e projetos, use o .NET Framework 4.0 como seu destino de linha de base. Para direcionar o .NET Framework, comece usando o Target Framework Moniker (TFM) correto que corresponde à versão do .NET Framework que você deseja suportar.
Versão do .NET Framework
TFM
.NET Framework 2.0
net20
.NET Framework 3.0
net30
.NET Framework 3.5
net35
.NET Framework 4.0
net40
.NET Framework 4.5
net45
.NET Framework 4.5.1
net451
.NET Framework 4.5.2
net452
.NET framework 4.6
net46
.NET Framework 4.6.1
net461
.NET Framework 4.6.2
net462
.NET Framework 4.7
net47
.NET Framework 4.8
net48
Em seguida, insira esse TFM na TargetFramework seção do seu arquivo de projeto. Por exemplo, veja como você escreveria uma biblioteca destinada ao .NET Framework 4.0:
E já está! Embora isso tenha sido compilado apenas para o .NET Framework 4, você pode usar a biblioteca em versões mais recentes do .NET Framework.
Como multitarget
Nota
As instruções a seguir pressupõem que você tenha o .NET Framework instalado em sua máquina. Consulte a seção Pré-requisitos para saber quais dependências você precisa instalar e de onde baixá-las.
Talvez seja necessário direcionar versões mais antigas do .NET Framework quando seu projeto oferece suporte ao .NET Framework e ao .NET. Nesse cenário, se você quiser usar APIs mais recentes e construções de linguagem para os destinos mais recentes, use #if diretivas em seu código. Também pode ser necessário adicionar pacotes e dependências diferentes para cada plataforma que você está segmentando para incluir as diferentes APIs necessárias para cada caso.
Por exemplo, digamos que você tenha uma biblioteca que execute operações de rede por HTTP. Para o .NET Standard e o .NET Framework versões 4.5 ou superiores, você pode usar a HttpClient classe do System.Net.Http namespace. No entanto, versões anteriores do .NET Framework não têm a HttpClient classe, então você pode usar a WebClientSystem.Net classe do namespace para esses em vez disso.
Seu arquivo de projeto pode ter esta aparência:
XML
<ProjectSdk="Microsoft.NET.Sdk"><PropertyGroup><TargetFrameworks>netstandard2.0;net40;net45</TargetFrameworks></PropertyGroup><!-- Need to conditionally bring in references for the .NET Framework 4.0 target --><ItemGroupCondition="'$(TargetFramework)' == 'net40'"><ReferenceInclude="System.Net" /></ItemGroup><!-- Need to conditionally bring in references for the .NET Framework 4.5 target --><ItemGroupCondition="'$(TargetFramework)' == 'net45'"><ReferenceInclude="System.Net.Http" /><ReferenceInclude="System.Threading.Tasks" /></ItemGroup></Project>
Você notará três grandes mudanças aqui:
O TargetFramework nó foi substituído por TargetFrameworks, e três TFMs são expressos no interior.
Há um <ItemGroup> nó para o net40 destino puxando em uma referência do .NET Framework.
Há um <ItemGroup> nó para o net45 destino puxando duas referências do .NET Framework.
Símbolos do pré-processador
O sistema de compilação está ciente dos seguintes símbolos de pré-processador usados em #if diretivas:
Estruturas de destino
Símbolos
Símbolos adicionais (disponível em SDKs do .NET 5+)
Símbolos da plataforma (disponível apenas quando você especifica um TFM específico do sistema operacional)
Os símbolos sem versão são definidos independentemente da versão que você está segmentando.
Os símbolos específicos da versão são definidos apenas para a versão que você está segmentando.
Os <framework>_OR_GREATER símbolos são definidos para a versão que você está segmentando e todas as versões anteriores. Por exemplo, se você estiver direcionando o .NET Framework 2.0, os seguintes símbolos serão definidos: NET20, NET20_OR_GREATER, NET11_OR_GREATERe NET10_OR_GREATER.
Os NETSTANDARD<x>_<y>_OR_GREATER símbolos são definidos apenas para destinos .NET Standard e não para destinos que implementam o .NET Standard, como .NET Core e .NET Framework.
Eles são diferentes dos monikers de estrutura de destino (TFMs) usados pela propriedade MSBuild TargetFramework e NuGet.
Aqui está um exemplo que faz uso da compilação condicional por destino:
C#
using System;
using System.Text.RegularExpressions;
#if NET40// This only compiles for the .NET Framework 4 targetsusing System.Net;
#else// This compiles for all other targetsusing System.Net.Http;
using System.Threading.Tasks;
#endifnamespaceMultitargetLib
{
publicclassLibrary
{
#if NET40privatereadonly WebClient _client = new WebClient();
privatereadonlyobject _locker = newobject();
#elseprivatereadonly HttpClient _client = new HttpClient();
#endif#if NET40// .NET Framework 4.0 does not have async/awaitpublicstringGetDotNetCount()
{
string url = "https://www.dotnetfoundation.org/";
var uri = new Uri(url);
string result = "";
// Lock here to provide thread-safety.lock(_locker)
{
result = _client.DownloadString(uri);
}
int dotNetCount = Regex.Matches(result, ".NET").Count;
return$"Dotnet Foundation mentions .NET {dotNetCount} times!";
}
#else// .NET Framework 4.5+ can use async/await!publicasync Task<string> GetDotNetCountAsync()
{
string url = "https://www.dotnetfoundation.org/";
// HttpClient is thread-safe, so no need to explicitly lock herevar result = await _client.GetStringAsync(url);
int dotNetCount = Regex.Matches(result, ".NET").Count;
return$"dotnetfoundation.org mentions .NET {dotNetCount} times in its HTML!";
}
#endif
}
}
Se você compilar este projeto com dotnet buildo , notará três diretórios na bin/ pasta:
net40/
net45/
netstandard2.0/
Cada um deles contém os .dll arquivos para cada destino.
Como testar bibliotecas no .NET
É importante poder testar em todas as plataformas. Você pode usar xUnit ou MSTest fora da caixa. Ambos são perfeitamente adequados para testar sua biblioteca no .NET. A forma como você configura sua solução com projetos de teste dependerá da estrutura da sua solução. O exemplo a seguir pressupõe que os diretórios de teste e de origem vivam no mesmo diretório de nível superior.
Navegue até o diretório do projeto de teste e adicione uma referência a MyProject.Test de MyProject.
.NET CLI
cd MyProject.Test
dotnetadd reference ../MyProject/MyProject.csproj
Restaure pacotes e construa projetos:
.NET CLI
dotnetrestoredotnetbuild
Verifique se o xUnit é executado executando o dotnet test comando. Se você optar por usar o MSTest, o executor do console MSTest deverá ser executado.
E já está! Agora você pode testar sua biblioteca em todas as plataformas usando ferramentas de linha de comando. Para continuar a testar agora que tem tudo configurado, testar a sua biblioteca é muito simples:
Faça alterações na sua biblioteca.
Execute testes a partir da linha de comando, no diretório de teste, com dotnet test o comando.
Seu código será reconstruído automaticamente quando você invocar dotnet test o comando.
Como usar vários projetos
Uma necessidade comum de bibliotecas maiores é colocar a funcionalidade em diferentes projetos.
Imagine que você deseja construir uma biblioteca que possa ser consumida em C# e F# idiomáticos. Isso significaria que os consumidores de sua biblioteca a consomem de maneiras naturais para C# ou F#. Por exemplo, em C# você pode consumir a biblioteca assim:
C#
using AwesomeLibrary.CSharp;
public Task DoThings(Data data)
{
var convertResult = await AwesomeLibrary.ConvertAsync(data);
var result = AwesomeLibrary.Process(convertResult);
// do something with result
}
Em F#, pode ter esta aparência:
F#
open AwesomeLibrary.FSharp
let doWork data = async {
let! result = AwesomeLibrary.AsyncConvert data // Uses an F# async function rather than C# async method// do something with result
}
Cenários de consumo como esse significam que as APIs acessadas precisam ter uma estrutura diferente para C# e F#. Uma abordagem comum para fazer isso é fatorar toda a lógica de uma biblioteca em um projeto principal, com projetos C# e F# definindo as camadas de API que chamam esse projeto principal. O restante da seção usará os seguintes nomes:
AwesomeLibrary.Core - Um projeto principal que contém toda a lógica para a biblioteca
AwesomeLibrary.CSharp - Um projeto com APIs públicas destinadas ao consumo em C#
AwesomeLibrary.FSharp - Um projeto com APIs públicas destinadas ao consumo em F#
Você pode executar os seguintes comandos em seu terminal para produzir a mesma estrutura deste guia:
.NET CLI
mkdir AwesomeLibrary && cd AwesomeLibrary
dotnetnewsln
mkdir AwesomeLibrary.Core && cd AwesomeLibrary.Core && dotnetnew classlib
cd ..
mkdir AwesomeLibrary.CSharp && cd AwesomeLibrary.CSharp && dotnetnew classlib
cd ..
mkdir AwesomeLibrary.FSharp && cd AwesomeLibrary.FSharp && dotnetnew classlib -lang"F#"cd ..
dotnetslnadd AwesomeLibrary.Core/AwesomeLibrary.Core.csproj
dotnetslnadd AwesomeLibrary.CSharp/AwesomeLibrary.CSharp.csproj
dotnetslnadd AwesomeLibrary.FSharp/AwesomeLibrary.FSharp.fsproj
Isso adicionará os três projetos acima e um arquivo de solução que os vincula. Criar o arquivo de solução e vincular projetos permitirá que você restaure e construa projetos a partir de um nível superior.
Referência de projeto a projeto
A melhor maneira de fazer referência a um projeto é usar a CLI do .NET para adicionar uma referência de projeto. Nos diretórios de projeto AwesomeLibrary.CSharp e AwesomeLibrary.FSharp, você pode executar o seguinte comando:
Os arquivos de projeto para AwesomeLibrary.CSharp e AwesomeLibrary.FSharp agora farão referência a AwesomeLibrary.Core como destino ProjectReference . Você pode verificar isso inspecionando os arquivos de projeto e vendo o seguinte neles:
Você pode adicionar esta seção a cada arquivo de projeto manualmente se preferir não usar a CLI do .NET.
Estruturação de uma solução
Outro aspeto importante das soluções multi-projeto é estabelecer uma boa estrutura geral do projeto. Você pode organizar o código como quiser, e desde que vincule cada projeto ao seu arquivo de solução com dotnet sln addo , você poderá executar dotnet restore e dotnet build no nível da solução.
Colabore connosco no GitHub
A origem deste conteúdo pode ser encontrada no GitHub, onde também pode criar e rever problemas e pedidos Pull. Para mais informações, consulte o nosso guia do contribuidor.
Comentários do .NET
O .NET é um projeto código aberto. Selecione um link para fornecer comentários:
Crie um projeto .NET e aprenda a adicionar pacotes e a gerir as dependências de pacotes do seu projeto. Utilize a CLI de .NET Core e o registo do NuGet para adicionar bibliotecas e ferramentas às aplicações C# através do Visual Studio Code.