Getting Started

Introduction

Armoryapi is a library written in C# that provides new and experienced .NET developers with an easy and efficient way to develop applications that interact with the World of Warcraft armory.

Setting up a Project

The armoryapi library currently requires that the project's target framework be 3.5 or higher.

After creating the project and setting up the target framework the next step is to add the reference to the armoryapi library. Download and extract the latest armoryapi package and you will find a DLL and an XML file inside, make note of where you have extracted these files and head back to Visual Studio. Open the "Add Reference" dialog (see http://msdn.microsoft.com/en-us/library/wkze6zky(v=vs.80).aspx) and click the tab labelled "Browse" and navigate to the armoryapi DLL that you extracted.

Note: in order for the intellisense documentation to work you must also extract the XML file to the same directory as the DLL

Your project is now setup and ready to utilise the armoryapi library.

Setting up a Database

The use of a database with armoryapi is optional but is recommended as it will provide a substantial increase in performance and will prevent your application requiring as many requests to the Battle.net RESTful API. Currently the only database that is supported by armoryapi is Microsoft SQL Server, if you require a free version you can pickup any of the express editions for free at http://www.microsoft.com/sqlserver/en/us/editions/express.aspx

Once you have setup your SQL database simply run This Script or execute the SQL below in SQL Management Studio.

USE [armoryapi]
GO
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
SET ANSI_PADDING ON
GO
CREATE TABLE [dbo].[achievements](
	[id] [int] NOT NULL,
	[title] [varchar](200) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_achievements_title]  DEFAULT (''),
	[points] [int] NOT NULL CONSTRAINT [DF_achievements_points]  DEFAULT ((0)),
	[description] [varchar](500) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_achievements_description]  DEFAULT (''),
 CONSTRAINT [PK_achievements] PRIMARY KEY CLUSTERED 
(
	[id] ASC
)WITH (PAD_INDEX  = OFF, IGNORE_DUP_KEY = OFF) ON [PRIMARY]
) ON [PRIMARY]

GO
SET ANSI_PADDING OFF
GO
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
CREATE TABLE [dbo].[character_achievements](
	[character_id] [int] NOT NULL CONSTRAINT [DF_character_achievements_character_id]  DEFAULT ((0)),
	[achievement_id] [int] NOT NULL CONSTRAINT [DF_character_achievements_achievement_id]  DEFAULT ((0)),
	[unlock_datetime] [datetime] NULL,
 CONSTRAINT [PK_character_achievements] PRIMARY KEY CLUSTERED 
(
	[character_id] ASC,
	[achievement_id] ASC
)WITH (PAD_INDEX  = OFF, IGNORE_DUP_KEY = OFF) ON [PRIMARY]
) ON [PRIMARY]

GO
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
SET ANSI_PADDING ON
GO
CREATE TABLE [dbo].[characters](
	[id] [int] IDENTITY(1,1) NOT NULL,
	[region] [varchar](20) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_characters_region]  DEFAULT ((0)),
	[character] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_characters_character]  DEFAULT (''),
	[friendlyRealm] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_characters_friendlyRealm]  DEFAULT (''),
	[realm] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_characters_realm]  DEFAULT (''),
	[guildID] [int] NOT NULL CONSTRAINT [DF_characters_guildID]  DEFAULT ((0)),
	[class] [smallint] NOT NULL CONSTRAINT [DF_characters_class]  DEFAULT ((0)),
	[race] [smallint] NOT NULL CONSTRAINT [DF_characters_race]  DEFAULT ((0)),
	[gender] [bit] NOT NULL CONSTRAINT [DF_characters_gender]  DEFAULT ((0)),
	[player_level] [smallint] NOT NULL CONSTRAINT [DF_characters_player_level]  DEFAULT ((0)),
	[achievementPoints] [int] NOT NULL CONSTRAINT [DF_characters_achievementPoints]  DEFAULT ((0)),
	[thumbnail] [varchar](100) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_characters_thumbnail]  DEFAULT (''),
	[last_modified] [datetime] NULL,
	[last_refresh] [datetime] NULL,
 CONSTRAINT [PK_characters] PRIMARY KEY CLUSTERED 
(
	[id] ASC
)WITH (PAD_INDEX  = OFF, IGNORE_DUP_KEY = OFF) ON [PRIMARY]
) ON [PRIMARY]

GO
SET ANSI_PADDING OFF
GO
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
SET ANSI_PADDING ON
GO
CREATE TABLE [dbo].[guilds](
	[id] [int] IDENTITY(1,1) NOT NULL,
	[guildName] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_guilds_guildName]  DEFAULT (''),
	[realm] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_guilds_realm]  DEFAULT (''),
	[friendlyRealm] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_guilds_friendlyRealm]  DEFAULT (''),
	[region] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_guilds_region]  DEFAULT (''),
	[guildLevel] [smallint] NOT NULL CONSTRAINT [DF_guilds_guildLevel]  DEFAULT ((0)),
	[members] [int] NOT NULL CONSTRAINT [DF_guilds_members]  DEFAULT ((0)),
	[achievementPoints] [int] NOT NULL CONSTRAINT [DF_guilds_achievementPoints]  DEFAULT ((0)),
	[last_refresh] [datetime] NULL,
 CONSTRAINT [PK_guilds] PRIMARY KEY CLUSTERED 
(
	[id] ASC
)WITH (PAD_INDEX  = OFF, IGNORE_DUP_KEY = OFF) ON [PRIMARY]
) ON [PRIMARY]

GO
SET ANSI_PADDING OFF
GO
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
SET ANSI_PADDING ON
GO
CREATE TABLE [dbo].[realms](
	[realm] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_realms_realm]  DEFAULT (''),
	[region] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_realms_region]  DEFAULT (''),
	[type] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_realms_type]  DEFAULT (''),
	[queue] [bit] NOT NULL CONSTRAINT [DF_realms_queue]  DEFAULT ((0)),
	[status] [bit] NOT NULL CONSTRAINT [DF_realms_status]  DEFAULT ((0)),
	[population] [varchar](20) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_realms_population]  DEFAULT (''''),
	[battlegroup] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_realms_battlegroup]  DEFAULT (''),
	[slug] [varchar](50) COLLATE Latin1_General_CI_AS NOT NULL CONSTRAINT [DF_realms_slug]  DEFAULT (''),
	[last_refresh] [datetime] NOT NULL,
 CONSTRAINT [PK_realms] PRIMARY KEY CLUSTERED 
(
	[realm] ASC,
	[region] ASC
)WITH (PAD_INDEX  = OFF, IGNORE_DUP_KEY = OFF) ON [PRIMARY]
) ON [PRIMARY]

GO
SET ANSI_PADDING OFF

Creating a Hello World!

If you haven't already, first read the Setting up a Project and Setting up a Database sections to ensure your environment is setup correctly.

Step One

Double click on your form to create the Load event and add the following code to create and instantiate a new Armory object:

VB.Net

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    Dim armory As ArmoryAPI.Armory = New ArmoryAPI.Armory(ArmoryAPI.BattleNetRegion.Europe, ArmoryAPI.BattleNetLocale.en_GB)
End Sub

private void Form1_Load(object sender, EventArgs e)
{
    Armory armory = new Armory(BattleNetRegion.Europe, BattleNetLocale.en_GB);
}

Step Two (Optional)

If you want to utilise a database to cache data (highly recommended) then add the following two lines to specify the connection string that will be used when establishing a database connection and to specify how long data should be cached for before being refreshed.

VB.Net

armory.ConnectionString = "Data Source=(local)\SQLEXPRESS;Initial Catalog=armoryapi;User ID=username;Password=password"
armory.RefreshInterval = 120

armory.ConnectionString = @"Data Source=(local)\SQLEXPRESS;Initial Catalog=armoryapi;User ID=username;Password=password";
armory.RefreshInterval = 120;

Step Three

Now that we have our armory object instantiated we can begin fetching data from the Battle.net servers, the following code will load the character record for Thombu on the Khadgar-EU server, and if a database has been specified will cache the data into the database.

VB.Net

Dim character As ArmoryAPI.Character = armory.GetCharacter("Thombu", "Khadgar")
MessageBox.Show(String.Format("{0} is level {1}, has accumulated {2} achievement points and plays on the {3} server", _
                                character.Name, character.Level, character.AchievementPoints, character.Realm))

Character character = armory.GetCharacter("Thombu", "Khadgar");
MessageBox.Show(String.Format("{0} is level {1}, has accumulated {2} achievement points and plays on the {3} server", 
                                character.Name, character.Level, character.AchievementPoints, character.Realm));

Code

Below you can find the full code for the Hello World applications

VB.Net

Public Class Form1
    Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        ' Create the armory object to interact with the European servers and return data in English
        Dim armory As ArmoryAPI.Armory = New ArmoryAPI.Armory(ArmoryAPI.BattleNetRegion.Europe, ArmoryAPI.BattleNetLocale.en_GB)

        ' Optional database properties
        armory.ConnectionString = "Data Source=(local)\SQLEXPRESS;Initial Catalog=armoryapi;User ID=username;Password=password"
        armory.RefreshInterval = 120

        ' Fetch the character record and output data to a message box
        Dim character As ArmoryAPI.Character = armory.GetCharacter("Thombu", "Khadgar")
        MessageBox.Show(String.Format("{0} is level {1}, has accumulated {2} achievement points and plays on the {3} server", _
                                        character.Name, character.Level, character.AchievementPoints, character.Realm))
    End Sub
End Class

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using ArmoryAPI;

namespace WindowsFormsApplication2
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {
            /* Create the armory object to interact with the European servers and return data in English */
            Armory armory = new Armory(BattleNetRegion.Europe, BattleNetLocale.en_GB);
            
            /* Optional database properties */
            armory.ConnectionString = @"Data Source=(local)\SQLEXPRESS;Initial Catalog=armoryapi;User ID=username;Password=password";
            armory.RefreshInterval = 120;

            /* Fetch the character record and output data to a message box */
            Character character = armory.GetCharacter("Thombu", "Khadgar");
            MessageBox.Show(String.Format("{0} is level {1}, has accumulated {2} achievement points and plays on the {3} server", 
                                            character.Name, character.Level, character.AchievementPoints, character.Realm));

        }
    }
}

► Sign in to add a comment