Edi Wang

From Azure Communication Services to Resend: Simplifying Moonglade Email with SMTP

2026-10-24T01:38:23Z

I recently migrated email notifications in my blogging system, Moonglade, from Azure Communication Services to Resend. Along the way, I consolidated email delivery into a single SMTP implementation.

For a personal blog, the email module has a straightforward job: notify the right people when someone leaves a comment, receives a reply, or sends a Webmention. It should be reliable, easy to configure, and easy to move between email services.

Those requirements guided this migration. The goals were to simplify the architecture and reduce dependence on a particular cloud vendor. The result uses no Resend SDK and introduces no ResendEmailSender. Resend connects through SMTP, using the same implementation that can serve other compatible SMTP services.

Where the Complexity Came From

Before the migration, Moonglade supported both SMTP and Azure Communication Services. Both paths served the same notification features, but delivery went through a dispatcher that selected a provider at runtime.

The previous EmailDispatcher read the configuration, located the matching implementation, and forwarded the message:

public class EmailDispatcher(
    IOptions<EmailServiceOptions> options,
    IEnumerable<IEmailProviderSender> senders) : IEmailDispatcher
{
    public async Task SendAsync(CommonMailMessage message)
    {
        var sender = options.Value.NormalizedProvider;
        var providerSender = senders.FirstOrDefault(s => string.Equals(s.Provider, sender, StringComparison.OrdinalIgnoreCase));

        if (providerSender == null)
        {
            throw new InvalidOperationException($"Email provider '{sender}' is not supported.");
        }

        await providerSender.SendAsync(message);
    }
}

This design had a purpose. When an application integrates directly with several email APIs, a dispatcher can keep their differences out of the business logic. However, the abstraction still left the project responsible for maintaining:

The Azure.Communication.Email SDK dependency.
AzureCommunicationSender, plus a wrapper and interface for the SDK client.
Configuration fields such as Provider, AcsConnectionString, and AcsSenderAddress.
Provider name normalization, separate validation branches, and provider-specific admin presentation.
Translation of Azure SDK exceptions into the application's retry decisions.

For example, the Azure implementation constructed the SDK's EmailMessage and initiated sending with WaitUntil.Started. The notification itself was simple, but the integration had to understand the vendor's message types and operation model.

Resend supports SMTP, and Moonglade already had SMTP support. That made this a good opportunity to reconsider whether both delivery paths were still worth maintaining.

Moving Provider Differences into Configuration

The new boundary is straightforward: Moonglade generates notifications, manages pending messages, and submits email through SMTP. The email service handles delivery after submission.

The application still needs a server address and credentials, and it still depends on an external service. However, switching to another SMTP service that meets the implementation's authentication, sender, and TLS requirements can usually be handled through configuration.

Replacing the Azure SDK with a Resend SDK would have introduced another vendor API into the application. Choosing SMTP instead lets the application depend on a common protocol, while the service provider's identity remains in deployment configuration.

There is a tradeoff. The current implementation does not integrate provider-specific delivery callbacks, analytics APIs, or idempotency headers. For the blog's existing notification requirements, that keeps the amount of code manageable. Additional integrations can be evaluated when there is a concrete need for them.

Separating Authentication from the Sender Address

One practical detail mattered immediately: an SMTP login username is not necessarily an email address.

Resend uses resend as its SMTP username and an API key as the password. The sender address must belong to a verified domain. A configuration that treats the SMTP username as the sender address cannot represent this setup correctly. These requirements are documented in Resend's SMTP documentation.

To support this, Moonglade gained a general-purpose SmtpSenderAddress setting:

Setting	Purpose	Resend example
`SmtpUserName`	SMTP authentication username	`resend`
`SmtpPassword`	SMTP authentication credential	API key supplied through deployment secrets
`SmtpSenderAddress`	Email sender address	`notifications@example.com`

The implementation does not detect Resend from the username or add a provider-specific branch. Authentication and sender identity are separate concepts, and the configuration now expresses that distinction.

To preserve existing configurations where the username is an email address, an omitted sender address falls back to the username:

public string EffectiveSmtpSenderAddress =>
    string.IsNullOrWhiteSpace(SmtpSenderAddress) ? SmtpUserName : SmtpSenderAddress;

The sender constructs the message with MimeKit and applies the effective address to both From and Sender:

var senderAddress = options.Value.EffectiveSmtpSenderAddress;
var mimeMessage = new MimeMessage
{
    Sender = new MailboxAddress(smtpSettings.SenderName, senderAddress),
    Subject = message.Subject,
    Body = new TextPart(message.BodyIsHtml ? TextFormat.Html : TextFormat.Plain) { Text = message.Body }
};
mimeMessage.From.Add(new MailboxAddress(smtpSettings.EmailDisplayName, senderAddress));

Authentication continues to use SmtpUserName and SmtpPassword. The account can therefore authenticate as resend, while the message headers and SMTP envelope sender use the actual email address.

Validation changed alongside the configuration. An explicitly supplied SmtpSenderAddress must be a valid bare email address. Display names are configured separately, so a value such as Blog <notifications@example.com> does not belong in this field.

The relevant code is in EmailServiceOptions.cs and SmtpEmailSender.cs.

Removing the Provider Selection Layer

With the sender address issue resolved, the next step was to remove the Azure delivery path and the code whose only purpose was choosing between providers.

Previously, the delivery registrations included the Azure client wrapper, two provider implementations, and the dispatcher:

services.AddSingleton<IAzureCommunicationEmailClient, AzureCommunicationEmailClient>();
services.AddSingleton<IEmailProviderSender, SmtpEmailSender>();
services.AddSingleton<IEmailProviderSender, AzureCommunicationSender>();
services.AddSingleton<IEmailDispatcher, EmailDispatcher>();

After the migration, that part became one line:

services.AddSingleton<IEmailDispatcher, SmtpEmailSender>();

SmtpEmailSender now implements the existing IEmailDispatcher directly. The background processor still calls the same interface and does not need to know which SMTP service is configured.

Keeping IEmailDispatcher is useful because it remains the boundary between background processing and network delivery, and it allows the sender to be replaced in tests. The deleted IEmailProviderSender and EmailDispatcher mainly existed to select a provider. With one delivery implementation, that extra layer no longer served a purpose.

The cleanup extended beyond those classes:

Removed the Azure.Communication.Email package reference.
Deleted the Azure client wrapper and its interface.
Removed provider selection, name normalization, and ACS configuration fields.
Changed configuration validation to check SMTP settings directly.
Updated the admin notification page to show SMTP and the effective sender address.
Removed Azure RequestFailedException classification while retaining SMTP error handling.
Updated configuration examples, documentation, and tests.

This removed an entire branch running through configuration, registration, execution, and failure handling. There is less code to understand when diagnosing a delivery problem.

The commit removing Azure email support changed 26 files, adding 39 lines and deleting 541: a net reduction of 502 lines. That includes tests and documentation, so it should not be presented as 502 lines of production code removed. It does show that this migration was primarily about consolidating and deleting code.

Keeping the Existing Outbox

Consolidating delivery into SMTP did not move network calls back into comment requests. Moonglade already had a database-backed outbox before this migration, and that pipeline remains in place:

flowchart TD
    A[Comment, reply, and Webmention events] --> B[Notification handlers]
    B --> C[Database outbox]
    C --> D[EmailOutboxWorker]
    D --> E[EmailOutboxMessageProcessor]
    E --> F[IEmailDispatcher / SmtpEmailSender]
    F --> G[SMTP service, currently Resend]

Notification handlers enqueue messages. The background worker creates a dependency injection scope and processes pending work. The processor validates each message, builds the email, invokes the sender, and records the result.

Template generation, retries, claim leases, and dead-letter handling stay inside the application. They do not have to be implemented separately for each email service. The SMTP sender handles connecting, authenticating, submitting the message, and disconnecting.

The reliability guarantees also remain explicit. When every recipient fails and at least one failure is transient, the processor schedules a retry. Permanent failures or exhausted attempts lead to dead-letter handling. If only some recipients fail, the processor logs a warning and completes the message, avoiding a retry of the whole notification for recipients whose messages were already submitted successfully.

The outbox uses at-least-once processing. If the SMTP service accepts an email but the application stops before recording success, a later retry can submit it again. SMTP does not automatically provide exactly-once delivery, and successful submission does not prove that a message reached the recipient's inbox.

There is another boundary worth being precise about: notification enqueueing uses its own SaveChangesAsync. Having an outbox alone does not mean that saving a comment and enqueueing its notification happen in the same database transaction.

Handling SMTP Transport Details

A later change fixed TLS behavior on port 465. Although the configuration property is called EnableSsl, SMTP supports different ways of establishing an encrypted connection. Port 465 typically starts TLS immediately when connecting, while port 587 typically upgrades an existing connection through STARTTLS.

The current implementation keeps that decision in a small method:

internal static SecureSocketOptions GetSocketOptions(int port, bool enableTls) =>
    port == 465 ? SecureSocketOptions.SslOnConnect :
    enableTls ? SecureSocketOptions.StartTls : SecureSocketOptions.Auto;

The connection and authentication code uses that result:

await smtp.ConnectAsync(
    settings.SmtpServer,
    settings.SmtpServerPort,
    GetSocketOptions(settings.SmtpServerPort, settings.EnableTls));
if (!string.IsNullOrEmpty(settings.SmtpUserName))
{
    await smtp.AuthenticateAsync(settings.SmtpUserName, settings.SmtpPassword);
}

var response = await smtp.SendAsync(mimeMessage);
await smtp.DisconnectAsync(true);

In this implementation, port 465 always uses implicit TLS. On other ports, EnableSsl=true requires STARTTLS. Setting it to false selects Auto, which uses STARTTLS when the server supports it but otherwise permits an unencrypted connection. The Resend example below uses port 587 with TLS explicitly enabled.

Standardizing on a protocol reduces vendor-specific behavior, but the protocol still needs to be implemented and tested correctly.

Configuring Resend

The current version can send through Resend with the following configuration:

{
  "Email": {
    "Enabled": true,
    "SmtpServer": "smtp.resend.com",
    "SmtpUserName": "resend",
    "SmtpSenderAddress": "notifications@example.com",
    "SmtpPort": 587,
    "EnableSsl": true
  }
}

Replace notifications@example.com with a permitted sender address on your verified domain. Supply the API key through the Email__SmtpPassword environment variable or your deployment's secret configuration, rather than committing it to appsettings.json. The host, authentication requirements, and supported ports are covered in Resend's SMTP documentation.

For an existing deployment, the migration steps are:

Remove Email:Provider, Email:AcsConnectionString, and Email:AcsSenderAddress. The current code no longer reads them.
Configure the SMTP host, port, credentials, and sender address.
If the deployment uses the old Email:OutboxWorker:Enabled switch, replace it with Email:Enabled. The old key is no longer read; worker tuning settings remain under Email:OutboxWorker.
Restart the application, enable email sending at /admin/settings/notification, and use Send Test Email to check actual delivery.

Email remains an optional capability. Missing configuration leaves email inactive while the blog starts normally. Invalid configuration produces an error log and validation details in the admin portal. While email is unavailable, the worker does not claim messages and built-in notification handlers do not enqueue new ones. Existing pending messages remain in the database and can be processed after valid configuration is supplied and the application is restarted.

The application-level Email:Enabled setting and the admin notification switch retain separate responsibilities. The former controls whether the email capability is enabled; the latter controls whether the blog produces notifications. Enabling notifications in the admin portal does not replace SMTP configuration.

What the Migration Achieved

The email module now has one fewer vendor SDK, no Azure client wrapper, and no provider selection layer. Their associated configuration and error-handling branches are gone. Notification features, templates, and the outbox continue to use the existing application pipeline.

Reducing vendor lock-in does not eliminate dependence on an external service. Domain verification, quotas, sending reputation, and operational data still belong to the provider's side of the boundary. The improvement is lower coupling between application code and provider APIs, with less application work required for a future switch.

Resend serves Moonglade's current email needs, and SMTP keeps that choice easier to change. If the next service meets the existing implementation's requirements, migration can focus on configuration, domain verification, and delivery testing, without adding another sender implementation to the application.

Not Only Azure: Migrating this Blog from Entra ID to Standard OIDC

2026-09-02T11:18:16Z

Moonglade has supported two authentication approaches for a long time: a built-in local administrator account and Microsoft Entra ID. The Entra ID integration worked well, especially for blogs hosted on Azure, but it also introduced an architectural limitation: the application understood a particular identity provider instead of the protocol behind it.

In PR #1001, I replaced the Entra-specific authentication path with a standards-based OpenID Connect implementation.

This does not mean Moonglade no longer supports Entra ID. Entra ID remains supported—as an OpenID Connect provider. The important change is that Moonglade is no longer designed around Azure identity alone.

Why Change a Working Authentication System?

The previous design used Microsoft.Identity.Web and configuration concepts specific to Entra ID, including tenant ID, instance, and domain.

That was convenient, but it made one identity provider part of the application’s architecture. Adding support for another provider would likely have required another authentication mode, another configuration model, and more provider-specific branches.

The new design reduces the authentication choices to two application-level modes:

Local
OpenIdConnect

Moonglade now cares about standard OIDC concepts such as authority, client ID, scopes, callback paths, and claims. Provider-specific details stay at the identity provider.

This creates a cleaner boundary: Moonglade defines what it needs from an identity system, while the OIDC provider decides how users authenticate.

A Provider-Neutral Configuration

The old Authentication:EntraID section has been replaced with Authentication:OpenIdConnect:

{
  "Authentication": {
    "Provider": "OpenIdConnect",
    "OpenIdConnect": {
      "Authority": "https://identity.example.com/",
      "ClientId": "moonglade",
      "CallbackPath": "/signin-oidc",
      "SignedOutCallbackPath": "/signout-callback-oidc",
      "NameClaimType": "name",
      "Scopes": [ "openid", "profile", "email" ],
      "AllowedSubjects": []
    }
  }
}

The client secret is intentionally excluded from the configuration file. It should come from a secure external source, such as an environment variable:

Authentication__OpenIdConnect__ClientSecret

Any provider used with Moonglade must publish discovery metadata over HTTPS and support the authorization code flow with PKCE.

Using the Standard ASP.NET Core OIDC Handler

The implementation now uses Microsoft.AspNetCore.Authentication.OpenIdConnect directly. The OIDC handler performs the external authentication, while Moonglade continues to use an encrypted application cookie for its local session.

The essential registration looks like this:

services.AddAuthentication(options =>
{
    options.DefaultScheme =
        CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme =
        BlogAuthSchemas.OpenIdConnect;
})
.AddCookie(
    CookieAuthenticationDefaults.AuthenticationScheme,
    ConfigureApplicationCookie)
.AddOpenIdConnect(BlogAuthSchemas.OpenIdConnect, options =>
{
    options.Authority = oidc.Authority;
    options.ClientId = oidc.ClientId;
    options.ClientSecret = oidc.ClientSecret;

    options.ResponseType = OpenIdConnectResponseType.Code;
    options.UsePkce = true;
    options.RequireHttpsMetadata = true;

    options.SignInScheme =
        CookieAuthenticationDefaults.AuthenticationScheme;
    options.MapInboundClaims = false;
    options.SaveTokens = false;
});

A few choices here are deliberate.

Authorization code flow with PKCE avoids the older implicit-flow model. HTTPS metadata is mandatory, claim names are kept in their original OIDC form, and access or refresh tokens are not persisted in the application cookie. Moonglade needs an authenticated identity, not long-term access to the provider’s APIs.

Sign-out now clears the Moonglade cookie and also invokes the OIDC provider’s logout endpoint when one is advertised in its metadata.

Authentication Is Not Authorization

The most important part of this change is not the replacement of a package. It is the separation of two questions:

Who is the user?
Is this user allowed to administer the blog?

A successful OIDC sign-in answers only the first question. It must not automatically grant access to the Admin Portal.

Moonglade now has one administrator policy named MoongladeAdministrator. Its behavior depends on the configured authentication mode:

services.AddAuthorizationBuilder()
    .AddPolicy(BlogAuthSchemas.AdministratorPolicy, policy =>
    {
        policy.RequireAuthenticatedUser();

        if (authentication.Provider == AuthenticationProvider.Local)
        {
            policy.RequireRole("Administrator");
            return;
        }

        var allowedSubjects = oidc.AllowedSubjects
            .ToHashSet(StringComparer.Ordinal);

        policy.RequireAssertion(context =>
            context.User.FindAll("sub")
                .Any(claim => allowedSubjects.Contains(claim.Value)));
    });

Local accounts continue to use the existing administrator role. OIDC identities are checked against an explicit allowlist of sub claims.

The same policy protects Admin Razor Pages, administrative API controllers, and UI elements that expose administrative actions. This keeps the authorization rule centralized instead of scattering provider checks throughout the Web layer.

Why Authorize with `sub`?

OIDC providers commonly return claims such as email address, display name, or preferred username. These values are useful for presentation, but they are poor authorization keys: they may change, be reassigned, or have different semantics across providers.

The sub claim is the subject identifier defined by OpenID Connect. Within the issuer boundary validated by the OIDC handler, it provides the stable identifier needed for an administrator allowlist.

Moonglade therefore does not grant administrator access based on email or display name. Every administrator must have an exact sub value in AllowedSubjects.

Some providers use pairwise subject identifiers, so changing the provider or client registration may produce a different sub for the same person. This is expected and must be considered during migration.

Bootstrapping the First Administrator

A new deployment starts safely with an empty allowlist:

"AllowedSubjects": []

Users can still complete OIDC authentication, but nobody can access the Admin Portal or administrative APIs.

To discover the first administrator identity, Moonglade provides:

