Skip to content

Commit 36c25ee

Browse files
ivankamkinivankamkin
committed
Add skill
1 parent ae07429 commit 36c25ee

5 files changed

Lines changed: 268 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,5 @@ obj
88
*.binlog
99
snippets_test/
1010
*.nupkg
11+
12+
/NetFrameworkTests/Configuration.json

‎skills/aspose-barcode-cloud-dotnet/SKILL.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
name: aspose-barcode-cloud-dotnet
3+
description: Write or update C#/.NET code that uses the Aspose.BarCode Cloud SDK (`Aspose.BarCode.Cloud.Sdk.*` namespaces; NuGet package `Aspose.BarCode-Cloud`) to generate, recognize, or scan barcodes through Aspose's cloud REST API. Use this skill whenever the user wants barcode work in C#/.NET, touches files under `submodules/dotnet`, or mentions `GenerateApi`, `RecognizeApi`, `ScanApi`, `Configuration`, `GenerateParams`, `RecognizeBase64Request`, or `ScanBase64Request`. The SDK has several easy-to-miss idioms - `Stream` return values, `JwtToken` switching auth mode, GET methods requiring a public `fileUrl`, `RecognizeBase64Async`/`ScanBase64Async` naming, and the `(clientSecret, clientId)` convenience-constructor order - so consult this skill instead of guessing.
4+
---
5+
6+
# Aspose.BarCode Cloud SDK for .NET
7+
8+
The .NET SDK is a thin generated client over the Aspose BarCode Cloud REST API. Most tasks boil down to choosing the right API class (`GenerateApi`, `RecognizeApi`, `ScanApi`), choosing the right transport variant (GET, body/base64, or multipart), and setting up `Configuration` correctly.
9+
10+
The NuGet package name and code namespaces differ. Install `Aspose.BarCode-Cloud`, then import namespaces under `Aspose.BarCode.Cloud.Sdk.*`.
11+
12+
## Quick start
13+
14+
Use these namespaces in most C# examples:
15+
16+
```csharp
17+
using Aspose.BarCode.Cloud.Sdk.Api;
18+
using Aspose.BarCode.Cloud.Sdk.Interfaces;
19+
using Aspose.BarCode.Cloud.Sdk.Model;
20+
```
21+
22+
Prefer constructing APIs from a `Configuration` instance:
23+
24+
```csharp
25+
var config = new Configuration
26+
{
27+
ClientId = clientId,
28+
ClientSecret = clientSecret
29+
};
30+
31+
var generateApi = new GenerateApi(config);
32+
var recognizeApi = new RecognizeApi(config);
33+
var scanApi = new ScanApi(config);
34+
```
35+
36+
If the task is repo maintenance inside `submodules/dotnet`, read `references/repo-workflow.md`. If the task needs style-matching examples or snippet locations, read `references/snippet-map.md`.
37+
38+
## Authentication
39+
40+
Use one of these two patterns:
41+
42+
1. Let the SDK fetch JWT tokens for you.
43+
44+
```csharp
45+
var config = new Configuration
46+
{
47+
ClientId = clientId,
48+
ClientSecret = clientSecret
49+
};
50+
```
51+
52+
2. Inject a pre-fetched bearer token.
53+
54+
```csharp
55+
var config = new Configuration
56+
{
57+
JwtToken = token
58+
};
59+
```
60+
61+
Setting `Configuration.JwtToken` changes `AuthType` from JWT to external bearer-token mode. Do not also expect `ClientId` and `ClientSecret` to be used after that.
62+
63+
Prefer `new GenerateApi(config)` and the equivalent `RecognizeApi`/`ScanApi` constructors. Convenience constructors exist, but their parameter order is `new GenerateApi(clientSecret, clientId)` and the same pattern applies to the other API classes. That order is easy to reverse, so avoid it unless there is a strong reason.
64+
65+
Inside this repo, `TestsBase` populates `Configuration` from `Tests/Configuration.json` or `TEST_CONFIGURATION_*` environment variables. Examples use `TEST_CONFIGURATION_JWT_TOKEN`; many snippets still use `TEST_CONFIGURATION_ACCESS_TOKEN`. Treat `Configuration.JwtToken` as the stable API surface and mirror the surrounding file when editing existing examples.
66+
67+
## Choose the right API shape
68+
69+
Pick the operation first:
70+
71+
- `GenerateApi`: create a barcode image.
72+
- `RecognizeApi`: decode a known or limited set of barcode types and optionally tune recognition.
73+
- `ScanApi`: auto-detect any barcode types with the smallest API surface.
74+
75+
Then pick the transport variant based on what the user has:
76+
77+
- Public internet URL to an image: use `RecognizeAsync` or `ScanAsync`. The `fileUrl` must be a public URL, not a local path.
78+
- Local file or stream: use `RecognizeMultipartAsync` or `ScanMultipartAsync`.
79+
- Raw bytes already in memory: base64-encode them yourself and use `RecognizeBase64Async` or `ScanBase64Async`.
80+
- Small text plus simple query parameters for barcode generation: use `GenerateAsync`.
81+
- Structured generate payload or larger data: use `GenerateBodyAsync`.
82+
- Multipart form generation: use `GenerateMultipartAsync` when the caller explicitly needs multipart.
83+
84+
Key method names:
85+
86+
- `GenerateAsync`
87+
- `GenerateBodyAsync`
88+
- `GenerateMultipartAsync`
89+
- `RecognizeAsync`
90+
- `RecognizeBase64Async`
91+
- `RecognizeMultipartAsync`
92+
- `ScanAsync`
93+
- `ScanBase64Async`
94+
- `ScanMultipartAsync`
95+
96+
## Non-obvious SDK rules
97+
98+
1. `GenerateAsync`, `GenerateBodyAsync`, and `GenerateMultipartAsync` return `Stream`, not `byte[]` or a file path. Save the stream or pass it onward, and dispose it with `using` or `await using`.
99+
2. `RecognizeBase64Async` and `ScanBase64Async` expect a base64 string in the request model. The SDK does not call `Convert.ToBase64String` for you.
100+
3. `RecognizeBase64Request.BarcodeTypes` accepts multiple `DecodeBarcodeType` values. `RecognizeAsync` and `RecognizeMultipartAsync` take a single `DecodeBarcodeType`.
101+
4. `ScanApi` does not take a barcode type or recognition-quality knobs. Use it when the caller wants auto-detection.
102+
5. GET-based recognize and scan methods only work with remote files reachable by URL. For local files on disk, do not pass a local path to `fileUrl`; use multipart or base64.
103+
6. `BarcodeResponseList` may contain multiple results. Iterate `response.Barcodes` and read `BarcodeValue`, `Type`, `Region`, and `Checksum`.
104+
7. API failures throw `Aspose.BarCode.Cloud.Sdk.Api.ApiException` with an `ErrorCode` HTTP status. Turn on `Configuration.DebugMode = true` when request or response logging would help.
105+
8. The repo has a tested end-to-end pattern where a generated `Stream` is passed directly into `ScanMultipartAsync` without saving to disk first. Reuse that pattern when it fits.
106+
107+
## Common patterns
108+
109+
Generate and save a QR code:
110+
111+
```csharp
112+
var config = new Configuration { ClientId = clientId, ClientSecret = clientSecret };
113+
var api = new GenerateApi(config);
114+
115+
await using Stream generated = await api.GenerateAsync(
116+
EncodeBarcodeType.QR,
117+
"hello from .NET",
118+
imageFormat: BarcodeImageFormat.Png,
119+
textLocation: CodeLocation.None);
120+
121+
await using FileStream file = File.Create("qr.png");
122+
await generated.CopyToAsync(file);
123+
```
124+
125+
Recognize specific barcode types from bytes already in memory:
126+
127+
```csharp
128+
var bytes = await File.ReadAllBytesAsync("many-types.png");
129+
var request = new RecognizeBase64Request
130+
{
131+
BarcodeTypes = new List<DecodeBarcodeType>
132+
{
133+
DecodeBarcodeType.QR,
134+
DecodeBarcodeType.Code128
135+
},
136+
FileBase64 = Convert.ToBase64String(bytes)
137+
};
138+
139+
BarcodeResponseList result = await new RecognizeApi(config).RecognizeBase64Async(request);
140+
```
141+
142+
Auto-scan a local stream without specifying the barcode type:
143+
144+
```csharp
145+
await using Stream image = File.OpenRead("unknown.png");
146+
BarcodeResponseList result = await new ScanApi(config).ScanMultipartAsync(image);
147+
```
148+
149+
## Working in this repo
150+
151+
Read `references/repo-workflow.md` when the task changes SDK source, tests, snippets, package metadata, or generated code in `submodules/dotnet`.
152+
153+
Read `references/snippet-map.md` when the task needs example code, README-aligned snippets, or the closest existing pattern for a generate, recognize, or scan scenario.
154+
155+
## Final checklist
156+
157+
1. Use the right package and namespace pair: NuGet `Aspose.BarCode-Cloud`, namespaces `Aspose.BarCode.Cloud.Sdk.*`.
158+
2. Prefer `Configuration`-based construction and avoid swapping `clientSecret` and `clientId`.
159+
3. Choose GET only for public URLs, multipart for local streams, and base64 or body variants for bytes or structured payloads.
160+
4. Base64-encode body payloads yourself before calling `RecognizeBase64Async` or `ScanBase64Async`.
161+
5. Dispose generated or opened streams.
162+
6. Iterate `response.Barcodes` instead of assuming a single result.
163+
7. When changing the repo, validate with the submodule workflow in `references/repo-workflow.md`.

‎skills/aspose-barcode-cloud-dotnet/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Aspose.BarCode Cloud .NET"
3+
short_description: "Write C# barcode code with Aspose Cloud"
4+
default_prompt: "Use $aspose-barcode-cloud-dotnet to write or update .NET code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud."

‎skills/aspose-barcode-cloud-dotnet/references/repo-workflow.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Dotnet submodule workflow
2+
3+
Use this reference when the task edits SDK source, tests, snippets, package metadata, or generated files inside `submodules/dotnet`.
4+
5+
## Layout
6+
7+
- `src/Api`: public API clients, `Configuration`, and `ApiException`.
8+
- `src/Interfaces`: public interfaces used by tests and examples.
9+
- `src/Model`: request and response models plus enums.
10+
- `src/Internal`: auth handlers, request pipeline, serialization, and debug logging.
11+
- `Tests`: NUnit coverage for configuration, auth, generate, recognize, scan, and error cases.
12+
- `snippets`: documentation snippets that are compiled and executed against the packed NuGet package.
13+
- `examples`: small standalone sample apps such as `GenerateQR` and `ReadQR`.
14+
- `scripts`: packaging, formatting, and snippet-runner helpers.
15+
- `Aspose.BarCode.Cloud.Sdk.sln`: main solution entry point.
16+
17+
## Validation
18+
19+
On Windows, run repo scripts and Make targets through WSL.
20+
21+
From `submodules/dotnet`:
22+
23+
- `make build`
24+
- `make test`
25+
- `make lint`
26+
- `make format`
27+
28+
`make test` does more than unit tests:
29+
30+
- runs `nuget`, which calls `./scripts/pack-nuget.bash` and `./scripts/test-nuget.bash`
31+
- runs `dotnet test -v normal --framework=net$(LATEST_SDK_VERSION)`
32+
- runs `./scripts/run_snippets.sh`
33+
34+
`run_snippets.sh` creates a temporary project, consumes the locally packed `.nupkg`, and executes every snippet. Treat snippet failures as package-consumer regressions, not just sample breakage.
35+
36+
## Test configuration
37+
38+
- Minimal JSON shape lives in `Tests/Configuration.template.json`.
39+
- Tests load `Tests/Configuration.json` first, then fall back to `TEST_CONFIGURATION_*` environment variables.
40+
- `TestsBase` only maps string-valued `Configuration` properties from the environment. Useful names include `TEST_CONFIGURATION_CLIENT_ID`, `TEST_CONFIGURATION_CLIENT_SECRET`, `TEST_CONFIGURATION_JWT_TOKEN`, `TEST_CONFIGURATION_API_BASE_URL`, `TEST_CONFIGURATION_TOKEN_URL`, and `TEST_CONFIGURATION_API_VERSION`.
41+
42+
## Regenerated code workflow
43+
44+
If you change generated SDK code in this mono-repo:
45+
46+
1. Make the desired SDK edit in `submodules/dotnet` so the target behavior is clear.
47+
2. Mirror the change in the matching template under `codegen/Templates` when the file is generated.
48+
3. Stage the dotnet submodule changes.
49+
4. From the repo root, run `make dotnet`.
50+
5. Ensure `submodules/dotnet` has no new unstaged diffs after regeneration.
51+
6. If regeneration reintroduces old code, keep fixing templates until the generated output matches the intended SDK change.
52+
53+
## Useful anchors
54+
55+
- `src/Aspose.BarCode.Cloud.Sdk.csproj`: package metadata, package id, and target framework (`netstandard2.0`).
56+
- `Tests/TestsBase.cs`: how repo tests construct `Configuration`.
57+
- `snippets/Snippets.csproj`: snippet target framework and package reference.

‎skills/aspose-barcode-cloud-dotnet/references/snippet-map.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Snippet and example map
2+
3+
Use this reference when you want the closest existing pattern before writing new `.NET` SDK code or when updating docs, snippets, and examples.
4+
5+
## Small end-user examples
6+
7+
- `examples/GenerateQR/Program.cs`: minimal QR generation to a local file.
8+
- `examples/ReadQR/Program.cs`: minimal QR recognition from local file bytes.
9+
- `snippets/ManualFetchToken.cs`: manual OAuth client-credentials token fetch without the SDK.
10+
11+
## Generate patterns
12+
13+
- `snippets/generate/save/GenerateGet.cs`: simple `GenerateAsync` and save-to-file flow.
14+
- `snippets/generate/save/GenerateBody.cs`: `GenerateBodyAsync` with `GenerateParams`.
15+
- `snippets/generate/save/GenerateMultipart.cs`: multipart generation flow.
16+
- `snippets/generate/set-text/*`: `EncodeData` and `EncodeDataType` examples.
17+
- `snippets/generate/set-size/*`: width, height, resolution, and units examples.
18+
- `snippets/generate/set-colorscheme/*`: foreground and background color examples.
19+
- `snippets/generate/appearance/*`: richer `BarcodeImageParams` examples.
20+
- `snippets/generate/svg/Combine.cs`: generate SVG output and combine results.
21+
22+
## Recognize and scan patterns
23+
24+
- `snippets/read/set-source/RecognizeGet.cs`: recognize from a public URL.
25+
- `snippets/read/set-source/RecognizeMultipart.cs`: recognize from a local stream.
26+
- `snippets/read/set-source/RecognizeBody.cs`: recognize from base64 bytes.
27+
- `snippets/read/set-source/ScanGet.cs`: auto-scan from a public URL.
28+
- `snippets/read/set-source/ScanMultipart.cs`: auto-scan from a local stream.
29+
- `snippets/read/set-source/ScanBody.cs`: auto-scan from base64 bytes.
30+
- `snippets/read/set-target-types/*`: choosing `DecodeBarcodeType` or `List<DecodeBarcodeType>`.
31+
- `snippets/read/set-quality/*`: `RecognitionMode` examples.
32+
- `snippets/read/set-image-kind/*`: `RecognitionImageKind` examples.
33+
34+
## Tests worth copying
35+
36+
- `Tests/GenerateAndThenRecognize.cs`: generate a barcode stream, then scan that same stream end to end.
37+
- `Tests/GenerateTests.cs`: generate via GET and body variants.
38+
- `Tests/RecognizeTests.cs`: recognize via base64 body, multipart, and URL.
39+
- `Tests/ScanTests.cs`: scan via base64 body, multipart, and URL.
40+
- `Tests/JwtAuthTests.cs`: pre-fetched JWT token auth path.
41+
- `Tests/ApiExceptionTests.cs`: expected failures and exception behavior.
42+
- `Tests/ConfigurationTests.cs`: configuration defaults and property behavior.

0 commit comments

Comments
 (0)