OpenServiceBroker.Client 0.4.6

There is a newer version of this package available.
See the version list below for details.
dotnet add package OpenServiceBroker.Client --version 0.4.6                
NuGet\Install-Package OpenServiceBroker.Client -Version 0.4.6                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OpenServiceBroker.Client" Version="0.4.6" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add OpenServiceBroker.Client --version 0.4.6                
#r "nuget: OpenServiceBroker.Client, 0.4.6"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install OpenServiceBroker.Client as a Cake Addin
#addin nuget:?package=OpenServiceBroker.Client&version=0.4.6

// Install OpenServiceBroker.Client as a Cake Tool
#tool nuget:?package=OpenServiceBroker.Client&version=0.4.6                

Open Service Broker API for .NET

Build API documentation

This project provides both a server and a client .NET library for the Open Service Broker API specification. This specification allows developers, ISVs, and SaaS vendors a single, simple, and elegant way to deliver services to applications running within cloud native platforms such as Cloud Foundry, OpenShift, and Kubernetes.

The Server Library implements the API for you using ASP.NET Core. You simply need to provide implementations for a few interfaces, shielded from the HTTP-related details.

The Client Library allows you to call Service Brokers that implement the API using idiomatic C# interfaces and type-safe DTOs.

Server Library

OpenServiceBroker.Server

Set up a regular ASP.NET Core 6.0+ project and add the NuGet package OpenServiceBroker.Server. Then implement the following interfaces:

Register your implementations in the IServiceCollection for dependency injection. For example:

services.AddTransient<ICatalogService, MyCatalogService>()
        .AddTransient<IServiceInstanceBlocking, MyServiceInstanceBlocking>()
        .AddTransient<IServiceBindingBlocking, MyServiceBindingBlocking>();

Then enable MVC Controllers using .AddMvc() or .AddControllers() followed by calling the .AddOpenServiceBroker() extension method:

services.AddControllers()
        .AddOpenServiceBroker();

You can use the project template to quickly set up a pre-configured ASP.NET Core 6.0 project with OpenServiceBroker.Server.

Versioning

The Server Library inspects the X-Broker-API-Version header for all requests (as defined in the specification). Currently it accepts all versions from 2.0 to 2.16.

Client Library

OpenServiceBroker.Client

Add the NuGet package OpenServiceBroker.Client to your project. You can then create an instance of the client like this:

var client = new OpenServiceBrokerClient(new Uri("http://example.com/"));

Asynchronous Operations

All operations that result in HTTP request are async. Non-successful HTTP status codes are mapped to domain-specific exception types (BrokerException and derived). Refer to the libraries XML documentation for details on which exceptions to expect on which invocations.

The Open Service Broker API specification allows for both synchronous/blocking and asynchronous/incomplete/deferred operations. To avoid confusion with the C# language concept of async this library uses the terms "blocking" and "deferred" to describe these API features.

Instances of OpenServiceBrokerClient have three properties that expose the same functionality in different ways:

  • .ServiceInstancesBlocking allows you to request blocking responses from the server. However, you may encounter AsyncRequiredException if the server does not support blocking operations.
  • .ServiceInstancesDeferred allows you to request deferred responses from the server. However, you have to manually handle waiting/polling for the completion of operations.
  • .ServiceInstancesPolling combines the advantages of both. It requests deferred responses from the server and transparently handles the waiting/polling for you. It is the recommended option for most use-cases.

Samples

Read the catalog:

var result = await client.Catalog.ReadAsync();

Provision a service instance:

var result = await client.ServiceInstancesPolling["123"].ProvisionAsync(new ServiceInstanceProvisionRequest
{
    ServiceId = "abc",
    PlanId = "xyz",
    Context = new JObject
    {
        {"platform", "myplatform"}
    },
    Parameters = new JObject
    {
        {"some_option", "some value"}
    }
});

Fetch a service instance:

var result = await client.ServiceInstancesPolling["123"].FetchAsync();

Update a service instance:

var result = await client.ServiceInstancesPolling["123"].UpdateAsync(new ServiceInstanceUpdateRequest
{
    ServiceId = "abc",
    PlanId = "xyz",
    Context = new JObject
    {
        {"platform", "myplatform"}
    },
    Parameters = new JObject
    {
        {"some_option", "some value"}
    }
});

Deprovision a service instance:

await client.ServiceInstancesPolling["123"].DeprovisionAsync(serviceId: "abc", planId: "xyz");

Create a service binding:

var result = await client.ServiceInstancesPolling["123"].ServiceBindings["456"].ProvisionAsync(new ServiceBindingRequest
{
    ServiceId = "abc",
    PlanId = "xyz",
    BindResource = new ServiceBindingResourceObject
    {
        AppGuid = "e490c9df-6627-4699-8db8-55edc2a88e58"
    },
    Context = new JObject
    {
        {"platform", "myplatform"}
    },
    Parameters = new JObject
    {
        {"some_option", "some value"}
    }
});

Fetch a service binding:

var result = await client.ServiceInstancesPolling["123"].ServiceBindings["456"].FetchAsync();

Delete a service binding:

await client.ServiceInstancesPolling["123"].ServiceBindings["456"].UnbindAsync(serviceId: "abc", planId: "xyz");

Versioning

The Client Library specifies the API version it expects by setting the X-Broker-API-Version header for all requests (as defined in the specification).

Currently the Client Library supports the 2.16 feature set but defaults to setting the version header to 2.13 for greater compatibility with older brokers. If the broker you are calling expects a different version and you are sure your request is compliant with that version of the specification you can override this:

client.SetApiVersion(new ApiVersion(2, 16));

Building

The source code is in src/, config for building the API documentation is in doc/ and generated build artifacts are placed in artifacts/. The source code does not contain version numbers. Instead the version is determined during CI using GitVersion.

To build run .\build.ps1 or ./build.sh.

Contributing

We welcome contributions to this project such as bug reports, recommendations and pull requests.

This repository contains an EditorConfig file. Please make sure to use an editor that supports it to ensure consistent code style, file encoding, etc.. For full tooling support for all style and naming conventions consider using JetBrains' ReSharper or Rider products.

Product 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 is compatible. 
.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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
0.5.0 131 3/6/2024
0.4.6 282 3/12/2023
0.4.5 300 1/13/2022
0.4.4 1,108 11/29/2021
0.4.3 336 9/5/2021
0.4.2 339 4/7/2021
0.4.0 884 9/20/2020
0.3.1 429 8/26/2020
0.3.0 449 7/30/2020
0.2.0 504 12/11/2019
0.1.5 582 2/25/2019
0.1.4 617 2/11/2019
0.1.3 853 1/17/2019
0.1.2 833 1/10/2019
0.1.1 708 10/23/2018
0.1.0 768 9/15/2018