/auth/identity

An authenticated OIDC user can open this endpoint to retrieve their own issuer, subject, and display name. The endpoint does not grant any permission and cannot inspect another user’s identity.

The administrator can then copy the returned subject into the configuration:

"AllowedSubjects": [
  "administrator-subject-1"
]

After restarting the application and signing in again, the administrator policy can authorize that identity.

When local authentication is configured, /auth/identity returns HTTP 404 because the endpoint is relevant only to the OIDC bootstrap process.

Failing Fast on Invalid Configuration

External authentication problems are often discovered only when someone tries to sign in. Moonglade now validates its OIDC configuration during startup instead.

The validator checks that:

The authority is an absolute HTTPS URL.
Client ID and client secret are present.
Callback paths are application-relative.
The scopes include openid.
The name claim type is configured.
The subject allowlist contains no blank entries.

This uses ASP.NET Core options validation with ValidateOnStart(). A deployment with incomplete authentication configuration fails immediately with a useful error instead of starting successfully with a broken sign-in flow.

Entra ID Still Works

Existing Entra ID deployments can continue using Microsoft identities through Entra’s standard OIDC endpoints. For a single-tenant blog, the authority should use the tenant-specific v2 endpoint:

https://login.microsoftonline.com/{tenant-id}/v2.0

The existing application client ID can usually be retained, but the application needs a Web client secret and registered sign-in and sign-out callback URLs.

No database migration is required. This is an application configuration and authentication architecture change.

A Smaller Dependency and a Larger Possibility

The goal of this migration was not to replace Microsoft Entra ID with another identity provider. It was to stop making any single provider part of Moonglade’s core authentication design.

Entra ID remains an excellent choice, particularly for Azure-hosted deployments. It now participates through the same standard protocol boundary as other compatible OIDC providers.

The resulting architecture is easier to understand:

OIDC authenticates the user.
Moonglade’s cookie maintains the application session.
A centralized policy authorizes administrators.
Stable subject identifiers define who may manage the blog.

By designing around a standard instead of a vendor, Moonglade keeps its existing Azure capabilities while gaining the freedom to work beyond Azure.

From Azure to Anywhere: Redesigning Image Storage Architecture for this Blog

2026-08-25T00:04:45Z

Image storage sounds simple: accept an upload, save the bytes, and return a URL. In practice, it can quickly pull cloud SDKs, credentials, provider-specific configuration, deployment logic, and operational assumptions deep into an application.

That was the situation in Moonglade. It supported the local filesystem, Azure Blob Storage, and S3-compatible object storage directly in the application. This worked, but each provider made the application responsible for more infrastructure knowledge.

In PR #999, I redesigned this subsystem around a simpler principle:

Moonglade should manage image files. The hosting environment should decide how those files are persisted.

The result is a filesystem-only application architecture that can still run on Azure, Docker, traditional servers, shared network storage, or other platforms.

The Previous Architecture

Moonglade already had an IBlogImageStorage abstraction, so most business code did not directly call Azure or AWS APIs. However, the application still contained three separate implementations:

Local filesystem storage
Azure Blob Storage
S3-compatible storage

The dependency injection layer selected one of them based on configuration:

Moonglade
    └── IBlogImageStorage
          ├── FileSystemImageStorage
          ├── AzureBlobImageStorage
          └── S3CompatibleImageStorage

This meant the application still needed to understand:

Azure Storage connection strings and container names
S3 endpoints, regions, buckets, and access keys
Azure and AWS SDK initialization
Provider-specific validation
Remote container creation during startup
Different behaviors and test suites for each provider

Although image consumers depended on an interface, the application as a whole remained coupled to specific storage platforms.

Adding another provider would have required another implementation, another SDK, more configuration, and more tests. That was not the direction I wanted for a personal blogging platform.

A New Responsibility Boundary

The redesigned architecture removes cloud storage providers from the application entirely:

Moonglade
    ↓
IBlogImageStorage
    ↓
Filesystem paths
    ↓
Local disk / Docker volume / Azure Files / SMB / NFS / mounted storage

Moonglade now reads and writes ordinary files. Durability, replication, sharing, backup, and cloud integration belong to the deployment environment.

This does not mean Moonglade can no longer use cloud storage. It means cloud storage is attached below the application boundary.

For example, the official Azure deployment mounts Azure Files shares into the Linux App Service container. Moonglade sees /app/images, while Azure provides durable storage behind that path. No Azure Storage SDK is required in the application.

A Smaller Storage Contract

The new interface describes only the operations Moonglade actually needs:

public interface IBlogImageStorage
{
    Task<string> InsertAsync(string fileName, byte[] imageBytes);

    Task<string> InsertOriginalAsync(string fileName, byte[] imageBytes);

    Task<ImageInfo> GetInfoAsync(string fileName);

    Task<Stream> OpenReadAsync(string fileName);

    Task DeleteAsync(string fileName);
}

There is no provider name, container concept, bucket concept, or cloud-specific operation.

The dependency injection registration also became much smaller. The application resolves two filesystem paths and registers one implementation:

var primaryPath = string.IsNullOrWhiteSpace(settings.FileSystemPath)
    ? FileSystemImageStorage.DefaultPath
    : settings.FileSystemPath;

var originalPath = string.IsNullOrWhiteSpace(settings.OriginalFileSystemPath)
    ? FileSystemImageStorage.DefaultOriginalPath
    : settings.OriginalFileSystemPath;

var imageConfiguration =
    FileSystemImageStorage.ResolveImageStoragePaths(
        primaryPath,
        originalPath);

services.AddSingleton(imageConfiguration)
    .AddSingleton<IBlogImageStorage, FileSystemImageStorage>();

As part of this change, Moonglade removed the Azure Blob and S3-compatible implementations, together with the Azure.Storage.Blobs and AWSSDK.S3 package references.

Fewer SDKs mean fewer transitive dependencies, fewer provider-specific code paths, and a smaller configuration surface.

Public Images and Private Originals

The redesign also clarified an important security boundary.

Moonglade can retain both a processed image and its original upload. Previously, this was described using “primary” and “secondary” storage terminology. The new model expresses the actual intent:

FileSystemPath stores processed, publicly retrievable images.
OriginalFileSystemPath stores private original uploads.

A typical production configuration looks like this:

"ImageStorage": {
  "CacheMinutes": 60,
  "FileSystemPath": "/app/images",
  "OriginalFileSystemPath": "/app/images-origin"
}

The two paths must be absolute and must not overlap. One cannot contain the other.

This is more than configuration validation. It prevents an original-image directory from accidentally appearing under a public root. Only the primary path is read by /image/{filename} and only that path may be exposed to a CDN.

The original-image root must remain outside static-file middleware, public endpoints, and CDN origins.

Cloud Integration Moves to Deployment

Removing cloud SDKs changes where infrastructure decisions are made, not whether they exist.

In Docker Compose, the two roots can be backed by separate named volumes:

services:
  moonglade:
    environment:
      ImageStorage__FileSystemPath: /app/images
      ImageStorage__OriginalFileSystemPath: /app/images-origin
    volumes:
      - moonglade-images:/app/images
      - moonglade-images-origin:/app/images-origin

The official Azure deployment follows the same model. It creates two Azure Files shares and mounts them into the App Service container at those paths.

Other environments can provide the filesystem contract differently:

A physical or virtual server can use durable local disks.
Multiple application replicas can use SMB or NFS.
Kubernetes can attach persistent volumes.
A hosting platform can use a suitable mounted-storage adapter.

Moonglade does not install or configure mount drivers, CSI integrations, sidecars, or vendor-specific volume plugins. Those are operational choices and should remain outside the application.

The storage presented to Moonglade must still behave like a reliable filesystem: writes must become visible when completed, data must survive restarts, and all replicas must see a coherent view.

Example: Mapping Azure Files into App Service

A filesystem-first design does not prevent Moonglade from using Azure platform capabilities. In the official deployment, two Azure Files shares are mounted into the Linux App Service container. Assuming the shares already exist, the volume mappings can be declared in Bicep like this:

resource storageMounts 'Microsoft.Web/sites/config@2022-03-01' = {
  parent: webApp
  name: 'azurestorageaccounts'
  properties: {
    primaryImages: {
      type: 'AzureFiles'
      accountName: storageAccount.name
      shareName: 'moonglade-images'
      accessKey: storageAccount.listKeys().keys[0].value
      mountPath: '/app/images'
    }
    originalImages: {
      type: 'AzureFiles'
      accountName: storageAccount.name
      shareName: 'moonglade-images-origin'
      accessKey: storageAccount.listKeys().keys[0].value
      mountPath: '/app/images-origin'
    }
  }
}

The application settings then point Moonglade to those mounted directories:

{
  name: 'ImageStorage__FileSystemPath'
  value: '/app/images'
}
{
  name: 'ImageStorage__OriginalFileSystemPath'
  value: '/app/images-origin'
}

From Moonglade’s perspective, these are ordinary filesystem paths. App Service and Azure Files provide the persistent, shared storage behind them. This demonstrates the new architectural boundary clearly: the application remains platform-neutral while the deployment can still take full advantage of Azure’s managed infrastructure. Azure also supports configuring these mounts through the portal or Azure CLI, as described in the App Service storage-mount documentation.

CDN Delivery Remains Independent

Storage and image delivery are separate concerns.

Moonglade continues to store image references using URLs such as:

/image/example.webp

When CDN redirection is enabled, rendered posts and feeds use the configured CDN endpoint. Requests to the legacy application URL can also redirect to the CDN.

The browser retrieves the image directly from the CDN; the bytes do not need to pass through Moonglade.

This behavior did not require a cloud storage SDK before, and it does not require one now. The only important rule is that the CDN origin may expose the public image root, but never the private original-image root.

CDN caching, media types, invalidation, TLS, and origin access policies remain deployment responsibilities.

The Trade-Off

This design makes the application smaller and more portable, but it does not make storage operations disappear.

Operators must now ensure that:

Both paths are writable and durable.
Containers do not store images only in ephemeral layers.
Multiple replicas share the same image data.
Backups include both roots.
The private original root is not publicly exposed.
Mounted storage has acceptable consistency and performance.

I consider this a better trade-off. These concerns already existed; keeping cloud SDKs inside Moonglade merely distributed them across both application and infrastructure code.

The new architecture gives them a clear owner.

Upgrading Existing Installations

This is a breaking deployment change for installations using Azure Blob Storage, S3-compatible storage, or a single shared filesystem directory.

Existing images must be copied into the new roots before upgrading:

Copy processed images into FileSystemPath.
Copy retained originals into OriginalFileSystemPath.
Preserve existing filenames.
Configure both new paths.
Remove the old provider settings and credentials.
Verify persistence, permissions, and public/private isolation before restoring traffic.

Database records and saved post content do not require URL rewriting because /image/{filename} remains the stable application-level URL.

Moonglade deliberately does not perform this data migration automatically. Copying data between storage systems is an infrastructure operation with deployment-specific authentication, availability, and rollback requirements.

Conclusion

The most important outcome of this redesign is not simply that some SDK packages were removed. It is that Moonglade now has a clearer architectural boundary.

The application owns:

Image validation and processing
Filename generation
Public and original image separation
Image HTTP behavior
CDN URL generation

The infrastructure owns:

Durable storage
Cloud-provider integration
Shared access between replicas
Mounting, backup, and recovery
CDN origin configuration

Moonglade can still run on Azure, but Azure is no longer embedded in its image-storage code. The same application can run with Docker volumes, shared network storage, or another platform without introducing another provider implementation.

That is the real meaning of moving from Azure to anywhere.

From Azure Functions to a Database Outbox: Simplifying Moonglade Email Notifications

2026-08-03T23:38:30Z

Moonglade used to send email notifications through a standalone service named Moonglade.Email.

That service was deployed as an Azure Function. The blog application submitted email notification messages, Azure Storage Queue held those messages, and the function processed them asynchronously before sending email through Azure Communication Services or SMTP.

It worked. But for a personal blogging system, it was more infrastructure than I wanted to keep.

Moonglade usually sends very few notification emails: new comments, admin replies, Webmentions, and test messages. Even for a busy post, the workload is tiny compared with what Azure Queue Storage and Azure Functions are designed to handle.

So I moved email notification processing back into the main Moonglade application.

Before: A Separate Azure Function Service

The old design looked like this:

sequenceDiagram
    participant Blog as Moonglade Web App
    participant Api as Moonglade.Email HTTP Function
    participant Queue as Azure Storage Queue
    participant Function as Azure Function Queue Trigger
    participant Template as Email Template Renderer
    participant Provider as ACS / SMTP

    Blog->>Api: Send email request
    Api->>Queue: Enqueue email message
    Queue->>Function: Trigger with queued message
    Function->>Template: Render email template
    Template-->>Function: Return rendered email
    Function->>Provider: Send email

This architecture had a few benefits:

email sending did not block comment submission
queue messages survived restarts
retries were handled outside the web request
email delivery was separated from the blog process

But it also required:

another repository
another deployment unit
Azure Functions
Azure Storage Queue
extra secrets and configuration
more operational knowledge for a small personal blog

For Moonglade, the cost was no longer justified.

After: An In-App Database Outbox

The new design keeps asynchronous and durable delivery, but removes the standalone Azure Function and Azure Storage Queue.

flowchart TD
    Event["Comment / Reply / Webmention"] --> Queue["IEmailNotificationQueue"]
    Queue --> Table["EmailOutboxMessage Table"]
    Table --> Worker["EmailOutboxWorker"]
    Worker --> Processor["EmailOutboxMessageProcessor"]
    Processor --> Builder["MessageBuilder"]
    Builder --> Dispatcher["EmailDispatcher"]
    Dispatcher --> ACS["Azure Communication Services"]
    Dispatcher --> SMTP["SMTP"]

The database is now the durable queue.

This is intentionally simple. Moonglade already requires SQL Server or PostgreSQL, so using the existing database avoids introducing RabbitMQ, Redis, Azure Queue Storage, or another hosted dependency.

Code Structure

The email implementation now lives inside the main Moonglade solution:

src/
  Moonglade.Email/
    CommentEvent.cs
    CommentReplyEvent.cs
    MentionEvent.cs
    TestEmailEvent.cs
    ServiceCollectionExtensions.cs
    Core/
      IEmailNotificationQueue.cs
      IEmailOutboxStore.cs
      DbEmailNotificationQueue.cs
      EmailOutboxWorker.cs
      EmailOutboxMessageProcessor.cs
      EmailOutboxWorkerOptions.cs

  Moonglade.Data/
    Entities/
      EmailOutboxMessageEntity.cs
      EmailOutboxMessageStatus.cs
    Configurations/
      EmailOutboxMessageConfiguration.cs

The main idea is:

event handlers enqueue email work
the database stores pending messages
a hosted service polls and claims messages
the processor sends emails and records success, retry, or dead-letter status

Event Handlers Only Enqueue Work

Request handlers do not send email directly. They publish LiteBus events such as CommentEvent, CommentReplyEvent, or MentionEvent.

The email event handlers turn those events into outbox messages.

public class CommentNotificationEventHandler(
    IEmailNotificationQueue queue,
    IBlogConfig blogConfig) : IEventHandler<CommentEvent>
{
    public async Task HandleAsync(CommentEvent notification, CancellationToken ct)
    {
        if (!blogConfig.NotificationSettings.EnableEmailSending)
        {
            return;
        }

        var payload = new NewCommentPayload
        {
            Username = notification.Username,
            Email = notification.Email,
            IpAddress = notification.IPAddress,
            PostTitle = notification.PostTitle,
            CommentContent = ContentProcessor.MarkdownToCommentHtml(notification.CommentContent)
        };

        await queue.EnqueueAsync(new EmailNotification
        {
            MessageType = MessageTypes.NewCommentNotification,
            DistributionList = blogConfig.GeneralSettings.OwnerEmail,
            MessageBody = JsonSerializer.Serialize(payload, MoongladeJsonSerializerOptions.Default)
        }, ct);
    }
}

This keeps the web request path short. The user action only persists a notification message. Actual email delivery happens later.

The Outbox Table

The outbox message entity stores everything needed to process, retry, and diagnose email delivery.

public class EmailOutboxMessageEntity
{
    public Guid Id { get; set; }
    public string MessageType { get; set; }
    public string DistributionList { get; set; }
    public string MessageBody { get; set; }
    public EmailOutboxMessageStatus Status { get; set; }
    public int AttemptCount { get; set; }
    public DateTime CreatedTimeUtc { get; set; }
    public DateTime? LastAttemptTimeUtc { get; set; }
    public DateTime? NotBeforeUtc { get; set; }
    public DateTime? LockedUntilUtc { get; set; }
    public string LockedBy { get; set; }
    public DateTime? SentTimeUtc { get; set; }
    public string LastError { get; set; }
    public Guid ConcurrencyToken { get; set; } = Guid.NewGuid();
}

The dequeue path has an index optimized for pending and retryable messages:

builder.HasIndex(
    nameof(EmailOutboxMessageEntity.Status),
    nameof(EmailOutboxMessageEntity.NotBeforeUtc),
    nameof(EmailOutboxMessageEntity.LockedUntilUtc),
    nameof(EmailOutboxMessageEntity.CreatedTimeUtc))
    .HasDatabaseName("IX_EmailOutboxMessage_Dequeue");

The status model is simple:

Pending -> Processing -> Succeeded
Pending -> Processing -> Failed -> Processing -> Succeeded
Pending -> Processing -> Failed -> DeadLettered

Claiming Messages With A Lease

The outbox store claims one available message at a time. A worker sets LockedBy, LockedUntilUtc, increments AttemptCount, and updates the concurrency token.

