项目作者: contentful

项目描述 :
.NET SDK for Contentful's Content Delivery and Management API
高级语言: C#
项目地址: git://github.com/contentful/contentful.net.git
创建时间: 2016-11-08T16:40:52Z
项目社区:https://github.com/contentful/contentful.net

开源协议:MIT License

下载


header



Join Contentful Community Slack



Join Contentful Community Forum

contentful.net - Contentful .NET Library

.NET library for the Contentful Content Delivery API, Content Preview API and the Contentful Management API. It helps you to easily access your Content stored in Contentful with your .NET applications.


This repository is actively maintained

MIT License



Build Status

What is Contentful?

Contentful provides content infrastructure for digital teams to power websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship their products faster.


Table of contents



- contentful.net - Contentful .NET Delivery library
- Core Features
- Getting started
- Your first request
- Using the library with the Preview API
- Authentication
- Further documentation
- Reach out to us
- You have questions about how to use this library?
- You found a bug or want to propose a feature?
- You need to share confidential information or have other questions?
- Get involved
- License
- Code of Conduct



Core Features

Getting started

We recommend you use the NuGet Package Manager to add the library to your .NET Application using one of the following options:

  • In Visual Studio, open Package Manager Console window and run the following command:

    1. PM> Install-Package contentful.csharp
  • In a command-line, run the following .NET CLI command:

    1. > dotnet add package contentful.csharp

Usage

The ContentfulClient handles all communication with the Contentful Content Delivery API.

To create a new client you need to pass an HttpClient, your delivery API key and any other configuration options:

  1. var httpClient = new HttpClient();
  2. var client = new ContentfulClient(httpClient, "<content_delivery_api_key>", "<content_preview_api_key>", "<space_id>");

or:

  1. var httpClient = new HttpClient();
  2. var options = new ContentfulOptions
  3. {
  4. DeliveryApiKey = "<content_delivery_api_key>",
  5. PreviewApiKey = "<content_preview_api_key>",
  6. SpaceId = "<space_id>"
  7. };
  8. var client = new ContentfulClient(httpClient, options);

If you are running asp.net core and wish to take advantage of the options pattern you can do so by passing an IOptions<ContentfulOptions> to the constructor. This lets you keep your authorization token in your application settings, in environment variables or your own custom Microsoft.Extensions.Configuration.IConfigurationSource provider.

Your first request

After creating a ContentfulClient, you can now query for a single entry:

  1. var entry = await client.GetEntry<Product>("<entry_id>");
  2. Console.WriteLine(entry.ProductName); // => Contentful
  3. Console.WriteLine(entry.Price); // => 12.38
  4. Console.WriteLine(entry.Description); // => A fantastic product.
  1. public class Product
  2. {
  3. public string ProductName { get; set; }
  4. public string Price { get; set; }
  5. public string Description { get; set; }
  6. }

The properties of your class will be automatically deserialized from fields with matching names.

If you’re interested in the system properties of the entry, add a SystemProperties property to the class.

  1. public class Product
  2. {
  3. public SystemProperties Sys { get; set; }
  4. public string ProductName { get; set; }
  5. public string Price { get; set; }
  6. public string Description { get; set; }
  7. }
  1. var productEntry = await client.GetEntry<Product>("<entry_id>");
  2. Console.WriteLine(productEntry.Price); // => 12.38
  3. Console.WriteLine(productEntry.Sys.Id); // => 2CfTFQGwogugS6QcOuwO6q

Management API

To edit, update and delete content you use the ContentfulManagementClient class which uses the same familiar pattern as the regular client.

  1. var httpClient = new HttpClient();
  2. var managementClient = new ContentfulManagementClient(httpClient, "<content_management_api_key>", "<space_id>");

