AlRevolver.GoogleSheets 1.1.0

AlRevolver.GoogleSheets

AlRevolver.GoogleSheets is an MSBuild task that reads Google Sheets through the Google Sheets API and generates project files during build.

It can generate:

• tables.json from regular sheets.
• Neutral and culture .resx files from sheets ending with .resx.
• Public *.Designer.cs resource classes for generated .resx files.

The package imports its MSBuild target automatically when it is referenced directly by a project.

Install

dotnet add package AlRevolver.GoogleSheets

Google Setup

1. Create a Google Cloud service account.
2. Enable the Google Sheets API for the project.
3. Download the service account JSON credentials file.
4. Open the JSON and copy the client_email value.
5. Share the Google Sheet with that client_email.

Do not commit the credentials file. Keep it local or provide it through CI secrets.

Example .gitignore entry:

/credentials.json
/.secrets/

Minimal Project Setup

Add these properties to the consuming .csproj:

<PropertyGroup>
  <AlRevolverGoogleSheetsEnabled>true</AlRevolverGoogleSheetsEnabled>
  <AlRevolverGoogleSheetsSpreadsheetId>YOUR_SPREADSHEET_ID</AlRevolverGoogleSheetsSpreadsheetId>
  <AlRevolverGoogleSheetsCredentialsFile>$(MSBuildProjectDirectory)\credentials.json</AlRevolverGoogleSheetsCredentialsFile>
</PropertyGroup>

SpreadsheetId is the value in a Google Sheets URL between /d/ and /edit.

For example, this URL:

https://docs.google.com/spreadsheets/d/1ZxCvBnMqWeRtYuIoPaSdFgHjKl123456789ABCDEf-vdmAPckw/edit

uses this id:

1ZxCvBnMqWeRtYuIoPaSdFgHjKl123456789ABCDEf-vdmAPckw

Build

dotnet build

Or pass the required values from the command line:

dotnet build `
  /p:AlRevolverGoogleSheetsEnabled=true `
  /p:AlRevolverGoogleSheetsSpreadsheetId=YOUR_SPREADSHEET_ID `
  /p:AlRevolverGoogleSheetsCredentialsFile=C:\path\to\credentials.json

If AlRevolverGoogleSheetsCredentialsFile is not set, the task checks these environment variables:

• ALREVOLVER_GOOGLE_SHEETS_CREDENTIALS_FILE
• GOOGLE_APPLICATION_CREDENTIALS

Generated Files

By default the task writes into:

Generated/GoogleSheets

Generated files are added to the current build:

• tables.json is added as Content with CopyToOutputDirectory=PreserveNewest.
• .resx files are added as EmbeddedResource.
• *.Designer.cs files are added as Compile.

The task writes files only when content changes, so unchanged sheets do not touch timestamps.

Regular Sheet Format

Each sheet name becomes a JSON property in tables.json.

Example sheet named Units:

Because the fourth header cell is empty, that column is ignored automatically:

{
  "Units": [
    {
      "Name": "Archer",
      "Hp": 100,
      "Attack": 20,
      "Type": "Range"
    },
    {
      "Name": "Cavale",
      "Hp": 100,
      "Attack": 20,
      "Type": "Cavalery"
    }
  ]
}

Rules:

• StartingIndex defaults to A1; that cell is the first header cell.
• Empty header cells are ignored.
• Explicitly ignored columns do not appear in JSON.
• Empty data rows are skipped.
• Values are parsed as bool, integer, decimal, or string.

ResX Sheet Format

Any sheet whose name ends with .resx generates .resx files and a public designer class.

Example sheet named Units.resx:

Generated files:

Generated/GoogleSheets/Units.resx
Generated/GoogleSheets/Units.ru-ru.resx
Generated/GoogleSheets/Units.Designer.cs

Generated code can be used like this:

using MyGame.Generated.GoogleSheets;

var archer = Units.Archer;

ResX columns:

• Name is required.
• Neutral, Neutral Value, or NeutralValue is required.
• Neutral Comment is optional.
• Culture columns are named by culture, for example ru-ru.
• Culture comment columns can be named like ru-ru Comment or ru-ruComment.

Starting Index and Ignored Columns

StartingIndex controls where a sheet table begins. The value is the first header cell.

Examples:

<AlRevolverGoogleSheetsStartingIndex>A1</AlRevolverGoogleSheetsStartingIndex>
<AlRevolverGoogleSheetsStartingIndex>G13</AlRevolverGoogleSheetsStartingIndex>
<AlRevolverGoogleSheetsStartingIndex>Units:A1;Units.resx:G11</AlRevolverGoogleSheetsStartingIndex>

IgnoredColumns is empty by default. Use semicolon-separated absolute Google Sheet columns when you need to skip columns.

Examples:

<AlRevolverGoogleSheetsIgnoredColumns>Z;AA</AlRevolverGoogleSheetsIgnoredColumns>
<AlRevolverGoogleSheetsIgnoredColumns>Units:Z;Units:AA;Items:AA</AlRevolverGoogleSheetsIgnoredColumns>

Sheet-specific entries use : and match sheet names case-insensitively.

MSBuild Properties