Add async client documentation to README and SDK use skill

Documents AsyncDataverseClient installation, quick start, query builder,
batch/changesets, and DataFrame patterns in README.md and both copies of
the dataverse-sdk-use SKILL.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Abel Milash

.claude/skills/dataverse-sdk-use/SKILL.md

@@ -588,6 +588,115 @@ except ValidationError as e:
 10. **Test in non-production environments** first
 11. **Use named constants** - Import cascade behavior constants from `PowerPlatform.Dataverse.common.constants`
 
+## Async Client
+
+The SDK ships a full async client, `AsyncDataverseClient`, under `PowerPlatform.Dataverse.aio`. Requires the `[async]` extra: `pip install "PowerPlatform-Dataverse-Client[async]"`.
+
+### Import
+```python
+from azure.identity.aio import InteractiveBrowserCredential  # or ClientSecretCredential, etc.
+from PowerPlatform.Dataverse.aio.async_client import AsyncDataverseClient
+```
+
+### Client Initialization
+```python
+# Context manager (recommended -- closes session and clears caches automatically)
+async with AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+    ...  # all operations here
+
+# Standalone (call aclose() in a finally block)
+client = AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential)
+try:
+    ...
+finally:
+    await client.aclose()
+```
+
+### CRUD Operations
+Every sync method has an async equivalent -- add `await`:
+```python
+# Create
+account_id = await client.records.create("account", {"name": "Contoso Ltd"})
+
+# Read
+account = await client.records.retrieve("account", account_id, select=["name", "telephone1"])
+
+# Update
+await client.records.update("account", account_id, {"telephone1": "555-0200"})
+
+# Delete
+await client.records.delete("account", account_id)
+
+# Bulk create
+ids = await client.records.create("account", [{"name": "A"}, {"name": "B"}])
+```
+
+### Query Builder
+```python
+from PowerPlatform.Dataverse.models.filters import col
+
+# Collect all results
+result = await (
+    client.query.builder("account")
+    .select("name", "telephone1")
+    .where(col("statecode") == 0)
+    .top(10)
+    .execute()
+)
+for record in result:
+    print(record["name"])
+
+# Lazy page iteration (memory-efficient)
+async for page in (
+    client.query.builder("account")
+    .select("name")
+    .page_size(500)
+    .execute_pages()
+):
+    for record in page:
+        print(record["name"])
+
+# SQL query
+rows = await client.query.sql("SELECT TOP 5 name FROM account")
+
+# FetchXML
+xml = '<fetch top="5"><entity name="account"><attribute name="name"/></entity></fetch>'
+rows = await client.query.fetchxml(xml).execute()
+```
+
+### Batch and Changesets
+```python
+# Plain batch
+batch = client.batch.new()
+batch.records.create("account", {"name": "Alpha"})
+result = await batch.execute()
+
+# Atomic changeset
+batch = client.batch.new()
+async with batch.changeset() as cs:
+    ref = cs.records.create("contact", {"firstname": "Alice"})
+    cs.records.update("account", account_id, {"primarycontactid@odata.bind": ref})
+result = await batch.execute()
+```
+
+### DataFrame Operations
+```python
+import pandas as pd
+
+# Query to DataFrame
+result = await (
+    client.query.builder("account")
+    .select("name", "telephone1")
+    .where(col("statecode") == 0)
+    .execute()
+)
+df = result.to_dataframe()
+
+# Create from DataFrame
+new_accounts = pd.DataFrame([{"name": "Contoso"}, {"name": "Fabrikam"}])
+ids = await client.dataframe.create("account", new_accounts)
+```
+
 ## Additional Resources
 
 Load these resources as needed during development:

README.md