entity.Status = EmailOutboxMessageStatus.Processing;
entity.LockedBy = request.WorkerId;
entity.LockedUntilUtc = request.UtcNow.Add(request.LeaseDuration);
entity.LastAttemptTimeUtc = request.UtcNow;
entity.AttemptCount++;
entity.ConcurrencyToken = Guid.NewGuid();

await db.SaveChangesAsync(cancellationToken);

Claimable messages include:

return db.EmailOutboxMessage.Where(m =>
    (m.Status == EmailOutboxMessageStatus.Pending ||
     m.Status == EmailOutboxMessageStatus.Failed ||
     (m.Status == EmailOutboxMessageStatus.Processing && m.LockedUntilUtc <= utcNow)) &&
    (m.NotBeforeUtc == null || m.NotBeforeUtc <= utcNow) &&
    (m.LockedUntilUtc == null || m.LockedUntilUtc <= utcNow));

This gives the system basic durability:

pending messages survive app restarts
failed messages can be retried later
stale processing locks can be recovered
multiple workers can avoid processing the same message through optimistic concurrency

The Background Worker

Email delivery runs in an ASP.NET Core hosted service.

public class EmailOutboxWorker(
    IServiceScopeFactory scopeFactory,
    IOptions<EmailOutboxWorkerOptions> options,
    ILogger<EmailOutboxWorker> logger) : BackgroundService
{
    private readonly string _workerId = $"{Environment.MachineName}-{Guid.NewGuid():N}";

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var workerOptions = options.Value;
        if (!workerOptions.Enabled)
        {
            logger.LogInformation("EmailOutboxWorker is disabled.");
            return;
        }

        logger.LogInformation("EmailOutboxWorker started with worker ID {WorkerId}.", _workerId);

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await ProcessBatchAsync(workerOptions, stoppingToken);
                await Task.Delay(workerOptions.PollInterval, stoppingToken);
            }
            catch (OperationCanceledException)
            {
                break;
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Error in EmailOutboxWorker.");
                await Task.Delay(workerOptions.PollInterval, stoppingToken);
            }
        }
    }
}

The worker is intentionally boring. It polls, processes a small batch, waits, and repeats.

That is enough for Moonglade’s workload.

Processing, Retry, And Dead Letter

The processor validates the message, builds the email, sends it to each recipient, and then updates the outbox state.

var failures = await SendToRecipientsAsync(message, recipients, cancellationToken);

if (failures.Count == 0)
{
    await outboxStore.CompleteAsync(message.Id, utcNow, cancellationToken);
    return;
}

if (failures.Count != recipients.Length)
{
    await outboxStore.CompleteAsync(message.Id, utcNow, cancellationToken);
    return;
}

var transientFailures = failures.Count(f => f.Kind == EmailDeliveryFailureKind.Transient);

if (transientFailures == 0)
{
    await outboxStore.DeadLetterAsync(
        new EmailOutboxFailure(message.Id, errorMessage, utcNow),
        cancellationToken);
    return;
}

await outboxStore.MarkFailedAsync(
    new EmailOutboxFailure(message.Id, errorMessage, utcNow),
    utcNow.Add(GetRetryDelay(message.AttemptCount)),
    cancellationToken);

The retry delay grows until it reaches the configured maximum.

private TimeSpan GetRetryDelay(int attemptCount)
{
    var delay = options.Value.InitialRetryDelay;

    for (var i = 1; i < attemptCount; i++)
    {
        delay = delay + delay;
        if (delay >= options.Value.MaxRetryDelay)
        {
            return options.Value.MaxRetryDelay;
        }
    }

    return delay;
}

This is not a full message broker. It is a small durable outbox designed for a personal blog.

Dependency Injection

The email system is registered as part of the main application.

services.AddScoped<DbEmailNotificationQueue>();
services.AddScoped<IEmailOutboxStore>(sp => sp.GetRequiredService<DbEmailNotificationQueue>());
services.AddScoped<IEmailNotificationQueue>(sp => sp.GetRequiredService<DbEmailNotificationQueue>());
services.AddScoped<IEmailOutboxMessageProcessor, EmailOutboxMessageProcessor>();
services.AddHostedService<EmailOutboxWorker>();

The same database-backed implementation serves both roles:

IEmailNotificationQueue for enqueueing
IEmailOutboxStore for worker-side claiming and state transitions

Configuration

The outbox worker is configured under the main Email section.

{
  "Email": {
    "Provider": "AzureCommunication",
    "OutboxWorker": {
      "Enabled": true,
      "BatchSize": 5,
      "PollIntervalSeconds": 30,
      "LeaseDurationSeconds": 300,
      "MaxAttempts": 3,
      "InitialRetryDelaySeconds": 60,
      "MaxRetryDelaySeconds": 3600
    }
  }
}

Email:OutboxWorker:Enabled=false stops in-process delivery but does not prevent enqueueing. That can be useful if only one app instance should process the outbox.

A Linux Docker Issue

After deploying to Azure App Service on Linux with Docker, I saw this error repeatedly:

System.UnauthorizedAccessException:
Access to the path '/app/mailConfiguration.xml' is denied.

The container runs as the non-root app user. The published files in /app are owned by root and should be treated as read-only.

The issue was caused by initializing the email template helper with a file path. Internally, that path-based constructor required write access.

The fix was to load the XML file explicitly with read-only access, deserialize it, and pass the configuration object to the email helper.

private static MailConfiguration LoadMailConfiguration()
{
    var configSource = Path.Join(AppContext.BaseDirectory, "mailConfiguration.xml");
    if (!File.Exists(configSource))
    {
        configSource = Path.Join(AppContext.BaseDirectory, "Moonglade.Email", "mailConfiguration.xml");
    }

    var serializer = new XmlSerializer(typeof(MailConfiguration));
    using var stream = File.Open(configSource, FileMode.Open, FileAccess.Read, FileShare.Read);

    return serializer.Deserialize(stream) as MailConfiguration
        ?? throw new InvalidOperationException("Configuration file for EmailHelper is invalid.");
}

Then DI can create the helper without requiring write access to /app.

services.AddSingleton<IEmailHelper>(_ => new EmailHelper(LoadMailConfiguration()));

I verified the fix locally with Docker Desktop:

the container ran as user app
/app/mailConfiguration.xml was owned by root
writing to the file failed with Permission denied
EmailOutboxWorker started successfully
no UnauthorizedAccessException appeared in the logs

Why This Design Fits Moonglade

This migration is not about building a better queue than Azure Storage Queue.

It is about choosing the right amount of infrastructure.

For Moonglade, the email workload is small. The important requirements are:

do not block user requests while sending email
persist notifications across app restarts
retry transient failures
avoid losing messages
reduce Azure dependencies
keep deployment simple

A database outbox meets those requirements with fewer moving parts.

Deprecating The Standalone Repository

With email processing integrated into the main application, the standalone Moonglade.Email Azure Functions repository is deprecated and will be archived.

Future email notification development will happen in the main Moonglade repository.

That leaves Moonglade with a simpler model:

one application
one deployment
one database
one configuration surface
one place to maintain email behavior

Final Thoughts

Azure Functions and Azure Storage Queue are good services. They were not the problem.

The problem was that the architecture had become larger than the product requirement.

For a personal blog, reliability matters, but simplicity matters too. Moving email notifications from Azure Functions into Moonglade’s own database outbox keeps delivery asynchronous and durable while removing an entire external service from the deployment.

That is the kind of tradeoff I want Moonglade to make more often.

Hot Reloading a File in Azure Container Apps with Zero Down Time

2026-03-03T09:37:30Z

Background

Recently, I developed an ASP.NET Core application that can query a local data file for IP address information. The application is deployed to Azure Container Apps, and the data file is mounted in Azure File Share as a volume for the container. There is another job that will update the data file every day on schedule. The application would not read the entire data file on each request for performance concerns, it would load the data into memory on start up. So, the problem is, when the data file is updated, how to reload it in my application?

The most easy way is to restart the container. But this approach clearly would cause downtime for my app, because there's currently only one instance running. So, I need a way to reload the data on the fly without downtime. Let's see how to do it.

The Design

The entire design has 3 core files:

QqwryDb: Immutable Snapshot of the File
QqwryDbProvider: The Thread-Safe Pointer Swap
QqwryDbWatcher: The Polling Engine

Let me explain them one by one.

QqwryDb

The entire .dat file is eagerly read into a byte[] in the constructor. After construction the object never touches the filesystem again. It is a completely immutable, self-contained snapshot.

public sealed class QqwryDb(string path)
{
    private readonly byte[] _data;
    // ...
    public QqwryDb(string path)
    {
        _data = File.ReadAllBytes(path); // entire file read into memory at construction time
        _indexStart = ReadUInt32LE(0);
        _indexEnd   = ReadUInt32LE(4);
    }
}

This is the foundational design decision that makes safe hot-reload possible: once a QqwryDb instance exists, it can be queried concurrently from any number of threads without any locks, because its data never changes.

QqwryDbProvider

This is the heart of the hot-reload design.

public sealed class QqwryDbProvider
{
    private volatile QqwryDb? _current;
    // ...
    internal void TryReload()
    {
        // Guard 1: file disappeared
        if (!File.Exists(_path)) { _current = null; return; }

        // Guard 2: write time hasn't changed — skip
        if (_current is not null && newWriteTime == _lastWriteTime) return;

        // Guard 3: file is suspiciously small — likely mid-write, skip
        if (fileSize < MinValidFileSizeBytes) return;

        var newDb = new QqwryDb(_path);           // construct new snapshot off to the side
        Interlocked.Exchange(ref _current, newDb); // atomically publish it
        _lastWriteTime = newWriteTime;
    }

    public IpLocation Query(IPAddress ip)
    {
        var db = _current ?? throw ...;
        return db.Query(ip); // reads from the snapshot captured at method entry
    }
}

volatile on _current ensures every thread always reads the freshest pointer value from main memory, not a CPU-cache copy.
Interlocked.Exchange makes publishing the new QqwryDb instance a single atomic operation. There is no window where another thread can see a half-initialized state.
The new instance is fully constructed before it is published. The call to new QqwryDb(_path) reads the file and builds all internal state; only then does the swap happen. This means the old instance stays live and queryable right up to the moment the new one takes over.
The file-size guard (MinValidFileSizeBytes = 1 MB) handles the classic race between the writer and the reader: If the external process is still writing the new file when the watcher fires, the file will be smaller than a valid database, so the reload is skipped and retried on the next tick.
The last-write-time guard means the file is only re-read when the OS timestamp actually changed, so normal ticks where nothing happened are completely free.

In-flight requests that captured _current before the swap continue to use the old QqwryDb object until they finish. Because QqwryDb holds its data in a plain managed array, the GC will collect the old instance automatically once no threads hold a reference to it. Zero manual cleanup required!

QqwryDbWatcher

This is a standard ASP.NET Core BackgroundService. It uses PeriodicTimer, which is preferable to Timer + callbacks because it is non-reentrant by design. If TryReload() takes longer than the interval, the next tick simply waits instead of firing a second concurrent reload. The interval is configurable via appsettings.json.

public sealed class QqwryDbWatcher(
    QqwryDbProvider provider,
    IConfiguration configuration,
    ILogger<QqwryDbWatcher> logger) : BackgroundService
{
    private readonly TimeSpan _interval = TimeSpan.FromSeconds(configuration.GetValue("IpDb:ReloadIntervalSeconds", 60));

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(_interval);
        while (await timer.WaitForNextTickAsync(stoppingToken))
        {
            try
            {
                provider.TryReload();
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Failed to reload QQWry database.");
            }
        }
    }
}

DI Registration

Finally, register them in DI container. Notice, QqwryDbProvider is a singleton, there is exactly one pointer in the process, shared by all requests.

builder.Services.AddSingleton(sp =>
    new QqwryDbProvider(qqwryPath, sp.GetRequiredService<ILogger<QqwryDbProvider>>()));

builder.Services.AddHostedService<QqwryDbWatcher>();

Why Polling Instead of FileSystemWatcher?

It's because FileSystemWatcher is unreliable on Linux (which this Docker-targeted app is designed for) and especially inside containers, where bind-mounts and volume drivers do not always propagate INotify events correctly. A periodic poll with a last-write-time check is simpler, portable, and nearly as fast (the cost of File.GetLastWriteTimeUtc is acceptable compared to the interval).

Summary of the Data Flow

[External updater replaces qqwry.dat on disk]
        ↓
[QqwryDbWatcher fires every N seconds]
        ↓
[QqwryDbProvider.TryReload()]
    → checks last-write-time  (cheap, skip if same)
    → checks file size        (guard against partial writes)
    → new QqwryDb(_path)      (reads full file into byte[])
    → Interlocked.Exchange    (atomic pointer swap)
        ↓
[All new requests pick up the new QqwryDb]
[In-flight requests finish against the old QqwryDb, then it is GC'd]

Conclusion

Hot-reloading a binary database file in a live ASP.NET Core can be solved without restarting your server, this three-layer approach of immutable snapshot, atomic pointer swap, background poller is a solid template to do it!

Migrating this Blog to Docker on Linux with Azure App Service

2026-02-05T05:09:58Z

This blog runs on my open-source project Moonglade, a blogging platform built with ASP.NET Core and hosted on Azure. Recently, I migrated it from a Windows Server environment to Docker on Linux, still running on Azure App Service. It’s been running smoothly in production for about two months now.

In this post, I’ll walk through that migration journey: what I changed, a few tips and tricks along the way, and some lessons learned that might help you if you’re considering a similar move.

A Little Bit of History

This project has a long history. Back in the summer of 2008, I was a high school graduate getting ready for university. I learned ASP.NET WebForms from a Microsoft MVP and started building my own website using VB.NET and an Access database. At that time, cloud platforms were still very new. I hosted my site on a shared VPS, which ran into issues almost daily because the provider was unprofessional and unreliable.

In 2012, a Microsoft employee introduced me to Azure, and I became one of the early users of Azure App Service. The idea of deploying a website without managing a full VM was very new back then. The nice part of using a PaaS service was that I no longer had to worry about the underlying infrastructure. Microsoft managed the VMs for me, so I could focus on building features for my blog engine and writing content. At that time, Azure App Service only supported Windows plans: Windows Server and IIS were the underlying stack running my code. For .NET Framework applications, that was basically the default choice, so my ASP.NET WebForms blog ran on Windows, which was a very typical setup.

In 2018, with the release of .NET Core 2.1, I rewrote the entire blog system using ASP.NET Core and open-sourced it on GitHub. The final release of this rewrite completed in 2019 on .NET Core 3.0. I wrote two detailed posts about that migration: “Migrating Old ASP.NET Applications to .NET Core” and “This Blog Now Runs on .NET Core 3.0 and Azure”. However, even after the rewrite, it wasn’t truly cross-platform. There were still legacy design choices, like using Windows-style folder paths. On top of that, I wasn’t very familiar with Linux, so I didn’t feel confident troubleshooting issues if I moved the blog to App Service with Linux. As a result, the blog continued to run on Windows Server behind Azure App Service.

Later, I made an effort to add Docker support so the system could run on Linux, but with limited functionality. Because it’s an open-source project, I can’t expect everyone to use the exact same setup I do. Many users prefer to run the blog engine on-premises on Linux machines, and that’s where they hit feature gaps: my Linux support just wasn’t as complete as on Windows. Ironically, even though my quick deployment script used Linux, my own blog was still running on Windows, which understandably confused new users trying to get started.

By the end of 2025, I decided it was time to fully move to Docker on Linux and start treating Linux as a first-class citizen in my codebase. That migration was successful, and that’s why you’re now reading this blog post running on Docker on Linux in Azure App Service. 🤣

Why Migrating to Docker on Linux

There are a few reasons I decided to make this migration:

Cost: Linux plans are typically about half the price of Windows plans on Azure App Service.
Consistency: Docker gives me a consistent environment across all deployments, which greatly reduces production “surprises”.
Deployment options: With Docker, my blog is no longer tied to Azure App Service only. Users can also run it on Azure Container Apps, AKS, or pretty much any container-friendly platform.
Simpler deployment: The codebase now uses a single deployment path based on Docker. By dropping the separate “code deployment on Windows vs. Linux” options, the scripts are easier to maintain and there’s less room for bugs.
Faster onboarding: Setting up a new Moonglade instance used to be painful, even with automated scripts. Now, with a single docker compose up, users can get a blog up and running in about a minute.
Sidecar support: Azure App Service supports sidecar pattern for Docker deployments, which makes it possible for me to integrate with Phi-4 SLM as sidecar in the future.

That said, this doesn’t mean I’ve stopped liking Windows Server, or that the blog no longer runs on Windows. Windows is still a supported option, it’s just no longer the preferred one.

Now, Let's walk through the key steps of this migration.

0. Prepare the Code for Fully Cross Platform

This is a checklist to ensure your code runs on Linux. I spent most of the time refactoring my code and tested it on Linux environments to make sure every feature works.

File system paths, separators, and drives

Remove hardcoded Windows paths ( C:\, D:\, UNC paths like \\server\share).
Replace backslash path building with Path.Combine(...).
Use Path.DirectorySeparatorChar only when needed; prefer Path.Combine.
Use IWebHostEnvironment.ContentRootPath / WebRootPath as base paths (not AppDomain.CurrentDomain.BaseDirectory).
Ensure paths don’t assume drive letters; use mount points or configurable base directories.
Treat file paths as case-sensitive (e.g., Images/logo.png ≠ images/logo.png).

Configuration differences

Remove dependencies on Windows Registry
Remove dependencies on machine.config

File permissions

Don’t write into the application install directory.
Use Path.GetTempPath() instead of hard coded Windows temp path.

Encoding and Time

Do not rely on Windows only encoding providers.
Do not hard code Windows time zone names like "Pacific Standard Time", use IANA names.

1. For Local or On-Prem Deployments: Docker Compose

To make it easier for users to spin up Moonglade on their own machine or in an on-prem environment, I chose Docker Compose. With Compose, all the dependencies like database, network, file storage, can be set up with a single command. Users don’t need to understand all the details or wire up each piece manually, Docker Compose takes care of that for them.

The final compose.yaml file is:

services:
  web:
    image: ${MOONGLADE_IMAGE:-ediwang/moonglade:latest}
    build:
      context: .
      dockerfile: Dockerfile
    container_name: moonglade-web
    environment:
      ASPNETCORE_ENVIRONMENT: "Production"
      ConnectionStrings__MoongladeDatabase: "Server=moonglade-sqlserver;Database=moonglade;User Id=sa;Password=${MSSQL_SA_PASSWORD:-Work@996};Trusted_Connection=False;TrustServerCertificate=True;"
      ImageStorage__FileSystemPath: "/app/images"
    ports:
      - "8080:8080"
    depends_on:
      - database
    volumes:
      - moonglade-images:/app/images
    networks:
      - moonglade-network
  database:
    image: mcr.microsoft.com/mssql/server:2025-latest
    container_name: moonglade-sqlserver
    environment:
      MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD:-Work@996}"
      MSSQL_PID: "Express"
      ACCEPT_EULA: "Y"
    ports:
      - "1433:1433"
    volumes:
      - mssql-data:/var/opt/mssql
    networks:
      - moonglade-network