You can then use the client to, for example, create a content type.

  1. var contentType = new ContentType();
  2. contentType.SystemProperties = new SystemProperties()
  3. {
  4. Id = "new-content-type"
  5. };
  6. contentType.Name = "New contenttype";
  7. contentType.Fields = new List<Field>()
  8. {
  9. new Field()
  10. {
  11. Name = "Field1",
  12. Id = "field1",
  13. Type = "Text"
  14. },
  15. new Field()
  16. {
  17. Name = "Field2",
  18. Id = "field2",
  19. Type = "Integer"
  20. }
  21. };
  22. await managementClient.CreateOrUpdateContentType(contentType);

Working with Taxonomies

The Management API supports working with taxonomies through concept schemes and concepts. Here’s how you can work with taxonomies:

Concept Schemes

  1. // Create a taxonomy concept scheme
  2. var conceptScheme = new TaxonomyConceptScheme
  3. {
  4. Name = "Product Categories",
  5. Description = "Categories for our products"
  6. };
  7. var createdScheme = await managementClient.CreateTaxonomyConceptScheme(organizationId, conceptScheme);
  8. // Create a scheme with a specific ID
  9. var schemeWithId = await managementClient.CreateTaxonomyConceptSchemeWithId(organizationId, "my-scheme-id", conceptScheme);
  10. // Get a specific concept scheme
  11. var scheme = await managementClient.GetTaxonomyConceptScheme(organizationId, "scheme-id");
  12. // Get all concept schemes
  13. var schemes = await managementClient.GetTaxonomyConceptSchemes(organizationId, limit: 100);
  14. // Get total number of concept schemes
  15. var totalSchemes = await managementClient.GetTotalTaxonomyConceptSchemes(organizationId);
  16. // Update a concept scheme
  17. var patches = new List<JsonPatchOperation>
  18. {
  19. new JsonPatchOperation { Op = "replace", Path = "/name", Value = "Updated Name" }
  20. };
  21. var updatedScheme = await managementClient.UpdateTaxonomyConceptScheme(organizationId, "scheme-id", version, patches);
  22. // Delete a concept scheme
  23. await managementClient.DeleteTaxonomyConceptScheme(organizationId, "scheme-id", version);

Concepts

  1. // Create a taxonomy concept
  2. var concept = new TaxonomyConcept
  3. {
  4. Name = "Electronics",
  5. Description = "Electronic products"
  6. };
  7. var createdConcept = await managementClient.CreateTaxonomyConcept(organizationId, concept);
  8. // Create a concept with a specific ID
  9. var conceptWithId = await managementClient.CreateTaxonomyConceptWithId(organizationId, "my-concept-id", concept);
  10. // Get a specific concept
  11. var concept = await managementClient.GetTaxonomyConcept(organizationId, "concept-id");
  12. // Get all concepts
  13. var concepts = await managementClient.GetTaxonomyConcepts(organizationId, limit: 100);
  14. // Get concepts for a specific scheme
  15. var schemeConcepts = await managementClient.GetTaxonomyConcepts(organizationId, conceptScheme: "scheme-id");
  16. // Get total number of concepts
  17. var totalConcepts = await managementClient.GetTotalTaxonomyConcepts(organizationId);
  18. // Get concept descendants (child concepts)
  19. var descendants = await managementClient.GetTaxonomyConceptDescendants(organizationId, "concept-id", depth: 2);
  20. // Get concept ancestors (parent concepts)
  21. var ancestors = await managementClient.GetTaxonomyConceptAncestors(organizationId, "concept-id", depth: 2);
  22. // Update a concept
  23. var patches = new List<JsonPatchOperation>
  24. {
  25. new JsonPatchOperation { Op = "replace", Path = "/name", Value = "Updated Name" }
  26. };
  27. var updatedConcept = await managementClient.UpdateTaxonomyConcept(organizationId, "concept-id", version, patches);
  28. // Delete a concept
  29. await managementClient.DeleteTaxonomyConcept(organizationId, "concept-id", version);