@@ -16,7 +16,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 - [Key features](#key-features)
 - [Getting started](#getting-started)
   - [Prerequisites](#prerequisites)
-  - [Install the package](#install-the-package)  
+  - [Install the package](#install-the-package)
   - [Authenticate the client](#authenticate-the-client)
 - [Key concepts](#key-concepts)
 - [Examples](#examples)
@@ -30,6 +30,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
   - [Relationship management](#relationship-management)
   - [File operations](#file-operations)
   - [Batch operations](#batch-operations)
+- [Async client](#async-client)
 - [Next steps](#next-steps)
 - [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
@@ -53,7 +54,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 
 ### Prerequisites
 
-- **Python 3.10+** (3.10, 3.11, 3.12, 3.13 supported)  
+- **Python 3.10+** (3.10, 3.11, 3.12, 3.13 supported)
 - **Microsoft Dataverse environment** with appropriate permissions
 - **OAuth authentication configured** for your application
 
@@ -92,7 +93,7 @@ The client requires any Azure Identity `TokenCredential` implementation for OAut
 
 ```python
 from azure.identity import (
-    InteractiveBrowserCredential, 
+    InteractiveBrowserCredential,
     ClientSecretCredential,
     CertificateCredential,
     AzureCliCredential
@@ -103,7 +104,7 @@ from PowerPlatform.Dataverse.client import DataverseClient
 credential = InteractiveBrowserCredential()  # Browser authentication
 # credential = AzureCliCredential()          # If logged in via 'az login'
 
-# Production options  
+# Production options
 # credential = ClientSecretCredential(tenant_id, client_id, client_secret)
 # credential = CertificateCredential(tenant_id, client_id, cert_path)
 
@@ -783,6 +784,102 @@ result = batch.execute()
 
 For a complete example see [examples/advanced/batch.py](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/batch.py).
 
+## Async client
+
+The SDK ships a full async client, `AsyncDataverseClient`, for use in async applications. It mirrors every operation of the sync client — the same namespaces (`records`, `query`, `tables`, `files`, `batch`), the same method signatures, and the same return types.
+
+### Install
+
+The async client requires `aiohttp`, which is an optional extra:
+
+```bash
+pip install "PowerPlatform-Dataverse-Client[async]"
+```
+
+### Quick start
+
+```python
+import asyncio
+from azure.identity.aio import InteractiveBrowserCredential
+from PowerPlatform.Dataverse.aio.async_client import AsyncDataverseClient
+
+async def main():
+    credential = InteractiveBrowserCredential()
+    try:
+        async with AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+            # Create a contact
+            contact_id = await client.records.create("contact", {"firstname": "John", "lastname": "Doe"})
+
+            # Read it back
+            contact = await client.records.retrieve("contact", contact_id, select=["firstname", "lastname"])
+            print(f"Created: {contact['firstname']} {contact['lastname']}")
+
+            # Clean up
+            await client.records.delete("contact", contact_id)
+    finally:
+        await credential.close()
+
+asyncio.run(main())
+```
+
+### Standalone usage (without `async with`)
+
+```python
+client = AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential)
+try:
+    account_id = await client.records.create("account", {"name": "Contoso Ltd"})
+finally:
+    await client.aclose()
+```
+
+### Query builder
+
+The async query builder API is identical to the sync one:
+
+```python
+from PowerPlatform.Dataverse.models.filters import col
+
+# Execute and collect all results
+result = await (
+    client.query.builder("account")
+    .select("name", "telephone1")
+    .where(col("statecode") == 0)
+    .top(10)
+    .execute()
+)
+for record in result:
+    print(record["name"])
+
+# Lazy page-by-page iteration (memory-efficient for large sets)
+async for page in (
+    client.query.builder("account")
+    .select("name")
+    .page_size(500)
+    .execute_pages()
+):
+    for record in page:
+        print(record["name"])
+```
+
+### Batch and changesets
+
+```python
+batch = client.batch.new()
+batch.records.create("account", {"name": "Alpha"})
+batch.records.create("account", {"name": "Beta"})
+result = await batch.execute()
+print(f"Created {len(list(result.entity_ids))} records")
+
+# Atomic changeset
+batch = client.batch.new()
+async with batch.changeset() as cs:
+    ref = cs.records.create("contact", {"firstname": "Alice"})
+    cs.records.update("account", account_id, {"primarycontactid@odata.bind": ref})
+result = await batch.execute()
+```
+
+See [examples/aio/](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/tree/main/examples/aio) for async equivalents of all sync examples.
+
 ## Next steps
 
 ### More sample code
@@ -808,7 +905,7 @@ For comprehensive information on Microsoft Dataverse and related technologies:
 | Resource | Description |
 |----------|-------------|
 | **[Dataverse Developer Guide](https://learn.microsoft.com/power-apps/developer/data-platform/)** | Complete developer documentation for Microsoft Dataverse |
-| **[Dataverse Web API Reference](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/)** | Detailed Web API reference and examples |  
+| **[Dataverse Web API Reference](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/)** | Detailed Web API reference and examples |
 | **[Azure Identity for Python](https://learn.microsoft.com/python/api/overview/azure/identity-readme)** | Authentication library documentation and credential types |
 | **[Power Platform Developer Center](https://learn.microsoft.com/power-platform/developer/)** | Broader Power Platform development resources |
 | **[Dataverse SDK for .NET](https://learn.microsoft.com/power-apps/developer/data-platform/org-service/overview)** | Official .NET SDK for Microsoft Dataverse |

src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-use/SKILL.md

@@ -588,6 +588,115 @@ except ValidationError as e:
 10. **Test in non-production environments** first
 11. **Use named constants** - Import cascade behavior constants from `PowerPlatform.Dataverse.common.constants`
 
+## Async Client
+
+The SDK ships a full async client, `AsyncDataverseClient`, under `PowerPlatform.Dataverse.aio`. Requires the `[async]` extra: `pip install "PowerPlatform-Dataverse-Client[async]"`.
+
+### Import
+```python
+from azure.identity.aio import InteractiveBrowserCredential  # or ClientSecretCredential, etc.
+from PowerPlatform.Dataverse.aio.async_client import AsyncDataverseClient
+```
+
+### Client Initialization
+```python
+# Context manager (recommended -- closes session and clears caches automatically)
+async with AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+    ...  # all operations here
+
+# Standalone (call aclose() in a finally block)
+client = AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential)
+try:
+    ...
+finally:
+    await client.aclose()
+```
+
+### CRUD Operations
+Every sync method has an async equivalent -- add `await`:
+```python
+# Create
+account_id = await client.records.create("account", {"name": "Contoso Ltd"})
+
+# Read
+account = await client.records.retrieve("account", account_id, select=["name", "telephone1"])
+
+# Update
+await client.records.update("account", account_id, {"telephone1": "555-0200"})
+
+# Delete
+await client.records.delete("account", account_id)
+
+# Bulk create
+ids = await client.records.create("account", [{"name": "A"}, {"name": "B"}])
+```
+
+### Query Builder
+```python
+from PowerPlatform.Dataverse.models.filters import col
+
+# Collect all results
+result = await (
+    client.query.builder("account")
+    .select("name", "telephone1")
+    .where(col("statecode") == 0)
+    .top(10)
+    .execute()
+)
+for record in result:
+    print(record["name"])
+
+# Lazy page iteration (memory-efficient)
+async for page in (
+    client.query.builder("account")
+    .select("name")
+    .page_size(500)
+    .execute_pages()
+):
+    for record in page:
+        print(record["name"])
+
+# SQL query
+rows = await client.query.sql("SELECT TOP 5 name FROM account")
+
+# FetchXML
+xml = '<fetch top="5"><entity name="account"><attribute name="name"/></entity></fetch>'
+rows = await client.query.fetchxml(xml).execute()
+```
+
+### Batch and Changesets
+```python
+# Plain batch
+batch = client.batch.new()
+batch.records.create("account", {"name": "Alpha"})
+result = await batch.execute()
+
+# Atomic changeset
+batch = client.batch.new()
+async with batch.changeset() as cs:
+    ref = cs.records.create("contact", {"firstname": "Alice"})
+    cs.records.update("account", account_id, {"primarycontactid@odata.bind": ref})
+result = await batch.execute()
+```
+
+### DataFrame Operations
+```python
+import pandas as pd
+
+# Query to DataFrame
+result = await (
+    client.query.builder("account")
+    .select("name", "telephone1")
+    .where(col("statecode") == 0)
+    .execute()
+)
+df = result.to_dataframe()
+
+# Create from DataFrame
+new_accounts = pd.DataFrame([{"name": "Contoso"}, {"name": "Fabrikam"}])
+ids = await client.dataframe.create("account", new_accounts)
+```
+
 ## Additional Resources
 
 Load these resources as needed during development: