SharePoint  

SharePoint Page Versioning (Major, Minor, Draft) – with C#

SharePoint page versioning can feel confusing, especially when you automate updates using C# and suddenly see errors like:

  • The file must be checked out before it can be updated

  • Page stuck in Draft even after update

  • Version conflicts after Update()

This article explains page versioning in very simple terms, with clear C# examples, so you know exactly what SharePoint is doing behind the scenes.

1. What Is a SharePoint Page, Really?

A modern SharePoint page (.aspx) is two things at the same time:

  1. A file in the Site Pages library

  2. A list item with metadata (Title, Category, Market, etc.)

Because of this, SharePoint applies:

  • File rules (checkout, publish)

  • List rules (versioning, approval)

Understanding this removes 80% of confusion.

2. Major vs Minor Versions

VersionMeaning
1.0Published page (visible to everyone)
1.1Draft version (not fully published)
2.0Next published version

Important rule: "Any edit creates a draft (minor) version first."

Read version info in C#

var file = context.Web.GetFileByServerRelativeUrl(pageUrl);
context.Load(file, f => f.MajorVersion, f => f.MinorVersion);
await context.ExecuteQueryAsync();


string version = $"{file.MajorVersion}.{file.MinorVersion}";

3. Why Pages Become Draft After Metadata Update

When you update page metadata, SharePoint thinks: "This page changed, so it's now a draft."

Internally, it updates a hidden field called: _ModerationStatus

int status = (int)item["_ModerationStatus"];

4. Checkout: Why SharePoint Blocks Your Code

Most Site Pages libraries require checkout.

So SharePoint says: "You must check out the page before changing it."

If you don't, any update will fail.

Correct checkout code

context.Load(file, f => f.CheckOutType);
await context.ExecuteQueryAsync();
if (file.CheckOutType == CheckOutType.None)
{
    file.CheckOut();
    await context.ExecuteQueryAsync();
}

5. Why item.Update() Creates Draft Versions

item.Update(); - Always creates a draft version when the page is checked out.

That is normal SharePoint behavior, not a bug.

6. How to Publish a Page Properly

To make the page visible again:

  1. Check in the page

  2. Publish it

Correct publishing code

file.CheckIn("Metadata updated", CheckinType.MajorCheckIn);
await context.ExecuteQueryAsync();
file.Publish("Published after update");
await context.ExecuteQueryAsync();

This creates:

  • A new major version (for example, 2.0)

  • _ModerationStatus = Approved

7. Renaming a Page

Renaming a page means updating: FileLeafRef

This must be done while the page is checked out.

string newName = "Monthly-Report.aspx";
string folder = file.ServerRelativeUrl.Substring(0, file.ServerRelativeUrl.LastIndexOf("/"));
file.MoveTo($"{folder}/{newName}", MoveOperations.Overwrite);
await context.ExecuteQueryAsync();

8. Safe & Simple Pattern

// Load page
var file = context.Web.GetFileByServerRelativeUrl(pageUrl);
context.Load(file, f => f.CheckOutType, f => f.ListItemAllFields);
await context.ExecuteQueryAsync();

// Checkout
if (file.CheckOutType == CheckOutType.None)
{
file.CheckOut();
await context.ExecuteQueryAsync();
}

// Update metadata
var item = file.ListItemAllFields;
item["Title"] = "Updated Title";
item.Update();
await context.ExecuteQueryAsync();

// Publish
file.CheckIn("Updated metadata", CheckinType.MajorCheckIn);
await context.ExecuteQueryAsync();
file.Publish("Published");
await context.ExecuteQueryAsync();

Conclusion

SharePoint page versioning often feels complicated, but in reality it follows a very strict and predictable flow.

The confusion usually comes from forgetting that a modern page is both a file and a list item. Because of this, SharePoint enforces checkout, draft versions, approval, and publishing — even when you update something small like metadata.

If you are working with C# (CSOM, Azure Functions, background jobs), remember these key points:

  • Any update creates a draft (minor) version

  • Metadata updates do not automatically publish pages

  • Checkout is mandatory when required by the library

  • Only CheckIn + Publish create a major version

Once you follow the correct lifecycle:

Checkout → Update → CheckIn → Publish

SharePoint page automation becomes stable, predictable, and error-free.

Membership not found