# Including Static Files in a NuGet Package: A Developer's Guide

### Why Static Files in NuGet Packages?

When developing utility libraries, you'll often need to bundle static files like JSON configurations, text templates, or images. This guide demonstrates two professional approaches to include these files in your NuGet package:

1.  **Embedded Resources** (Files compiled into the assembly)
    
2.  **Content Files** (Files added to consumer projects)
    

## Step 1: Project Setup (YourProject.csproj)

Base Configuration

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <PackageId>YourProject</PackageId>
    <Version>1.0.5</Version>
    <!-- Other metadata -->
  </PropertyGroup>
</Project>
```

Key Additions for Static Files

```xml
<ItemGroup>
  <!-- As Embedded Resource -->
  <EmbeddedResource Include="Phone/countries.json" />

  <!-- As Content File -->
  <None Include="Phone/countries.json" 
        Pack="True" 
        PackagePath="contentFiles/any/any/Phone/" />
</ItemGroup>
```

**What These Do?**

*   `EmbeddedResource`: Bakes the file into your DLL
    
*   `None` with `Pack`: Includes file in NuGet's `contentFiles` directory
    

## Step 2: Accessing Embedded Resources

```csharp
using System.Reflection;
using Newtonsoft.Json;

public class PhoneNumberOperation
{
    public List<CountryCode> CountryCodes { get; } = new();

    public PhoneNumberOperation()
    {
        var assembly = Assembly.GetExecutingAssembly();
        var resourceName = "YourProject.Phone.countries.json";

        using var stream = assembly.GetManifestResourceStream(resourceName) 
            ?? throw new FileNotFoundException($"Missing resource: {resourceName}");
        
        using var reader = new StreamReader(stream);
        CountryCodes = JsonConvert.DeserializeObject<List<CountryCode>>(reader.ReadToEnd())
            ?? new List<CountryCode>();
    }
}
```

**Key Notes:**

*   Resource naming follows `Namespace.Folder.Filename.extension`
    
*   Always validate null streams
    
*   Consider using `System.Text.Json` for modern .NET projects
    

## **Step 3: Understanding Content Files**

When consumers install your package, files in `contentFiles` will appear in their project under:

```plaintext
Project/
└── Phone/
    └── countries.json
```

**Consumer Control:**

*   Files can be marked as Copy Always/Never
    
*   Build action can be modified
    

## **Step 4: Package Verification**

1.  Build your package:
    
    ```bash
    dotnet pack --configuration Release
    ```
    
2.  Inspect using:
    
    *   **NuGet Package Explorer** (GUI tool)
        
    *   Manual inspection by renaming `.nupkg` → `.zip`
        

**Expected Structure:**

```plaintext
├── lib
│   └── net9.0
│       └── YourProject.dll
└── contentFiles
    └── any
        └── any
            └── Phone
                └── countries.json
```

## **Pro Tips & Troubleshooting**

1.  **Double-Check Resource Names**
    
    ```csharp
    var resources = assembly.GetManifestResourceNames();
    Console.WriteLine(string.Join("\n", resources));
    ```
    
2.  **ContentFiles Not Appearing?**
    
    *   Ensure the consumer's project SDK is `Microsoft.NET.Sdk`
        
    *   Verify `<IncludeContentInPack>true</IncludeContentInPack>`
        
3.  **When to Use Which Method**
    
    | **Embedded Resources** | **Content Files** |
    | --- | --- |
    | Internal configs | User-editable files |
    | Critical data | Example templates |
    | Small files | Larger assets |
    

## **Complete Project File Reference**

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <!-- Package Metadata -->
    <PackageId>YourProject</PackageId>
    <PackageReadmeFile>README.md</PackageReadmeFile>
  </PropertyGroup>

  <ItemGroup>
    <!-- Dependencies -->
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>

  <ItemGroup>
    <!-- Static Files -->
    <EmbeddedResource Include="Phone/countries.json" />
    <None Include="Phone/countries.json" 
          Pack="True" 
          PackagePath="contentFiles/any/any/Phone/" />
    <None Include="README.md" Pack="True" PackagePath="/" />
  </ItemGroup>
</Project>
```

## **Conclusion:**

Including static files like JSON or text resources in NuGet packages elevates your library’s utility and flexibility. By leveraging **embedded resources**, you ensure critical files remain secure and directly accessible within your assembly. Meanwhile, **content files** empower consumers to customize configurations or reference external assets in their projects.

Always verify your package structure post-build and test consumption scenarios thoroughly. Whether you’re distributing localization files, templates, or configuration data, these techniques ensure your NuGet package delivers a polished, professional experience.

*Empower your libraries—static files are no longer static limitations, but dynamic tools!*

### **CONTACT:**

I’m Kumar Bishojit Paul, the Founder and CEO of [**BIKIRAN**](https://www.bikiran.com/). If you need further assistance, please leave a comment. I’m interested in helping you.

**Got questions?** Drop a comment below or reach out at contact@bikiran.com. Happy packaging!



---

## 🏢 About Bikiran

**[Bikiran](https://bikiran.com/)** is a software development and cloud infrastructure company founded in 2012, headquartered in Khulna, Bangladesh. With 15,000+ clients and over a decade of experience, Bikiran builds and operates a suite of products spanning domain services, cloud hosting, app deployment, workflow automation, and developer tools.

| SL  | Topic        | Product                                                              | Description                                             |
| --- | ------------ | -------------------------------------------------------------------- | ------------------------------------------------------- |
| 1   | Website      | [Bikiran](https://bikiran.com/)                                      | Main platform — Domain, hosting & cloud services        |
| 2   | Website      | [Edusoft](https://www.edusoft.com.bd/)                               | Education management software for institutions          |
| 3   | Website      | [n8n Clouds](https://n8nclouds.com/)                                 | Managed n8n workflow automation hosting                 |
| 4   | Website      | [Timestamp Zone](https://www.timestamp.zone/)                        | Unix timestamp converter & timezone tool                |
| 5   | Website      | [PDFpi](https://pdfpi.bikiran.com/)                                  | Online PDF processing & manipulation tool               |
| 6   | Website      | [Blog](https://blog.bikiran.com/)                                    | Technical articles, guides & tutorials                  |
| 7   | Website      | [Support](https://support.bikiran.com/)                              | 24/7 customer support portal                            |
| 8   | Website      | [Probackup](https://probackup.bikiran.com/)                          | Automated database backup for SQL, PostgreSQL & MongoDB |
| 9   | Service      | [Domain](https://www.bikiran.com/domain)                             | Domain registration, transfer & DNS management          |
| 10  | Service      | [Hosting](https://www.bikiran.com/services/hosting/web)              | Web, app & email hosting on NVMe SSD                    |
| 11  | Service      | Email & SMS                                                          | Bulk email & SMS notification service                   |
| 12  | npm          | [Chronopick](https://www.npmjs.com/package/@bikiran/chronopick)      | Date & time picker React component                      |
| 13  | npm          | [Rich Editor](https://www.npmjs.com/package/@bikiran/editor)         | WYSIWYG rich text editor for React                      |
| 14  | npm          | [Button](https://www.npmjs.com/package/@bikiran/button)              | Reusable React button component library                 |
| 15  | npm          | [Electron Boilerplate](https://www.npmjs.com/package/create-edx-app) | CLI to scaffold Electron.js project templates           |
| 16  | NuGet        | [Bkash](https://www.nuget.org/packages/Bikiran.Payment.Bkash)        | bKash payment gateway integration for .NET              |
| 17  | NuGet        | [Bikiran Engine](https://www.nuget.org/packages/Bikiran.Engine)      | Core .NET engine library for Bikiran services           |
| 18  | Open Source  | [PDFpi](https://github.com/bikirandev/pdfpi)                         | PDF processing tool — open source                       |
| 19  | Open Source  | [Bikiran Engine](https://github.com/bikirandev/Bikiran.Engine)       | Core .NET engine — open source                          |
| 20  | Open Source  | [Drive CLI](https://github.com/bikirandev/DriveCLI)                  | CLI tool to manage Google Drive from terminal           |
| 21  | Docker       | [Pgsql](https://github.com/bikirandev/docker-pgsql)                  | Docker setup for PostgreSQL                             |
| 22  | Docker       | [n8n](https://github.com/bikirandev/docker-n8n)                      | Docker setup for n8n automation                         |
| 23  | Docker       | [Pgadmin](https://github.com/bikirandev/docker-pgadmin)              | Docker setup for pgAdmin                                |
| 24  | Social Media | [LinkedIn](https://www.linkedin.com/company/bikiran12)               | Bikiran on LinkedIn                                     |
| 25  | Social Media | [Facebook](https://www.facebook.com/bikiran12)                       | Bikiran on Facebook                                     |
| 26  | Social Media | [YouTube](https://www.youtube.com/@bikiranofficial)                  | Bikiran on YouTube                                      |
| 27  | Social Media | [FB n8nClouds](https://www.facebook.com/n8nclouds)                   | n8n Clouds on Facebook                                  |