volumes:
  mssql-data:
  moonglade-images:

networks:
  moonglade-network:
    driver: bridge

Image and build

image: The image name is configurable via the MOONGLADE_IMAGE environment variable.

If MOONGLADE_IMAGE is not set, it falls back to ediwang/moonglade:latest.

This makes it easy to use a custom image in CI/CD, or just run the default public image locally.

Environment variables

ASPNETCORE_ENVIRONMENT: "Production": Runs the app in Production mode (as opposed to Development or Staging). This impacts things like error pages, logging, and configuration behavior.

ConnectionStrings__MoongladeDatabase: This is the standard ASP.NET Core config convention: ConnectionStrings:MoongladeDatabase in appsettings maps to ConnectionStrings__MoongladeDatabase in environment variables.

About image storage

ImageStorage__FileSystemPath: "/app/images": Tells the app to store images under /app/images inside the container.

This blog is storing images with file system by default. Users can configure the location of the image files in appsettings.json like this.

"ImageStorage": {
  "Provider": "filesystem",
  "FileSystemPath": "/app/images"
}

In Docker deployments, this will be typically mapped to a volume. To enable that, I need to first modify Dockerfile so that it can have correct ownership for image storage.

USER root
RUN mkdir -p /app/images && chown -R app:app /app/images

So that this will work in Docker Compose.

volumes:
  - moonglade-images:/app/images

This mounts a named volume called moonglade-images at /app/images inside the web container.

It matches the ImageStorage__FileSystemPath setting, and ensures uploaded images persist even if the container is recreated.

Network

The web container is attached to the moonglade-network Docker network (defined later). This is how it can resolve moonglade-sqlserver as the DB server.

Database

Uses the official SQL Server container image from the Microsoft Container Registry. Express is free and sufficient for many small/medium workloads like a blog system.

MSSQL_SA_PASSWORD: Sets the password for the sa login. It reads from the host environment variable MSSQL_SA_PASSWORD if present. Otherwise falls back to Work@996.

In a real deployment, you should override this with a secure password (e.g., via a secret or environment variable).

mssql-data is a named volume.

/var/opt/mssql is where SQL Server stores its data files inside the container.

This ensures that your database data persists across container restarts. You can update or recreate the database container without losing data.

Running Docker Compose

Now, users can deploy Moonglade on any machine that has Docker installed with one single command: docker compose up -d

Visiting port 8080, you can see Moonglade is now running.

You can also use Docker Compose with Azure Container Apps, but in my case it’s not the right choice. Azure already provides SQL Database as a fully managed service, which is easier and more secure to use. There’s no real benefit in running a SQL Express instance alongside the web container when a managed Azure SQL Database is available.

2. For Azure Deployment

Migrating App Service Instance

First, there is a limit: You can not change an App Service from Windows Plan to Linux, you have to re-create a new App Service with a Linux Plan.

You need to choose "Container" as publish method when creating the App Service. You will no longer be able to change it after creation for now (Feb 2026).

The container image configuration can be changed after the initial creation. I publish my image to Docker Hub, the setup is like below.

Please note, the "Continuous deployment" checkbox will sometimes does not work with Docker Hub, although it seem to work fine with Azure Container Registry. So I would prefer leave this option unselected. If I need to update my production deployment, I will just restart my App Service instance. This will force Azure to check for image update.

Please also be aware that App Service by default, check for common HTTP port like 80, 443, 8080. In my case, I am using 8080, so the App Service can find my workload automatically. If your container uses other ports, you need to setup it in HTTP_PORT environment variable.

Update Environment Variables

This is a key difference between Windows and Linux configuration for an ASP.NET Core application. On Linux, you need to use a double underscore __ to represent a single colon : in configuration keys.

About ASP.NET Core Runtime

In the past, if you are using FDD on Azure App Service with Windows, the ASP.NET Core runtime will be pre-installed on the underlying web worker VM. You can install a new version in the "Extension" blade when a new release comes even before Microsoft pushes the update to every server farm.

Now, it is not possible and not necessary any more. Because Docker just contains the ASP.NET Core runtime itself when building the container image. In fact, the code is now served by Kestrel instead of IIS. So you don't need to worry about things like IIS magic, ANCM blow up etc.

Migrating IIS Magics

Previously, a lot of things were handled at the web server level through the web.config file. In a typical IIS-hosted ASP.NET Core app, you might configure things like:

Static and dynamic compression (gzip)
Adding CSP headers
MIME type registrations
Removing IIS server headers
URL rewrite rules
Reverse proxy via ARR
HTTPS redirection

On Linux with Docker, there’s no IIS and no web.config, so these concerns need to be handled differently. You either move them into your application code, or put a proxy in front of the app (like Nginx, or in my case, Azure Front Door) and configure them there instead.

Database

In Azure, I don’t run SQL Server as another container in the same Docker network. Instead, I use Azure SQL Database, just like before. So the data layer stays exactly the same, and I don’t need Docker Compose for the Azure deployment at this point.

Networking

ASP.NET Core running in Docker needs to enable forwarded headers to correctly read client IP address. In Moonglade, it can be enabled by a simple switch.

"ForwardedHeaders": {
  "Enabled": true
}

Typically, in an ASP.NET Core application, you can either setup it in the code or use the ASPNETCORE_FORWARDEDHEADERS_ENABLED=true environment variable.

Conclusion

Migrating an ASP.NET Core application from Windows to Docker on Linux and running it on Azure App Service involves a few key steps:

Remove Windows-specific dependencies in code

Eliminate assumptions about Windows paths, file systems, IIS integration, or registry access. Make sure the app is truly cross-platform.

Prepare your Dockerfile (and optional Docker Compose)

Create a Dockerfile with the right base image, permissions, and volume mappings so your data persists across container restarts. Optionally, use Docker Compose for local or on-prem scenarios.

Configure Azure App Service for Linux

Move to an App Service Linux plan, point it to your container image, configure environment variables with the correct naming conventions, and remove any IIS-specific configuration or reliance on web.config.

Once these pieces are in place, your ASP.NET Core app should run smoothly in Docker on Linux in Azure App Service.

Happy coding!

程序员的情绪价值：用 C# 构建实时 MIDI 播放器

2025-09-25T13:27:34Z

引言

在数字音乐的世界里，MIDI（Musical Instrument Digital Interface）就像是音乐的"基因密码"。作为直男程序员，我最近使用.NET 9.0 C# 写了一个命令行 MIDI 播放器，用来增加自己的情绪价值。本文将分析这个有趣的开源项目 Edi.MIDIPlayer，它不仅能播放MIDI音乐，还能实时显示每一个音符的"生命轨迹"。

什么是 MIDI？

MIDI 格式介绍

MIDI 并不是音频文件，而是一种指令协议，一种面向电子乐器、计算机和其他相关设备的标准通讯协议与数据格式。想象一下，如果音频文件是录制好的演奏录音，那么 MIDI 就是乐谱上的指令。MIDI 协议定义了乐器与乐器、乐器与电脑之间的数字信息传输方式，但它本身并不直接包含声音数据，而是传递“事件信息”（例如：演奏某个音符、控制某个参数、开始/停止等），例如：

何时按下哪个键（Note On 事件）
多大力度按下（Velocity，0-127）
何时松开键（Note Off 事件）
哪个通道发出声音（Channel，支持16个通道）
用什么乐器演奏（Program Change）

MIDI 广泛应用于音乐制作、游戏音效、电子乐器等领域。它的优势在于文件小、易于编辑和实时控制。

标准 MIDI 文件（SMF，Standard MIDI File）由三部分组成：

1 Header Chunk

标记为"MThd"，存储文件类型（0/1/2）、轨道数量、时间单位（Ticks per Quarter Note，TPQN）

2 Track Chunk

标记为"MTrk"

每个 Track 为一个 MIDI 数据流，内容为一组有时间戳标记的 MIDI 事件（例如演奏音符、控件变化）。

类型0：单一轨道
类型1：多轨道（常见于编曲，有主控轨+乐器轨）
类型2：多序列轨道，罕见

3 MIDI 事件

频道消息（Channel Messages）：音符开/关、力度、控制器、乐器选择等
系统消息（System Messages）：同步、元事件（如歌词、节拍、作者信息等）

MIDI 文件示例

4D 54 68 64    // "MThd" Header
00 00 00 06    // Head Size = 6
00 01          // Type 1 (多轨道)
00 02          // 两个轨道
00 60          // 96 ticks/quarter note

4D 54 72 6B    // "MTrk" Track
00 00 00 30    // Track Size

00 90 3C 64    // DeltaTime=0, Note On, middle C, velocity 100
81 40 80 3C 40 // DeltaTime=192, Note Off, middle C, velocity 64
...

好消息是，我们不需要自己 996 实现 MIDI 文件的解析，这个播放器程序使用 NAudio 库来处理 MIDI 文件。

乐理知识的代码实现

音符

在深入代码之前，我们需要了解一些音乐基础：

音符命名：C、C#、D、D#、E、F、F#、G、G#、A、A#、B（12个半音）
八度：每12个半音为一个八度，中央C为C4
MIDI音符编号：0-127，其中60号是中央C（C4）

在代码中，我们可以看到音符名称的转换逻辑：

private static readonly Dictionary<int, string> NoteNames = new()
{
    { 0, "C" }, { 1, "C#" }, { 2, "D" }, { 3, "D#" }, { 4, "E" }, { 5, "F" },
    { 6, "F#" }, { 7, "G" }, { 8, "G#" }, { 9, "A" }, { 10, "A#" }, { 11, "B" }
};

public string GetNoteName(int noteNumber)
{
    var octave = (noteNumber / 12) - 1;  // 计算八度
    var note = NoteNames[noteNumber % 12];  // 计算音符名称
    return $"{note}{octave}";
}

这个算法巧妙地将 MIDI 音符编号转换为我们熟悉的音符名称。例如：

音符60 → 60 % 12 = 0 (C), 60 / 12 - 1 = 4 → "C4"
音符73 → 73 % 12 = 1 (C#), 73 / 12 - 1 = 5 → "C#5"

节拍

节拍，是乐理中的一个重要概念，用于表示音乐中强弱规律的循环。

乐谱开头通常会标注一个拍号，比如“4/4”、“3/4”，这表示每小节有多少拍（上数字），以及每一拍用了哪种音符（下数字，例如“4”代表四分音符）。

在 MIDI 文件中，节拍的相关参数主要通过一种特殊的元事件（Meta Event）来表示，这个事件叫做“节拍事件”（Set Tempo）和“时基（PPQN／TPQN）”，“但严格来说，拍号（Time Signature）表示的是每小节包含的拍数和每拍的音符类型”。

MIDI 文件内部不直接用秒来表示时间，而是用“Tick”（时基）单位。Tick数取决于MIDI文件头中设定的“PPQN”（Parts Per Quarter Note，四分音符每分多少Tick）。例如：如果PPQN设为480，则一个四分音符等于480 Tick。

通过Meta事件类型 0xFF 0x51，设置每个四分音符的微秒数，从而间接决定每分钟的节拍数（BPM）。

拍号/节拍事件用 Meta Event 类型 0xFF 0x58 表示，一般描述每小节有几拍，每拍是什么音符类型，与乐理中的拍号类似。

程序里需要将 Tick 转换为实际时间：

public TimeSpan TicksToTimeSpan(long ticks, List<TempoChange> tempoMap, int ticksPerQuarterNote)
{
    var totalMicroseconds = 0.0;
    var currentTick = 0L;

    for (int i = 0; i < tempoMap.Count; i++)
    {
        var tempoChange = tempoMap[i];
        var nextTick = (i + 1 < tempoMap.Count) ? tempoMap[i + 1].Tick : ticks;

        if (nextTick > ticks) nextTick = ticks;

        if (nextTick > currentTick)
        {
            var ticksInThisSegment = nextTick - currentTick;
            var microsecondsPerTick = (double)tempoChange.MicrosecondsPerQuarterNote / ticksPerQuarterNote;
            totalMicroseconds += ticksInThisSegment * microsecondsPerTick;
        }

        currentTick = nextTick;
        if (currentTick >= ticks) break;
    }

    return TimeSpan.FromMilliseconds(totalMicroseconds / 1000.0);
}

这个算法处理了 MIDI 中的变速情况——一首曲子中可能有多个速度变化，每个段落都需要用不同的时间计算公式。

程序还需要构建整个 MIDI 文件的速度变化映射表，查找类型为 MetaEvent 且子类型为 SetTempo 的事件，并记录速度变化：

tempoMap.Add(new TempoChange
   {
       Tick = eventInfo.AbsoluteTime,  // 速度变化的时钟位置
       MicrosecondsPerQuarterNote = tempoEvent.MicrosecondsPerQuarterNote  // 新的速度值
   });

这对于准确播放 MIDI 文件至关重要，确保音乐按照正确的速度和节拍进行播放。

程序架构解析

依赖注入与服务架构

这个MIDI播放器采用了现代.NET的最佳实践，使用了依赖注入来管理各个组件：

private static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureServices((context, services) =>
        {
            services.AddSingleton<IConsoleDisplay, ConsoleDisplayService>();
            services.AddSingleton<IInputHandler, InputHandlerService>();
            services.AddSingleton<ITempoManager, TempoManagerService>();
            services.AddSingleton<INoteProcessor, NoteProcessorService>();
        });

整个系统分为几个核心服务：

ConsoleDisplayService：负责所有的控制台输出和视觉效果
TempoManagerService：处理MIDI的节拍和时间计算
NoteProcessorService：处理音符事件的显示逻辑
MidiPlayerService：核心播放逻辑

实时MIDI事件处理

程序的核心在于如何准确地按时间播放 MIDI 事件。让我们看看这个精巧的时间控制算法：

private async Task PlayEventsAsync(List<MidiEventInfo> allEvents, IMidiDeviceWrapper midiDevice, int ticksPerQuarterNote)
{
    var stopwatch = Stopwatch.StartNew();
    var playbackStart = stopwatch.Elapsed;

    foreach (var midiEntry in allEvents)
    {
        // 计算这个事件的预期播放时间
        var expectedTime = playbackStart.Add(tempoManager.TicksToTimeSpan(midiEntry.AbsoluteTime, tempoMap, ticksPerQuarterNote));
        var currentTime = stopwatch.Elapsed;

        // 等待直到该播放这个事件
        var delayNeeded = expectedTime - currentTime;
        if (delayNeeded > TimeSpan.Zero)
        {
            await Task.Delay(delayNeeded);
        }

        ProcessMidiEvent(midiEntry, midiDevice, stopwatch, activeNotes);
    }
}

这里的关键是精确的时间同步：

使用 Stopwatch 获得高精度计时
计算每个 MIDI 事件的绝对播放时间
使用 Task.Delay 进行非阻塞等待
确保音乐按照正确的节拍播放

视觉魔法：让音乐可见

实时力度

最有趣的功能之一是力度条的显示。每个音符的演奏力度（0-127）会被转换为彩色的条形图：

public string CreateVelocityBar(int velocity)
{
    var barLength = 10;
    var filledLength = (int)((velocity / 127.0) * barLength);
    var bar = new StringBuilder();

    for (int i = 0; i < barLength; i++)
    {
        if (i < filledLength)
        {
            if (i < 3) Console.ForegroundColor = ConsoleColor.Green;      // 轻柔
            else if (i < 7) Console.ForegroundColor = ConsoleColor.Yellow; // 中等
            else Console.ForegroundColor = ConsoleColor.Red;              // 强烈
            bar.Append('█');
        }
        else
        {
            Console.ForegroundColor = ConsoleColor.DarkGray;
            bar.Append('░');
        }
    }
    
    return bar.ToString();
}

这样，我们就能直观地看到音乐的动态变化：

VEL:0x4F ██████░░░░  // 中等力度
VEL:0x7F ██████████  // 最大力度
VEL:0x20 ███░░░░░░░  // 轻柔力度

彩色音符显示

程序还根据音符类型显示不同颜色：

public ConsoleColor GetNoteColor(int noteNumber)
{
    return (noteNumber % 12) switch
    {
        0 or 2 or 4 or 5 or 7 or 9 or 11 => ConsoleColor.White,  // 自然音（白键）
        _ => ConsoleColor.Magenta  // 升降音（黑键）
    };
}

这个设计模拟了钢琴键盘的布局，白键音符显示为白色，黑键音符显示为紫色。

控制台输出的实时同步

线程安全的输出

由于 MIDI 事件可能来自多个通道，程序使用了锁机制确保输出的一致性：

lock (consoleDisplay.GetConsoleLock())
{
    Console.Write("[");
    Console.ForegroundColor = ConsoleColor.DarkGray;
    Console.Write(timestamp);
    Console.ResetColor();
    Console.Write("] ");

    Console.ForegroundColor = ConsoleColor.Green;
    Console.Write("▲ NOTE_ON  ");
    // ... 更多输出逻辑
}

信息密度的平衡

每行输出都包含了丰富的信息，但又保持了很好的可读性：

[14:23:45.123] ▲ NOTE_ON  C4   CH01 VEL:0x64 ████████░░ │ ACTV: 0x03 │ NOTE: 0x3C
[14:23:45.823] ▼ NOTE_OFF C4   CH01 VEL:0x00 ░░░░░░░░░░ │ ACTV: 0x02 │ NOTE: 0x3C

这行输出告诉我们：

时间戳：精确到毫秒的播放时间
事件类型：▲表示按键，▼表示释放
音符信息：C4 表示中央C
通道信息：CH01 表示第1通道
力度信息：0x64 表示中等力度，用条形图可视化
状态信息：当前活跃音符数量和原始 MIDI 数据

结语

这个 MIDI 播放器不仅仅是一个播放工具，更是一个音乐数据的实时可视化器。它让我们能够"看见"音乐的流动，理解 MIDI 数据的结构，体验数字音乐的魅力。

通过这个项目，我们学到了：

MIDI 格式的内部结构
精确时间控制的编程技巧
控制台应用的视觉设计
现代 .NET 的最佳实践

无论你是音乐爱好者还是程序员，这个项目都展示了技术与艺术结合的美妙可能性。下次当你听到 MIDI 音乐时，不妨想象一下背后那些精密的数字指令，它们正在控制着每一个音符的生命周期。

源代码地址：https://github.com/EdiWang/Edi.MIDIPlayer

凑发票算法：经典背包问题的变种

2025-02-08T01:59:22Z

在日常工作中，特别是报销或财务处理时，经常会遇到这样的问题：如何从一堆发票中找到金额满足某个值的最优组合？本文将基于 C#，使用背包问题的思路来卷这个问题，并详细讲解其设计和实现细节。

问题

假设我们有一组发票，每张发票以文件名的形式存储，文件名包含发票金额，例如 酒店-996.35.pdf 打车-251.00 医疗-404.00 。我们的目标是从这些发票中，找到金额总和 至少等于目标金额 的最优组合，并且总金额尽可能接近目标金额。以最大程度的节省发票以供下次报销使用。

例如：我需要报销1000元，现有发票如下：

酒店-996.00.pdf
咖喱饭-35.00.pdf
文具-7.00.pdf

显然，要凑1000元的发票，最优解是使用 酒店-996.00.pdf + 文具-7.00.pdf = 1003.00 元，这样的话，咖喱饭-35.00.pdf 可用于下次报销使用。在文件较少的情况下，肉眼就能找到最优组合，但当文件夹里有几十、上百张发票的时候，人工凑发票就会让你996。

算法设计

要解决这个问题，我们可以将其看作一个 背包问题的变种，即在给定一组发票的情况下，找到满足条件的金额组合。本文的算法采用 回溯法 来实现，逐步尝试每种可能的组合，并记录满足条件的最佳结果。

背包问题（英语：Knapsack problem）是一种组合优化的NP完全问题。问题可以描述为：给定一组物品，每种物品都有自己的重量和价格，在限定的总重量内，我们如何选择，才能使得物品的总价格最高。问题的名称来源于如何选择最合适的物品放置于给定背包中，背包的空间有限，但我们需要最大化背包内所装物品的价值。背包问题通常出现在资源分配中，决策者必须分别从一组不可分割的项目或任务中进行选择，而这些项目又有时间或预算的限制。

首先，我们定义一个 Invoice 类，用来存储发票的文件名和金额：

private class Invoice
{
    public string FileName { get; set; }
    public double Amount { get; set; }
}

从当前目录中读取所有 PDF 文件，并将文件名存储到一个列表中：

// 获取当前目录
string currentDirectory = Path.GetDirectoryName(Util.CurrentQueryPath);

// 获取当前目录下所有PDF文件的文件名
string[] pdfFiles = Directory.GetFiles(currentDirectory, "*.pdf");

// 创建一个List<string>集合来存储文件名
List<string> invoiceFileNames = new List<string>();

// 将每个文件的文件名添加到List<string>集合中
foreach (string file in pdfFiles)
{
    // 只获取文件名，不包括路径
    string fileName = Path.GetFileName(file);
    invoiceFileNames.Add(fileName);
}

发票的文件名采用了固定的格式，例如 加班福报-996.35.pdf，我们通过解析文件名来提取金额：

var invoices = invoiceFileNames.Select(fileName =>
{
    var parts = Path.GetFileNameWithoutExtension(fileName).Split('-');
    return new Invoice
    {
        FileName = fileName,
        Amount = double.Parse(parts[1], CultureInfo.InvariantCulture)
    };
}).ToList();

这里我们将文件名按 - 分割，提取第二部分作为金额，并将其转换为 double 类型（其实金融计算更适合用decimal，但不要在意这些细节）

核心算法部分是一个回溯函数，用来尝试所有可能的发票组合：

void FindCombination(List<Invoice> currentCombination, int startIndex, double currentSum)
{
    // 如果当前组合的金额满足条件，且比之前的最佳组合更优，则更新最佳组合
    if (currentSum >= targetAmount && (bestCombination == null || currentSum < bestAmount))
    {
        bestAmount = currentSum;
        bestCombination = new List<Invoice>(currentCombination);
        return;
    }

    // 遍历剩余的发票，尝试加入当前组合
    for (int i = startIndex; i < invoices.Count; i++)
    {
        currentCombination.Add(invoices[i]);
        FindCombination(currentCombination, i + 1, currentSum + invoices[i].Amount);
        currentCombination.RemoveAt(currentCombination.Count - 1); // 回溯
    }
}

回溯的核心逻辑：

递归搜索：从起始位置开始，逐步尝试将每张发票加入当前组合。
剪枝条件：如果当前组合的金额已经满足条件且优于之前的组合，则更新最佳组合。
回溯：在递归返回时，移除最后一张发票，尝试其他可能的组合。

找到最佳组合后，我们将结果输出到控制台：

if (selectedInvoices != null)
{
    Console.WriteLine($"满足至少{targetAmount}的最优发票组合:");
    Console.WriteLine("----------------------------------");
    
    foreach (var invoice in selectedInvoices)
    {
        Console.WriteLine(invoice.FileName);
    }
    
    Console.WriteLine("----------------------------------");
    Console.WriteLine(selectedInvoices.Sum(p => p.Amount));
}
else
{
    Console.WriteLine("发票不够");
}

示例运行

当前目录有发票文件如下：

医疗-404.00.pdf
咖喱饭-35.00.pdf
打车-251.00.pdf
文具-7.00.pdf
酒店-996.00.pdf

设定目标金额为 290.00 元，程序输出结果为：

满足至少290的最优发票组合:
----------------------------------
咖喱饭-35.00.pdf
打车-251.00.pdf
文具-7.00.pdf
----------------------------------
293

设定目标金额为 1000.00 元，程序输出结果为：

满足至少1000的最优发票组合:
----------------------------------
文具-7.00.pdf
酒店-996.00.pdf
----------------------------------
1003

直观图示

拿文章开头的问题来说，在 酒店-996.00.pdf 咖喱饭-35.00.pdf 文具-7.00.pdf 中寻找满足1000元的最佳发票组合的过程是将问题转化为一个递归决策树，每个节点表示当前组合的金额总和和发票选择状态。算法从根节点开始，每次递归尝试包含或不包含当前发票，直到遍历所有可能的组合。

Start (Sum = 0, Combination = [])
├── Include 酒店-996.00.pdf (Sum = 996.00, Combination = [酒店-996.00.pdf])
│   ├── Include 咖喱饭-35.00.pdf (Sum = 1031.00, Combination = [酒店-996.00.pdf, 咖喱饭-35.00.pdf])
│   │   ├── Include 文具-7.00.pdf (Sum = 1038.00, Combination = [酒店-996.00.pdf, 咖喱饭-35.00.pdf, 文具-7.00.pdf])
│   │   └── Exclude 文具-7.00.pdf (Sum = 1031.00, Combination = [酒店-996.00.pdf, 咖喱饭-35.00.pdf])
│   └── Exclude 咖喱饭-35.00.pdf (Sum = 996.00, Combination = [酒店-996.00.pdf])
│       ├── Include 文具-7.00.pdf (Sum = 1003.00, Combination = [酒店-996.00.pdf, 文具-7.00.pdf]) -> 满足条件，记录最佳组合
│       └── Exclude 文具-7.00.pdf (Sum = 996.00, Combination = [酒店-996.00.pdf])
├── Exclude 酒店-996.00.pdf (Sum = 0, Combination = [])
    ├── Include 咖喱饭-35.00.pdf (Sum = 35.00, Combination = [咖喱饭-35.00.pdf])
    │   ├── Include 文具-7.00.pdf (Sum = 42.00, Combination = [咖喱饭-35.00.pdf, 文具-7.00.pdf])
    │   └── Exclude 文具-7.00.pdf (Sum = 35.00, Combination = [咖喱饭-35.00.pdf])
    └── Exclude 咖喱饭-35.00.pdf (Sum = 0, Combination = [])
        ├── Include 文具-7.00.pdf (Sum = 7.00, Combination = [文具-7.00.pdf])
        └── Exclude 文具-7.00.pdf (Sum = 0, Combination = [])

算法从金额为 0 的空组合开始。每个分支表示对当前发票的两种选择：Include 或 Exclude。叶子节点表示所有发票都已处理完成，此时检查组合是否满足条件，即金额 >= 1000 元。如果当前金额已经满足条件，则记录组合并停止进一步递归。

从递归树中可以看出，满足至少 1000 元的组合有以下路径：

路径 A：包含 酒店-996.00.pdf 和 文具-7.00.pdf ，总金额：996.00 + 7.00 = 1003.00
路径 B：包含 酒店-996.00.pdf 和 咖喱饭-35.00.pdf ，总金额：996.00 + 35.00 = 1031.00

最终，算法选择金额最接近目标值的路径A。

算法复杂度分析

时间复杂度：由于回溯法会尝试所有可能的组合，其时间复杂度为 $O(2^n)$ ，其中 $n$ 是发票的数量。

空间复杂度：递归调用栈的深度为。

虽然时间复杂度较高，但对于发票数量较少的场景（例如几十张发票），该算法依然可以在可接受的时间内完成计算。

总结

本文通过一个实际的发票金额匹配问题，详细介绍了如何使用 C# 实现一个基于回溯法的凑发票算法。该算法的核心在于递归搜索所有可能的组合，并通过剪枝优化来提高效率。希望本文的讲解能够帮助大家更好地理解回溯法的应用场景，并为实际工作中的类似问题提供参考解决方案。

Understanding the "Efficient Shipping" Interview Question in C#

2025-01-28T01:22:47Z

This blog post is assisted by AI

When preparing for interviews, you'll often come across optimization problems that test both your problem-solving skills and your ability to write efficient code. I have such an interesting programming interview question years ago. The Efficient Shipping problem. Let's break it down and analyze the solution. And to understand the flaws in the first version of my code and how we can improve it.

Problem Statement: Efficient Shipping

You are tasked with maximizing the number of units that can be shipped using a truck with a limited capacity. Here's how the problem is defined:

"A warehouse manager needs to create a shipment to fill a truck. All of the products in the warehouse are in boxes of the same size. Each product is packed in some number of units per box. Given the number of boxes the truck can hold, determine the maximum number of units of any mix of products that can be shipped."

Example

boxes = [1, 2, 3] (1 box of Product 0, 2 boxes of Product 1, 3 boxes of Product 2)
unitsPerBox = [3, 2, 1] (Product 0 has 3 units/box, Product 1 has 2 units/box, Product 2 has 1 unit/box)
trucksize = 3 (The truck can carry 3 boxes in total)

Output

The maximum number of units that can be shipped is 3+2+2 = 7

Issues in the First Version of My Code

At the interview, the code I use was:

public static long GetMaxUnits(List<long> boxes, List<long> unitsPerBox, long trucksize)
{
	long result = 0;
	long cap = 0; 
	long max = 0;

	for (int i = 0; i < boxes.Count; i++)
	{
		cap += boxes[i]; 
		if (cap <= trucksize)
		{
			max += boxes[i] * unitsPerBox[i]; 
			if (result < max) result = max;
		}
	}

	return result;
}

It's one of the solution that you can easily Googled it online, like this https://www.youtube.com/watch?v=GadpHxosSTw

At first glance, the code seems like it's trying to calculate the maximum units by iterating through the list of boxes and adding them to the truck until the capacity is reached. However, there are several issues with this implementation:

No Sorting by Units per Box:
- The problem is about maximizing the number of units, but the code does not prioritize products with the highest units per box. Instead, it processes the boxes in the order they appear in the input.
- For example, if unitsPerBox = [1, 3, 2], the truck might pick low-value boxes first, leading to a suboptimal result.
Incorrect Capacity Handling (cap):
- The variable cap tracks how many boxes have been added so far. However, it doesn't handle cases where adding a product would exceed the truck’s capacity. The code assumes that all boxes of a product can fit into the truck, which is not always true.
Inefficiency:
- The algorithm has a time complexity of O(n), but it doesn't maximize the units shipped because it doesn't sort or prioritize the boxes effectively.

Improved Solution

To solve this problem correctly, we need to focus on greedy optimization. The key idea is to always pick boxes with the highest unitsPerBox first. Here’s how we can approach it:

Pair Boxes with Units per Box: Create a list of tuples where each tuple represents a product (boxes[i], unitsPerBox[i]).
Sort by Units per Box: Sort the list in descending order of unitsPerBox.
Iterate and Fill the Truck: Start adding boxes to the truck, prioritizing products with the most units per box. If the truck's capacity is exceeded, take only the number of boxes that fit.

This is now the corrected code:

public static long GetMaxUnits(List<long> boxes, List<long> unitsPerBox, long trucksize)
{
    // Pair boxes with unitsPerBox and sort by unitsPerBox in descending order
    var products = boxes
        .Select((box, index) => new { Boxes = box, UnitsPerBox = unitsPerBox[index] })
        .OrderByDescending(product => product.UnitsPerBox)
        .ToList();

    long result = 0;

    foreach (var product in products)
    {
        if (trucksize == 0) break;

        // Take as many boxes as the truck can fit
        long boxesToTake = Math.Min(product.Boxes, trucksize);

        // Add units to the result
        result += boxesToTake * product.UnitsPerBox;

        // Decrease truck capacity
        trucksize -= boxesToTake;
    }

    return result;
}

Step-by-Step Explanation of the Code

Pairing and Sorting

We pair each product's boxes and unitsPerBox into a list of objects. Then, we sort this list in descending order based on unitsPerBox to prioritize the most valuable products.

Iterating Through Products

For each product, we calculate how many boxes can be taken without exceeding the truck’s capacity. Multiply the number of boxes taken by the unitsPerBox to calculate the total units added to the truck.

Updating the Truck Capacity

After adding boxes of a product, we reduce the truck’s remaining capacity (trucksize).

Breaking Early

If the truck is full (trucksize == 0), we stop processing further products.

Complexity Analysis

Sorting: Sorting the products by unitsPerBox takes , where is the number of products.
Iteration: Iterating through the sorted products takes .
Overall Time Complexity: O(n log⁡ n).

Example Walkthrough

Let’s run the example input:

void Main()
{
	List<long> boxes = [1, 2, 3];
	List<long> unitsPerBox = [3, 2, 1];
	long trucksize = 3;
	
	var result = GetMaxUnits(boxes, unitsPerBox, trucksize);
	Console.WriteLine(result);
}

Pair and sort:
- Products: [{Boxes = 1, UnitsPerBox = 3}, {Boxes = 2, UnitsPerBox = 2}, {Boxes = 3, UnitsPerBox = 1}].
Start filling the truck:
- Take 1 box of Product 0 (1×3=3 units).
- Take 2 boxes of Product 1 (2×2=4 units).
Truck is full. Total units = 3+4=7.

Conclusion

This problem is a great example of how sorting and greedy algorithms can be applied to solve real-world optimization problems. The corrected solution uses a greedy approach to maximize the number of units shipped. By sorting the products based on their value (units per box) and strategically filling the truck, we ensure the most efficient use of the truck’s capacity.

Migrating Moonglade.Email to Azure Communication Service

2024-11-25T02:58:17Z

Background

The email service used by this blog system, Moonglade.Email, is an Azure Function that originally relied on SMTP for sending emails. I introduced its design in a previous blog post "Cloud Architecture Design of My Email Notification Infrastructure on Azure."

Recently, Microsoft implemented a change that prevents connections to both personal and enterprise Office 365 Outlook mailboxes. The issue stems from the discontinuation of basic authentication due to security concerns. For enterprise M365 users, migrating to the modern OAuth method is straightforward. However, this isn't feasible for personal Outlook.com users since we don't control the server.

To ensure the email service continues functioning, I needed an alternative method for sending emails. Since my entire system operates on Azure, I decided to integrate Azure Communication Services.

In this blog post, I will explain how I implemented support for Azure Communication Services in the Moonglade.Email Azure Function.

Setup Azure Communication Service

Create Azure Communication Service

In Azure portal, deploy a new Azure Communication Service is super easy. Select your subscription and resource group, give it a name, and choose your desired Data location. Nothing more.

Add Email Communication Service

Once the deployment is completed, search "email" in Azure portal, and then create a Email Communication Service

Select the same Data location as your primary Azure Communication Service. In my case, they should be both "United States"

Try Email

Once the Email Communication Service is deployed, go back to your Azure Communication Service instance. Go to "Try Email" menu, then select "Set up a free Azure subdomain" in the "Send email from" dropdown list.

Select the email service that was previously deployed, and hit "Create + Activate".

Once the subdomain is activated, go back and select this domain from the dropdown list. Fill everything else, then you can send a test email.

Please be noted, the test email from a random subdomain is likely to go to your junk email folder, make sure to check your junk box for that.

Bind Custom Domain

Now that our test email works, it's time to bind your custom domain to avoid your emails going to user's junk boxes.

You can do this by following the instructions in "Domains" menu.

Get Connection String

Finally, copy the connection string in "Keys" menu. This will be used in our code to call the Azure Communication Service API for sending emails.

Implementing the Code

C# Sample code in an Azure Function:

public class AzureCommunicationSender
{
    public async Task<EmailSendOperation> SendAsync(CommonMailMessage message)
    {
        var connectionString = EnvHelper.Get<string>("AzureCommunicationConnection");
        var senderAddress = EnvHelper.Get<string>("AzureCommunicationSenderAddress");

        var emailClient = new EmailClient(connectionString);

        var emailMessage = new EmailMessage(
            senderAddress: senderAddress,
            content: new EmailContent(message.Subject),
            recipients: new EmailRecipients(message.Receipts.Select(p => new EmailAddress(p))));

        if (message.BodyIsHtml)
        {
            emailMessage.Content.Html = message.Body;
        }
        else
        {
            emailMessage.Content.PlainText = message.Body;
        }

        var emailSendOperation = await emailClient.SendAsync(WaitUntil.Completed, emailMessage);
        return emailSendOperation;
    }
}

Make sure to add Azure.Communication.Email nuget package first.

The code is pretty straight forward, just one thing to mention. There are two options for sending an email:

namespace Azure
{
    /// <summary>
    /// Indicates whether the invocation of a long running operation should return once it has
    /// started or wait for the server operation to fully complete before returning.
    /// </summary>
    public enum WaitUntil
    {
        /// <summary>
        /// Indicates the method should wait until the server operation fully completes.
        /// </summary>
        Completed,
        /// <summary>
        /// Indicates the method should return once the server operation has started.
        /// </summary>
        Started
    }
}

Azure Communication Service is designed to use a queue, just like how Moonglade.Email is designed. This is a typical cloud native design pattern. If you just want to "fire and forget", set the option to "Started", then your code will finish once the email message is enqueue, no need to wait.

For me, the fundamental design of Moonglade.Email didn't change, as you can refer to previous blog post "Cloud Architecture Design of My Email Notification Infrastructure on Azure.". Azure Communication Service is just another provider besides the original SMTP.

private async Task SendMessageInternal(CommonMailMessage message)
{
    string sender = "smtp";
    var envSender = EnvHelper.Get<string>("Sender");
    if (!string.IsNullOrWhiteSpace(envSender))
    {
        sender = envSender.ToLower();
    }

    switch (sender)
    {
        case "smtp":
            var response = await message.SendAsync();
            logger.LogInformation($"SMTP response: {response}");
            break;

        case "azurecommunication":
            var result = await message.SendAzureCommunicationAsync();
            logger.LogInformation($"AzureCommunication operation ID: {result.Id}");
            break;

        default:
            throw new InvalidOperationException("Sender not supported");
    }
}

So, in my case, there are two queue used to send emails now. A message will first go to the original Azure Storage Queue used in Moonglade.Email. The QueueProcessor then take it out, and decide to use SMTP or Azure Communication Service to process the message. If it is Azure, the email message will then go to another queue internally used by the Azure Communication Service, which is transparent to us.

Conclusion

Azure Communication Service offers a convenient solution for sending email notifications. It's easy to set up and doesn't require complex coding for integration.

Upload Files to Azure Blob Storage without Azure SDK

2024-09-02T01:38:36Z

Problem

Typically, we use the Azure SDK to upload files to Azure Blob Storage, as it is the easiest method supported by Microsoft. However, there are situations where the Azure SDK might not be available. So, how can we still upload files to Azure Blob Storage in such cases? In this post, I will guide you through the steps to upload files to your Azure Storage Account without using the Azure SDK.

Solution

Azure Blob Storage provides REST APIs that allow clients to perform all kinds of operations. This is the underlying mechanism behind the Azure SDK, there's no magic involved. This means that even without the Azure SDK, we can still use REST APIs to upload files. The basic steps are as follows:

Generates an authorization header for HTTP PUT request.
1. Constructs a string that includes HTTP verb, content length, content type, date, and other required headers.
2. Uses HMAC-SHA256 to sign the string with the account key, then encodes it in base64.
3. Please note, things may change when you read this post, please always refer to this Microsoft official document for latest updates.
Constructs the necessary headers including the date, version, content-type, and blob type.
Sends a PUT request to upload the file to Azure Blob Storage.
Checks the response to determine if the upload was successful.

I've setup a storage account, named test996, with a container named goodstuff. Now I need to upload a file on my local disk named myfile.txt to the container.

I also need storage account key to generate authentication header in HTTP requests, which can be found in the "Access keys" blade of your Azure Storage Account instance.

C# Example

class Program
{
    static async Task Main(string[] args)
    {
        string accountName = "test996";
        string accountKey = "*******************";
        string filePath = "myfile.txt";
        string containerName = "goodstuff";
        string blobName = "myfile1.txt";
        string contentType = "text/plain";
        string date = DateTime.UtcNow.ToString("R");

        string urlPath = $"/{containerName}/{blobName}";
        string url = $"https://{accountName}.blob.core.windows.net{urlPath}";

        long contentLength = new FileInfo(filePath).Length;

        string authorizationHeader = GenerateAuthorizationHeader(accountName, accountKey, "PUT", contentLength, contentType, date, urlPath);

        Console.WriteLine($"Authorization: {authorizationHeader}");
        Console.WriteLine($"x-ms-date: {date}");

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("x-ms-date", date);
            client.DefaultRequestHeaders.Add("x-ms-version", "2020-10-02");
            client.DefaultRequestHeaders.Add("Authorization", authorizationHeader);
            client.DefaultRequestHeaders.Add("x-ms-blob-type", "BlockBlob");

            using (FileStream fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read))
            {
                HttpContent content = new StreamContent(fileStream);
                content.Headers.Add("Content-Type", contentType);
                content.Headers.Add("Content-Length", contentLength.ToString());

                HttpResponseMessage response = await client.PutAsync(url, content);

                if (response.StatusCode == System.Net.HttpStatusCode.Created)
                {
                    Console.WriteLine("File uploaded successfully");
                }
                else
                {
                    Console.WriteLine($"File upload blow up sky high: {(int)response.StatusCode}");
                    Console.WriteLine(await response.Content.ReadAsStringAsync());
                }
            }
        }
    }

    static string GenerateAuthorizationHeader(string accountName, string accountKey, string verb, long contentLength, string contentType, string date, string urlPath)
    {
        string stringToSign = $"{verb}\n\n\n{contentLength}\n\n{contentType}\n\n\n\n\n\n\nx-ms-blob-type:BlockBlob\nx-ms-date:{date}\nx-ms-version:2020-10-02\n/{accountName}{urlPath}";
        byte[] key = Convert.FromBase64String(accountKey);
        using (HMACSHA256 hmac = new HMACSHA256(key))
        {
            byte[] signatureBytes = Encoding.UTF8.GetBytes(stringToSign);
            byte[] hash = hmac.ComputeHash(signatureBytes);
            string signedString = Convert.ToBase64String(hash);
            return $"SharedKey {accountName}:{signedString}";
        }
    }
}

Python Example

import hmac
import hashlib
import base64
from datetime import datetime
import os
import requests

def generate_authorization_header(account_name, account_key, verb, content_length, content_type, date, url_path):
    string_to_sign = f"{verb}\n\n\n{content_length}\n\n{content_type}\n\n\n\n\n\n\nx-ms-blob-type:BlockBlob\nx-ms-date:{date}\nx-ms-version:2020-10-02\n/{account_name}{url_path}"
    signed_string = base64.b64encode(hmac.new(base64.b64decode(account_key), string_to_sign.encode('utf-8'), hashlib.sha256).digest()).decode('utf-8')
    authorization_header = f"SharedKey {account_name}:{signed_string}"
    return authorization_header

account_name = 'test996'
account_key = '************'
file_path = 'myfile.txt'
container_name = 'goodstuff'
blob_name = 'myfile.txt'
content_length = str(os.path.getsize(file_path))
content_type = 'text/plain'
date = datetime.utcnow().strftime('%a, %d %b %Y %H:%M:%S GMT')
url_path = f'/{container_name}/{blob_name}'
authorization_header = generate_authorization_header(account_name, account_key, 'PUT', content_length, content_type, date, url_path)

print(f"Authorization: {authorization_header}")
print(f"x-ms-date: {date}")

url = f"https://{account_name}.blob.core.windows.net{url_path}"
headers = {
    'x-ms-date': date,
    'x-ms-version': '2020-10-02',
    'Authorization': authorization_header,
    'Content-Type': content_type,
    'Content-Length': content_length,
    'x-ms-blob-type': 'BlockBlob'
}

with open(file_path, 'rb') as f:
    response = requests.put(url, headers=headers, data=f)

if response.status_code == 201:
    print("File uploaded successfully")
else:
    print(f"File upload blow up sky high: {response.status_code}")
    print(response.text)

Solving NuGet Package Target Naming Conflict

2024-08-15T00:59:33Z

Problem

In my ASP.NET Core project, I referenced the NuGet package tinymce.7.3.0.nupkg, which contains the following build\TinyMCE.targets file:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <SourceScriptFiles Include="$(MSBuildThisFileDirectory)..\content\scripts\tinymce\**\*.*" />
    </ItemGroup>
    <Target Name="CopyScriptsToProject" BeforeTargets="Build">
        <Copy SourceFiles="@(SourceScriptFiles)" DestinationFolder="$(ProjectDir)\wwwroot\lib\tinymce\%(RecursiveDir)" />
    </Target>
</Project>

After installing this package, the TinyMCE files are copied to the wwwroot\lib\tinymce directory during the build.

I created a similar NuGet package Moonglade.MonacoEditor with the following build\Moonglade.MonacoEditor.targets file:

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <SourceFiles Include="$(MSBuildThisFileDirectory)..\content\monaco\**\*.*" />
    </ItemGroup>
    <Target Name="CopyScriptsToProject" BeforeTargets="Build">
        <Copy SourceFiles="@(SourceFiles)" DestinationFolder="$(ProjectDir)\wwwroot\lib\moonglade-monaco\%(RecursiveDir)" />
    </Target>
</Project>

This package also successfully copies files to wwwroot\lib\moonglade-monaco during the build.

However, when both packages are referenced in the same ASP.NET Core project, only the files from Moonglade.MonacoEditor are copied, and no files from the TinyMCE package are copied to wwwroot\lib.

Solution

After work 996. I found that in MSBuild, target names must be unique. If two `.targets` files define targets with the same name (e.g., CopyScriptsToProject), the latter will overwrite the former, resulting in only the files from the last loaded package being copied.

To resolve this issue, I need to rename the target, ensure each `.targets` file has a unique target name. Since I do not own TinyMCE, I have to rename target in my own Moonglade.MonacoEditor package.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
    <ItemGroup>
        <SourceFiles Include="$(MSBuildThisFileDirectory)..\content\monaco\**\*.*" />
    </ItemGroup>
    <Target Name="CopyMonacoScriptsToProject" BeforeTargets="Build">
        <Copy SourceFiles="@(SourceFiles)" DestinationFolder="$(ProjectDir)\wwwroot\lib\moonglade-monaco\%(RecursiveDir)"
        />
    </Target>
</Project>

Now, both packages can correctly copy their own files!

How to Add JsonStringEnumConverter in Azure Function Isolated Worker

2024-04-08T01:02:26Z

Problem

Azure Function Isolated worker for .NET replaced its default Json Serializer from Newtonsoft.Json with System.Text.Json. This change caused certain behavior differences. In my case, I am not able to deserialize an Enum type from a string value.

My request object is EventLogQueryRequest

public class EventLogQueryRequest
{
    public int Take { get; set; } = 100;

    public MpsEventId[] EventIds { get; set; }

    public Guid? UserId { get; set; }
}

MpsEventId is a C# enum type.

public enum MpsEventId
{
    General = 0,

    Login = 1001,
    Logout = 1002
    // ...
}

When client send request that uses string value for the Enum, an exception will be thrown.

{
    "take": 10,
    "eventIds": [
        "Login",
        "CreateEditCard",
        "SubmitReviewCard"
    ],
    "userId": null
}

Exception: System.InvalidOperationException: The JSON value could not be converted to MPSFunc.EventLog.MpsEventId. Path: $.eventIds[0] | LineNumber: 3 | BytePositionInLine: 15.

Solution

At first, among my search from the Internet, I can Configure JsonSerializerOptions in Program.cs in this way. But unfortunately, this won't work.

services.Configure<JsonSerializerOptions>(options =>
{
    options.PropertyNameCaseInsensitive = true;
    options.Converters.Add(new JsonStringEnumConverter())
});

The correct way is to use AddJsonOptions() method just like a normal ASP.NET Core application.

services.AddControllers()
        .AddJsonOptions(options => options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter()));

The complete Program.cs now looks like this:

using System.Text.Json.Serialization;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services =>
    {
        services.AddControllers()
                .AddJsonOptions(options => options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter()));

        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

Now, the request can be successfully serialized, the code works like a charm!

Json Serialization Caveat in Azure Function

2024-02-07T08:35:05Z

Background

Creating Azure Functions using C# and .NET can feel quite familiar to those versed in creating ASP.NET Core Web APIs. Despite the similarities, one key difference lies in the process of JSON serialization, which can present unexpected challenges. In this post, I'll explore the two most common issues developers encounter with JSON in Azure Functions and provide practical solutions to overcome them.

Please be noted: This blog post only talks about Azure Function V4 with .NET 6.0 in process worker. Things may change in the future version of Azure Function.

Customize Json Property Name

Problem

Define a class, with JsonPropertyName attribute, like this:

class Product
{
    [JsonPropertyName("displayName")]
    public string Name { get; set; }
    public decimal Price { get; set; }
}

What I want is to output the Name property in Json as "displayName"

Now, guess what's the result of this function?

[FunctionName("Function1")]
public static IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)] HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var products = new List<Product>
    {
        new() { Name = "Apple", Price = 1.99m },
        new() { Name = "Banana", Price = 2.99m },
        new() { Name = "Cherry", Price = 3.99m }
    };

    return new OkObjectResult(products);
}

The JsonPropertyName does not work.

[
    {
        "name": "Apple",
        "price": 1.99
    },
    {
        "name": "Banana",
        "price": 2.99
    },
    {
        "name": "Cherry",
        "price": 3.99
    }
]

Root cause

The underlying issue stems from Azure Functions' reliance on a different serialization engine than one might expect. Instead of utilizing System.Text.Json, which is common in modern .NET applications, Azure Functions default to the venerable Newtonsoft.Json package. This package isn't explicitly listed in your project file; rather, it's included as a dependency of the Microsoft.NET.Sdk.Functions package.

Although the coding experience in C# for Azure Functions closely mirrors that of ASP.NET Core, and both may run on .NET 6.0, assumptions about consistency in JSON serialization can lead to confusion. Contrary to ASP.NET Core 6.0, which defaults to System.Text.Json for serialization, Azure Functions diverge in this aspect. Despite using the same OkObjectResult class from ASP.NET Core's framework, the serialization process under the hood is handled differently due to the reliance on Newtonsoft.Json

#region Assembly Microsoft.AspNetCore.Mvc.Core, Version=2.2.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60
// location unknown
// Decompiled with ICSharpCode.Decompiler 8.1.1.7464
#endregion

using Microsoft.AspNetCore.Mvc.Infrastructure;

namespace Microsoft.AspNetCore.Mvc;

//
// Summary:
//     An Microsoft.AspNetCore.Mvc.ObjectResult that when executed performs content
//     negotiation, formats the entity body, and will produce a Microsoft.AspNetCore.Http.StatusCodes.Status200OK
//     response if negotiation and formatting succeed.
[DefaultStatusCode(200)]
public class OkObjectResult : ObjectResult
{
    private const int DefaultStatusCode = 200;

    //
    // Summary:
    //     Initializes a new instance of the Microsoft.AspNetCore.Mvc.OkObjectResult class.
    //
    //
    // Parameters:
    //   value:
    //     The content to format into the entity body.
    public OkObjectResult(object value)
        : base(value)
    {
        base.StatusCode = 200;
    }
}

Fix

Use JsonProperty from Newtonsoft.Json

class Product
{
    [JsonProperty("displayName")]
    public string Name { get; set; }
    public decimal Price { get; set; }
}

Now, the response is what I desired.

[
    {
        "displayName": "Apple",
        "price": 1.99
    },
    {
        "displayName": "Banana",
        "price": 2.99
    },
    {
        "displayName": "Cherry",
        "price": 3.99
    }
]

Model Binding

Problem

This is a real bug in my blog's email sending function. This code intends to serialize req.Payload to a string to be inserted in to Azure Storage Queue.

[FunctionName("Enqueue")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] EnqueueRequest req,
    ILogger log)
{
    log.LogInformation($"C# HTTP trigger function `Enqueue` processed a request. OriginAspNetRequestId={req.OriginAspNetRequestId}");

    var conn = Environment.GetEnvironmentVariable("moongladestorage");
    var queue = new QueueClient(conn, "moongladeemailqueue");

    var en = new EmailNotification
    {
        DistributionList = string.Join(';', req.Receipts),
        MessageType = req.Type,
        MessageBody = System.Text.Json.JsonSerializer.Serialize(req.Payload, MoongladeJsonSerializerOptions.Default),
    };

    await InsertMessageAsync(queue, en, log);

    return new AcceptedResult();
}

The EnqueueRequest class has a Payload property with object type.

public class EnqueueRequest
{
    public string Type { get; set; }
    public string[] Receipts { get; set; }
    public object Payload { get; set; }
    public string OriginAspNetRequestId { get; set; } = Guid.Empty.ToString();
}

But in runtime, the MessageBody never get the correct Json string.

The values in the original req object are removed after serialization.

It intends to be:

{
  "name": "Fubao",
  "price": 996.35
}

But it just become this:

"{\r\n  \"name\": [],\r\n  \"price\": []\r\n}"

Root cause

Again, this is because the model binding in Azure Function is also using Newtonsoft.Json instead of System.Text.Json like many will assume it to be. In this case, I use object type for Payload property. This will become Newtonsoft.Json.Linq.Object, which System.Text.Json.JsonSerializer has no idea how to serialize it correctly.

Fix

Change the code to use JsonConvert from Newtonsoft.Json

MessageBody = JsonConvert.SerializeObject(req.Payload)

Now it works fine

Conclusion

While C# Azure Functions and ASP.NET Core share many similarities in their development models, there's a significant difference in how they handle JSON serialization and deserialization. Azure Functions, by default, use Newtonsoft.Json for both serializing response objects and deserializing incoming request data during model binding. This is a critical point of consideration for developers who might be accustomed to System.Text.Json, which is the default in ASP.NET Core. Special attention is needed when working with Azure Functions to ensure that any custom serialization settings or attributes are compatible with Newtonsoft.Json, and developers should be cautious when attempting to use System.Text.Json in scenarios where Azure Functions implicitly expect Newtonsoft.Json.

How to Detect If Your Application is Running in Azure App Service

2023-12-14T08:34:41Z

Problem

An application needs to know if itself is running in Azure App Service, so that it can apply special logic and optimization for Azure.

Solution

When deploying an application to Azure App Service, the platform automatically assigns a set of environment variables that can be accessed by the application code.

To view the complete list of environment variables applicable to your application at runtime, you can navigate to the "Advanced Tools" blade within your App Service Instance.

Then, go to "Environment" page. You will see the entire list here. Among them, are a few environment variables that are suitable for identify if the application is running on Azure App Service.

WEBSITE_SKU
WEBSITE_SITE_NAME
WEBSITE_HOSTNAME

Now, in our code, we can try to get the values of those environment variables, example code for ASP.NET Core Razor Page is like:

<tr>
    <td>@SharedLocalizer["Azure App Service"]</td>
    <td class="text-muted">
        WEBSITE_SKU : @Environment.GetEnvironmentVariable("WEBSITE_SKU") <br />
        WEBSITE_SITE_NAME: @Environment.GetEnvironmentVariable("WEBSITE_SITE_NAME") <br />
        WEBSITE_HOSTNAME : @Environment.GetEnvironmentVariable("WEBSITE_HOSTNAME") <br />
        REGION_NAME  : @Environment.GetEnvironmentVariable("REGION_NAME") <br />
    </td>
</tr>

Example result:

Call API with Windows Authentication from Blazor Web Assembly

2023-10-20T07:17:07Z

Problem

I was rewriting an old Angular application to Blazor Web Assembly a couple of days ago. The App is an internal tool, which uses a backend API that has Windows Authentication. In Angular, we used to add withCredentials: true to HTTP interceptor to make it work. The most equivalent method in .NET is typically adding UseDefaultCredentials = true in HttpClient. However, Blazor WASM will gives you an exception for this as indicated in this StackOverflow thread: WASM: System.PlatformNotSupportedException: System.Net.Http.HttpClientHandler is not supported on the current platform.

The majority of internet search result so far tell you it's not possible to call Windows Authentication API from Blazor. Really? Let's see how to make it work with a few lines of code.

Solution

Approach A

The original StackOverflow thread has 2 answers currently. The answer by ca8msm works, but the cost is not to use HttpClient, that we need to do everything manually in order to add BrowserRequestCredentials.Include to the request header. This approach sacrifices what we love about the HttpClient, but gives you ultimate control over the http request details.

string APIURL = "https://localhost:44390/api/models";

// create request object and pass windows authentication credentials
var request = new HttpRequestMessage(HttpMethod.Get, APIURL);
request.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);

// send the request and convert the results to a list
var httpResponse = await Http.SendAsync(request);
models = await httpResponse.Content.ReadFromJsonAsync<myModel[]>();

Approach B

I come up with a better approach, which can keep the HttpClient we already like.

First, add a custom DelegatingHandler, this is used for adding BrowserRequestCredentials.Include to each request.

using Microsoft.AspNetCore.Components.WebAssembly.Http;

public class CredentialsMessageHandler : DelegatingHandler
{
    protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        request.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);
        return base.SendAsync(request, cancellationToken);
    }
}

Second, create your typed client as usual. I prefer typed client, you may also use HttpClientFactory, it doesn't matter. You can find more information about how to make http request in best practice in this document.

public class CardClient
{
    private readonly HttpClient http;

    public CardClient(HttpClient http)
    {
        // ...
        this.http = http;
    }

    // ...
}

Finally, register the client in DI, with the CredentialsMessageHandler we wrote in the first step.

builder.Services.AddHttpClient<CardClient>(client => client.BaseAddress = new Uri(ApiEndpoint.FullUrl)).AddHttpMessageHandler<CredentialsMessageHandler>();

Now, you can still use the HttpClient the way you always been using it with Windows Authentication enabled API!

BTW, Why I am not answering this in StackOverflow? Because I lost access to my account years ago :(

How Azure App Service for Linux Runs Your .NET Application

2023-09-01T00:53:09Z

Abstract

Azure App Service expanded its support to include Linux and containers in 2017. This update brought similar functionalities to the classic App Service on Windows Server. Both versions allow you to run various types of applications, such as .NET, Java, NodeJS, PHP, and Ruby, with features like continuous integration and deployment (CI/CD) and automatic scaling. To illustrate the workings of Azure App Service, this post will focus on an ASP.NET Core application as an example.

A Simple Test

I created a new web app using Code deployment on Linux. Notice, I am NOT choosing Docker Container here.

Code vs Docker Container

The difference between Code and Docker Container is that Code deployment doesn't require you to have a Dockerfile and build your docker image before publishing, while Docker Container requires your image to be ready before publishing to Azure App Service, which means you need to write a Dockerfile for your website and also build the image, push it to Docker Hub or other container registries.

A typical ASP.NET Core application that uses Docker will have a Dockerfile look like this:

FROM mcr.microsoft.com/dotnet/aspnet:7.0 AS base
LABEL maintainer="edi.wang@outlook.com"
LABEL repo="https://github.com/EdiWang/Elf"

WORKDIR /app
EXPOSE 80
EXPOSE 443

ENV ASPNETCORE_FORWARDEDHEADERS_ENABLED=true

FROM mcr.microsoft.com/dotnet/sdk:7.0 AS build
WORKDIR /src
COPY ["Elf.Api/Elf.Api.csproj", "Elf.Api/"]
RUN dotnet restore "Elf.Api/Elf.Api.csproj"
COPY . .
WORKDIR "/src/Elf.Api"
RUN dotnet build "Elf.Api.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "Elf.Api.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "Elf.Api.dll"]

And, because you need to build your own image when using Docker Container option, this means the Runtime stack is also included in your image, so Azure won't let you choose the program runtime here. When use Code deployment, you only need to build the code, in my case, I am using ASP.NET Core 6.0, Azure manages the runtime for me, so Azure will need to setup the ASP.NET Core 6.0 runtime ready to run my code.

Detecting container

This application I wrote is just to detect if the current process is running in Docker as mentioned in this Microsoft document.

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var isInDocker = Environment.GetEnvironmentVariable("DOTNET_RUNNING_IN_CONTAINER") ?? false.ToString();

app.MapGet("/", () => $"DOTNET_RUNNING_IN_CONTAINER: {isInDocker}");

app.Run();

And it doesn't have a Dockerfile

When running on my local machine without docker, it shows False

Now, I publish this code to the Azure App Service Linux instance I created before from Visual Studio.

As the output indicates, this ASP.NET Core application is running in Docker.

As we can see, even if I did not choose "Docker Container" when creating Azure App Service, my code still runs in Docker. I don't have to build a Docker image for my application, I don't need to learn Docker, I don't even need to be aware of the Docker underlying, Azure manages the runtime for me.

Explore the underlying Docker infrastructure

To future explore how it works. I use the Kudu tool that integrated in every Azure App Service resource.

Logs

From the landing page, I can download "Current Docker logs".

In the "Environment" menu, I can also find a few information about the Docker version Microsoft is using, and even Azure App Service's SSH password.

Docker log file shows how Azure App Service is using Docker to run my application.

2023-08-23T01:47:56.969Z INFO  - Logging is not enabled for this container.
Please use https://aka.ms/linux-diagnostics to enable logging to see container logs here.
2023-08-23T01:48:04.719Z INFO  - Initiating warmup request to container linux996_3_f13b8c09 for site linux996
2023-08-23T01:48:24.563Z INFO  - Container linux996_3_f13b8c09 for site linux996 initialized successfully and is ready to serve requests.
2023-08-23T01:48:25.195Z INFO  - Starting container for site
2023-08-23T01:48:25.213Z INFO  - docker run -d --expose=8080 --name linux996_4_ed97a4fb -e WEBSITE_SITE_NAME=linux996 -e WEBSITE_AUTH_ENABLED=False -e WEBSITE_ROLE_INSTANCE_ID=0 -e WEBSITE_HOSTNAME=linux996.azurewebsites.net -e WEBSITE_INSTANCE_ID=90f7789cd4cc1d5a4fe2a8c0e9db0d4e3d0c73856fa77c2d8c30202608ce99f6 -e ASPNETCORE_HOSTINGSTARTUPASSEMBLIES=Microsoft.ApplicationInsights.StartupBootstrapper -e DOTNET_STARTUP_HOOKS=/agents/core/StartupHook/Microsoft.ApplicationInsights.StartupHook.dll -e WEBSITE_USE_DIAGNOSTIC_SERVER=True appsvc/dotnetcore:6.0_20230726.2.tuxprod dotnet DockerDetect.dll 

2023-08-23T01:48:25.214Z INFO  - Logging is not enabled for this container.
Please use https://aka.ms/linux-diagnostics to enable logging to see container logs here.
2023-08-23T01:48:33.368Z INFO  - Initiating warmup request to container linux996_4_ed97a4fb for site linux996
2023-08-23T01:48:45.009Z INFO  - Container linux996_4_ed97a4fb for site linux996 initialized successfully and is ready to serve requests.

The Docker image

From the log, I can see it is using a Docker image named appsvc/dotnetcore

