Feature/#163 documentation enhancement (#165)

* feat: Add CryptoNet.Examples project with various encryption examples

- Introduced `Program.cs` to demonstrate DSA and AES examples.
- Added test files for AES and RSA examples including `.docx`, `.pdf`, `.png`, and `.xlsx`.
- Updated `CryptoNet.ExtPack` project to improve MD5 calculation and string comparison.
- Modified solution file to include the new `CryptoNet.Examples` project.
- Removed outdated contributing guidelines from `README.md`.
- Deleted `RELEASE-NOTES` file as it was no longer needed.
- Created various PowerShell scripts for build, code coverage, Docker setup, documentation generation, and NuGet validation.
- Added migration guide for transitioning from CryptoNet v2.4.0 to v3.4.3, detailing breaking changes and updates.
- Updated table of contents in documentation to include migration and examples sections.

* #163 Support UTF-8 and special character encryption

Added `Example_6_Wokring_With_Special_Character_Text` to demonstrate encryption and decryption of text with special characters (e.g., emojis) using UTF-8 encoding. Updated `Program.cs` to include the new example and re-enable previously commented-out AES and RSA examples.

Modified `BytesToString` and `StringToBytes` in `ExtShared.cs` to use UTF-8 encoding instead of ASCII for better handling of non-ASCII characters. Updated `migration.md` with a TODO note about encrypting strings with special characters and suggested using byte arrays for clarity.

* #163 Refactor examples, docs, and improve developer tooling

Refactored example methods to use PascalCase, added XML comments, and improved variable naming for clarity. Standardized key management APIs across AES, DSA, and RSA examples. Enhanced file encryption examples to support arbitrary file types.

Updated documentation with detailed examples, migration guides, and a new `tooling.md` for developer workflows. Improved CI/CD documentation and reusable workflow examples in `CONTRIBUTING.md`.

Added support for special characters in encryption examples and advanced PEM operations. Updated project structure to include a "Docs" project and additional documentation files. Enhanced code readability, consistency, and developer experience.

Author: maythamfahmi

.github/copilot-instructions.md

