You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
All conventions live in **`skills/*/SKILL.md`** and linked **`skills/*/references/*.md`**. This folder only points contributors to those paths so editor-specific config does not duplicate the canonical docs.
8
+
All conventions live in **`skills/*/SKILL.md`**. This folder only points contributors to those paths so editor-specific config does not duplicate the canonical docs.
Copy file name to clipboardExpand all lines: skills/README.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,14 +13,14 @@ Source of truth for detailed guidance. Read [`AGENTS.md`](../AGENTS.md) first, t
13
13
14
14
## How to use these skills
15
15
16
-
-**In the repo:** open `skills/<folder>/SKILL.md` for the topic you need. Longer templates and checklists live under `skills/<folder>/references/*.md` where linked.
16
+
-**In the repo:** open `skills/<folder>/SKILL.md` for the topic you need.
17
17
-**In Cursor / other AI chats:** reference a skill by path, e.g. `skills/http-pipeline/SKILL.md` or `@skills/http-pipeline` if your tooling resolves that alias to this folder.
18
18
19
19
## Example prompts
20
20
21
-
- “Add a new CMA endpoint wrapper following `skills/contentstack-management-dotnet-sdk/SKILL.md` and `references/cma-architecture.md`.”
22
-
- “Adjust retry behavior for 429 responses using `skills/http-pipeline/` and update unit tests under `Contentstack.Management.Core.Unit.Tests/Runtime/Pipeline/`.”
23
-
- “Write a unit test with MSTest + Moq following `skills/testing/references/mstest-patterns.md`.”
21
+
- “Add a new CMA endpoint wrapper following `skills/contentstack-management-dotnet-sdk/SKILL.md`.”
22
+
- “Adjust retry behavior for 429 responses using `skills/http-pipeline/SKILL.md` and update unit tests under `Contentstack.Management.Core.Unit.Tests/Runtime/Pipeline/`.”
23
+
- “Write a unit test with MSTest + Moq following `skills/testing/SKILL.md`.”
24
24
25
25
## When to use which skill
26
26
@@ -36,4 +36,4 @@ Source of truth for detailed guidance. Read [`AGENTS.md`](../AGENTS.md) first, t
36
36
|[`aspnetcore-integration/`](aspnetcore-integration/)|`Contentstack.Management.ASPNETCore` package, `IHttpClientFactory`, DI registration. |
37
37
|[`documentation/`](documentation/)| Building or updating DocFX API documentation under `docfx_project/`. |
38
38
39
-
Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`).**Deep dives:** see the **Quick reference** line at the top of each `SKILL.md` for links to `references/`.
39
+
Each folder contains **`SKILL.md`** with YAML frontmatter (`name`, `description`).
Copy file name to clipboardExpand all lines: skills/aspnetcore-integration/SKILL.md
-5Lines changed: 0 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,8 +29,3 @@ When extending DI support, align with Microsoft.Extensions.DependencyInjection a
29
29
### Core dependency
30
30
31
31
- The ASP.NET Core project references the core management package; public types come from [`Contentstack.Management.Core`](../../Contentstack.Management.Core/).
32
-
33
-
## References
34
-
35
-
-[`../contentstack-management-dotnet-sdk/SKILL.md`](../contentstack-management-dotnet-sdk/SKILL.md) — core client and options.
36
-
-[`../framework/SKILL.md`](../framework/SKILL.md) — NuGet and TFMs.
@@ -29,16 +27,66 @@ description: Use when reviewing or preparing a pull request for contentstack-man
29
27
-**Style:** Follow [`../csharp-style/SKILL.md`](../csharp-style/SKILL.md); match surrounding code.
30
28
-**Documentation:** User-visible behavior changes reflected in `README.md` or package release notes when needed.
31
29
32
-
For markdown blocks to paste into PRs, use [`references/checklist.md`](references/checklist.md).
30
+
For markdown blocks to paste into PRs, copy from **PR review checklist (copy-paste)** below.
33
31
34
32
### Severity (optional labels)
35
33
36
34
-**Blocker:** Build or CI broken; security issue; violates branch policy.
37
35
-**Major:** Missing tests for risky logic; breaking API without process.
38
36
-**Minor:** Naming nits, non-user-facing cleanup.
39
37
40
-
## References
38
+
### PR review checklist (copy-paste)
39
+
40
+
Copy sections into a PR comment when useful. This checklist is for **this** repo (`HttpClient` + pipeline + MSTest), **not** the Content Delivery .NET SDK.
41
+
42
+
#### Branch policy
43
+
44
+
```markdown
45
+
-[ ]**Default:** PR targets **`development`** unless this is a documented **hotfix** to **`main`**
46
+
-[ ] If base is **`main`**: head branch is **`staging`** (see `.github/workflows/check-branch.yml`)
47
+
```
48
+
49
+
#### Breaking changes
50
+
51
+
```markdown
52
+
-[ ] No public method/property removed or narrowed without deprecation / major version plan
53
+
-[ ]`JsonProperty` / JSON names for API-facing models unchanged unless intentional and documented
54
+
-[ ] New required `ContentstackClientOptions` fields have safe defaults or are optional
55
+
-[ ] Strong naming: assembly signing still consistent if keys or `csproj` changed
56
+
```
57
+
58
+
#### HTTP and pipeline
59
+
60
+
```markdown
61
+
-[ ] New or changed HTTP calls go through existing client/pipeline (`ContentstackClient` → `IContentstackService` → pipeline), not ad-hoc `HttpClient` usage inside services without justification
62
+
-[ ] Retry-sensitive changes reviewed alongside `RetryHandler` / `DefaultRetryPolicy` and unit tests under `Contentstack.Management.Core.Unit.Tests/Runtime/Pipeline/`
63
+
-[ ] Headers, query params, and path segments align with CMA docs; no hardcoded production URLs where options.Host should be used
64
+
```
65
+
66
+
#### Services and query API
67
+
68
+
```markdown
69
+
-[ ]`IContentstackService` implementations set `ResourcePath`, `HttpMethod`, `Parameters` / `QueryResources` / `PathResources` / `Content` consistently with sibling services
70
+
-[ ] New fluent `Query` methods only add to `ParameterCollection` with correct API parameter names
71
+
```
72
+
73
+
#### Tests
74
+
75
+
```markdown
76
+
-[ ] Unit tests use MSTest; `sh ./Scripts/run-unit-test-case.sh` passes for core changes
77
+
-[ ] Integration tests only when needed; no secrets committed (`appsettings.json` stays local)
78
+
```
79
+
80
+
#### Security and hygiene
81
+
82
+
```markdown
83
+
-[ ] No API keys, tokens, or passwords in source or test data checked into git
- Adding or changing `ContentstackClient` behavior, options, or service entry points.
@@ -15,6 +13,8 @@ description: Use when changing or using the CMA client API, authentication, or N
15
13
16
14
## Instructions
17
15
16
+
Official API reference: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/).
17
+
18
18
### Packages and entry points
19
19
20
20
| Package ID | Project | Role |
@@ -45,13 +45,92 @@ OAuth-related code lives under [`Services/OAuth/`](../../Contentstack.Management
45
45
### Integration boundaries
46
46
47
47
- The SDK talks to Contentstack **Management** HTTP APIs. Do not confuse with Delivery API clients.
48
-
- HTTP behavior (retries, handlers) is documented under [`../framework/SKILL.md`](../framework/SKILL.md) and [`../http-pipeline/SKILL.md`](../http-pipeline/SKILL.md).
48
+
- Retries, handlers, and pipeline details: [`../http-pipeline/SKILL.md`](../http-pipeline/SKILL.md). TFMs and packaging: [`../framework/SKILL.md`](../framework/SKILL.md).
49
+
50
+
### Architecture
51
+
52
+
This describes how requests flow through **this** SDK. It is **not** the Content Delivery (CDA) client: there is no `HttpWebRequest`-only layer or delivery-token query-string-only rule set here.
53
+
54
+
#### Entry and configuration
55
+
56
+
1.**`ContentstackClient`** ([`ContentstackClient.cs`](../../Contentstack.Management.Core/ContentstackClient.cs)) is the public entry point.
3. The client builds a **`ContentstackRuntimePipeline`** in `BuildPipeline()`: **`HttpHandler`** → **`RetryHandler`** (see [`../http-pipeline/SKILL.md`](../http-pipeline/SKILL.md)).
59
+
60
+
#### Stack-scoped API
61
+
62
+
-**`Stack`** ([`Models/Stack.cs`](../../Contentstack.Management.Core/Models/Stack.cs)) is obtained from the client (e.g. `client.Stack(apiKey, managementToken)` or overloads). Most management operations are stack-relative.
63
+
- Domain types under **`Models/`** (entries, assets, content types, etc.) expose methods that construct or call **`IContentstackService`** implementations.
64
+
65
+
#### Service interface and invocation
66
+
67
+
-**`IContentstackService`** ([`Services/IContentstackService.cs`](../../Contentstack.Management.Core/Services/IContentstackService.cs)) defines one CMA operation: resource path, HTTP method, headers, query/path resources, body (`HttpContent`), and hooks to build the outbound request and handle the response.
68
+
- The client executes services via **`InvokeSync`** / **`InvokeAsync`**, which run the pipeline and return **`ContentstackResponse`**.
69
+
70
+
Important members on `IContentstackService`:
71
+
72
+
-**`Parameters`** — [`ParameterCollection`](../../Contentstack.Management.Core/Queryable/ParameterCollection.cs) for typed query/body parameters (used by list/query flows).
-**`UseQueryString`** — some operations send parameters as query string instead of body.
75
+
-**`CreateHttpRequest`** / **`OnResponse`** — integrate with [`ContentstackHttpRequest`](../../Contentstack.Management.Core/Http/ContentstackHttpRequest.cs) and response parsing.
76
+
77
+
Concrete services live under **`Services/`** (including nested folders by domain, e.g. stack, organization, OAuth).
78
+
79
+
#### OAuth and auth
80
+
81
+
Implementation details span **`OAuthHandler`**, **`Services/OAuth/`**, and client token dictionaries on **`ContentstackClient`** (high-level behavior is under **Authentication** above).
82
+
83
+
#### Adding a feature (checklist)
84
+
85
+
1. Confirm the CMA contract (path, method, query vs body) from [official API docs](https://www.contentstack.com/docs/developers/apis/content-management-api/).
86
+
2. Implement or extend an **`IContentstackService`** (or reuse patterns from a sibling service in `Services/`).
87
+
3. Expose a method on the appropriate **`Stack`** / model type; keep public API consistent with existing naming.
88
+
4. Add **unit tests** (MSTest + mocks); add **integration** tests only when live API coverage is required.
89
+
5. If behavior touches HTTP retries or status codes, coordinate with [`../http-pipeline/SKILL.md`](../http-pipeline/SKILL.md).
90
+
91
+
### Query and parameters (fluent list API)
92
+
93
+
The management SDK exposes a **fluent `Query`** type for listing resources (stacks, entries, assets, roles, etc.). It is separate from the Content Delivery SDK’s query DSL.
94
+
95
+
#### Types
96
+
97
+
| Type | Location | Role |
98
+
| ---- | -------- | ---- |
99
+
|**`Query`**|[`Queryable/Query.cs`](../../Contentstack.Management.Core/Queryable/Query.cs)| Fluent methods add entries to an internal `ParameterCollection`, then `Find` / `FindAsync` runs `QueryService`. |
100
+
|**`ParameterCollection`**|[`Queryable/ParameterCollection.cs`](../../Contentstack.Management.Core/Queryable/ParameterCollection.cs)|`SortedDictionary<string, QueryParamValue>` with overloads for `string`, `double`, `bool`, `List<string>`, etc. |
101
+
102
+
#### Typical usage pattern
103
+
104
+
Models such as **`Entry`**, **`Asset`**, **`Role`**, **`Stack`** expose **`Query()`** returning a **`Query`** bound to that resource path. Chain parameters, then call **`Find()`** or **`FindAsync()`**:
105
+
106
+
```csharp
107
+
// Illustrative — see XML examples on Query/Stack/Entry in the codebase.
108
+
ContentstackResponseresponse=client
109
+
.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
110
+
.ContentType("<CONTENT_TYPE_UID>")
111
+
.Entry()
112
+
.Query()
113
+
.Limit(10)
114
+
.Skip(0)
115
+
.Find();
116
+
```
117
+
118
+
Requirements enforced by **`Query`**:
119
+
120
+
- Stack must be logged in where applicable (`ThrowIfNotLoggedIn`).
121
+
- Stack API key must be present for the call (`ThrowIfAPIKeyEmpty`).
122
+
123
+
#### Extra parameters on `Find`
124
+
125
+
`Find(ParameterCollection collection = null)` and `FindAsync` merge an optional **`ParameterCollection`** into the query before building **`QueryService`**. Use this when ad-hoc parameters are not exposed as fluent methods.
126
+
127
+
#### Implementing new fluent methods
128
+
129
+
1. Add a method on **`Query`** that calls `_collection.Add("api_key", value)` (or the appropriate `ParameterCollection` overload).
130
+
2. Return **`this`** for chaining.
131
+
3. Add XML documentation with a short `<example>` consistent with existing **`Query`** members.
132
+
4. Add unit tests if serialization or parameter keys are non-trivial.
49
133
50
-
##References
134
+
#### Relationship to `IContentstackService`
51
135
52
-
-[`references/cma-architecture.md`](references/cma-architecture.md) — architecture and invocation flow.
List operations ultimately construct a **`QueryService`** that implements **`IContentstackService`** and is executed through **`ContentstackClient.InvokeSync` / `InvokeAsync`**. Path and HTTP details live on the service; the fluent API only shapes **`ParameterCollection`**. For the overall request path, see **Architecture** above.
0 commit comments