AzureNotificationHubs.Community 5.0.0

.NET Client for Azure Notification Hubs (community fork)

An unofficial, community-maintained fork of Microsoft.Azure.NotificationHubs, published as AzureNotificationHubs.Community. It is Native AOT compatible, has no Newtonsoft.Json or DataContractSerializer dependency, and drops retired platforms. The namespace is unchanged, so migrating means replacing the package reference. See the changelog for breaking changes.

Table of Contents:

• Building Code
• Getting Started
• Azure Notification Hubs Management Operations
  • Create a namespace manager
  • Create an Azure Notification Hub
  • Get a Azure Notification Hub
  • Update an Azure Notification Hub
  • Delete an Azure Notification Hub
• Azure Notification Hubs Operations
• Azure Notification Hubs Installation API
  • Delete an Installation
• Azure Notification Hub Registration API
  • Create an Apple Registration
  • Create Template Registrations
  • Update a Registration
  • Delete a Registration
  • Get a Single Registration
  • Get Registrations With a Given Tag
  • Get Registrations By Channel
• Send Notifications
  • Send an Apple Push Notification
  • Send a Template Notification
  • Send To An Installation ID
  • Send to a User ID
  • Send To An Installation Template For An Installation
• Scheduled Send Operations
  • Schedule Apple Native Send Operation
  • Cancel Scheduled Notification
• Import and Export Registrations
  • Submit an Export Job
  • Submit an Import Job
  • Wait for Job Completion
  • Get All jobs
• References

Building Code

Building requires the .NET SDK in global.json. The library targets .NET Standard 2.0 and .NET 10.0; tests run on .NET 10.0.

Getting Started

To get started, you can find all the classes in the Microsoft.Azure.NotificationHubs namespace, for example:

using Microsoft.Azure.NotificationHubs;

Azure Notification Hubs Management Operations

This section details the usage of the Azure Notification Hubs SDK for .NET management operations for CRUD operations on Notification Hubs and Notification Hub Namespaces.

Create a namespace manager

var namespaceManager = new NamespaceManagerClient("connection string");

Create an Azure Notification Hub

var hub = new NotificationHubDescription("hubname");
hub.WnsCredential = new WnsCredential("sid","key");
hub = await namespaceManager.CreateNotificationHubAsync(hub);

Get a Azure Notification Hub

var hub = await namespaceManager.GetNotificationHubAsync("hubname", CancellationToken.None);

Update an Azure Notification Hub

hub.FcmV1Credential = new FcmV1Credential("private-key", "project-id", "client-email");
hub = await namespaceManager.UpdateNotificationHubAsync(hub, CancellationToken.None);

Delete an Azure Notification Hub

await namespaceManager.DeleteNotificationHubAsync("hubname", CancellationToken.None);

Azure Notification Hubs Operations

The NotificationHubClient class and INotificationHubClient interface is the main entry point for installations/registrations, but also sending push notifications. To create a NotificationHubClient, you need the connection string from your Access Policy with the desired permissions such as Listen, Manage and Send, and in addition, the hub name to use.

INotificationHubClient hub = new NotificationHubClient("connection string", "hubname");

Azure Notification Hubs Installation API

An Installation is an enhanced registration that includes a bag of push related properties. It is the latest and best approach to registering your devices.

The following are some key advantages to using installations:

• Creating or updating an installation is fully idempotent. So you can retry it without any concerns about duplicate registrations.
• The installation model supports a special tag format ($InstallationId:{INSTALLATION_ID}) that enables sending a notification directly to the specific device. For example, if the app's code sets an installation ID of joe93developer for this particular device, a developer can target this device when sending a notification to the $InstallationId:{joe93developer} tag. This enables you to target a specific device without having to do any additional coding.
• Using installations also enables you to do partial registration updates. The partial update of an installation is requested with a PATCH method using the JSON-Patch standard. This is useful when you want to update tags on the registration. You don't have to pull down the entire registration and then resend all the previous tags again.

Using this SDK, you can do these Installation API operations. For example, we can create an installation for an Amazon Kindle Fire using the Installation class.

var installation = new Installation
{
    InstallationId = "installation-id",
    PushChannel = "adm-push-channel",
    Platform = NotificationPlatform.Adm
};
await hub.CreateOrUpdateInstallationAsync(installation);

Alternatively, we can use specific installation classes per type for example AdmInstallation for Amazon Kindle Fire devices.

var installation = new AdmInstallation("installation-id", "adm-push-channel");
await hub.CreateOrUpdateInstallationAsync(installation);

An installation can have multiple tags and multiple templates with its own set of tags and headers.

installation.Tags = new List<string> { "foo" };
installation.Templates = new Dictionary<string, InstallationTemplate>
{
    { "template1", new InstallationTemplate { Body = "{\"data\":{\"key1\":\"$(value1)\"}}" } },
    { "template2", new InstallationTemplate { Body = "{\"data\":{\"key2\":\"$(value2)\"}}" } }
};
await hub.CreateOrUpdateInstallationAsync(installation);

For advanced scenarios we have partial update capability which allows to modify only particular properties of the installation object. Basically partial update is subset of JSON Patch operations you can run against Installation object.

var addChannel = new PartialUpdateOperation
{ 
    Operation = UpdateOperationType.Add, ,
    Path = "/pushChannel", 
    Value = "adm-push-channel2"
};
var addTag = new PartialUpdateOperation
{
    Operation = UpdateOperationType.Add, 
    Path = "/tags", 
    Value = "bar"
};
var replaceTemplate = new PartialUpdateOperation
{
    Operation = UpdateOperationType.Replace, 
    Path = "/templates/template1",
    Value = new InstallationTemplate { Body = "{\"data\":{\"key3\":\"$(value3)\"}}" }.ToJson()
};
await hub.PatchInstallationAsync(
    "installation-id", 
    new List<PartialUpdateOperation> { addChannel, addTag, replaceTemplate }
);

Delete an Installation

await hub.DeleteinstallationAsync("installation-id");

Keep in mind that CreateOrUpdateInstallationAsync, PatchInstallationAsync and DeleteInstallationAsync are eventually consistent with GetInstallationAsync. In fact operation just goes to the system queue during the call and will be executed in background. Moreover Get is not designed for main runtime scenario but just for debug and troubleshooting purposes, it is tightly throttled by the service.

Azure Notification Hub Registration API

A registration associates the Platform Notification Service (PNS) handle for a device with tags and possibly a template. The PNS handle could be a ChannelURI, device token, or FCM registration ID. Tags are used to route notifications to the correct set of device handles. Templates are used to implement per-registration transformation. The Registration API handles requests for these operations.

Create an Apple Registration

var deviceToken = "device-token";
var tags = new HashSet<string> { "platform_ios", "os_tvos" };
AppleRegistrationDescription created = await hub.CreateAppleNativeRegistrationAsync(deviceToken, tags);

Analogous for Android (FCM V1), Windows (WNS), Kindle Fire (ADM), Baidu, and browsers.

Create Template Registrations

var deviceToken = "device-token";
var jsonBody = "{\"aps\": {\"alert\": \"$(message)\"}}";
AppleTemplateRegistrationDescription created = await hub.CreateAppleTemplateRegistrationAsync(deviceToken, jsonBody);

Create registrations using create registrationid+upsert pattern (removes duplicates deriving from lost responses if registration ids are stored on the device):

var deviceToken = "device-token";
var registrationId = await hub.CreateRegistrationIdAsync();
var jsonBody = "{\"aps\": {\"alert\": \"$(message)\"}}";
var reg = new AppleTemplateRegistrationDescription(deviceToken, jsonBody) { RegistrationId = registrationId };
AppleTemplateRegistrationDescription upserted = await hub.CreateOrUpdateRegistrationAsync(reg);

Update a Registration

await hub.UpdateRegistrationAsync(reg);

Delete a Registration

await hub.DeleteRegistrationAsync(registrationId);

Get a Single Registration

AppleRegistrationDescription registration = hub.GetRegistrationAsync(registrationId);

Get Registrations With a Given Tag

This query support $top and continuation tokens.

var registrations = await hub.GetRegistrationsByTagAsync("platform_ios");

Get Registrations By Channel

This query support $top and continuation tokens.

var registrations = await hub.GetRegistrationsByChannelAsync("devicetoken");

Send Notifications

The Notification object is simply a body with headers, some utility methods help in building the native and template notifications objects.

Send an Apple Push Notification

var jsonBody = "{\"aps\":{\"alert\":\"Notification Hub test notification\"}}";
var n = new AppleNotification(jsonBody);
NotificationOutcome outcome = await hub.SendNotificationAsync(n);

Analogous for Android (FCM V1), Windows, Kindle Fire, Baidu and browsers.

Send a Template Notification

var props =  new Dictionary<string, string>
{
    { "prop1", "v1" },
    { "prop2", "v2" }
};
var n = new TemplateNotification(props);
NotificationOutcome outcome = hub.SendNotificationAsync(n);

Send To An Installation ID

Send flow for Installations is the same as for Registrations. We've just introduced an option to target notification to the particular Installation - just use tag "$InstallationId:{desired-id}". For case above it would look like this:

var jsonBody = "{\"aps\":{\"alert\":\"Notification Hub test notification\"}}";
var n = new AppleNotification(jsonBody);
var tags = new List<string> { "$InstallationId:{installation-id}" };
NotificationOutcome outcome = await hub.SendNotificationAsync(n, tags);

Send to a User ID

With the Installation API we now have a new feature that allows you to associate a user ID with an installation and then be able to target it with a send to all devices for that user. To set the user ID for the installation, set the UserId property of the Installation.

var installation = new AppleInstallation("installation-id", "device-token");
installation.UserId = "user1234";

await hub.CreateOrUpdateInstallationAsync(installation);

The user can then be targeted to send a notification with the tag format of $UserId:{USER_ID}, for example like the following:

var jsonPayload = "{\"aps\":{\"alert\":\"Notification Hub test notification\"}}";
var n = new AppleNotification(jsonPayload);
NotificationOutcome outcome = await hub.SendNotificationAsync(n, "$UserId:user1234");

Send To An Installation Template For An Installation

var props = new Dictionary<string, string>
{
    { "value3", "some value" }
};
var n = new TemplateNotification(prop);
NotificationOutcome outcome = await hub.SendNotificationAsync(n, "$InstallationId:{installation-id} && template1");

Scheduled Send Operations

Note: This feature is only available for STANDARD Tier.

Scheduled send operations are similar to a normal send operations, with a scheduledTime parameter which says when notification should be delivered. The Azure Notification Hubs Service accepts any point of time between now + 5 minutes and now + 7 days.

Schedule Apple Native Send Operation

var scheduledDate = DateTimeOffset.UtcNow.AddHours(12);

var jsonPayload = "{\"aps\":{\"alert\":\"Notification Hub test notification\"}}";
var n = new AppleNotification(jsonPayload);

ScheduledNotification outcome = await hub.ScheduleNotificationAsync(n, scheduledDate);

Cancel Scheduled Notification

await hub.CancelNotificationAsync(outcome.ScheduledNotificationId);

Import and Export Registrations

Note: This feature is only available for STANDARD Tier.

Sometimes it is required to perform bulk operation against registrations. Usually it is for integration with another system or just to update the tags. It is strongly not recommended to use Get/Update flow if you are modifying thousands of registrations. Import/Export capability is designed to cover the scenario. You provide an access to some blob container under your storage account as a source of incoming data and location for output.

Submit an Export Job

var job = new NotificationHubJob
{
    JobType = NotificationHubJobType.ExportRegistrations,
    OutputContainerUri = new Uri("container uri with SAS signature"),
};

job = await hub.SubmitNotificationHubJobAsync(job);

Submit an Import Job

var job = new NotificationHubJob
{
    JobType = NotificationHubJobType.ImportCreateRegistrations,
    ImportFileUri = new Uri("input file uri with SAS signature"),
    OutputContainerUri = new Uri("container uri with SAS signature")
};

job = await hub.SubmitNotificationHubJobAsync(job);

Wait for Job Completion

while (true) {
    await Task.Delay(1000);
    job = await hub.GetNotificationHubJobAsync(job.JobId);
    if (job.Status == NotificationHubJobStatus.Completed) {
        break;
    }
}

Get All jobs

var allJobs = await hub.GetNotificationHubJobsAsync()

References

Microsoft Azure Notification Hubs Docs

Contributing

Issues and pull requests are welcome. Contributions are accepted under the MIT license. If you would like to help maintain the project, say so in an issue.