.NET Standard
Read more how to use the .NET Standard SDK for .NET Framework, .NET Core and Xamarin.
This means that the API is fully covered, including all endpoints that are also used by the frontend. You can also use the SDK to create and configure apps, schemas and rules.
The downside is that some of the methods are not as user friendly as they could be. Most methods have the app name as an required parameter, which is redundant because the SDK is designed to mainly connect to a single app anyway and has the app name as a global configuration option.
Because of localization the OpenAPI specification and the generated classes are very difficult to use, especially if your fields are not localized. Therefore we recommend to create the mapping classes for your schemas manually. But of course you can also use OpenAPI to generate them.
Our recommendation is to use NSwag for that. The code generator is also available as a class library to you automated the code generation in your CI pipeline.
dotnet add package Squidex.ClientLibrary
The main entry class is the
SquidexClientManager which maintains the authentication and provides methods to create client classes for different endpoints.To instantiate the client manager you need your app name, the client id and secret.
var clientManager =
new SquidexClientManager(
new SquidexOptions
{
AppName = "...",
ClientId = "...",
ClientSecret = "...",
Url = "https://cloud.squidex.io"
});
Just go the clients screen in your app and click the connect button.
The clients for your app
Then follow the third link to get instructions how to connect with the SDK:
The Connect wizard for you app client
You can just copy and paste the sample code to your source file.
The sample code for the client manager
The client manager will create an access token using your client credentials automatically and cache this token in memory for 30 days. When the token expires the token will be recreated automatically.
Read more about the authentication flow and best practices:
The next step is to create concrete clients, e.g. when you want to query or upload assets you need the assets client:
var assetsClient = clientManager.CreateAssetsClient();
The clients are designed to be reused. When you make use of a dependency system container you can also register them as singleton.
public void AddSquidexServices(IServiceCollection serviceCollection)
{
var clientManager =
new SquidexClientManager(
new SquidexOptions
{
AppName = "...",
ClientId = "...",
ClientSecret = "...",
Url = "https://cloud.squidex.io"
});
serviceCollection.AddSingleton(clientManager);
serviceCollection.AddSingleton<IAssetsClient>(c =>
c.GetRequiredServices<SquidexClientManager>()
.CreateAssetsClient());
}
The interfaces can then be replaced with Mocks for automated tests, if needed.
If you use
Microsoft.Extensions.DependencyInjection, for example in ASP.NET Core you can also use the integration library:dotnet add package Squidex.ClientLibrary.ServiceExtensions
serviceCollection.AddSquidexClient(options =>
{
options.AppName = "...";
options.ClientId = "...";
options.ClientSecret = "...";
options.Url = "https://cloud.squidex.io";
});
This extension method registers all client class and the
ISquidexClientManager.// Resolve client manager
var clientManager = services.GetRequiredService<ISquidexClientManager>();
// Resolve assets client.
var assetsClient = services.GetRequiredService<IAssetsClient>();
Content clients need to be registered manually:
// Register contents clients
serviceCollection.AddSquidexClient(
cm => cm.CreateContentsClient<BlogPost, BlogPostData>("blog-post"));
// Resolve contents client
var contentsClient =
services.GetRequiredService<IContentsClient<BlogPost, BlogPostData>();
The Client Library supports multiple apps now:
serviceCollection.AddSquidexClient(options =>
{
options.AppName = "squidex-website";
options.ClientId = "....";
options.ClientSecret = "...";
options.AppCredentials = new Dictionary<string, AppCredentials>
{
["other-website"] = new AppCredentials
{
ClientId = "...",
ClientSecret = "...",
}
};
options.Url = "https://cloud.squidex.io";
})
You also use make any changes to the HTTP pipeline with the following method. This can be used to integrate logging or to integrate Polly.
serviceCollection.AddSquidexHttpClient()
.AddHttpMessageHandler(() =>
{
// YOUR CODE
}).Services
As mentioned before dealing with contents requires more work.
The reason is the json structure of the content data. Lets assume we have a
blog-post schema with two fields, a localized title field and normal (invariant) slugfield. The resulting content response will look like this then:{
"title": {
"en": "Hello Squidex",
"de": "HALLO Squidex"
},
"slug": {
"iv": "hello-squidex"
}
}
When you map a structure to a C# class, every json object is mapped to either a Dictionary or a class.
A a code generator would then create the following class structure and would also convert all json property names to a Pascal-Case naming to align the naming with the C# conventions. So whenever you work with invariant fields you have to access the
Iv property to get access to the value.public class BlogPostTitle {
public string En { get; set; }
public string De { get; set; }
}
public class BlogPostSlug {
public string Iv { get; set; }
}
public class BlogPostData {
public BlogPostTitle Title { get; set; }
public BlogPostSlug Slug { get; set; }
}
Therefore we create the classes manually:
For each schema you want to consume, two classes are needed.
The data object is the structure of your content data:
public sealed class BlogPostData
{
// The invariant converter converts the object to a flat property.
[JsonConverter(typeof(InvariantConverter))]
public string Slug { get; set; }
// For localizable fields you can use dictionaries.
public Dictionary<string, string> Title { get; set; }
}
We also create another class for the blog post itself, which holds the data and metadata.
public sealed class BlogPost : Content<BlogPostData>
{
}
It depends on your field type, which .NET type you use for a field.
Our recommendation:
Field Type | .NET Type |
|---|---|
Assets | System.Collections.Generic.List<System.Guid> |
Boolean | bool |
DateTime | System.DateTime or System.DateTimeOffset |
Geolocation | A custom class. |
Json | Newtonsoft.Json.Linq.JObject or a custom class. |
Number | double |
References | System.Collections.Generic.List<System.Guid> |
String | string |
Tags | System.Collections.Generic.List<Sstring> |
Array | A custom class. |
At the moment the SDK does not provide a ready to use structure for geolocations, but you can use the following class:
public class Geolocation
{
public double Latitude { get; set; }
public double Longitude { get; set; }
}
When you have an array field you need a class for your array items, for example:
public class Comment
{
public string Author { get; set; }
public string Text { get; set; }
}
public sealed class BlogPostData
{
// For invariant array fields.
[JsonConverter(typeof(InvariantConverter))]
public List<Comment> Comments { get; set; }
// For localized array fields.
public Dictionary<string, List<Comment>> Comments { get; set; }
}
Please note that the
InvariantConverteris only needed for root fields.Next to have to use a client again. You have to pass in the name of your schemas an argument and the two created classes as type arguments.
var client =
clientManager
.CreateContentsClient<BlogPost, BlogPostData>("blog-post");
The client is also designed to be reused, but when you complex queries our recommendation is to create a wrapper class and to register the wrapper in the service container to make testing easier.
Using the client is very easy, for example:
var id = Guid.Parse("xxx...");
var post = await client.GetAsync(id);
var slug = post.Data.Slug;
var titleEN = post.Data.Title["en"];
var titleDE = post.Data.Title["de"];
var data = new BlogPostData
{
Slug = "hello-squidex",
Title = new Dictionary<string, string>
{
["en"] = "Hello Squidex",
["de"] = "Hallo Squidex"
}
}
var posts = await client.GetAsync(new ContentQuery
{
Filter = $"data/slug/iv eq '{slug}'"
});
We also use the .NET client for API tests. The do cover all endpoints yet, but are helpful reference: