System.ClientModel
1.1.0-beta.4
Prefix Reserved
See the version list below for details.
dotnet add package System.ClientModel --version 1.1.0-beta.4
NuGet\Install-Package System.ClientModel -Version 1.1.0-beta.4
<PackageReference Include="System.ClientModel" Version="1.1.0-beta.4" />
paket add System.ClientModel --version 1.1.0-beta.4
#r "nuget: System.ClientModel, 1.1.0-beta.4"
// Install System.ClientModel as a Cake Addin #addin nuget:?package=System.ClientModel&version=1.1.0-beta.4&prerelease // Install System.ClientModel as a Cake Tool #tool nuget:?package=System.ClientModel&version=1.1.0-beta.4&prerelease
System.ClientModel library for .NET
System.ClientModel
contains building blocks for communicating with cloud services. It provides shared primitives, abstractions, and helpers for .NET service client libraries.
System.ClientModel
allows client libraries built from its components to expose common functionality in a consistent fashion, so that once you learn how to use these APIs in one client library, you'll know how to use them in other client libraries as well.
Getting started
Typically, you will not need to install System.ClientModel
. It will be installed for you when you install a client library that uses it.
Install the package
Install the client library for .NET with NuGet.
dotnet add package System.ClientModel
Prerequisites
None needed for System.ClientModel
.
Key concepts
System.ClientModel
contains two major categories of types: (1) types used to author service clients, and (2) types exposed in the public APIs of clients built using System.ClientModel
types. The latter are intended for use by the end-users of service clients to communicate with cloud services.
Types used to author service clients appear in the System.ClientModel.Primitives
namespace. Key concepts involving these types include:
- Client pipeline used to send and receive HTTP messages (
ClientPipeline
). - Interfaces used to read and write input and output models exposed in client convenience APIs (
IPersistableModel<T>
andIJsonModel<T>
).
Service methods that end-users of clients call to invoke service operations fall into two categories: convenience methods and lower-level protocol methods. Types used in clients' convenience methods appear in the root System.ClientModel
namespace. Types used in protocol methods and other lower-level scenarios appear in the System.ClientModel.Primitives
namespace. Key concepts involving these types include:
- Results that provide access to the service response and the HTTP response details (
ClientResult<T>
,ClientResult
). - Exceptions that result from failed requests (
ClientResultException
). - Options used to configure the service client pipeline (
ClientPipelineOptions
). - Options used to customize HTTP requests (
RequestOptions
). - Content sent in an HTTP request body (
BinaryContent
).
Below, you will find sections explaining these shared concepts in more detail.
Examples
Send a message using ClientPipeline
System.ClientModel
-based clients, or service clients, use the ClientPipeline
type to send and receive HTTP messages. The following sample shows a minimal example of what a service client implementation might look like.
public class SampleClient
{
private readonly Uri _endpoint;
private readonly ApiKeyCredential _credential;
private readonly ClientPipeline _pipeline;
// Constructor takes service endpoint, credential used to authenticate
// with the service, and options for configuring the client pipeline.
public SampleClient(Uri endpoint, ApiKeyCredential credential, SampleClientOptions? options = default)
{
// Default options are used if none are passed by the client's user.
options ??= new SampleClientOptions();
_endpoint = endpoint;
_credential = credential;
// Authentication policy instance is created from the user-provided
// credential and service authentication scheme.
ApiKeyAuthenticationPolicy authenticationPolicy = ApiKeyAuthenticationPolicy.CreateBearerAuthorizationPolicy(credential);
// Pipeline is created from user-provided options and policies
// specific to the service client implementation.
_pipeline = ClientPipeline.Create(options,
perCallPolicies: ReadOnlySpan<PipelinePolicy>.Empty,
perTryPolicies: new PipelinePolicy[] { authenticationPolicy },
beforeTransportPolicies: ReadOnlySpan<PipelinePolicy>.Empty);
}
// Service method takes an input model representing a service resource
// and returns `ClientResult<T>` holding an output model representing
// the value returned in the service response.
public ClientResult<SampleResource> UpdateResource(SampleResource resource)
{
// Create a message that can be sent via the client pipeline.
using PipelineMessage message = _pipeline.CreateMessage();
// Modify the request as needed to invoke the service operation.
PipelineRequest request = message.Request;
request.Method = "PATCH";
request.Uri = new Uri($"https://www.example.com/update?id={resource.Id}");
request.Headers.Add("Accept", "application/json");
// Add request body content that will be written using methods
// defined by the model's implementation of the IJsonModel<T> interface.
request.Content = BinaryContent.Create(resource);
// Send the message.
_pipeline.Send(message);
// Obtain the response from the message Response property.
// The PipelineTransport ensures that the Response value is set
// so that every policy in the pipeline can access the property.
PipelineResponse response = message.Response!;
// If the response is considered an error response, throw an
// exception that exposes the response details.
if (response.IsError)
{
throw new ClientResultException(response);
}
// Read the content from the response body and create an instance of
// a model from it, to include in the type returned by this method.
SampleResource updated = ModelReaderWriter.Read<SampleResource>(response.Content)!;
// Return a ClientResult<T> holding the model instance and the HTTP
// response details.
return ClientResult.FromValue(updated, response);
}
}
For more information on authoring clients, see Client implementation samples.
Reading and writing model content to HTTP messages
Service clients provide model types representing service resources as input parameters and return values from service clients' convenience methods. Client authors can implement the IPersistableModel<T>
and IJsonModel<T>
interfaces their in model implementations to make it easy for clients to write input model content to request message bodies, and to read response content and create instances of output models from it. An example of how clients' service methods might use such models is shown in Send a message using the ClientPipeline. The following sample shows a minimal example of what a persistable model implementation might look like.
public class SampleResource : IJsonModel<SampleResource>
{
public SampleResource(string id)
{
Id = id;
}
public string Id { get; init; }
SampleResource IJsonModel<SampleResource>.Create(ref Utf8JsonReader reader, ModelReaderWriterOptions options)
=> FromJson(reader);
SampleResource IPersistableModel<SampleResource>.Create(BinaryData data, ModelReaderWriterOptions options)
=> FromJson(new Utf8JsonReader(data));
string IPersistableModel<SampleResource>.GetFormatFromOptions(ModelReaderWriterOptions options)
=> options.Format;
void IJsonModel<SampleResource>.Write(Utf8JsonWriter writer, ModelReaderWriterOptions options)
=> ToJson(writer);
BinaryData IPersistableModel<SampleResource>.Write(ModelReaderWriterOptions options)
=> ModelReaderWriter.Write(this, options);
// Write the model JSON that will populate the HTTP request content.
private void ToJson(Utf8JsonWriter writer)
{
writer.WriteStartObject();
writer.WritePropertyName("id");
writer.WriteStringValue(Id);
writer.WriteEndObject();
}
// Read the JSON response content and create a model instance from it.
private static SampleResource FromJson(Utf8JsonReader reader)
{
reader.Read(); // start object
reader.Read(); // property name
reader.Read(); // id value
return new SampleResource(reader.GetString()!);
}
}
For more information on reading and writing persistable models, see Model reader writer samples.
Accessing the service response
Service clients have methods that are used to call cloud services to invoke service operations. These methods on a client are called service methods, and they send a request to the service and return a representation of its response to the caller. Service clients expose two types of service methods: convenience methods and protocol methods.
Convenience methods provide a convenient way to invoke a service operation. They are methods that take a strongly-typed model as input and return a ClientResult<T>
that holds a strongly-typed representation of the service response. Details from the HTTP response may also be obtained from the return value.
Protocol method are low-level methods that take parameters that correspond to the service HTTP API and return a ClientResult
holding only the raw HTTP response details. These methods also take an optional RequestOptions
parameter that allows the client pipeline and the request to be configured for the duration of the call.
The following sample illustrates how to call a convenience method and access the output model created from the service response.
MapsClient client = new(new Uri("https://atlas.microsoft.com"), credential);
// Call a convenience method, which returns ClientResult<T>
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");
ClientResult<IPAddressCountryPair> result = await client.GetCountryCodeAsync(ipAddress);
// Access the output model from the service response.
IPAddressCountryPair value = result.Value;
Console.WriteLine($"Country is {value.CountryRegion.IsoCode}.");
If needed, callers can obtain the details of the HTTP response by calling the result's GetRawResponse
method.
// Access the HTTP response details.
PipelineResponse response = result.GetRawResponse();
Console.WriteLine($"Response status code: '{response.Status}'.");
Console.WriteLine("Response headers:");
foreach (KeyValuePair<string, string> header in response.Headers)
{
Console.WriteLine($"Name: '{header.Key}', Value: '{header.Value}'.");
}
For more information on client service methods, see Client service method samples.
Handling exceptions that result from failed requests
When a service call fails, service clients throw a ClientResultException
. The exception exposes the HTTP status code and the details of the service response if available.
try
{
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");
ClientResult<IPAddressCountryPair> result = await client.GetCountryCodeAsync(ipAddress);
}
// Handle exception with status code 404
catch (ClientResultException e) when (e.Status == 404)
{
// Handle not found error
Console.Error.WriteLine($"Error: Response failed with status code: '{e.Status}'");
}
Whether or not a response is considered an error by the client is determined by the PipelineMessageClassifier
held by a message when it is sent through the client pipeline. For more information on how client authors can customize error classification, see Configuring error response classification samples.
Configuring service clients
Service clients provide a constructor that takes a service endpoint and a credential used to authenticate with the service. They also provide a constructor overload that takes an endpoint, a credential, and an instance of ClientPipelineOptions
.
Passing ClientPipelineOptions
when a client is created will configure the pipeline that the client uses to send and receive HTTP requests and responses. Client pipeline options can be used to override default values such as the network timeout used to send or retry a request.
MapsClientOptions options = new()
{
NetworkTimeout = TimeSpan.FromSeconds(120),
};
string? key = Environment.GetEnvironmentVariable("MAPS_API_KEY");
ApiKeyCredential credential = new(key!);
MapsClient client = new(new Uri("https://atlas.microsoft.com"), credential, options);
For more information on client configuration, see Client configuration samples.
Customizing HTTP requests
Service clients expose low-level protocol methods that allow callers to customize HTTP requests by passing an optional RequestOptions
parameter. RequestOptions
can be used to modify various aspects of the request sent by the service method, such as adding a request header, or adding a policy to the client pipeline that can modify the request directly before sending it to the service. RequestOptions
also allows a client user to pass a CancellationToken
to the method.
// Create RequestOptions instance.
RequestOptions options = new();
// Set the CancellationToken.
options.CancellationToken = cancellationToken;
// Add a header to the request.
options.AddHeader("CustomHeader", "CustomHeaderValue");
// Create an instance of a model that implements the IJsonModel<T> interface.
CountryRegion region = new("US");
// Create BinaryContent from the input model.
BinaryContent content = BinaryContent.Create(region);
// Call the protocol method, passing the content and options.
ClientResult result = await client.AddCountryCodeAsync(content, options);
For more information on customizing requests, see Protocol method samples.
Provide request content
In service clients' protocol methods, users pass the request content as a BinaryContent
parameter. There are a variety of ways to create a BinaryContent
instance:
- From
BinaryData
, which can be created from a string, a stream, an object, or from a byte array containing the serialized UTF-8 bytes - From a model type that implements the
IPersistableModel<T>
orIJsonModel<T>
interfaces.
The following examples illustrate some of the different ways to create BinaryContent
and pass it to a protocol method.
From a string literal
// Create a BinaryData instance from a JSON string literal.
BinaryData input = BinaryData.FromString("""
{
"countryRegion": {
"isoCode": "US"
},
}
""");
// Create a BinaryContent instance to set as the HTTP request content.
BinaryContent requestContent = BinaryContent.Create(input);
// Call the protocol method.
ClientResult result = await client.AddCountryCodeAsync(requestContent);
// Obtain the output response content from the returned ClientResult.
BinaryData output = result.GetRawResponse().Content;
using JsonDocument outputAsJson = JsonDocument.Parse(output.ToString());
string isoCode = outputAsJson.RootElement
.GetProperty("countryRegion")
.GetProperty("isoCode")
.GetString();
Console.WriteLine($"Code for added country is '{isoCode}'.");
From an anonymous type
// Create a BinaryData instance from an anonymous object representing
// the JSON the service expects for the service operation.
BinaryData input = BinaryData.FromObjectAsJson(new
{
countryRegion = new
{
isoCode = "US"
}
});
// Create the BinaryContent instance to pass to the protocol method.
BinaryContent content = BinaryContent.Create(input);
// Call the protocol method.
ClientResult result = await client.AddCountryCodeAsync(content);
From an input stream
// Create a BinaryData instance from a file stream
FileStream stream = File.OpenRead(@"c:\path\to\file.txt");
BinaryData input = BinaryData.FromStream(stream);
// Create the BinaryContent instance to pass to the protocol method.
BinaryContent content = BinaryContent.Create(input);
// Call the protocol method.
ClientResult result = await client.AddCountryCodeAsync(content);
From a model type
// Create an instance of a model that implements the IJsonModel<T> interface.
CountryRegion region = new("US");
// Create BinaryContent from the input model.
BinaryContent content = BinaryContent.Create(region);
// Call the protocol method, passing the content and options.
ClientResult result = await client.AddCountryCodeAsync(content);
Troubleshooting
You can troubleshoot service clients by inspecting the result of any ClientResultException
thrown from a client's service method.
For more information on client service method errors, see Handling exceptions that result from failed requests.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. 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
- System.Memory.Data (>= 1.0.2)
- System.Text.Json (>= 4.7.2)
-
net6.0
- System.Memory.Data (>= 1.0.2)
- System.Text.Json (>= 4.7.2)
NuGet packages (126)
Showing the top 5 NuGet packages that depend on System.ClientModel:
Package | Downloads |
---|---|
Azure.Core
This is the implementation of the Azure Client Pipeline |
|
Azure.ResourceManager
Microsoft Azure Resource Manager client SDK for Azure resources. |
|
Microsoft.VisualStudio.Services.InteractiveClient
Integrate with Azure DevOps Server 2022 and Azure DevOps Services from desktop-based Windows applications that require interactive sign-in by a user. |
|
Azure.ResourceManager.Storage
Microsoft Azure management client SDK for Azure resource provider Microsoft.Storage. |
|
Azure.ResourceManager.Resources
Microsoft Azure Resource Manager client SDK for Azure resource provider Resources. |
GitHub repositories (11)
Showing the top 5 popular GitHub repositories that depend on System.ClientModel:
Repository | Stars |
---|---|
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
|
|
Azure/azure-sdk-for-net
This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.
|
|
openai/openai-dotnet
The official .NET library for the OpenAI API
|
|
optimajet/WorkflowEngine.NET
WorkflowEngine.NET - component that adds workflow in your application. It can be fully integrated into your application, or be in the form of a specific service (such as a web service).
|
|
Kyrodan/KeeAnywhere
A cloud storage provider plugin for KeePass Password Safe
|
Version | Downloads | Last updated |
---|---|---|
1.1.0-beta.7 | 6,966 | 8/14/2024 |
1.1.0-beta.6 | 772 | 8/1/2024 |
1.1.0-beta.5 | 36,085 | 7/11/2024 |
1.1.0-beta.4 | 236,377 | 5/16/2024 |
1.1.0-beta.3 | 5,161 | 4/5/2024 |
1.1.0-beta.2 | 2,949 | 2/29/2024 |
1.1.0-beta.1 | 2,639 | 2/1/2024 |
1.0.0 | 39,900,836 | 1/3/2024 |
1.0.0-beta.4 | 540 | 3/12/2024 |
1.0.0-beta.3 | 4,970 | 1/4/2024 |
1.0.0-beta.2 | 485 | 12/14/2023 |
1.0.0-beta.1 | 347 | 11/27/2023 |