This used to be published in Docker Hub (https://hub.docker.com/r/appsvc/dotnetcore/tags), but it hasn't been updated for 2 years. So is its code on GitHub (https://github.com/Azure-App-Service/dotnetcore). The tag from the log is 6.0_20230726.2.tuxprod, it isn't on the outdated Docker Hub image. After some digging, it is moved to Microsoft Artifact Registry (mcr.microsoft.com), which can be pulled from anywhere:

docker pull mcr.microsoft.com/appsvc/dotnetcore:6.0_20230726.2.tuxprod

How does it run my code

This appsvc/dotnetcore image is only the ASP.NET Core 6.0 runtime, it doesn't include the application files used by Azure customers. My code isn't in the image, how does it run my application?

From the log above, I can see a parameter that starts my application

dotnet DockerDetect.dll

This is the exact same command used by .NET runtime to run any ASP.NET Core application.

Now, go deeper into the image itself to find it's Entrypoint:

docker inspect mcr.microsoft.com/appsvc/dotnetcore:6.0_20230726.2.tuxprod

Gives

"WorkingDir": "/home/site/wwwroot",
"Entrypoint": [
    "/bin/init_container.sh"
],

It also shows how "DOTNET_RUNNING_IN_CONTAINER" environment variable is set to true, which is what I used to determine a Docker environment in the previous section.

"Env": [
    "PATH=/opt/dotnetcore-tools:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/site/wwwroot",
    "ASPNETCORE_URLS=",
    "DOTNET_RUNNING_IN_CONTAINER=true",
    "USER_DOTNET_AI_VERSION=2.8.42",
    "ORYX_AI_CONNECTION_STRING=InstrumentationKey=4aadba6b-30c8-42db-9b93-024d5c62b887",
    "DOTNET_VERSION=6.0",
    "ASPNETCORE_LOGGING__CONSOLE__DISABLECOLORS=true",
    "PATH_CA_CERTIFICATE=/etc/ssl/certs/ca-certificate.crt",
    "LANG=C.UTF-8",
    "LANGUAGE=C.UTF-8",
    "LC_ALL=C.UTF-8",
    "CNB_STACK_ID=oryx.stacks.skeleton",
    "PORT=8080",
    "SSH_PORT=2222",
    "WEBSITE_ROLE_INSTANCE_ID=localRoleInstance",
    "WEBSITE_INSTANCE_ID=localInstance",
    "ASPNETCORE_FORWARDEDHEADERS_ENABLED=true",
    "HOME=/home"
]

Run the image on my local machine to see the content of init_container.sh

docker run -it --rm --entrypoint "bash" mcr.microsoft.com/appsvc/dotnetcore:6.0_20230726.2.tuxprod

cat /bin/init_container.sh

From this file, we can see the startup command location

startupCommandPath="/opt/startup/startup.sh"

But this file is created on the fly, so we can't cat this currently. It is generated by generate_and_execute_startup_script.sh

# Dockerfile copies generate_and_execute_startup_script.sh from /templates/startup_scripts directory based on assetDirs in tuxib.yml
source /bin/generate_and_execute_startup_script.sh

This file is simple. We can see it is calling Oryx to generate startup command.

Oryx is a build system which automatically compiles source code repos into runnable artifacts. It is used to build web apps for Azure App Service and other platforms.

#!/bin/bash

oryxArgs="create-script -appPath $appPath -output $startupCommandPath -defaultAppFilePath $defaultAppPath \
    -bindPort $PORT -bindPort2 '$HTTP20_ONLY_PORT' -userStartupCommand '$userStartupCommand' $runFromPathArg"

echo "Running oryx $oryxArgs"
eval oryx $oryxArgs
exec $startupCommandPath

I don't want to work 996 to test the script generation on my local environment. Instead, the generated script can be found from the web SSH in Kudu.

As you can see, the script is finally calling dotnet DockerDetect.dll, which is from the docker run parameter that Azure provided.

What else is in the image

Labels that show its build information.

"Labels": {
    "com.microsoft.oryx.build-number": "20230721.1",
    "com.microsoft.oryx.git-commit": "e01b34550f75a38df92af2041687cb2b0ad41ec0",
    "com.microsoft.oryx.release-tag-name": "20230721.1",
    "io.buildpacks.stack.id": "oryx.stacks.skeleton",
    "maintainer": "Azure App Services Container Images <appsvc-images@microsoft.com>"
}

A bunch of .NET tools are also available inside the image. App Service can use these tools to monitor and trouble shoot the application.

root@55a2f2c9e303:/opt# ls
dotnetcore-tools  startup  startupcmdgen
root@55a2f2c9e303:/opt# cd dotnetcore-tools/
root@55a2f2c9e303:/opt/dotnetcore-tools# ls -la
total 856
drwxr-xr-x 3 root root   4096 Jul 21 01:34 .
drwxr-xr-x 1 root root   4096 Jul 26 11:53 ..
drwxr-xr-x 9 root root   4096 Jul 21 01:34 .store
-rwxr-xr-x 1 root root 142840 Jul 21 01:34 dotnet-counters
-rwxr-xr-x 1 root root 142840 Jul 21 01:33 dotnet-dump
-rwxr-xr-x 1 root root 142840 Jul 21 01:34 dotnet-gcdump
-rwxr--r-- 1 root root 142840 Jul  6 20:17 dotnet-monitor
-rwxr-xr-x 1 root root 142840 Jul 21 01:33 dotnet-sos
-rwxr-xr-x 1 root root 142840 Jul 21 01:33 dotnet-trace

.NET runtime is located in /usr/share/dotnet

root@55a2f2c9e303:/usr/share/dotnet# ls -la
total 244
drwxrwxr-x 4 root root   4096 Jun 20 19:39 .
drwxr-xr-x 1 root root   4096 Jul 26 11:53 ..
-rw-rw-r-- 1 root root   1116 Jun 20 19:31 LICENSE.txt
-rw-rw-r-- 1 root root  78479 Jun 20 19:31 ThirdPartyNotices.txt
-rwxr-xr-x 1 root root 141760 Jun 20 19:33 dotnet
drwxrwxr-x 3 root root   4096 Jun 20 19:39 host
drwxrwxr-x 4 root root   4096 Jul 21 01:34 shared

Default application that shows a welcome page of a new created App Service instance is located in /defaulthome/hostingstart

root@55a2f2c9e303:/defaulthome/hostingstart# ls -la
total 296
drwxr-xr-x 1 root root   4096 Jul 26 11:53 .
drwxr-xr-x 1 root root   4096 Jul 26 11:53 ..
-rwxr-xr-x 1 root root 142760 May 10  2021 hostingstart
-rw-r--r-- 1 root root 103261 May 10  2021 hostingstart.deps.json
-rw-r--r-- 1 root root   5632 May 10  2021 hostingstart.dll
-rw-r--r-- 1 root root  18756 May 10  2021 hostingstart.pdb
-rw-r--r-- 1 root root    311 May 10  2021 hostingstart.runtimeconfig.json
-rw-r--r-- 1 root root    488 May 10  2021 web.config
drwxr-xr-x 2 root root   4096 Jul 26 11:53 wwwroot
root@55a2f2c9e303:/defaulthome/hostingstart# cd wwwroot/
root@55a2f2c9e303:/defaulthome/hostingstart/wwwroot# ls
hostingstart.html

A part of the HTML code

<div class="pl-5 ml-5 col-xl-5 col-lg-5 col-md-10 col-sm-11 col-xs-11">
    <div class="container-fluid">
        <div class="row">
            <h2 id="upRunning">Your web app is running and waiting for your content</h2>
        </div>
        <div class="row mt-4 pt-4">
            <div id="appIsLive" style="font-size:16px;width: 516px;">Your web app is live, but we don’t have
                your content yet. If you’ve already deployed, it could take up to 5 minutes for your content
                to show up, so come back soon.</div>
        </div>
        <div class="row mt-4">
            <h5 id="supporting" class="mt-5"><img height="50" width="50"
                    src="https://appservice.azureedge.net/images/linux-landing-page/v4/built-dotnet.svg" /> Built with .NET</h5>
        </div>
    </div>
</div>

Application files

The final puzzle is how it find my DockerDetect.dll, it took some tricks to find my application file. Just ls in the default SSH landing directory won't show anything.

Summary

In this post, I created an ASP.NET Core 6.0 web application and deployed it to Azure App Service for Linux. Azure is using a Docker image to run my code. The image contains ASP.NET Core runtime and uses Oryx to generate a startup script that finally calls dotnet to run my application files.

Cloud Architecture Design of My Email Notification Infrastructure on Azure

2023-02-21T01:47:36Z

Background

My blog system "Moonglade" needs to send email notifications to blog owner when there are events like new comments, new pingbacks, and send email to readers when their comments are replied.

There are two options for sending emails in web application. Build my own infrastructure or use a third-party service like SendGrid. I've explored both options and finally decided to build my own infrastructure. During the last few years, this infrastructure has been redesigned many times. In this post, I will share the journey of how this email infrastructure evolved and the things I learnt.

Version 1: Inside Moonglade Application

The initial design is to send email directly from Moonglade itself, which is a ASP.NET Core web application. I've built a .NET library that can configure email in XML template and send messages by SMTP.

It's adding an xml configuration file under application folder like this:

<?xml version="1.0"?>
<MailConfiguration>
  <CommonConfiguration OverrideToAddress="false" ToAddress="overridetest@test.com" />
  <MailMessage MessageType="TestMail" IsHtml="true">
    <MessageSubject>Test Mail on {MachineName.Value}</MessageSubject>
    <MessageBody>
      <![CDATA[
Mail configuration on {MachineName.Value} is good: <br />
Smtp Server: {SmtpServer.Value}<br />
Smtp Port: {SmtpServerPort.Value}<br />
Smtp Username: {SmtpUserName.Value}<br />
Email Display Name: {EmailDisplayName.Value}<br />
Enable SSL: {EnableSsl.Value}<br />
      ]]>
    </MessageBody>
  </MailMessage>
</MailConfiguration>

Then send email in code

var smtpServer = "smtp-mail.outlook.com";
var userName = "Edi.Test@outlook.com";
var password = "***********";
var port = 587;
var toAddress = "Edi.Wang@outlook.com";

var configSource = $"{Directory.GetCurrentDirectory()}\\mailConfiguration.xml";
var emailHelper = new EmailHelper(configSource, smtpServer, userName, password, port)
     .WithTls()
     .WithSenderName("Test Sender")
     .WithDisplayName("Edi.TemplateEmail.TestConsole");

Pros

Only need to deploy one application, which saves cost on Azure.
Straight forward coding experience

Cons

Bad cloud architecture. I cannot scale the email infrastructure alone when there is large amount of traffic. The web server is doing one more job, sending email is not a "Web" thing.
Upgrading or fixing bugs in email component requires redeploying the entire web application.
Hard to deal with failures. Without a database or queue, I cannot track failed email messages and resend them.
Potential security and network restriction. In certain scenarios, web servers won't be allowed to access SMTP services, which makes email fail to send.
Coding language must be the same withing one application. If some day, there is a much better email library written in another language, it's hard to migrate because other pieces of the application is written in C#.

Version 2: A standalone ASP.NET Web API

The next version separates web workload and email sending workload by building a standalone API, just doing one thing: Send emails. It's a typical architecture design.

Pros

Email API can be scaled, upgraded, and deployed separately without affecting the web application.
I can choose different versions of .NET and C# or even another language to build the email API.

Cons

I have to pay for an extra server instance even when most of the time there is no email sending API calls.
Extra deployment and management for another server instance.
Still hard to deal with failures. During email API deployment or down time, any API call from web application will fail, and users won't be able to receive emails.

Version 3: Single Azure Function

The most significant problem for using a full ASP.NET Web API is the cost, including operation and maintenance costs and development costs.

First, the App Service Plan that hosts the Web API is a huge overhead. For an ASP.NET Core application, there is currently no way to choose Consumption Plan, so the API will be billed even when it is idle. According to business, the API is only called about ten times a day, and the total processing time is less than 2 minutes. But I have to pay for the rest 1438 minutes every day.

Secondly, even a simple and ordinary Email notification function still needs a complete basic framework to host it. Although ASP.NET Core provides a very flexible and powerful framework, Azure Function can completely free up these basic tasks. Azure Function only cares about business code, not infrastructure. In general, developers only need to write the business logic of the function, and do not need to write code such as how to start, route, and assign API Keys.

This is fully explained in my previous blog post 'Migrating an ASP.NET Core Web API Project to Azure Function'.

The function code looks like this

public class EmailSendingFunction
{
    [FunctionName("EmailSending")]
    public async Task<IActionResult> Run(
        [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] NotificationRequest request,
        ILogger log, ExecutionContext executionContext)
    {
        T GetModelFromPayload<T>() where T : class
        {
            var json = request.Payload.ToString();
            return JsonSerializer.Deserialize<T>(json);
        }

        log.LogInformation("EmailSending HTTP trigger function processed a request.");

        try
        {

            var configRootDirectory = executionContext.FunctionAppDirectory;
            AppDomain.CurrentDomain.SetData(Constants.AppBaseDirectory, configRootDirectory);
            log.LogInformation($"Function App Directory: {configRootDirectory}");

            IMoongladeNotification notification = new EmailHandler(log)
            {
                AdminEmail = request.AdminEmail,
                EmailDisplayName = request.EmailDisplayName
            };

            switch (request.MessageType)
            {
                case MailMesageTypes.TestMail:
                    await notification.SendTestNotificationAsync();
                    return new OkObjectResult("TestMail Sent");

                //  skip a few code...

                default:
                    throw new ArgumentOutOfRangeException();
            }
        }
        catch (Exception e)
        {
            log.LogError(e, e.Message);
            return new ConflictObjectResult(e.Message);
        }
    }
}

Pros

Save cost by a serverless consumption plan
Free from writing ASP.NET Core infrastructure code, only focus on business code
Easy to migrate to another programming language like Java, Python, NodeJS, or even PowerShell

Cons

Still hard to deal with failures. During email function deployment or down time, any API call from web application will fail, and users won't be able to receive emails.

Version 4: Azure Function and SQL Database

To deal with failures, I added a SQL database for storing email messages and their status. The web application no longer makes direct API calls to the Azure Function. Instead, it only writes messages to a database table and forgets about it. It's the Azure Function's responsibility to pick new messages from database and send them. If email sending failed, it will record and retry a few times until mark the message as failed completely and then move to next message. Yes, it is using database as a queue.

In this version, the function code looks like this

[FunctionName("NotificationV2")]
public async Task Run([TimerTrigger("*/2 * * * *")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"NotificationV2 Timer trigger function executed at UTC: {DateTime.UtcNow}");
    // logic ...
}

Pros

Dealing with failures. As long as the web application is alive and can write messages into database, any deployment or downtime of Azure Function won't lose any email. When the function is restored up running again, it will continue where it's left.

Cons

Using database as a queue requires writing every queue feature manually. Like peek message and retry logic.
Azure Function needs to have a timer trigger to query database for new messages. It is an extra consumption because most of the time the query will return no new messages.

Version 4: Azure Function and Storage Queue

Using database as a queue makes me work 996. Azure has provided real message queue services, Azure Storage Queue and Azure Service Bus. For sending emails, I prefer using Storage Queue.

"Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account. Queue storage is often used to create a backlog of work to process asynchronously."

If you need more details when choosing architecture design, you can see this document for detailed comparison between these two.

Now I am free from writing basic queue features like enqueue, dequeue, peek, retry, etc.

When an Azure Function instance picks up a message, it will be invisible to other instances for a period, this is called visibility timeout mechanism. So that when you have multiple instances at scale, the same message won't be processed multiple times.

By default, Azure will try 5 times for failed message and put them into a poison queue automatically. So that a failed message won't block current instance or other instances from picking up following up messages.

Web application code using Azure.Storage.Queues package.

public async Task EnqueueNotification<T>(MailMesageTypes type, string[] toAddresses, T payload) where T : class
{
    try
    {
        var queue = new QueueClient(_notificationSettings.AzureStorageQueueConnection, "moongladeemailqueue");

        var en = new EmailNotification
        {
            DistributionList = string.Join(';', toAddresses),
            MessageType = type.ToString(),
            MessageBody = JsonSerializer.Serialize(payload, MoongladeJsonSerializerOptions.Default),
        };

        await InsertMessageAsync(queue, en);
    }
    catch (Exception e)
    {
        _logger.LogError(e, e.Message);
        throw;
    }
}

private async Task InsertMessageAsync(QueueClient queue, EmailNotification emailNotification)
{
    if (null != await queue.CreateIfNotExistsAsync())
    {
        _logger.LogInformation($"Azure Storage Queue '{queue.Name}' was created.");
    }

    var json = JsonSerializer.Serialize(emailNotification);
    var bytes = Encoding.UTF8.GetBytes(json);
    var base64Json = Convert.ToBase64String(bytes);

    await queue.SendMessageAsync(base64Json);
}

Function code.

[FunctionName("NotificationStorageQueue")]
public async Task Run(
    [QueueTrigger("moongladeemailqueue", Connection = "moongladestorage")] QueueMessage queueMessage,
    ILogger log,
    Microsoft.Azure.WebJobs.ExecutionContext executionContext)
{
    log.LogInformation($"C# Queue trigger function processed: {queueMessage.MessageId}");
    // logic...
}

Pros

Free from writing queue logic
Change timed trigger to queue trigger, saving a lot of database and compute consumption

Cons

Learning curve for how to use Azure Storage Queue

Conclusion and more

When designing systems for cloud. Keep in mind cloud native patterns. Message queue is a common way to decoupling system parts that are scaled independently. Email sending is one of those scenarios that can use a message queue. By decoupling email component from main application, it can be scaled to handle large amount of traffic, use a different programming language, resilient to failure, and save cost in certain ways.

Get Client IP When Your ASP.NET Core App is behind Reversed Proxy on Azure App Service

2022-12-09T07:54:03Z

Problem

I have a web app with a web front end and API backend both deployed to Azure App Service. I reversed proxy the API using this method I described before, so that my web front end can access API without having CORS issue, and the end users won't need to access my API address directly. However, for the API code, the client IP address I got is always Azure app service's outbound IP instead of real client IP. Let's see how to fix this problem.

Solution

Just like with any reverse proxy, ASP.NET Core already has built in support for respecting "X-Forwarded-For" HTTP header.

Typically, we will add this in DI

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});

And use in Middleware

app.UseForwardedHeaders();

However, this is not enough on Azure. We also need to manually add all the possible proxy IP addresses to the ForwardedHeadersOptions.

Get your App Service's outbound IP addresses

In my case, I call API from Web server. So, I go to the "Networking" blade in the web app's instance and copy all Outbound addresses to clipboard.

Set known proxies

I don't like hard code IP addresses in code. So I go to appsettings.json file and add a new section named "AzureKnownProxies" with the IP I copied before.

 "AzureKnownProxies": [
   "52.163.244.128",
   "13.75.34.175",
   "168.63.220.81",
   "207.46.136.220",
   "168.63.210.90",
   "23.101.15.21",
   "23.101.7.253",
   "207.46.136.152",
   "65.52.180.140",
   "23.101.13.231",
   "23.101.3.51"
 ],

Then, modify DI code for adding forwarded headers to this

var knownProxies = builder.Configuration.GetSection("AzureKnownProxies").Get<string[]>();
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    options.ForwardLimit = null;
    options.KnownProxies.Clear();
    if (knownProxies != null)
    {
        foreach (var ip in knownProxies)
        {
            options.KnownProxies.Add(IPAddress.Parse(ip));
        }
    }
});

Now, we can successfully get real client IP address!

Move CRON Expression from Hard Code to Configuration in Azure Function App

2022-09-13T07:24:59Z

Problem

When creating Azure Function with Timer trigger, we usually write CRON expression like [TimerTrigger("*/2 * * * *")] in our function code. It works most of the cases, but when you need to dynamically adjust your timer based on business needs, you will have to update your code and redeploy the function, which may not be so easy in an enterprise application.

Let's see how we can remove the hard code CRON expression and put it into configuration so that we can easily update on the Azure Portal without redeploying the code.

Solution

In my case, I created a function that will execute every 2 minutes to send email notifications. The CRON expression is hard coded as */2 * * * *

[FunctionName("NotificationV2")]
public async Task Run([TimerTrigger("*/2 * * * *")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"NotificationV2 Timer trigger function executed at UTC: {DateTime.UtcNow}");
    // logic ...
}

To make it read values from configuration, we need to first create a local.settings.json file if you don't have one. This is typically already created by VS, or the Azure Function tools. It is just for local development use.

Then, add a key and value in "Values" node, which represents the CRON expression. In my case, I use "NotificationV2CRON" with "*/2 * * * *"

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "NotificationV2CRON": "*/2 * * * *"
  }
}

Now, change the original code to %NotificationV2CRON%

[FunctionName("NotificationV2")]
public async Task Run([TimerTrigger("%NotificationV2CRON%")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"NotificationV2 Timer trigger function executed at UTC: {DateTime.UtcNow}");
    // logic ...
}

Run your code and test if it works

Deploy your code to Azure. Then go to "Configuration" tab under your Azure Function App. Add a new application setting with the name of your CRON expression, in my case "NotificationV2CRON".

Observe the function log to make sure it works

Now you will be able to update the CRON value on the fly within a few clicks in Azure Portal!

Edi Wang

From Azure Communication Services to Resend: Simplifying Moonglade Email with SMTP

Where the Complexity Came From

Moving Provider Differences into Configuration

Separating Authentication from the Sender Address

Removing the Provider Selection Layer

Keeping the Existing Outbox

Handling SMTP Transport Details

Configuring Resend

What the Migration Achieved

Not Only Azure: Migrating this Blog from Entra ID to Standard OIDC

Why Change a Working Authentication System?

A Provider-Neutral Configuration

Using the Standard ASP.NET Core OIDC Handler

Authentication Is Not Authorization

Why Authorize with sub?

Bootstrapping the First Administrator

Failing Fast on Invalid Configuration

Entra ID Still Works

A Smaller Dependency and a Larger Possibility

From Azure to Anywhere: Redesigning Image Storage Architecture for this Blog

The Previous Architecture

A New Responsibility Boundary

A Smaller Storage Contract

Public Images and Private Originals

Cloud Integration Moves to Deployment

Example: Mapping Azure Files into App Service

CDN Delivery Remains Independent

The Trade-Off

Upgrading Existing Installations

Conclusion

From Azure Functions to a Database Outbox: Simplifying Moonglade Email Notifications

Before: A Separate Azure Function Service

After: An In-App Database Outbox

Code Structure

Event Handlers Only Enqueue Work

The Outbox Table

Claiming Messages With A Lease

The Background Worker

Processing, Retry, And Dead Letter

Dependency Injection

Configuration

A Linux Docker Issue

Why This Design Fits Moonglade

Deprecating The Standalone Repository

Final Thoughts

Hot Reloading a File in Azure Container Apps with Zero Down Time

Background

The Design

QqwryDb

QqwryDbProvider

QqwryDbWatcher

DI Registration

Why Polling Instead of FileSystemWatcher?

Summary of the Data Flow

Conclusion

Migrating this Blog to Docker on Linux with Azure App Service

A Little Bit of History

Why Migrating to Docker on Linux

0. Prepare the Code for Fully Cross Platform

File system paths, separators, and drives

Configuration differences

File permissions

Encoding and Time

1. For Local or On-Prem Deployments: Docker Compose

Image and build

Environment variables

About image storage

Network

Database

Running Docker Compose

2. For Azure Deployment

Migrating App Service Instance

Update Environment Variables

About ASP.NET Core Runtime

Migrating IIS Magics

Database

Networking

Conclusion

程序员的情绪价值：用 C# 构建实时 MIDI 播放器

Why Authorize with `sub`?