.NET Standard
Read more how to use the .NET Standard SDK for .NET Framework, .NET Core and Xamarin.
Introduction
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.
Generating content classes
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.
How to use the SDK?
1. Install the SDK
1
dotnet add package Squidex.ClientLibrary
Copied!
2. Instantiate the client manager
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.
1
var clientManager =
2
new SquidexClientManager(
3
new SquidexOptions
4
{
5
AppName = "...",
6
ClientId = "...",
7
ClientSecret = "...",
8
Url = "https://cloud.squidex.io"
9
});
Copied!
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:
2. Create concrete clients
The next step is to create concrete clients, e.g. when you want to query or upload assets you need the assets client:
1
var assetsClient = clientManager.CreateAssetsClient();
Copied!
The clients are designed to be reused. When you make use of a dependency system container you can also register them as singleton.
1
public void AddSquidexServices(IServiceCollection services)
2
{
3
var clientManager =
4
new SquidexClientManager(
5
new SquidexOptions
6
{
7
AppName = "...",
8
ClientId = "...",
9
ClientSecret = "...",
10
Url = "https://cloud.squidex.io"
11
});
12
​
13
services.AddSingleton(clientManager);
14
​
15
services.AddSingleton<IAssetsClient>(c =>
16
c.GetRequiredServices<SquidexClientManager>()
17
.CreateAssetsClient());
18
}
Copied!
The interfaces can then be replaced with Mocks for automated tests, if needed.
How to work with contents?
As mentioned before dealing with contents requires more work.
Why no code generation?
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:1
{
2
"title": {
3
"en": "Hello Squidex",
4
"de": "HALLO Squidex"
5
},
6
"slug": {
7
"iv": "hello-squidex"
8
}
9
}
Copied!
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.1
public class BlogPostTitle {
2
public string En { get; set; }
3
public string De { get; set; }
4
}
5
​
6
public class BlogPostSlug {
7
public string Iv { get; set; }
8
}
9
​
10
public class BlogPostData {
11
public BlogPostTitle Title { get; set; }
12
​
13
public BlogPostSlug Slug { get; set; }
14
}
Copied!
Therefore we create the classes manually:
1. Create your class model
For each schema you want to consume, two classes are needed.
The data object is the structure of your content data:
1
public sealed class BlogPostData
2
{
3
// The invariant converter converts the object to a flat property.
4
[JsonConverter(typeof(InvariantConverter))]
5
public string Slug { get; set; }
6
​
7
// For localizable fields you can use dictionaries.
8
public Dictionary<string, string> Title { get; set; }
9
}
Copied!
We also create another class for the blog post itself, which holds the data and metadata.
1
public sealed class BlogPost : Content<BlogPostData>
2
{
3
}
Copied!
How to map fields to .NET types
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
boolDateTime
System.DateTime or System.DateTimeOffsetGeolocation
A custom class.
Json
Newtonsoft.Json.Linq.JObject or a custom class.Number
doubleReferences
System.Collections.Generic.List<System.Guid>String
stringTags
System.Collections.Generic.List<Sstring>Array
A custom class.
Geolocation classes
At the moment the SDK does not provide a ready to use structure for geolocations, but you can use the following class:
1
public class Geolocation
2
{
3
public double Latitude { get; set; }
4
public double Longitude { get; set; }
5
}
Copied!
Arrays
When you have an array field you need a class for your array items, for example:
1
public class Comment
2
{
3
public string Author { get; set; }
4
​
5
public string Text { get; set; }
6
}
7
​
8
public sealed class BlogPostData
9
{
10
// For invariant array fields.
11
[JsonConverter(typeof(InvariantConverter))]
12
public List<Comment> Comments { get; set; }
13
​
14
// For localized array fields.
15
public Dictionary<string, List<Comment>> Comments { get; set; }
16
}
Copied!
Please note that the
InvariantConverteris only needed for root fields.2. Instantiate the client
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.
1
var client =
2
clientManager
3
.CreateContentsClient<BlogPost, BlogPostData>("blog-post");
Copied!
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.
3. Use the client
Using the client is very easy, for example:
Get a content item by id
1
var id = Guid.Parse("xxx...");
2
​
3
var post = await client.GetAsync(id);
4
​
5
var slug = post.Data.Slug;
6
var titleEN = post.Data.Title["en"];
7
var titleDE = post.Data.Title["de"];
Copied!
Create a new content item
1
var data = new BlogPostData
2
{
3
Slug = "hello-squidex",
4
Title = new Dictionary<string, string>
5
{
6
["en"] = "Hello Squidex",
7
["de"] = "Hallo Squidex"
8
}
9
}
Copied!
Query items by filter
1
var posts = await client.GetAsync(new ContentQuery
2
{
3
Filter = quot;data/slug/iv eq '{slug}'"
4
});
Copied!
More samples
We also use the .NET client for API tests. The do cover all endpoints yet, but are helpful reference: