Skip to content

Commit be26a0b

Browse files
ivankamkinDenis-Averin
ivankamkin
and
Denis-Averin
authored
Add skill for AI Agents (#123)
* Add skill * Add AI agent skill section to README * Rename .NET skill to generate-and-scan-barcode --------- Co-authored-by: Denis Averin <59285247+Denis-Averin@users.noreply.github.com>
1 parent f13b823 commit be26a0b

6 files changed

Lines changed: 272 additions & 1 deletion

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

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ To use these SDKs, you will need Client Id and Client Secret which can be looked
3838

3939
The complete source code is available in this repository folder. You can either directly use it in your project via source code or get [NuGet distribution](https://www.nuget.org/packages/Aspose.BarCode-Cloud/) (recommended).
4040

41+
## AI Agent Skills
42+
43+
This repository includes an AI-agent skill in [`skills/generate-and-scan-barcode-dotnet/SKILL.md`](skills/generate-and-scan-barcode-dotnet/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns.
44+
4145
## Prerequisites
4246

4347
To use Aspose.BarCode Cloud SDK for .NET you need to register an account with [Aspose Cloud](https://www.aspose.cloud) and lookup/create Client Secret and Client Id at [Cloud Dashboard](https://dashboard.aspose.cloud/applications). There is free quota available. For more details, see [Aspose Cloud Pricing](https://purchase.aspose.cloud/).
@@ -252,4 +256,3 @@ Class | Method | HTTP request | Description
252256
- [Model.RecognizeBase64Request](docs/RecognizeBase64Request.md)
253257
- [Model.RegionPoint](docs/RegionPoint.md)
254258
- [Model.ScanBase64Request](docs/ScanBase64Request.md)
255-

‎skills/generate-and-scan-barcode-dotnet/SKILL.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
name: generate-and-scan-barcode-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+
# Generate and scan barcode in .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/generate-and-scan-barcode-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: "Generate and scan barcode in .NET"
3+
short_description: "Use Aspose.BarCode Cloud from .NET"
4+
default_prompt: "Use $generate-and-scan-barcode-dotnet to write or update .NET code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud."

‎skills/generate-and-scan-barcode-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/generate-and-scan-barcode-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)