Using Concepts with Entries and Assets

  1. // Add taxonomy concepts to an entry
  2. var entry = new Entry<dynamic>();
  3. entry.Metadata = new ContentfulMetadata
  4. {
  5. Concepts = new List<Reference>
  6. {
  7. new Reference
  8. {
  9. Sys = new ReferenceProperties
  10. {
  11. Id = "concept-id",
  12. LinkType = SystemLinkTypes.TaxonomyConcept
  13. }
  14. }
  15. }
  16. };
  17. await managementClient.CreateOrUpdateEntry(entry);
  18. // Add taxonomy concepts to an asset
  19. var asset = new ManagementAsset();
  20. asset.Metadata = new ContentfulMetadata
  21. {
  22. Concepts = new List<Reference>
  23. {
  24. new Reference
  25. {
  26. Sys = new ReferenceProperties
  27. {
  28. Id = "concept-id",
  29. LinkType = SystemLinkTypes.TaxonomyConcept
  30. }
  31. }
  32. }
  33. };
  34. await managementClient.CreateOrUpdateAsset(asset);

Using Concepts with Content Types

You can also add taxonomy concepts to content types to enable concept-based categorization at the content type level:

  1. // Create a content type with taxonomy concepts
  2. var contentType = new ContentType();
  3. contentType.SystemProperties = new SystemProperties()
  4. {
  5. Id = "product"
  6. };
  7. contentType.Name = "Product";
  8. contentType.Fields = new List<Field>()
  9. {
  10. new Field()
  11. {
  12. Name = "Title",
  13. Id = "title",
  14. Type = "Text"
  15. },
  16. new Field()
  17. {
  18. Name = "Description",
  19. Id = "description",
  20. Type = "Text"
  21. }
  22. };
  23. // Add taxonomy concepts to the content type
  24. contentType.Metadata = new ContentfulMetadata
  25. {
  26. Concepts = new List<Reference>
  27. {
  28. new Reference
  29. {
  30. Sys = new ReferenceProperties
  31. {
  32. Id = "product-category-concept",
  33. LinkType = SystemLinkTypes.TaxonomyConcept
  34. }
  35. }
  36. }
  37. };
  38. await managementClient.CreateOrUpdateContentType(contentType);

This allows you to:

  • Categorize entire content types with specific taxonomy concepts
  • Filter and query content based on content type-level concepts
  • Maintain consistent categorization across all entries of a content type
  • Apply concept-based workflows and validations at the content type level

Using the library with the Preview API

This library can also be used with the Preview API. Make sure you have a preview API key configured and set UsePreviewAPI on your client.

  1. var httpClient = new HttpClient();
  2. var options = new ContentfulOptions()
  3. {
  4. DeliveryApiKey = "<content_delivery_api_key>",
  5. PreviewApiKey, "<content_preview_api_key>"
  6. SpaceId = "<space_id>",
  7. UsePreviewApi = true
  8. }
  9. var client = new ContentfulClient(httpClient, options);

Authentication

To get your own content from Contentful, an app should authenticate with an OAuth bearer token.

You can create API keys using the Contentful web interface. Go to the app, open the space that you want to access (top left corner lists all the spaces), and navigate to the APIs area. Open the API Keys section and create your first token. Done.

For more information, check the Contentful REST API reference on Authentication.

Further documentation

You can read the full documentation at https://www.contentful.com/developers/docs/net/ and explore the api at https://contentful.github.io/contentful.net-docs

Reach out to us

You have questions about how to use this library?

  • Reach out to our community forum: Contentful Community Forum
  • Jump into our community slack channel: Contentful Community Slack

You found a bug or want to propose a feature?

  • File an issue here on GitHub: File an issue. Make sure to remove any credentials from your code before sharing it.

You need to share confidential information or have other questions?

  • File a support ticket at our Contentful Customer Support: File support ticket

Get involved

PRs Welcome

We appreciate any help on our repositories. For more details about how to contribute see our CONTRIBUTING.md document.

License

This repository is published under the MIT license.

Code of Conduct

We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.

Read our full Code of Conduct.