[tomasr78]

Rewrites README.md so its code runs as copied, adds a quick start and a free-token link, uses C# task wording, and makes the repository README the one that nuget.org shows. No SDK code changes; those come in 3.3.0.

What changes

• README.md: new top, a quick start, a task table, "... in C#" sections for 8 tasks, every snippet a complete program, a security section. Details below.
• One README for GitHub and NuGet. ConvertApi/ConvertApi.csproj packs ../README.md as README.md. The drifted ConvertApi/docs/README.md is deleted.
• .github/workflows/publish.yml: a step before "Build and pack" rewrites utm_source=github to utm_source=nuget in the run's checkout, so the packed copy's sign-up links are tagged for nuget.org. "Check the package" now fails if the packed README.md is missing or still says utm_source=github.
• RELEASING.md (step 3) and CHANGELOG.md ([Unreleased]) describe both.
• main merged in on 2026-11-09, bringing Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84. The only conflict was in CHANGELOG.md, where both branches had opened ## [Unreleased]. It is now one section: Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84's Fixed entry, then one Changed list with Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84's two entries first and this PR's two after them.

Before and after

	Before (main, 510 lines)	After
Top	"ConvertAPI C# Client", an overview paragraph, a 29-bullet feature list	H1 "ConvertAPI C# SDK for .NET", one line naming the tasks, 4 badges (NuGet version, NuGet downloads, build, MIT), "Free trial: 250 conversions, no credit card. Get your API token"
First complete program	Line 482 of 510; reads c:\source\test.docx and saves to c:\	"Quick start" at line 9: dotnet add package ConvertApi, set CONVERTAPI_TOKEN, a 6-line program that converts the hosted sample DOCX to PDF in the current folder; one line each on .NET 10 file-based apps, .NET Framework and ASP.NET Core user secrets
Output folder	29 snippets save to C:\output\ and line 493 to c:\. In 3.2.2, SaveFilesAsync never creates folders, so these throw unless the folder exists, and always on macOS and Linux	Every snippet saves to a relative output folder that it creates with Directory.CreateDirectory. 3.2.2, the version dotnet add package ConvertApi installs today, needs that line. With #84, SaveFilesAsync creates the folder itself, and the line is harmless
Snippets	3-line fragments without using ConvertApiDotNet; or a convertApi object	Every conversion snippet is a complete program that runs when pasted into Program.cs
Result files	ProcessedFile[] files = result.Files; (the type is now ConvertApiFile) and SaveFilesAsync without await	ConvertApiFile[], awaited, plus saving one file, reading a stream and DeleteFilesAsync
User information	convert.GetUserAsync(): no such variable	convertApi.GetUserAsync()
PDF to JPG parameters	ScaleImage and ScaleProportions, which pdf-to-jpg ignores	FitToSize with ImageWidth and ImageHeight: the thumbnail fits in 300 x 300 (231 x 300 on the test PDF)
PDF/A	pdfa2b here, pdfa2 in the NuGet README. The API rejects pdfa2 with 400 Bad Request	pdfA2b, spelled as in the API spec
Converter names	web to pdf, pdf to watermark, any to zip, and RotatePage for rotation. None of these is in the current API spec at https://v2.convertapi.com/info/openapi (the first three still work on staging; the rotate parameter is Angle, default 90)	html to pdf with Url, text-watermark, file to zip, Angle
HTML to PDF	A URL only	An HTML file, an HTML string and a web page URL
Errors	"Secret is not provided or no additional seconds left in the account"	401 = token missing or invalid, 403 = no conversions left or account suspended, 503 = retry; plus the ArgumentNullException when the variable is not set
Calls to action	An untagged link to /a/authentication	The same tagged sign-up link twice: at the top and in "Set the API token". ReturnUrl lands new users and signed-in customers on their tokens. Tags are top-level, not inside ReturnUrl
Headings	"Office to PDF", "HTML/Web to PDF", ...	"... in C#" only for Word (DOCX) to PDF, HTML to PDF, Excel to PDF, PDF to Word, PDF to JPG or PNG, extract text from PDF, compress PDF and HTML to DOCX. The other task headings keep their words, so their anchors still work
Feature list	29 bullets	A task table that links each snippet and its example file by /blob/ URL
More examples	A /tree/ link to the Examples folder, then per-file links	The "### More examples" heading (#more-examples) and its per-file links from #81 are kept; the /tree/ link is gone
Compatibility	Above Usage; lists Xamarin and UWP	Below Usage; without them
Security	None	"Security, data and support": files stored at most 3 hours, DeleteFilesAsync, encryption, server locations, compliance, status and support links
Small fixes	"using a headless Chrome browser", "Refere", an http MIT link, /doc/... links that redirect	Engine phrase removed, typo fixed, https links, final /docs/... URLs
nuget.org	ConvertApi/docs/README.md: H1 "ConvertAPI NuGet Package", "C#" 0 times, no example links, pdfa2	The repository README, with utm_source=nuget

All links are absolute https URLs, except in-page anchors. nuget.org renders those too: its current page has heading ids and working #... links. The badges use img.shields.io, which nuget.org allows. The README is plain ASCII and uses no HTML.

Tested snippets

Every C# block in the new README was run on macOS with .NET SDK 10.0.401, against the staging API (https://stag-v2.convertapi.com). Each block became Program.cs of a fresh dotnet new console project with ConvertApi 3.2.2 from nuget.org, byte for byte. A separate module-initializer file pointed the SDK at staging, the way Examples/ConverterCatalogDemo sets ApiBaseUri. The output files were then checked with pdfinfo, pdftotext, qpdf, sips and unzip.

All 43 blocks passed:

README section	Input	Result
Quick start	hosted document.docx	document.pdf in the current folder (2 pages); prints its full path
Set the API token (one line)	-	compiles inside a minimal program
Set the conversion location (one line)	-	compiles; ApiBaseUri reads https://eu-v2.convertapi.com
Convert Word (DOCX) to PDF in C#	document.docx	output/document.pdf, 2 pages with the document's text
Convert HTML to PDF in C#: file	page.html	output/page.pdf, A4, with the page's text
Convert HTML to PDF in C#: string	-	output/invoice.pdf with "Invoice 1001"
Convert HTML to PDF in C#: URL	https://www.example.com	output/www_example_com.pdf, title "Example Domain"
Convert Excel to PDF in C#	spreadsheet.xlsx	output/spreadsheet.pdf
Convert PDF to Word in C#	document.pdf (6 pages)	output/document.docx
Convert PDF to JPG or PNG in C#	document.pdf	6 JPGs: document.jpg, document-2.jpg ... document-6.jpg
Extract text from PDF in C#	document.pdf	the text printed to the console
Compress PDF in C#	document.pdf, 1,086,060 bytes	246,543 bytes
Convert HTML to DOCX in C#	page.html	output/page.docx with the page's heading
PowerPoint to PDF	presentation.pptx	7 pages
Image to PDF	image.jpg	1 page
PDF to PowerPoint	document.pdf	6 slides
eBook conversion	book.epub	160 pages
Email conversion	email.eml	output/email.pdf
Merge documents	first.pdf (6 pages), second.pdf (1)	7 pages
Split PDF	document.pdf	6 files
Rotate pages	document.pdf	pages rotated 90 degrees
Delete pages	document.pdf	6 pages to 4
Add watermark	document.pdf	"Confidential" on the pages
Flatten PDF	form.pdf, 19 form fields	0 form fields
Repair PDF	a damaged PDF	2 pages, qpdf --check clean
Rasterize PDF	document.pdf	no selectable text left, pages are images
Password protect PDF	document.pdf	opening needs the password
Remove PDF password	the protected PDF from the row above	not encrypted
Redact PDF	document.pdf	output/document.pdf, 6 pages
Convert to PDF/A	document.pdf	XMP says PDF/A part 2, conformance B
Remove metadata	document.pdf with an author	title, subject, author, creator and keywords empty
Extract tables from PDF	document.pdf	output/document.xlsx
Extract images from PDF	document.pdf	18 PNG files
Extract form data	form.pdf	output/form.fdf
Extract email attachments	email.eml	the attached file
Generate document from template	template.docx with {{name}}	PDF reads "Hello John"
Compare documents	original.docx, revised.docx	DOCX with 144 insertions and 115 deletions as tracked changes
Create ZIP archive	document.pdf, document.docx	output/document.zip with both files
Work with the result	document.pdf	cost and 6 files printed, 6 JPGs and first-page.jpg saved, server files deleted
Convert a file from a URL	hosted presentation.pptx	38 pages
Additional conversion parameters	document.pdf	output/document.jpg, 231 x 300 pixels
Handle errors	document.docx	output/document.pdf; with an invalid token it prints the 401 line
User information	-	prints "Conversions used: N of M"

Also run:

• .NET 10 file-based app: #:package ConvertApi@* plus the quick start, with one test-only line pointing at staging, saved document.pdf. #:package ConvertApi without a version fails with NU1015, so the note says @*.
• ASP.NET Core note: dotnet new web, dotnet user-secrets init, dotnet user-secrets set ConvertApi:Token ... and new ConvertApi(builder.Configuration["ConvertApi:Token"]) converted a file on staging. set fails without init, so the note has both.
• .NET Framework note: the quick start inside static async Task Main(), with using System; and using System.Threading.Tasks;, compiles for net48 with C# 7.3. Not run: there is no Mono on this Mac.
• Side claims: a .doc file with "docx" converts; "png" in place of "jpg" gives PNG pages; an .msg file with "eml" converts; non-ASCII text in the HTML string survives without a <meta charset>; DeleteFilesAsync deleted 7 files (6 results and the upload); an invalid token prints 401 Unauthorized: {"Code":4011,"Message":"Unauthorized. Invalid or missing API credentials."}.
• Conversion location: the line compiles and sets the address; https://eu-v2.convertapi.com/user answers 401 without a token. Nothing was converted on production.
• Against the merged main, with Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84: after the merge, the library was packed from this branch as 3.3.0-local.pr83 into a local feed, and all 43 blocks were run again on staging against it. All 43 passed, and every output check matched the 3.2.2 run. The merged tree also passes the build check's steps: restore, a build of all 23 projects, the 4 unit tests and pack. Its only 3 warnings come from two examples this PR does not touch (ConverterCatalogDemo, GetConverterInfoDemo).

Package

• dotnet pack: README.md sits at the package root, byte-identical to the repository's README.md, and the nuspec has <readme>README.md</readme>. The NU5048 PackageIconUrl warning was already there; 3.3.0 replaces the icon.
• The publish steps, run by hand on a copy: the retag step turns both sign-up links into utm_source=nuget, and the new check passes. The check fails (exit 1) on a package packed without the retag, and on one without a README.
• After the merge with main, the pack result is the same: README.md at the package root, byte-identical to the repository's.

Not in this PR

• SDK fixes planned for 3.3.0 that are not on main yet: the SDK reading CONVERTAPI_TOKEN, clearer 401 and 403 messages, the package icon. Two of the planned fixes, SaveFilesAsync creating its folder and SaveFileAsync replacing a longer file, are on main since Fix SaveFileAsync keeping old bytes when it overwrites a longer file #84.
• The examples still use names that are not in the current API spec: web (ConvertUrlToPdf), watermark and watermark-overlay (WatermarkPdf), jpg to zip (Workflow). web and watermark still work on staging; the other two were not tried. CreatePdfThumbnail is fixed in PDF thumbnail example: fix the comment, keep the thumbnail inside 300x300 #82.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the documentation and shared README packaging changes.

No open issues 🎉

What changed in this PR

Improves the .NET SDK’s onboarding documentation and uses one README for both GitHub and NuGet, without changing SDK implementation code.

Changes:

• Adds a quick start, task navigation, complete C# conversion examples, and security guidance.
• Packages the repository README and removes the separate NuGet copy.
• Updates publishing to retag README links for NuGet and validate the packaged README.

File	Description
RELEASING.md	Documents the shared README and NuGet link tagging.
README.md	Reworks setup, task examples, error handling, and security guidance.
ConvertApi/​docs/​README.md	Removes the duplicated NuGet README.
ConvertApi/​ConvertApi.csproj	Packs the repository README at the package root.
CHANGELOG.md	Records the documentation and packaging changes.
.github/​workflows/​publish.yml	Retags links and checks the packaged README before publishing.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The README’s hard-coded .NET 10 output path can cause FileNotFoundException with other target frameworks or debugger working directories and should instead reference the configured working directory.

1 open issue

• Use the debugger's working directory for the input file · New

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues remain for the documentation and packaging changes.

No open issues 🎉

1 resolved since last review

• Use the debugger's working directory for the input file

_{Review effort: Balanced}