We’re excited to introduce the Xero-Dotnet-AppStore-Sample-App, our latest .NET sample application built to help developers seamlessly integrate with the Xero API. This new app, targeting the net9 framework, brings together the best of several previously released sample apps and offers a comprehensive, modern development experience with improved portability and features.

What’s in the new sample app?

This new sample app combines the essential components from earlier repositories and adds important new features:

• Core logic for creating and accessing Xero tenant data using the Xero Netstandard SDK
• A streamlined Sign Up with Xero flow using SQLite3 and Entity Framework Core
• Xero Webhook handler implementation for all contact, invoice, and subscription
• Integrated support for the Xero App Store Subscription (XASS) flows

As the successor to earlier .NET sample apps, it retains existing functionality for making calls to most Xero APIs such as accounting, files, payroll and more. Let’s explore the new features it offers.

Demo of the new sample app on YouTube

Check out a full walk-through of the new Dotnet Sample app and it’s features on our YouTube channel.

Key New Features

If you’ve worked with earlier versions of the .NET sample apps, you’ll notice new tabs: Sign Up With Xero, Xero App Store, and Webhooks.

Sign Up with Xero and Database

Previously, we published separate Sign Up with Xero samples using Microsoft SQL Server. Those are still great resources, especially if you’re interested in comparing the recommended vs. modified sign-up flows.

In contrast, this sample app uses SQLite3 with Microsoft Entity Framework for improved portability and cross-platform support. It simulates an end-to-end experience where users sign up via the Xero App Store, are registered into the database, connect a Xero organisation, and subscribe to a plan.

You will have to have installed the Microsoft Entity Framework to use the sample app — follow the steps in the readme.md file.

Xero App Store

The app allows developers to test the subscription flow from purchasing a plan to upgrade, downgrade, cancel, and renew with all of the currently available pricing types.

Webhooks

The page shows the last webhook received which can be Create or Update type webhooks for contact, invoice or subscription related activity from Xero dashboard side.

Project Structure and Setup

Let’s break down the setup and components of the app:

XeroDotnetSampleApp.csproj Configuration

The project targets .NET 9 and refers below packages:

• AspNetCore.Session to make the app available as a web app
• SQLite and Microsoft.EntityFrameworkCore for lightweight, file-based database management
• Duende.AccessTokenManagement for OAuth2 token management
• The Xero NetStandard SDKs for accessing API endpoints — ensure you update to the most recent versions

appsettings.json Configuration

In this file, you’ll customize:

• Your app’s Client ID and Secret
• App ID (found in your developer portal URL)
• Your Xero Webhook Key
• You may change the Scopes or CallbackUri configuration to suit your needs as well
  — If you are developing your app to have it certified, you must use the offline_access scope as it’s a technical requirement
  — Another requirement is to be actively manage connections, including those who partially complete onboarding (e.g. connect their Xero organisation to your app but do not convert into paying customers)
  — If you are unsure how to do that, you can find more detailed resources here

launch.json Configuration from .vscode

This file is a local launch setting for your VS Code if you are using debugger. Update the XeroConfiguration__ClientId, XeroConfiguration__ClientSecret, WebhookSettings__WebhookKey and others (optional) to the same settings in appsettings.json if you wish to use the Dotnet debugger.

Registering and Storing User Data

In Startup.cs, we configure the app to use SQLite and register services like AppStoreService.cs and DatabaseService.cs.

We define our database models in UserContext.cs and SignUpWithXeroUser.cs. These models store data extracted from the ID token, Xero’s Get Organisation API during the Sign Up with Xero flow and from the subscription webhook events.

Creating the Database

Use the following CLI commands:

dotnet ef migrations add InitialCreate

dotnet ef database update

To make schema updates later:

dotnet ef migrations add YourMigrationName

dotnet ef database update

Sign Up with Xero Flow

Go to the Sign Up With Xero (For Customers) tab and go through the Sign Up with Xero flow, log into Xero and connect your organisation — try with Demo Company, especially if you wish to try the subscription flow as well. Upon returning back to the app, you will see the referral table from Xero Referral Users (For Developers) page filled with your user information.

The app processes the returned AccessToken and IdToken to define the referral user to save into the SignUpWithXeroUsers.db database as shown above code snippet. Note that the subscription information is not retrieved yet. The task defined as RegisterUserToDb in the DatabaseService.cs service will record the user data into the database.

Handling Webhooks and Subscriptions

Webhooks are enabled and tested using ngrok, if you do not have an account yet, use the link and follow their comprehensive instructions.

For Xero Developer Portal configuration, be sure to:

1. Update your Webhooks Delivery URL with https://YOUR_NGROK_FORWARDING_URL/webhooks
2. While your app is running and the ngrok “server” is running, send a test intent and confirm an OK response

The webhook controller:

1. Verifies the signature
2. Parses webhook payloads by EventCategory (Invoice, Contact, Subscription)
3. Differentiates between EventType Create and Update events

Example: Creating a Contact

When you manually create a new contact in Xero (e.g., tester), the app will receive and log a contact webhook. From there, if you wish, you can extend your logic to call the GET Contacts API and update your UI.

Subscription Webhook

This is where the webhook logic gets more sophisticated. Go to Xero Developer Portal and configure;

• Xero App Store Subscription (XASS) plans
• After subscribe URL to https://YOUR_NGROK_FORWARDING_URL/Views/AppStore/GetSubscription.cshtml

After a successful Sign Up With Xero flow and the referral user recorded to the database, go to the Subscribe To A Plan (For Customers) tab and subscribe to your subscription plans for your app. Use the Demo Company for testing purposes. Once subscribed:

• A Subscription Create webhook will be received
• The app will process the webhook’s payload and update the database with the subscription ID and plan
• If you click the Get Subscription Info (For Developers) now, the GetSubscriptionAsync function will be invoked to retrieve the subscription information using the subscriptionId and present the data in the Subscription Summary table on the Web UI

Note: You’ll need a client credentials access token (non-tenanted) to access subscription and connection APIs. This token is generated using your app’s client ID and secret.

Get Building

The new sample app is a robust, portable, and up-to-date app for developers building with the Xero ecosystem. If you’ve got a suggested improvement, feel free to raise an issue or send through a pull request!

Get started by exploring the code, follow the setup steps, and start building your own Xero integration today!

Don’t miss the walk-through of the new sample app on Xero Developer YouTube.