@@ -0,0 +1,263 @@
+# CryptoNet - AI Coding Agent Instructions
+
+## Project Overview
+CryptoNet is a cross-platform .NET cryptography library providing RSA, AES, and DSA implementations. The core library targets .NET Standard 2.0 for maximum compatibility, while tests and examples use .NET 8.0.
+
+## Architecture
+
+### Project Structure
+- **CryptoNet** (netstandard2.0): Core library with `CryptoNetRsa`, `CryptoNetAes`, `CryptoNetDsa` classes
+- **CryptoNet.Models** (netstandard2.0): Shared models (`CryptoNetInfo`, `RsaDetail`, `AesDetail`, `DsaDetail`, `KeyType`, `EncryptionType`)
+- **CryptoNet.ExtShared** (netstandard2.0): Internal utilities for certificate handling and byte operations
+- **CryptoNet.ExtPack** (net8.0): Extension methods for MD5 hashing, PEM export, and content validation
+- **CryptoNet.UnitTests** (net8.0): NUnit tests with NUnit, Moq, Shouldly assertions
+
+### Key Dependencies
+All projects use **Central Package Management** via `Directory.Packages.props`. Never add package versions directly to `.csproj` files—only add `<PackageReference Include="PackageName" />` without versions.
+
+### NuGet Packaging Pattern
+The main `CryptoNet.csproj` uses `PrivateAssets="all"` for project references to `ExtShared` and `Models`, then explicitly includes their DLLs in the package via `IncludeReferencedDllsInPackage` target. This creates a self-contained NuGet package.
+
+## Development Workflows
+
+### Building & Testing
+```powershell
+# Standard build and test
+dotnet build
+dotnet test --configuration Release --no-build
+
+# Code coverage with HTML report
+.\Scripts\run_codecoverage.ps1  # Runs tests, generates coverage, opens in Edge
+
+# Docker build
+.\Scripts\run_docker_build.ps1
+# or: docker build . --file .\Dockerfile --tag cryptonet-service:latest
+```
+
+### Documentation Generation
+Documentation uses **DocFX** to generate API docs from XML comments:
+```powershell
+.\Scripts\run_docs.ps1  # Cleans, builds, serves on localhost:8080
+
+# Setup (one-time): dotnet tool install -g docfx
+```
+
+The `index.md` is kept in sync with `README.md`:
+```powershell
+.\Scripts\run_update_index.ps1  # Adds YAML header and appends README content
+```
+
+### Release Process
+Releases are tag-based with version format `vX.Y.Z` or `vX.Y.Z-previewYYYYMMDDHmm`:
+```powershell
+# Preview release
+.\Scripts\run_release.ps1 -VersionNumber 3.0.0 -IsPreview $true
+
+# Production release
+.\Scripts\run_release.ps1 -VersionNumber 3.0.0 -IsPreview $false
+```
+
+Pushing tags triggers GitHub Actions workflows (`cd-release.yml`, `cd-release-preview.yml`) that build, test, pack, and publish to NuGet.
+
+## Coding Conventions
+
+### Code Quality Standards
+- **Nullable reference types enabled**: Use `?` for nullable types, handle nulls explicitly
+- **TreatWarningsAsErrors**: All warnings are errors—code must be warning-free
+- **XML documentation required**: Public APIs must have `<summary>` tags (enforced by `GenerateDocumentationFile`)
+- **Deterministic builds**: `<Deterministic>true</Deterministic>` in `Directory.Build.Props`
+
+### Interface Pattern
+All main crypto classes implement interfaces (`ICryptoNetRsa`, `ICryptoNetAes`, `ICryptoNetDsa`) which inherit from `ICryptoNet`. This base interface defines:
+```csharp
+CryptoNetInfo Info { get; }
+byte[] EncryptFromString(string content);
+string DecryptToString(byte[] bytes);
+byte[] EncryptFromBytes(byte[] bytes);
+byte[] DecryptToBytes(byte[] bytes);
+```
+
+### Constructor Overloading Pattern
+Crypto classes follow a consistent constructor pattern:
+```csharp
+// Self-generated keys
+public CryptoNetRsa(int keySize = 2048)
+
+// String key (XML or PEM)
+public CryptoNetRsa(string key, int keySize = 2048)
+
+// File-based key
+public CryptoNetRsa(FileInfo fileInfo, int keySize = 2048)
+
+// X509 certificate
+public CryptoNetRsa(X509Certificate2? certificate, KeyType keyType, int keySize = 2048)
+```
+
+### Testing Patterns
+Tests use **NUnit** with **Shouldly** for assertions:
+```csharp
+result.ShouldBe(expected);  // NOT Assert.AreEqual
+ExtensionPack.CheckContent(original, decrypted).ShouldBeTrue();  // MD5-based content comparison
+```
+
+Test resource files are in `Resources/` with `<CopyToOutputDirectory>Always</CopyToOutputDirectory>`.
+
+## Common Pitfalls
+
+### Version Management
+- **Never** hardcode versions in individual `.csproj` files
+- Update versions in `Directory.Build.Props` (global) and `Directory.Packages.props` (package versions)
+- Release versions must match the format `^\d+\.\d+\.\d+$` in `run_release.ps1`
+
+### Cross-Platform Compatibility
+- Core library must remain .NET Standard 2.0 compatible
+- Avoid .NET 8+ specific APIs in `CryptoNet`, `CryptoNet.Models`, `CryptoNet.ExtShared`
+- Use `System.Security.Cryptography` types from .NET Standard 2.0
+
+### GitHub Actions Workflows
+- **Never add `runs-on` to caller jobs** when using reusable workflows (see `CONTRIBUTING.md`)
+- Reusable workflows declare `on: workflow_call` and define their own `runs-on`
+- Example: `cd-build-test-pack.yml` is a reusable workflow called by release workflows
+
+### File Header Conventions
+All C# files include copyright headers:
+```csharp
+// <copyright file="FileName.cs" company="itbackyard" year="2021">
+// Copyright (c) 2021 All Rights Reserved
+// </copyright>
+// <author>Maytham Fahmi</author>
+// <date>DD-MM-YYYY HH:MM:SS</date>
+// <summary>part of CryptoNet project</summary>
+```
+
+## Key Files
+- `Directory.Build.Props`: Global MSBuild properties (version, warnings, symbols)
+- `Directory.Packages.props`: Central package version management
+- `docfx.json`: DocFX configuration for API documentation
+- `RELEASE-NOTES`: Changelog file read during NuGet packing (see `PrepareReleaseNotes` target)
+- `coverlet.runsettings`: Code coverage configuration
+
+## Development Tips
+- Use `ExtShared.LoadFileToString()` for reading key files consistently
+- Use `ExtensionPack.CheckContent()` for MD5-based content validation in tests
+- Key files are stored/loaded using `SaveKey(FileInfo, bool isPrivate)` and constructor overloads
+- The `Info` property exposes algorithm details, key types, and loaded keys for inspection
+
+## Migration Guide: Old API → Latest CryptoNet v3+
+
+### API Changes Summary
+- **Removed**: `ExportKey()`, `ExportKeyAndSave()` methods
+- **Replaced with**: `GetKey()` and `SaveKey()` methods
+- **Namespace change**: `CryptoNetUtils` → `ExtShared.ExtShared`
+- All crypto classes now expose `Info` property with algorithm details
+
+### AES Examples
+
+#### Old: Encrypt/Decrypt with Symmetric Key
+```csharp
+// OLD API (v2.x)
+ICryptoNet cryptoNet = new CryptoNetAes();
+var key = cryptoNet.ExportKey();
+ICryptoNet encryptClient = new CryptoNetAes(key);
+var encrypt = encryptClient.EncryptFromString(data);
+ICryptoNet decryptClient = new CryptoNetAes(key);
+var decrypt = decryptClient.DecryptToString(encrypt);
+```
+
+#### New: Encrypt/Decrypt with Symmetric Key
+```csharp
+// NEW API (v3.x)
+ICryptoNetAes cryptoNet = new CryptoNetAes();
+var key = cryptoNet.GetKey();  // Changed from ExportKey()
+
+ICryptoNetAes encryptClient = new CryptoNetAes(key);
+var encrypt = encryptClient.EncryptFromString(data);
+
+ICryptoNetAes decryptClient = new CryptoNetAes(key);
+var decrypt = decryptClient.DecryptToString(encrypt);
+```
+
+#### Old: Export and Import Symmetric Key from File
+```csharp
+// OLD API (v2.x)
+ICryptoNet cryptoNet = new CryptoNetAes();
+var file = new FileInfo("symmetric.key");
+cryptoNet.ExportKeyAndSave(file);
+var encrypt = cryptoNet.EncryptFromString(data);
+ICryptoNet cryptoNetImport = new CryptoNetAes(file);
+var decrypt = cryptoNetImport.DecryptToString(encrypt);
+```
+
+#### New: Save and Load Symmetric Key from File
+```csharp
+// NEW API (v3.x)
+ICryptoNetAes cryptoNet = new CryptoNetAes();
+var file = new FileInfo("symmetric.key");
+cryptoNet.SaveKey(file);  // Changed from ExportKeyAndSave()
+
+var encrypt = cryptoNet.EncryptFromString(data);
+
+ICryptoNetAes cryptoNetImport = new CryptoNetAes(file);
+var decrypt = cryptoNetImport.DecryptToString(encrypt);
+```
+
+### RSA Examples
+
+#### Old: Generate RSA Key Pair and Save
+```csharp
+// OLD API (v2.x)
+ICryptoNet cryptoNet = new CryptoNetRsa();
+cryptoNet.ExportKeyAndSave(new FileInfo("private.key"), true);
+cryptoNet.ExportKeyAndSave(new FileInfo("public.key"), false);
+ICryptoNet pubKeyCrypto = new CryptoNetRsa(new FileInfo("public.key"));
+var encrypt = pubKeyCrypto.EncryptFromString(data);
+ICryptoNet priKeyCrypto = new CryptoNetRsa(new FileInfo("private.key"));
+var decrypt = priKeyCrypto.DecryptToString(encrypt);
+```
+
+#### New: Generate RSA Key Pair and Save
+```csharp
+// NEW API (v3.x)
+ICryptoNetRsa cryptoNet = new CryptoNetRsa();
+cryptoNet.SaveKey(new FileInfo("private.key"), true);   // Changed from ExportKeyAndSave()
+cryptoNet.SaveKey(new FileInfo("public.key"), false);   // Changed from ExportKeyAndSave()
+
+ICryptoNetRsa pubKeyCrypto = new CryptoNetRsa(new FileInfo("public.key"));
+var encrypt = pubKeyCrypto.EncryptFromString(data);
+
+ICryptoNetRsa priKeyCrypto = new CryptoNetRsa(new FileInfo("private.key"));
+var decrypt = priKeyCrypto.DecryptToString(encrypt);
+```
+
+### X509 Certificate Examples
+
+#### Old: Use X509 Certificate for Encryption
+```csharp
+// OLD API (v2.x)
+X509Certificate2? cert = CryptoNetUtils.GetCertificateFromStore("CN=Maytham");
+ICryptoNet publicKeyCrypto = new CryptoNetRsa(cert, KeyType.PublicKey);
+var encrypt = publicKeyCrypto.EncryptFromString(data);
+ICryptoNet privateKeyCrypto = new CryptoNetRsa(cert, KeyType.PrivateKey);
+var decrypt = privateKeyCrypto.DecryptToString(encrypt);
+```
+
+#### New: Use X509 Certificate for Encryption
+```csharp
+// NEW API (v3.x)
+using CryptoNet.ExtShared;  // Namespace change: CryptoNetUtils → ExtShared
+
+X509Certificate2? cert = ExtShared.GetCertificateFromStore("CN=Maytham");  // Changed from CryptoNetUtils
+
+ICryptoNetRsa publicKeyCrypto = new CryptoNetRsa(cert, KeyType.PublicKey);
+var encrypt = publicKeyCrypto.EncryptFromString(data);
+
+ICryptoNetRsa privateKeyCrypto = new CryptoNetRsa(cert, KeyType.PrivateKey);
+var decrypt = privateKeyCrypto.DecryptToString(encrypt);
+```
+
+### Key Migration Points
+1. **Method renames**: `ExportKey()` → `GetKey()`, `ExportKeyAndSave()` → `SaveKey()`
+2. **Namespace**: `CryptoNetUtils` → `CryptoNet.ExtShared.ExtShared`
+3. **Interface specificity**: Prefer `ICryptoNetRsa`, `ICryptoNetAes`, `ICryptoNetDsa` over generic `ICryptoNet`
+4. **Info property**: Access algorithm details via `cryptoNet.Info` (includes key types, sizes, loaded keys)
+5. **File operations**: Both `FileInfo` and `string` filename overloads available for `SaveKey()`

CONTRIBUTING.md

@@ -18,18 +18,18 @@ contributors must follow to avoid common build and packaging failures.
 
 ### Example: Caller (no `runs-on`)
 
-``` yaml
+~~~ yaml
 jobs:
   call-build:
     uses: ./.github/workflows/cd-build-test-pack.yml
     with:
       version: ${{ github.ref_name }}
       configuration: Release
-```
+~~~
 
 ### Example: Reusable Workflow
 
-``` yaml
+~~~ yaml
 on:
   workflow_call:
     inputs:
@@ -47,8 +47,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      # …
-```
+      # �
+~~~
 
 ## Versioning and Git Tag Guidelines
 
@@ -78,15 +78,15 @@ jobs:
 
 ### Sanitization Example
 
-``` yaml
+~~~ yaml
 - name: Sanitize version
   id: sanitize
   run: |
     v="${{ inputs.version }}"
     v="${v#v}"
     v="${v#V}"
     echo "sanitized_version=$v" >> "$GITHUB_OUTPUT"
-```
+~~~
 
 Use via: `${{ steps.sanitize.outputs.sanitized_version }}`
 
@@ -98,3 +98,15 @@ Use via: `${{ steps.sanitize.outputs.sanitized_version }}`
 ## Maintenance
 
 -   Keep conventions aligned with GitHub Actions and NuGet rules.
+
+## Contributing
+
+You are more than welcome to contribute in one of the following ways:
+
+1. Basic: Give input, and suggestions for improvement by creating an issue and labeling it https://github.com/itbackyard/CryptoNet/issues
+2. Advance: if you have good knowledge of C# and Cryptography just grab one of the issues, or features, or create a new one and refactor and add a pull request.
+3. Documentation: Add, update, or improve documentation, by making a pull request.
+
+### How to contribute:
+
+[Here](https://www.dataschool.io/how-to-contribute-on-github/) is a link to learn how to contribute if you are not aware of how to do it.

CryptoNet.Examples/CryptoNet.Examples.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="CryptoNet" Version="3.4.3" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Update="TestFiles\test.docx">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+    <None Update="TestFiles\test.pdf">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+    <None Update="TestFiles\test.png">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+    <None Update="TestFiles\test.xlsx">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>